/rg/pkg/kaffe/libraries/javalib/gnu/crypto/assembly/package.html
HTML | 253 lines | 173 code | 35 blank | 45 comment | 0 complexity | b1cd097a68df2a77d31388a2b12def45 MD5 | raw file
- <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
- <html><head>
- <!--
- $Id: package.html,v 1.2 2005/10/20 12:04:23 alexa Exp $
- Copyright (C) 2003, Free Software Foundation, Inc.
- This file is part of GNU Crypto.
- GNU Crypto is free software; you can redistribute it and/or modify
- it under the terms of the GNU General Public License as published by
- the Free Software Foundation; either version 2, or (at your option)
- any later version.
- GNU Crypto is distributed in the hope that it will be useful, but
- WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
- General Public License for more details.
- You should have received a copy of the GNU General Public License
- along with this program; see the file COPYING. If not, write to the
- Free Software Foundation Inc.,
- 51 Franklin Street, Fifth Floor,
- Boston, MA 02110-1301
- USA
- Linking this library statically or dynamically with other modules is
- making a combined work based on this library. Thus, the terms and
- conditions of the GNU General Public License cover the whole
- combination.
- As a special exception, the copyright holders of this library give
- you permission to link this library with independent modules to
- produce an executable, regardless of the license terms of these
- independent modules, and to copy and distribute the resulting
- executable under terms of your choice, provided that you also meet,
- for each linked independent module, the terms and conditions of the
- license of that module. An independent module is a module which is
- not derived from or based on this library. If you modify this
- library, you may extend this exception to your version of the
- library, but you are not obligated to do so. If you do not wish to
- do so, delete this exception statement from your version.
- -->
- </head><body>
- Provides a high-level API for combining and using GNU Crypto cipher, mode,
- and padding primitives.
- <h2>Package overview</h2>
- <p>This package describes two patterns implemneted by the GNU Crypto
- library that allow users to combine the basic cipher (and other) primitives
- into higher level components in order to offer more flexible functionalities.
- These two patterns are: <i>Cascade</i> and <i>Assembly</i>.</p>
- <p>The <i>Cascade</i> is a means of assembling block cipher Modes of
- Operations into an ordered sequence of <i>stages</i>. A <i>stage</i>
- is a representation of a Mode (of Operations) wired in a designated
- <i>direction</i>: FORWARD or REVERSED. A Mode staged in the FORWARD
- direction would encrypt input blocks, producing ciphertext, while the
- same Mode, wired in the REVERSED direction would do the opposite; i.e.
- decrypt an input text producing a plaintext.</p>
- <p>In the simplest case, all stages in a <i>Cascade</i> have <i>k</i>-bit
- keys, and the stage inputs and outputs are all <i>n</i>-bit quantities.
- The stage ciphers may differ (general cascade of ciphers), or all be
- identical (cascade of identical ciphers).</p>
- <p>An <i>Assembly</i> is a construction of an ordered set of <i>Transformer</i>
- objects. Each <i>Transformer</i> is wired to operate in PRE_PROCESSING or
- POST_PROCESSING mode --the Transformer's <i>operation</i>. In
- PRE_PROCESSING, the input is first processed by the <i>Transformer</i>
- before being passed to the rest of the chain, while in POST_PROCESSING
- state, the <i>Transformer</i> first passes the input to the rest of the
- chain and only processes the output of the returned data.</p>
- <h3>Cascade pattern</h3>
- <p>The following diagram shows the important classes participating in the
- <i>Cascade</i> pattern:</p>
- <p><img src="{@docRoot}/../diagrams/cascade_class_diag.png"
- width=525 height=195 border=0></p>
- <p>Here is an example of how a <i>Cascade</i> is used to construct a
- <i>DES-EDE</i> symetric-key block cipher from three independent
- <i>DES</i> cipher instances:</p>
- <pre>
- HashMap map = new HashMap();
- HashMap map1 = new HashMap();
- HashMap map2 = new HashMap();
- HashMap map3 = new HashMap();
- Cascade new3DES = new Cascade();
- Object des1 = new3DES.append(
- Stage.getInstance(
- ModeFactory.getInstance(Registry.ECB_MODE, new DES(), 8),
- Direction.FORWARD));
- Object des2 = new3DES.append(
- Stage.getInstance(
- ModeFactory.getInstance(Registry.ECB_MODE, new DES(), 8),
- Direction.REVERSED));
- Object des3 = new3DES.append(
- Stage.getInstance(
- ModeFactory.getInstance(Registry.ECB_MODE, new DES(), 8),
- Direction.FORWARD));
- map.put(des1, map1);
- map.put(des2, map2);
- map.put(des3, map3);
- map1.put(IBlockCipher.KEY_MATERIAL, key1material);
- map2.put(IBlockCipher.KEY_MATERIAL, key2material);
- map3.put(IBlockCipher.KEY_MATERIAL, key3material);
- // encryption
- map.put(Cascade.DIRECTION, Direction.FORWARD);
- byte[] pt = ...; // some plaintext to encrypt
- byte[] ct = new byte[pt.length]; // where ciphertext is returned
- try
- {
- new3DES.init(map);
- new3DES.update(pt, 0, ct, 0);
- }
- catch (InvalidKeyException x)
- {
- x.printStackTrace(System.err);
- }
- </pre>
- <h3>Assembly pattern</h3>
- <p>The following diagram shows the important classes participating in the
- <i>Assembly</i> pattern:</p>
- <p><img src="{@docRoot}/../diagrams/assembly_class_diag.png"
- width=455 height=313 border=0></p>
- <p>Here is an example of how to compress and encrypt a stream of
- plaintext:</p>
- <pre>
- import gnu.crypto.Registry;
- import gnu.crypto.util.Util;
- import gnu.crypto.assembly.Assembly;
- import gnu.crypto.assembly.Cascade;
- import gnu.crypto.assembly.Direction;
- import gnu.crypto.assembly.Stage;
- import gnu.crypto.assembly.Transformer;
- import gnu.crypto.assembly.TransformerException;
- import gnu.crypto.cipher.Blowfish;
- import gnu.crypto.cipher.IBlockCipher;
- import gnu.crypto.mode.IMode;
- import gnu.crypto.mode.ModeFactory;
- import gnu.crypto.pad.IPad;
- import gnu.crypto.pad.PadFactory;
- HashMap attributes = new HashMap();
- HashMap modeAttributes = new HashMap();
- Cascade ofbBlowfish = new Cascade();
- Object modeNdx = ofbBlowfish.append(
- Stage.getInstance(
- ModeFactory.getInstance(Registry.OFB_MODE, new Blowfish(), 8),
- Direction.FORWARD));
- attributes.put(modeNdx, modeAttributes);
- IPad pkcs7 = PadFactory.getInstance(Registry.PKCS7_PAD);
- Assembly asm = new Assembly();
- asm.addPreTransformer(Transformer.getCascadeTransformer(ofbBlowfish));
- asm.addPreTransformer(Transformer.getPaddingTransformer(pkcs7));
- asm.addPreTransformer(Transformer.getDeflateTransformer());
- // plaintext and key material
- byte[] km = new byte[] { 0, 1, 2, 3, 4, 5, 6, 7, 8};
- byte[] iv = new byte[] {-1, -2, -3, -4, -5, -6, -7, -8, -9};
- byte[] pt = new byte[] { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11};
- byte[] tpt = new byte[11 * pt.length];
- // forward transformation
- modeAttributes.put(IBlockCipher.KEY_MATERIAL, km);
- modeAttributes.put(IMode.IV, iv);
- attributes.put(Assembly.DIRECTION, Direction.FORWARD);
- try
- {
- asm.init(attributes);
- }
- catch (TransformerException x)
- {
- x.printStackTrace(System.err);
- }
- byte[] ct = null;
- ByteArrayOutputStream baos = new ByteArrayOutputStream();
- try
- {
- for (int i = 0; i < 10; i++)
- { // transform in parts of 12-byte a time
- System.arraycopy(pt, 0, tpt, i * pt.length, pt.length);
- ct = asm.update(pt);
- baos.write(ct, 0, ct.length);
- }
- }
- catch (TransformerException x)
- {
- x.printStackTrace(System.err);
- }
- try
- {
- System.arraycopy(pt, 0, tpt, 10 * pt.length, pt.length);
- ct = asm.lastUpdate(pt);
- }
- catch (TransformerException x)
- {
- x.printStackTrace(System.err);
- }
- baos.write(ct, 0, ct.length);
- ct = baos.toByteArray();
- // reversed transformation
- attributes.put(Assembly.DIRECTION, Direction.REVERSED);
- try
- {
- asm.init(attributes);
- }
- catch (TransformerException x)
- {
- x.printStackTrace(System.err);
- }
- byte[] ot = null;
- try
- {
- ot = asm.lastUpdate(ct); // transform the lot in one go
- }
- catch (TransformerException x)
- {
- x.printStackTrace(System.err);
- }
- </pre>
- <!-- $Revision: 1.2 $ -->
- </body></html>