package.html | searchcode

/rg/pkg/kaffe/libraries/javalib/gnu/crypto/assembly/package.html

https://github.com/GunioRobot/MI424WR_GEN2_Rev_E-F
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>