mirror of
https://github.com/moparisthebest/open-keychain
synced 2024-11-14 04:45:04 -05:00
942 lines
39 KiB
HTML
942 lines
39 KiB
HTML
|
<html>
|
||
|
|
<head>
|
||
|
|
<title>Bouncy Castle Crypto Package</title>
|
||
|
|
</head>
|
||
|
|
|
||
|
|
<body bgcolor="#ffffff" text="#000000#">
|
||
|
|
|
||
|
|
<center>
|
||
|
|
<h1>Bouncy Castle Crypto Package</h1>
|
||
|
|
<font size=1>
|
||
|
|
<pre>
|
||
|
|
</pre>
|
||
|
|
</font>
|
||
|
|
</center>
|
||
|
|
<h2>1.0 Introduction</h2>
|
||
|
|
The Bouncy Castle Crypto package is a Java implementation of
|
||
|
|
cryptographic algorithms. The package is organised so that it
|
||
|
|
contains a light-weight API suitable for use in any environment
|
||
|
|
(including the newly released J2ME) with the additional infrastructure
|
||
|
|
to conform the algorithms to the JCE framework.
|
||
|
|
<p>
|
||
|
|
Except where otherwise stated, this software is distributed under a license
|
||
|
|
based on the MIT X
|
||
|
|
Consortium license. To view the license, see <a href="./LICENSE.html">here</a>.
|
||
|
|
The OpenPGP library also includes a modified BZIP2 library which
|
||
|
|
is licensed under the <a href="http://www.apache.org/licenses/">Apache Software License, Version 2.0</a>.
|
||
|
|
|
||
|
|
<p>
|
||
|
|
If you have the full package you will have six jar files, bcprov*.jar
|
||
|
|
which contains the BC provider, jce-*.jar which contains
|
||
|
|
the JCE provider, clean room API, and bcmail*.jar which contains the
|
||
|
|
mail API.
|
||
|
|
<p>
|
||
|
|
Note: if you are using JDK 1.0, you will just find a class hierarchy in
|
||
|
|
the classes directory.
|
||
|
|
<p>
|
||
|
|
To view examples, look at the test programs in the packages:
|
||
|
|
<ul>
|
||
|
|
<li><b>org.bouncycastle.crypto.test</b>
|
||
|
|
<li><b>org.bouncycastle.jce.provider.test</b>
|
||
|
|
</ul>
|
||
|
|
<p>
|
||
|
|
To verify the packages, run the following Java programs with the
|
||
|
|
appropriate classpath:
|
||
|
|
<ul>
|
||
|
|
<li><b>java org.bouncycastle.crypto.test.RegressionTest</b>
|
||
|
|
<li><b>java org.bouncycastle.jce.provider.test.RegressionTest</b>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
|
||
|
|
<h2>2.0 Patents</h2>
|
||
|
|
<p>
|
||
|
|
Some of the algorithms in the Bouncy Castle APIs are patented in some
|
||
|
|
places. It is upon the user of the library to be aware of what the
|
||
|
|
legal situation is in their own situation, however we have been asked
|
||
|
|
to specifically mention the patent below, in the following terms, at
|
||
|
|
the request of the patent holder. Algorithms that appear here are only
|
||
|
|
distributed in the -ext- versions of the provider.
|
||
|
|
<p>
|
||
|
|
The IDEA encryption algorithm is patented in the USA, Japan, and Europe
|
||
|
|
including at least Austria, France, Germany, Italy, Netherlands, Spain, Sweden,
|
||
|
|
Switzerland and the United Kingdom. Non-commercial use is free, however
|
||
|
|
any commercial products that make use of IDEA are liable for royalties.
|
||
|
|
Please see
|
||
|
|
<a href="http://www.mediacrypt.com">www.mediacrypt.com</a> for
|
||
|
|
further details.
|
||
|
|
|
||
|
|
<h2>3.0 Specifications</h2>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li> clean room implementation of the JCE API
|
||
|
|
<li> light-weight cryptographic API consisting of support for
|
||
|
|
<ul>
|
||
|
|
<li>BlockCipher
|
||
|
|
<li>BufferedBlockCipher
|
||
|
|
<li>AsymmetricBlockCipher
|
||
|
|
<li>BufferedAsymmetricBlockCipher
|
||
|
|
<li>StreamCipher
|
||
|
|
<li>BufferedStreamCipher
|
||
|
|
<li>KeyAgreement
|
||
|
|
<li>IESCipher
|
||
|
|
<li>Digest
|
||
|
|
<li>Mac
|
||
|
|
<li>PBE
|
||
|
|
<li>Signers
|
||
|
|
</ul>
|
||
|
|
<li> JCE compatible framework for a Bouncy Castle provider
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<h2>4.0 Light-weight API</h2>
|
||
|
|
|
||
|
|
<p>
|
||
|
|
This API has been specifically developed for those circumstances
|
||
|
|
where the rich API and integration requirements of the JCE are
|
||
|
|
not required.
|
||
|
|
<p>
|
||
|
|
However as a result, the light-weight API requires more effort
|
||
|
|
and understanding on the part of a developer to initialise and
|
||
|
|
utilise the algorithms.
|
||
|
|
|
||
|
|
<h3>4.1 Example</h3>
|
||
|
|
|
||
|
|
<p>To utilise the light-weight API in a program, the fundamentals
|
||
|
|
are as follows;
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
<code>
|
||
|
|
/*
|
||
|
|
* This will use a supplied key, and encrypt the data
|
||
|
|
* This is the equivalent of DES/CBC/PKCS5Padding
|
||
|
|
*/
|
||
|
|
BlockCipher engine = new DESEngine();
|
||
|
|
BufferedBlockCipher cipher = new PaddedBlockCipher(new CBCCipher(engine));
|
||
|
|
|
||
|
|
byte[] key = keyString.getBytes();
|
||
|
|
byte[] input = inputString.getBytes();
|
||
|
|
|
||
|
|
cipher.init(true, new KeyParameter(key));
|
||
|
|
|
||
|
|
byte[] cipherText = new byte[cipher.getOutputSize(input.length)];
|
||
|
|
|
||
|
|
int outputLen = cipher.processBytes(input, 0, input.length, cipherText, 0);
|
||
|
|
try
|
||
|
|
{
|
||
|
|
cipher.doFinal(cipherText, outputLen);
|
||
|
|
}
|
||
|
|
catch (CryptoException ce)
|
||
|
|
{
|
||
|
|
System.err.println(ce);
|
||
|
|
System.exit(1);
|
||
|
|
}
|
||
|
|
</code>
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<h3>4.2 Algorithms</h3>
|
||
|
|
|
||
|
|
<p>The light-weight API has built in support for the following:
|
||
|
|
|
||
|
|
<h4>Symmetric (Block)</h4>
|
||
|
|
|
||
|
|
<p>
|
||
|
|
The base interface is <b>BlockCipher</b> and has the following
|
||
|
|
implementations which match the modes the block cipher can
|
||
|
|
be operated in.
|
||
|
|
<p>
|
||
|
|
<table cellpadding=5 cellspacing=0 border=1 width=80%>
|
||
|
|
<tr><th>Name</th><th>Constructor</th><th>Notes</th></tr>
|
||
|
|
<tr><td><b>BufferedBlockCipher</b></td><td>BlockCipher</td><td> </td></tr>
|
||
|
|
<tr><td><b>CBCBlockCipher</b></td><td>BlockCipher</td><td> </td></tr>
|
||
|
|
<tr><td><b>CFBBlockCipher</b></td><td>BlockCipher, block size (in bits)</td><td> </td></tr>
|
||
|
|
<tr><td><b>CCMBlockCipher</b></td><td>BlockCipher</td><td>Packet mode - requires all data up front.</td></tr>
|
||
|
|
<tr><td><b>GCMBlockCipher</b></td><td>BlockCipher</td><td>Packet mode - NIST SP 800-38D.</td></tr>
|
||
|
|
<tr><td><b>GCFBlockCipher</b></td><td>BlockCipher</td><td>GOST CFB mode with CryptoPro key meshing.</td></tr>
|
||
|
|
<tr><td><b>EAXBlockCipher</b></td><td>BlockCipher</td><td> </td></tr>
|
||
|
|
<tr><td><b>OCBBlockCipher</b></td><td>BlockCipher</td><td> </td></tr>
|
||
|
|
<tr><td><b>OFBBlockCipher</b></td><td>BlockCipher, block size (in bits)</td><td> </td></tr>
|
||
|
|
<tr><td><b>SICBlockCipher</b></td><td>BlockCipher, block size (in bits)</td><td>Also known as CTR mode</td></tr>
|
||
|
|
<tr><td><b>OpenPGPCFBBlockCipher</b></td><td>BlockCipher</td><td> </td></tr>
|
||
|
|
<tr><td><b>GOFBBlockCipher</b></td><td>BlockCipher</td><td>GOST OFB mode</td></tr>
|
||
|
|
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<p>
|
||
|
|
The base interface for AEAD (Authenticated Encryption Associated Data) modes is <b>AEADBlockCipher</b>
|
||
|
|
and has the following implemenations.
|
||
|
|
<p>
|
||
|
|
<table cellpadding=5 cellspacing=0 border=1 width=80%>
|
||
|
|
<tr><th>Name</th><th>Constructor</th><th>Notes</th></tr>
|
||
|
|
<tr><td><b>CCMBlockCipher</b></td><td>BlockCipher</td><td>Packet mode - requires all data up front.</td></tr>
|
||
|
|
<tr><td><b>EAXBlockCipher</b></td><td>BlockCipher</td><td> </td></tr>
|
||
|
|
<tr><td><b>GCMBlockCipher</b></td><td>BlockCipher</td><td>Packet mode - NIST SP 800-38D.</td></tr>
|
||
|
|
<tr><td><b>OCBBlockCipher</b></td><td>BlockCipher</td><td> </td></tr>
|
||
|
|
</table>
|
||
|
|
</p>
|
||
|
|
|
||
|
|
<p>
|
||
|
|
<b>BufferedBlockCipher</b> has a further sub-classes
|
||
|
|
<p>
|
||
|
|
<table cellpadding=5 cellspacing=0 border=1 width=80%>
|
||
|
|
<tr><th>Name</th><th>Constructor</th><th>Notes</th></tr>
|
||
|
|
<tr><td><b>PaddedBufferedBlockCipher</b></td><td>BlockCipher</td><td>a buffered block cipher that can use padding - default PKCS5/7 padding</td></tr>
|
||
|
|
<tr><td><b>CTSBlockCipher</b></td><td>BlockCipher</td><td>Cipher Text Stealing</td></tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<p>The following paddings can be used with the PaddedBufferedBlockCipher.
|
||
|
|
<p>
|
||
|
|
<table cellpadding=5 cellspacing=0 border=1 width=80%>
|
||
|
|
<tr><th>Name</th><th>Description</th></tr>
|
||
|
|
<tr><td>PKCS7Padding</td><td>PKCS7/PKCS5 padding</td></tr>
|
||
|
|
<tr><td>ISO10126d2Padding</td><td>ISO 10126-2 padding</td></tr>
|
||
|
|
<tr><td>X932Padding</td><td>X9.23 padding</td></tr>
|
||
|
|
<tr><td>ISO7816d4Padding</td><td>ISO 7816-4 padding (ISO 9797-1 scheme 2)</td></tr>
|
||
|
|
<tr><td>ZeroBytePadding</td><td>Pad with Zeros (not recommended)</td></tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<p>The following cipher engines are implemented that can be
|
||
|
|
used with the above modes.
|
||
|
|
<p>
|
||
|
|
<table cellpadding=5 cellspacing=0 border=1 width=80%>
|
||
|
|
<tr><th>Name</th><th>KeySizes (in bits) </th><th>Block Size</th><th>Notes</th></tr>
|
||
|
|
<tr><td><b>AESEngine</b></td><td>0 .. 256 </td><td>128 bit</td><td> </td></tr>
|
||
|
|
<tr><td><b>AESWrapEngine</b></td><td>0 .. 256 </td><td>128 bit</td><td>Implements FIPS AES key wrapping</td></tr>
|
||
|
|
<tr><td><b>BlowfishEngine</b></td><td>0 .. 448 </b></td><td>64 bit</td><td> </td></tr>
|
||
|
|
<tr><td><b>CamelliaEngine</b></td><td>128, 192, 256</td><td>128 bit</td><td> </td></tr>
|
||
|
|
<tr><td><b>CamelliaWrapEngine</b></td><td>128, 192, 256</td><td>128 bit</td><td> </td></tr>
|
||
|
|
<tr><td><b>CAST5Engine</b></td><td>0 .. 128 </b></td><td>64 bit</td><td> </td></tr>
|
||
|
|
<tr><td><b>CAST6Engine</b></td><td>0 .. 256 </b></td><td>128 bit</td><td> </td></tr>
|
||
|
|
<tr><td><b>DESEngine</b></td><td>64</td><td>64 bit</td><td> </td></tr>
|
||
|
|
<tr><td><b>DESedeEngine</b></td><td>128, 192</td><td>64 bit</td><td> </td></tr>
|
||
|
|
<tr><td><b>DESedeWrapEngine</b></td><td>128, 192</td><td>64 bit</td><td>Implements Draft IETF DESede key wrapping</td></tr>
|
||
|
|
<tr><td><b>GOST28147Engine</b></td><td>256</td><td>64 bit</td><td>Has a range of S-boxes</td></tr>
|
||
|
|
<tr><td><b>IDEAEngine</b></td><td>128</td><td>64 bit</td><td> </td></tr>
|
||
|
|
<tr><td><b>NoekeonEngine</b></td><td>128</td><td>128 bit</td><td> </td></tr>
|
||
|
|
<tr><td><b>RC2Engine</b></td><td>0 .. 1024 </td><td>64 bit</td><td> </td></tr>
|
||
|
|
<tr><td><b>RC532Engine</b></td><td>0 .. 128 </td><td>64 bit</td><td>Uses a 32 bit word</td></tr>
|
||
|
|
<tr><td><b>RC564Engine</b></td><td>0 .. 128 </td><td>128 bit</td><td>Uses a 64 bit word</td></tr>
|
||
|
|
<tr><td><b>RC6Engine</b></td><td>0 .. 256 </td><td>128 bit</td><td> </td></tr>
|
||
|
|
<tr><td><b>RijndaelEngine</b></td><td>0 .. 256 </td><td>128 bit, 160 bit, 192 bit, 224 bit, 256 bit</td><td> </td></tr>
|
||
|
|
<tr><td><b>SEEDEngine</b></td><td>128</td><td>128 bit</td><td> </td></tr>
|
||
|
|
<tr><td><b>SEEDWrapEngine</b></td><td>128</td><td>128 bit</td><td> </td></tr>
|
||
|
|
<tr><td><b>SerpentEngine</b></td><td>128, 192, 256 </td><td>128 bit</td><td> </td></tr>
|
||
|
|
<tr><td><b>SkipjackEngine</b></td><td>0 .. 128 </td><td>64 bit</td><td> </td></tr>
|
||
|
|
<tr><td><b>TEAEngine</b></td><td>128</td><td>64 bit</td><td> </td></tr>
|
||
|
|
<tr><td><b>ThreefishEngine</b></td><td>256/512/1024 </td><td>256 bit/512 bit/1024 bit</td><td>Tweakable block cipher</td></tr>
|
||
|
|
<tr><td><b>TwofishEngine</b></td><td>128, 192, 256 </td><td>128 bit</td><td> </td></tr>
|
||
|
|
<tr><td><b>XTEAEngine</b></td><td>128</td><td>64 bit</td><td> </td></tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<h4>Symmetric (Stream)</h4>
|
||
|
|
|
||
|
|
<p>
|
||
|
|
The base interface is <b>StreamCipher</b> and has the following
|
||
|
|
implementations which match the modes the stream cipher can
|
||
|
|
be operated in.
|
||
|
|
|
||
|
|
<p>
|
||
|
|
<table cellpadding=5 cellspacing=0 border=1 width=80%>
|
||
|
|
<tr><th>Name</th><th>Constructor</th><th>Notes</th></tr>
|
||
|
|
<tr><td><b>BlockStreamCipher</b></td><td>BlockCipher</td><td> </td></tr>
|
||
|
|
</table>
|
||
|
|
<p>The following cipher engines are implemented that can be
|
||
|
|
used with the above modes.
|
||
|
|
<p>
|
||
|
|
|
||
|
|
<table cellpadding=5 cellspacing=0 border=1 width=80%>
|
||
|
|
<tr><th>Name</th><th>KeySizes (in bits) </th><th>Notes</th></tr>
|
||
|
|
<tr><td><b>RC4Engine</b></td><td>40 .. 2048</td><td> </td></tr>
|
||
|
|
<tr><td><b>HC128Engine</b></td><td>128</td><td> </td></tr>
|
||
|
|
<tr><td><b>HC256Engine</b></td><td>256</td><td> </td></tr>
|
||
|
|
<tr><td><b>ChaChaEngine</b></td><td>128/256</td><td>64 bit IV</td></tr>
|
||
|
|
<tr><td><b>Salsa20Engine</b></td><td>128/256</td><td>64 bit IV</td></tr>
|
||
|
|
<tr><td><b>XSalsa20Engine</b></td><td>256</td><td>192 bit IV</td></tr>
|
||
|
|
<tr><td><b>ISAACEngine</b></td><td>32 .. 8192</td><td> </td></tr>
|
||
|
|
<tr><td><b>VMPCEngine</b></td><td>8 .. 6144</td><td> </td></tr>
|
||
|
|
<tr><td><b>Grainv1Engine</b></td><td>80</td><td>64 bit IV</td></tr>
|
||
|
|
<tr><td><b>Grain128Engine</b></td><td>128</td><td>96 bit IV</td></tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<h4>Block Asymmetric</h4>
|
||
|
|
|
||
|
|
<p>
|
||
|
|
The base interface is <b>AsymmetricBlockCipher</b> and has the following
|
||
|
|
implementations which match the modes the cipher can be operated in.
|
||
|
|
|
||
|
|
<p>
|
||
|
|
<table cellpadding=5 cellspacing=0 border=1 width=80%>
|
||
|
|
<tr><th>Name</th><th>Constructor</th><th>Notes</th></tr>
|
||
|
|
<tr><td><b>BufferedAsymmetricBlockCipher</b></td><td>AsymmetricBlockCipher</td><td> </td></tr>
|
||
|
|
<tr><td><b>OAEPEncoding</b></td><td>AsymmetricBlockCipher</td><td> </td></tr>
|
||
|
|
<tr><td><b>PKCS1Encoding</b></td><td>AsymmetricBlockCipher</td><td> </td></tr>
|
||
|
|
<tr><td><b>ISO9796d1Encoding</b></td><td>AsymmetricBlockCipher</td><td>ISO9796-1</td></tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<p>The following cipher engines are implemented that can be
|
||
|
|
used with the above modes.
|
||
|
|
<p>
|
||
|
|
<table cellpadding=5 cellspacing=0 border=1 width=80%>
|
||
|
|
<tr><th>Name</th><th>KeySizes (in bits)</th><th>Notes</th></tr>
|
||
|
|
<tr><td><b>RSAEngine</b></td><td>any multiple of 8 large enough for the encoding.</td><td> </td></tr>
|
||
|
|
<tr><td><b>ElGamalEngine</b></td><td>any multiple of 8 large enough for the encoding.</td><td> </td></tr>
|
||
|
|
<tr><td><b>NTRUEngine</b></td><td>any multiple of 8 large enough for the encoding.</td><td> </td></tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<h4>Digest</h4>
|
||
|
|
|
||
|
|
<p>
|
||
|
|
The base interface is <b>Digest</b> and has the following
|
||
|
|
implementations
|
||
|
|
<p>
|
||
|
|
<table cellpadding=5 cellspacing=0 border=1 width=80%>
|
||
|
|
<tr><th>Name</th><th>Output (in bits)</th><th>Notes</th></tr>
|
||
|
|
<tr><td><b>MD2Digest</b></td><td>128</td><td> </td></tr>
|
||
|
|
<tr><td><b>MD4Digest</b></td><td>128</td><td> </td></tr>
|
||
|
|
<tr><td><b>MD5Digest</b></td><td>128</td><td> </td></tr>
|
||
|
|
<tr><td><b>RipeMD128Digest</b></td><td>128</td><td>basic RipeMD</td></tr>
|
||
|
|
<tr><td><b>RipeMD160Digest</b></td><td>160</td><td>enhanced version of RipeMD</td></tr>
|
||
|
|
<tr><td><b>RipeMD256Digest</b></td><td>256</td><td>expanded version of RipeMD128</td></tr>
|
||
|
|
<tr><td><b>RipeMD320Digest</b></td><td>320</td><td>expanded version of RipeMD160</td></tr>
|
||
|
|
<tr><td><b>SHA1Digest</b></td><td>160</td><td> </td></tr>
|
||
|
|
<tr><td><b>SHA224Digest</b></td><td>224</td><td>FIPS 180-2</td></tr>
|
||
|
|
<tr><td><b>SHA256Digest</b></td><td>256</td><td>FIPS 180-2</td></tr>
|
||
|
|
<tr><td><b>SHA384Digest</b></td><td>384</td><td>FIPS 180-2</td></tr>
|
||
|
|
<tr><td><b>SHA512Digest</b></td><td>512</td><td>FIPS 180-2</td></tr>
|
||
|
|
<tr><td><b>SHA3Digest</b></td><td>224, 256, 288, 384, 512</td><td></td></tr>
|
||
|
|
<tr><td><b>SkeinDigest</b></td><td>any byte length</td><td>256 bit, 512 bit and 1024 state sizes. Additional parameterisation using SkeinParameters.</td></tr>
|
||
|
|
<tr><td><b>SM3Digest</b></td><td>256</td><td>The SM3 Digest.</td></tr>
|
||
|
|
<tr><td><b>TigerDigest</b></td><td>192</td><td>The Tiger Digest.</td></tr>
|
||
|
|
<tr><td><b>GOST3411Digest</b></td><td>256</td><td>The GOST-3411 Digest.</td></tr>
|
||
|
|
<tr><td><b>WhirlpoolDigest</b></td><td>512</td><td>The Whirlpool Digest.</td></tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<h4>MAC</h4>
|
||
|
|
|
||
|
|
<p>
|
||
|
|
The base interface is <b>Mac</b> and has the following
|
||
|
|
implementations
|
||
|
|
<p>
|
||
|
|
<table cellpadding=5 cellspacing=0 border=1 width=80%>
|
||
|
|
<tr><th>Name</th><th>Output (in bits)</th><th>Notes</th></tr>
|
||
|
|
<tr><td><b>CBCBlockCipherMac</b></td><td>blocksize/2 unless specified</td><td> </td></tr>
|
||
|
|
<tr><td><b>CFBBlockCipherMac</b></td><td>blocksize/2, in CFB 8 mode, unless specified</td><td> </td></tr>
|
||
|
|
<tr><td><b>CMac</b></td><td>24 to 128 bits</td><td>Usable with block ciphers, NIST SP 800-38B.</td></tr>
|
||
|
|
<tr><td><b>GMac</b></td><td>96 to 128 bits</td><td>Usable with GCM mode ciphers, defined for AES, NIST SP 800-38D.</td></tr>
|
||
|
|
<tr><td><b>GOST28147Mac</b></td><td>32 bits</td><td> </td></tr>
|
||
|
|
<tr><td><b>ISO9797Alg3Mac</b></td><td>multiple of 8 bits up to underlying cipher size.</td><td> </td></tr>
|
||
|
|
<tr><td><b>HMac</b></td><td>digest length</td><td> </td></tr>
|
||
|
|
<tr><td><b>Poly1305</b></td><td>128 bits</td><td>Usable with 128 bit block ciphers. Use Poly1305KeyGenerator to generate keys.</td></tr>
|
||
|
|
<tr><td><b>SkeinMac</b></td><td>any byte length</td><td>256 bit, 512 bit and 1024 state size variants. Additional parameterisation using SkeinParameters.</td></tr>
|
||
|
|
<tr><td><b>SipHash</b></td><td>64 bits</td><td> </td></tr>
|
||
|
|
<tr><td><b>VMPCMac</b></td><td>160 bits</td><td> </td></tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<h4>PBE</h4>
|
||
|
|
|
||
|
|
<p>
|
||
|
|
The base class is <b>PBEParametersGenerator</b> and has the following
|
||
|
|
sub-classes
|
||
|
|
</p>
|
||
|
|
<table cellpadding=5 cellspacing=0 border=1 width=80%>
|
||
|
|
<tr><th>Name</th><th>Constructor</th><th>Notes</th></tr>
|
||
|
|
<tr><td><b>PKCS5S1ParametersGenerator</b></td><td>Digest</td><td> </td></tr>
|
||
|
|
<tr><td><b>PKCS5S2ParametersGenerator</b></td><td> </td><td>Uses SHA1/Hmac as defined</td></tr>
|
||
|
|
<tr><td><b>PKCS12ParametersGenerator</b></td><td>Digest</td><td> </td></tr>
|
||
|
|
<tr><td><b>OpenSSLPBEParametersGenerator</b></td><td> </td><td>Uses MD5 as defined</td></tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<h4>IESCipher</h4>
|
||
|
|
<p>
|
||
|
|
The IES cipher is based on the one described in IEEE P1363a (draft 10), for
|
||
|
|
use with either traditional Diffie-Hellman or Elliptic Curve Diffie-Hellman.
|
||
|
|
</p>
|
||
|
|
<b>Note:</b> At the moment this is still a draft, don't use it for anything
|
||
|
|
that may be subject to long term storage, the key values produced may well
|
||
|
|
change as the draft is finalised.
|
||
|
|
</p>
|
||
|
|
|
||
|
|
<h4>Commitments</h4>
|
||
|
|
<p>
|
||
|
|
The base class is <b>Committer</b> and has the following
|
||
|
|
sub-classes
|
||
|
|
</p>
|
||
|
|
<table cellpadding=5 cellspacing=0 border=1 width=80%>
|
||
|
|
<tr><th>Name</th><th>Notes</th></tr>
|
||
|
|
<tr><td><b>HashCommitter</b></td><td>Hash commitment algorithm described in Usenix RPC MixNet Paper (2002)</td></tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<h4>Key Agreement</h4>
|
||
|
|
<p>
|
||
|
|
Two versions of Diffie-Hellman key agreement are supported, the basic
|
||
|
|
version, and one for use with long term public keys. Two versions of
|
||
|
|
key agreement using Elliptic Curve cryptography are also supported,
|
||
|
|
standard Diffie-Hellman key agreement and standard key agreement with
|
||
|
|
co-factors.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
The agreement APIs are in the <b>org.bouncycastle.crypto.agreement</b> package.
|
||
|
|
Classes for generating Diffie-Hellman parameters can be found in the
|
||
|
|
<b>org.bouncycastle.crypto.params</b> and <b>org.bouncycastle.crypto.generators</b> packages.
|
||
|
|
</p>
|
||
|
|
|
||
|
|
<h4>Key Encapsulation Mechanisms</h4>
|
||
|
|
<p>
|
||
|
|
The base class is <b>KeyEncapsulation</b> and has the following
|
||
|
|
sub-classes
|
||
|
|
</p>
|
||
|
|
<table cellpadding=5 cellspacing=0 border=1 width=80%>
|
||
|
|
<tr><th>Name</th><th>Notes</th></tr>
|
||
|
|
<tr><td><b>RSAKeyEncapsulation</b></td><td>RSA-KEM from ISO 18033-2</td></tr>
|
||
|
|
<tr><td><b>PKCS5S2ParametersGenerator</b></td><td>ECIES-KEM from ISO 18033-2</td></tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<h4>Signers</h4>
|
||
|
|
<p>
|
||
|
|
DSA, ECDSA, ISO-9796-2, GOST-3410-94, GOST-3410-2001, DSTU-4145-2002, and RSA-PSS are supported by the <b>org.bouncycastle.crypto.signers</b>
|
||
|
|
package. Note: as these are light weight classes, if you need to use SHA1 or GOST-3411
|
||
|
|
(as defined in the relevant standards) you'll also need to make use of the appropriate
|
||
|
|
digest class in conjunction with these.
|
||
|
|
Classes for generating DSA and ECDSA parameters can be found in the
|
||
|
|
<b>org.bouncycastle.crypto.params</b> and <b>org.bouncycastle.crypto.generators</b> packages.
|
||
|
|
<p>
|
||
|
|
|
||
|
|
<h3>4.4 Elliptic Curve Transforms.</h3>
|
||
|
|
|
||
|
|
<p>
|
||
|
|
The org.bouncycastle.crypto.ec package contains implementations for a variety of EC cryptographic transforms such as EC ElGamal.
|
||
|
|
</p>
|
||
|
|
|
||
|
|
<h3>4.4 TLS/DTLS</h3>
|
||
|
|
|
||
|
|
<p>
|
||
|
|
The org.bouncycastle.crypto.tls package contains implementations for TLS 1.1 and DTLS 1.0.
|
||
|
|
</p>
|
||
|
|
|
||
|
|
<h3>4.5 Deterministic Random Bit Generators (DRBG) and SecureRandom wrappers</h3>
|
||
|
|
|
||
|
|
<p>
|
||
|
|
The org.bouncycastle.crypto.prng package contains implementations for a variety of bit generators including those
|
||
|
|
from SP 800-90A, as well as builders for SecureRandom objects based around them.
|
||
|
|
</p>
|
||
|
|
<h3>4.6 ASN.1 package</h3>
|
||
|
|
|
||
|
|
<p>The light-weight API has direct interfaces into a package capable of
|
||
|
|
reading and writing DER-encoded ASN.1 objects and for the generation
|
||
|
|
of X.509 V3 certificate objects and PKCS12 files. BER InputStream and
|
||
|
|
OutputStream classes are provided as well.
|
||
|
|
|
||
|
|
<h2>5.0 Bouncy Castle Provider</h2>
|
||
|
|
|
||
|
|
<p>The Bouncy Castle provider is a JCE compliant provider that
|
||
|
|
is a wrapper built on top of the light-weight API.</p>
|
||
|
|
|
||
|
|
<p>
|
||
|
|
The advantage for writing application code that uses the
|
||
|
|
provider interface to cryptographic algorithms is that the
|
||
|
|
actual provider used can be selected at run time. This
|
||
|
|
is extremely valuable for applications that may wish to
|
||
|
|
make use of a provider that has underlying hardware for
|
||
|
|
cryptographic computation, or where an application may have
|
||
|
|
been developed in an environment with cryptographic export
|
||
|
|
controls.
|
||
|
|
</p>
|
||
|
|
|
||
|
|
<h3>5.1 Example</h3>
|
||
|
|
|
||
|
|
<p>To utilise the JCE provider in a program, the fundamentals
|
||
|
|
are as follows;
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
<code>
|
||
|
|
/*
|
||
|
|
* This will generate a random key, and encrypt the data
|
||
|
|
*/
|
||
|
|
Key key;
|
||
|
|
KeyGenerator keyGen;
|
||
|
|
Cipher encrypt;
|
||
|
|
|
||
|
|
Security.addProvider(new BouncyCastleProvider());
|
||
|
|
|
||
|
|
try
|
||
|
|
{
|
||
|
|
// "BC" is the name of the BouncyCastle provider
|
||
|
|
keyGen = KeyGenerator.getInstance("DES", "BC");
|
||
|
|
keyGen.init(new SecureRandom());
|
||
|
|
|
||
|
|
key = keyGen.generateKey();
|
||
|
|
|
||
|
|
encrypt = Cipher.getInstance("DES/CBC/PKCS5Padding", "BC");
|
||
|
|
}
|
||
|
|
catch (Exception e)
|
||
|
|
{
|
||
|
|
System.err.println(e);
|
||
|
|
System.exit(1);
|
||
|
|
}
|
||
|
|
|
||
|
|
encrypt.init(Cipher.ENCRYPT_MODE, key);
|
||
|
|
|
||
|
|
bOut = new ByteArrayOutputStream();
|
||
|
|
cOut = new CipherOutputStream(bOut, encrypt);
|
||
|
|
|
||
|
|
cOut.write("plaintext".getBytes());
|
||
|
|
cOut.close();
|
||
|
|
|
||
|
|
// bOut now contains the cipher text
|
||
|
|
</code>
|
||
|
|
</pre>
|
||
|
|
<p>
|
||
|
|
The provider can also be configured as part of your environment via static registration
|
||
|
|
by adding an entry to the java.security properties file (found in $JAVA_HOME/jre/lib/security/java.security, where $JAVA_HOME is the location of your JDK/JRE distribution). You'll find detailed
|
||
|
|
instructions in the file but basically it comes down to adding a line:
|
||
|
|
<pre>
|
||
|
|
<code>
|
||
|
|
security.provider.<n>=org.bouncycastle.jce.provider.BouncyCastleProvider
|
||
|
|
</code>
|
||
|
|
</pre>
|
||
|
|
<p>Where <n> is the preference you want the provider at (1 being the most prefered).
|
||
|
|
<p>Where you put the jar is up to mostly up to you, although with jdk1.3 and
|
||
|
|
jdk1.4 the best (and in some cases only) place to have it is in $JAVA_HOME/jre/lib/ext. Note: under Windows there will normally be a JRE and a JDK install of Java if you think you have installed it correctly and it still doesn't work chances are you have added the provider to the installation not being used.
|
||
|
|
<p>
|
||
|
|
<b>Note</b>: with JDK 1.4 and later you will need to have installed the unrestricted policy
|
||
|
|
files to take full advantage of the provider. If you do not install the policy files you are likely
|
||
|
|
to get something like the following:
|
||
|
|
<b>
|
||
|
|
<pre>
|
||
|
|
java.lang.SecurityException: Unsupported keysize or algorithm parameters
|
||
|
|
at javax.crypto.Cipher.init(DashoA6275)
|
||
|
|
</pre>
|
||
|
|
</b>
|
||
|
|
The policy files can be found at the same place you downloaded the JDK.
|
||
|
|
<p>
|
||
|
|
<h3>5.2 Algorithms</h3>
|
||
|
|
|
||
|
|
<h4>Symmetric (Block)</h4>
|
||
|
|
|
||
|
|
<p>Modes:
|
||
|
|
<ul>
|
||
|
|
<li>ECB
|
||
|
|
<li>CBC
|
||
|
|
<li>OFB(n)
|
||
|
|
<li>CFB(n)
|
||
|
|
<li>SIC (also known as CTR)
|
||
|
|
<li>OpenPGPCFB
|
||
|
|
<li>CTS (equivalent to CBC/WithCTS)
|
||
|
|
<li>GOFB
|
||
|
|
<li>GCFB
|
||
|
|
<li>CCM (AEAD)
|
||
|
|
<li>EAX (AEAD)
|
||
|
|
<li>GCM (AEAD)
|
||
|
|
<li>OCB (AEAD)
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>
|
||
|
|
Where <i>(n)</i> is a multiple of 8 that gives the blocksize in bits,
|
||
|
|
eg, OFB8. Note that OFB and CFB mode can be used with plain text that
|
||
|
|
is not an exact multiple of the block size if NoPadding has been specified.
|
||
|
|
<p>
|
||
|
|
All <i>AEAD</i> (Authenticated Encryption Associated Data) modes support
|
||
|
|
Additional Authentication Data (AAD) using the <code>Cipher.updateAAD()</code>
|
||
|
|
methods added in Java SE 7.
|
||
|
|
<p>
|
||
|
|
|
||
|
|
|
||
|
|
Padding Schemes:
|
||
|
|
<ul>
|
||
|
|
<li>No padding
|
||
|
|
<li>PKCS5/7
|
||
|
|
<li>ISO10126/ISO10126-2
|
||
|
|
<li>ISO7816-4/ISO9797-1
|
||
|
|
<li>X9.23/X923
|
||
|
|
<li>TBC
|
||
|
|
<li>ZeroByte
|
||
|
|
<li>withCTS (if used with ECB mode)
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>
|
||
|
|
When placed together this gives a specification for an algorithm
|
||
|
|
as;
|
||
|
|
<ul>
|
||
|
|
<li>DES/CBC/X9.23Padding
|
||
|
|
<li>DES/OFB8/NoPadding
|
||
|
|
<li>IDEA/CBC/ISO10126Padding
|
||
|
|
<li>IDEA/CBC/ISO7816-4Padding
|
||
|
|
<li>SKIPJACK/ECB/PKCS7Padding
|
||
|
|
<li>DES/ECB/WithCTS
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>
|
||
|
|
Note: default key sizes are in bold.
|
||
|
|
<p>
|
||
|
|
<table cellpadding=5 cellspacing=0 border=1 width=80%>
|
||
|
|
<tr><th>Name</th><th>KeySizes (in bits) </th><th>Block Size</th><th>Notes</th></tr>
|
||
|
|
<tr><td>AES</td><td>0 .. 256 <b>(192)</b></td><td>128 bit</td><td> </td></tr>
|
||
|
|
<tr><td>AESWrap</td><td>0 .. 256 <b>(192)</b></td><td>128 bit</td><td>A FIPS AES key wrapper</td></tr>
|
||
|
|
<tr><td>Blowfish</td><td>0 .. 448 <b>(448)</b></td><td>64 bit</td><td> </td></tr>
|
||
|
|
<tr><td>Camellia</td><td>128, 192, 256</td><td>128 bit</td><td> </td></tr>
|
||
|
|
<tr><td>CamelliaWrap</td><td>128, 192, 256</td><td>128 bit</td><td> </td></tr>
|
||
|
|
<tr><td>CAST5</td><td>0 .. 128<b>(128)</b></td><td>64 bit</td><td> </td></tr>
|
||
|
|
<tr><td>CAST6</td><td>0 .. 256<b>(256)</b></td><td>128 bit</td><td> </td></tr>
|
||
|
|
<tr><td>DES</td><td>64</td><td>64 bit</td><td> </td></tr>
|
||
|
|
<tr><td>DESede</td><td>128, 192</td><td>64 bit</td><td> </td></tr>
|
||
|
|
<tr><td>DESedeWrap</td><td>128, 192</td><td>128 bit</td><td>A Draft IETF DESede key wrapper</td></tr>
|
||
|
|
<tr><td>GCM</td><td>128, 192, 256<b>(192)</b></td><td>AEAD Mode Cipher</td><td>Galois/Counter Mode, as defined in NIST Special Publication SP 800-38D.</td></tr>
|
||
|
|
<tr><td>GOST28147</td><td>256</td><td>64 bit</td><td> </td></tr>
|
||
|
|
<tr><td>IDEA</td><td>128 <b>(128)</b></td><td>64 bit</td><td> </td></tr>
|
||
|
|
<tr><td>Noekeon</td><td>128<b>(128)</b></td><td>128 bit</td><td> </td></tr>
|
||
|
|
<tr><td>RC2</td><td>0 .. 1024 <b>(128)</b></td><td>64 bit</td><td> </td></tr>
|
||
|
|
<tr><td>RC5</td><td>0 .. 128 <b>(128)</b></td><td>64 bit</td><td>Uses a 32 bit word</td></tr>
|
||
|
|
<tr><td>RC5-64</td><td>0 .. 256 <b>(256)</b></td><td>128 bit</td><td>Uses a 64 bit word</td></tr>
|
||
|
|
<tr><td>RC6</td><td>0 .. 256 <b>(128)</b></td><td>128 bit</td><td> </td></tr>
|
||
|
|
<tr><td>Rijndael</td><td>0 .. 256 <b>(192)</b></td><td>128 bit</td><td> </td></tr>
|
||
|
|
<tr><td>SEED</td><td>128<b>(128)</b></td><td>128 bit</td><td> </td></tr>
|
||
|
|
<tr><td>SEEDWrap</td><td>128<b>(128)</b></td><td>128 bit</td><td> </td></tr>
|
||
|
|
<tr><td>Serpent</td><td>128, 192, 256 <b>(256)</b></td><td>128 bit</td><td> </td></tr>
|
||
|
|
<tr><td>Skipjack</td><td>0 .. 128 <b>(128)</b></td><td>64 bit</td><td> </td></tr>
|
||
|
|
<tr><td>TEA</td><td>128 <b>(128)</b></td><td>64 bit</td><td> </td></tr>
|
||
|
|
<tr><td>Threefish-256</td><td>256</td><td>256 bit</td><td> </td></tr>
|
||
|
|
<tr><td>Threefish-512</td><td>512</td><td>512 bit</td><td> </td></tr>
|
||
|
|
<tr><td>Threefish-1024</td><td>1024</td><td>1024 bit</td><td> </td></tr>
|
||
|
|
<tr><td>Twofish</td><td>128, 192, 256 <b>(256)</b></td><td>128 bit</td><td> </td></tr>
|
||
|
|
<tr><td>XTEA</td><td>128 <b>(128)</b></td><td>64 bit</td><td> </td></tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<h4>Symmetric (Stream)</h4>
|
||
|
|
|
||
|
|
<p>
|
||
|
|
Note: default key sizes are in bold.
|
||
|
|
<p>
|
||
|
|
<table cellpadding=5 cellspacing=0 border=1 width=80%>
|
||
|
|
<tr><th>Name</th><th>KeySizes (in bits)</th><th>Notes</th></tr>
|
||
|
|
<tr><td>RC4</td><td>40 .. 2048 bits <b>(128)</b></td><td> </td></tr>
|
||
|
|
<tr><td>HC128</td><td>(128)</td><td> </td></tr>
|
||
|
|
<tr><td>HC256</td><td>(256)</td><td> </td></tr>
|
||
|
|
<tr><td>ChaCha</td><td><b>128</b>/256</td><td>64 bit IV</td></tr>
|
||
|
|
<tr><td>Salsa20</td><td><b>128</b>/256</td><td>64 bit IV</td></tr>
|
||
|
|
<tr><td>XSalsa20</td><td>256</td><td>182 bit IV</td></tr>
|
||
|
|
<tr><td>VMPC</td><td>128/6144<b>(128)</b></td><td> </td></tr>
|
||
|
|
<tr><td>Grainv1</b></td><td>80</td><td>64 bit IV</td></tr>
|
||
|
|
<tr><td>Grain128</b></td><td>128</td><td>96 bit IV</td></tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<h4>Block Asymmetric</h4>
|
||
|
|
|
||
|
|
<p>Encoding:
|
||
|
|
<ul>
|
||
|
|
<li>OAEP - Optimal Asymmetric Encryption Padding
|
||
|
|
<li>PCKS1 - PKCS v1.5 Padding
|
||
|
|
<li>ISO9796-1 - ISO9796-1 edition 1 Padding
|
||
|
|
</ul>
|
||
|
|
<p>Note: except as indicated in PKCS 1v2 we recommend you use OAEP, as
|
||
|
|
mandated in X9.44.
|
||
|
|
|
||
|
|
<p>
|
||
|
|
When placed together with RSA this gives a specification for an algorithm
|
||
|
|
as;
|
||
|
|
<ul>
|
||
|
|
<li>RSA/NONE/NoPadding
|
||
|
|
<li>RSA/NONE/PKCS1Padding
|
||
|
|
<li>RSA/NONE/OAEPWithMD5AndMGF1Padding
|
||
|
|
<li>RSA/NONE/OAEPWithSHA1AndMGF1Padding
|
||
|
|
<li>RSA/NONE/OAEPWithSHA224AndMGF1Padding
|
||
|
|
<li>RSA/NONE/OAEPWithSHA256AndMGF1Padding
|
||
|
|
<li>RSA/NONE/OAEPWithSHA384AndMGF1Padding
|
||
|
|
<li>RSA/NONE/OAEPWithSHA512AndMGF1Padding
|
||
|
|
<li>RSA/NONE/ISO9796-1Padding
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<table cellpadding=5 cellspacing=0 border=1 width=80%>
|
||
|
|
<tr><th>Name</th><th>KeySizes (in bits)</th><th>Notes</th></tr>
|
||
|
|
<tr><td>RSA</td><td>any multiple of 8 bits large enough for the encryption<b>(2048)</b></td><td> </td></tr>
|
||
|
|
<tr><td>ElGamal</td><td>any multiple of 8 bits large enough for the encryption<b>(1024)</b></td><td> </td></tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<h4>Key Agreement</h4>
|
||
|
|
|
||
|
|
<p>
|
||
|
|
Diffie-Hellman key agreement is supported using the "DH", "ECDH", and
|
||
|
|
"ECDHC" (ECDH with cofactors) key agreement instances.
|
||
|
|
<p>
|
||
|
|
Note: with basic "DH" only the basic algorithm fits in with the JCE API, if
|
||
|
|
you're using long-term public keys you may want to look at the light-weight
|
||
|
|
API.
|
||
|
|
<p>
|
||
|
|
<h4>ECIES</h4>
|
||
|
|
<p>
|
||
|
|
An implementation of ECIES (stream mode) as described in IEEE P 1363a.
|
||
|
|
<p>
|
||
|
|
<b>Note:</b> At the moment this is still a draft, don't use it for anything
|
||
|
|
that may be subject to long term storage, the key values produced may well
|
||
|
|
change as the draft is finalised.
|
||
|
|
<p>
|
||
|
|
<h4>Digest</h4>
|
||
|
|
<p>
|
||
|
|
<table cellpadding=5 cellspacing=0 border=1 width=80%>
|
||
|
|
<tr><th>Name</th><th>Output (in bits)</th><th>Notes</th></tr>
|
||
|
|
<tr><td>GOST3411</td><td>256</td><td> </td></tr>
|
||
|
|
<tr><td>MD2</td><td>128</td><td> </td></tr>
|
||
|
|
<tr><td>MD4</td><td>128</td><td> </td></tr>
|
||
|
|
<tr><td>MD5</td><td>128</td><td> </td></tr>
|
||
|
|
<tr><td>RipeMD128</td><td>128</td><td>basic RipeMD</td></tr>
|
||
|
|
<tr><td>RipeMD160</td><td>160</td><td>enhanced version of RipeMD</td></tr>
|
||
|
|
<tr><td>RipeMD256</td><td>256</td><td>expanded version of RipeMD128</td></tr>
|
||
|
|
<tr><td>RipeMD320</td><td>320</td><td>expanded version of RipeMD160</td></tr>
|
||
|
|
<tr><td>SHA1</td><td>160</td><td> </td></tr>
|
||
|
|
<tr><td>SHA-224</td><td>224</td><td>FIPS 180-2</td></tr>
|
||
|
|
<tr><td>SHA-256</td><td>256</td><td>FIPS 180-2</td></tr>
|
||
|
|
<tr><td>SHA-384</td><td>384</td><td>FIPS 180-2</td></tr>
|
||
|
|
<tr><td>SHA-512</td><td>512</td><td>FIPS 180-2</td></tr>
|
||
|
|
<tr><td>SHA3-224</td><td>224</td><td> </td></tr>
|
||
|
|
<tr><td>SHA3-256</td><td>256</td><td> </td></tr>
|
||
|
|
<tr><td>SHA3-384</td><td>384</td><td> </td></tr>
|
||
|
|
<tr><td>SHA3-512</td><td>512</td><td> </td></tr>
|
||
|
|
<tr><td>Skein-256-*</td><td>128, 160, 224, 256</td><td>e.g. Skein-256-160</td></tr>
|
||
|
|
<tr><td>Skein-512-*</td><td>128, 160, 224, 256, 384, 512</td><td>e.g. Skein-512-256</td></tr>
|
||
|
|
<tr><td>Skein-1024-*</td><td>384, 512, 1024</td><td>e.g. Skein-1024-1024</td></tr>
|
||
|
|
<tr><td>Tiger</td><td>192</td><td> </td></tr>
|
||
|
|
<tr><td>Whirlpool</td><td>512</td><td> </td></tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<h4>MAC</h4>
|
||
|
|
|
||
|
|
<table cellpadding=5 cellspacing=0 border=1 width=80%>
|
||
|
|
<tr><th>Name</th><th>Output (in bits)</th><th>Notes</th></tr>
|
||
|
|
<tr><td>Any MAC based on a block cipher, CBC (the default) and CFB modes.</td><td>half the cipher's block size (usually 32 bits)</td><td> </td></tr>
|
||
|
|
<tr><td>*-GMAC</td><td>96 to 128 bits</td><td>Usable with GCM mode ciphers, defined for AES, NIST SP 800-38D. e.g. AES-GMAC.</td></tr>
|
||
|
|
<tr><td>VMPC-MAC</td><td>128</td><td> </td></tr>
|
||
|
|
<tr><td>HMac-MD2</td><td>128</td><td> </td></tr>
|
||
|
|
<tr><td>HMac-MD4</td><td>128</td><td> </td></tr>
|
||
|
|
<tr><td>HMac-MD5</td><td>128</td><td> </td></tr>
|
||
|
|
<tr><td>HMac-RipeMD128</td><td>128</td><td> </td></tr>
|
||
|
|
<tr><td>HMac-RipeMD160</td><td>160</td><td> </td></tr>
|
||
|
|
<tr><td>HMac-SHA1</td><td>160</td><td> </td></tr>
|
||
|
|
<tr><td>HMac-SHA224</td><td>224</td><td> </td></tr>
|
||
|
|
<tr><td>HMac-SHA256</td><td>256</td><td> </td></tr>
|
||
|
|
<tr><td>HMac-SHA384</td><td>384</td><td> </td></tr>
|
||
|
|
<tr><td>HMac-SHA512</td><td>512</td><td> </td></tr>
|
||
|
|
<tr><td>HMac-SHA3-224</td><td>224</td><td> </td></tr>
|
||
|
|
<tr><td>HMac-SHA3-256</td><td>256</td><td> </td></tr>
|
||
|
|
<tr><td>HMac-SHA3-384</td><td>384</td><td> </td></tr>
|
||
|
|
<tr><td>HMac-SHA3-512</td><td>512</td><td> </td></tr>
|
||
|
|
<tr><td>HMAC-Skein-256-*</td><td>128, 160, 224, 256</td><td>e.g. HMAC-Skein-256-160</td></tr>
|
||
|
|
<tr><td>HMAC-Skein-512-*</td><td>128, 160, 224, 256, 384, 512</td><td>e.g. HMAC-Skein-512-256</td></tr>
|
||
|
|
<tr><td>HMAC-Skein-1024-*</td><td>384, 512, 1024</td><td>e.g. HMAC-Skein-1024-1024</td></tr>
|
||
|
|
<tr><td>Skein-MAC-256-*</td><td>128, 160, 224, 256</td><td>e.g. Skein-MAC-256-160</td></tr>
|
||
|
|
<tr><td>Skein-MAC-512-*</td><td>128, 160, 224, 256, 384, 512</td><td>e.g. Skein-MAC-512-256</td></tr>
|
||
|
|
<tr><td>Skein-MAC-1024-*</td><td>384, 512, 1024</td><td>e.g. Skein-MAC-1024-1024</td></tr>
|
||
|
|
<tr><td>HMac-Tiger</td><td>192</td><td> </td></tr>
|
||
|
|
<tr><td>Poly1305-*</td><td>128</td><td>Defined for recent 128 bit block ciphers, e.g. Poly1305-AES, Poly1305-Serpent</td></tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<p>Examples:
|
||
|
|
<ul>
|
||
|
|
<li>DESMac
|
||
|
|
<li>DESMac/CFB8
|
||
|
|
<li>DESedeMac
|
||
|
|
<li>DESedeMac/CFB8
|
||
|
|
<li>DESedeMac64
|
||
|
|
<li>SKIPJACKMac
|
||
|
|
<li>SKIPJACKMac/CFB8
|
||
|
|
<li>IDEAMac
|
||
|
|
<li>IDEAMac/CFB8
|
||
|
|
<li>RC2Mac
|
||
|
|
<li>RC2Mac/CFB8
|
||
|
|
<li>RC5Mac
|
||
|
|
<li>RC5Mac/CFB8
|
||
|
|
<li>ISO9797ALG3Mac
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
|
||
|
|
<h4>Signature Algorithms</h4>
|
||
|
|
|
||
|
|
<p>Schemes:
|
||
|
|
<ul>
|
||
|
|
<li>DSTU4145</li>
|
||
|
|
<li>GOST3411withGOST3410 (GOST3411withGOST3410-94)
|
||
|
|
<li>GOST3411withECGOST3410 (GOST3411withGOST3410-2001)
|
||
|
|
<li>MD2withRSA
|
||
|
|
<li>MD5withRSA
|
||
|
|
<li>SHA1withRSA
|
||
|
|
<li>RIPEMD128withRSA
|
||
|
|
<li>RIPEMD160withRSA
|
||
|
|
<li>RIPEMD160withECDSA
|
||
|
|
<li>RIPEMD256withRSA
|
||
|
|
<li>SHA1withDSA
|
||
|
|
<li>SHA224withDSA
|
||
|
|
<li>SHA256withDSA
|
||
|
|
<li>SHA384withDSA
|
||
|
|
<li>SHA512withDSA
|
||
|
|
<li>SHA1withDetDSA
|
||
|
|
<li>SHA224withDetDSA
|
||
|
|
<li>SHA256withDetDSA
|
||
|
|
<li>SHA384withDetDSA
|
||
|
|
<li>SHA512withDetDSA
|
||
|
|
<li>NONEwithDSA
|
||
|
|
<li>SHA1withDetECDSA
|
||
|
|
<li>SHA224withDetECDSA
|
||
|
|
<li>SHA256withDetECDSA
|
||
|
|
<li>SHA384withDetECDSA
|
||
|
|
<li>SHA512withDetECDSA
|
||
|
|
<li>SHA1withECDSA
|
||
|
|
<li>NONEwithECDSA
|
||
|
|
<li>SHA224withECDSA
|
||
|
|
<li>SHA256withECDSA
|
||
|
|
<li>SHA384withECDSA
|
||
|
|
<li>SHA512withECDSA
|
||
|
|
<li>SHA1withECNR
|
||
|
|
<li>SHA224withECNR
|
||
|
|
<li>SHA256withECNR
|
||
|
|
<li>SHA384withECNR
|
||
|
|
<li>SHA512withECNR
|
||
|
|
<li>SHA224withRSA
|
||
|
|
<li>SHA256withRSA
|
||
|
|
<li>SHA384withRSA
|
||
|
|
<li>SHA512withRSA
|
||
|
|
<li>SHA1withRSAandMGF1
|
||
|
|
<li>SHA256withRSAandMGF1
|
||
|
|
<li>SHA384withRSAandMGF1
|
||
|
|
<li>SHA512withRSAandMGF1
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<h4>PBE</h4>
|
||
|
|
|
||
|
|
<p>Schemes:
|
||
|
|
<ul>
|
||
|
|
<li>PKCS5S1, any Digest, any symmetric Cipher, ASCII
|
||
|
|
<li>PKCS5S2, SHA1/HMac, any symmetric Cipher, ASCII, UTF8
|
||
|
|
<li>PKCS12, any Digest, any symmetric Cipher, Unicode
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>
|
||
|
|
Defined in Bouncy Castle JCE Provider
|
||
|
|
<table cellpadding=5 cellspacing=0 border=1 width=80%>
|
||
|
|
<tr><th>Name</th><th>Key Generation Scheme</th><th>Key Length (in bits)</th><th>Char to Byte conversion</th></tr>
|
||
|
|
<tr><td>PBEWithMD2AndDES</td><td>PKCS5 Scheme 1</td><td>64</td><td>8 bit chars</td></tr>
|
||
|
|
<tr><td>PBEWithMD2AndRC2</td><td>PKCS5 Scheme 1</td><td>128</td><td>8 bit chars</td></tr>
|
||
|
|
<tr><td>PBEWithMD5AndDES</td><td>PKCS5 Scheme 1</td><td>64</td><td>8 bit chars</td></tr>
|
||
|
|
<tr><td>PBEWithMD5AndRC2</td><td>PKCS5 Scheme 1</td><td>128</td><td>8 bit chars</td></tr>
|
||
|
|
<tr><td>PBEWithSHA1AndDES</td><td>PKCS5 Scheme 1</td><td>64</td><td>8 bit chars</td></tr>
|
||
|
|
<tr><td>PBEWithSHA1AndRC2</td><td>PKCS5 Scheme 1</td><td>128</td><td>8 bit chars</td></tr>
|
||
|
|
<tr><td>PBKDF2WithHmacSHA1</td><td>PKCS5 Scheme 2</td><td>variable</td><td>UTF-8 chars</td></tr>
|
||
|
|
<tr><td>PBKDF2WithHmacSHA1AndUTF8</td><td>PKCS5 Scheme 2</td><td>variable</td><td>UTF-8 chars</td></tr>
|
||
|
|
<tr><td>PBKDF2WithHmacSHA1And8bit</td><td>PKCS5 Scheme 2</td><td>variable</td><td>8 bit chars</td></tr>
|
||
|
|
<tr><td>PBEWithSHAAnd2-KeyTripleDES-CBC</td><td>PKCS12</td><td>128</td><td>16 bit chars</td></tr>
|
||
|
|
<tr><td>PBEWithSHAAnd3-KeyTripleDES-CBC</td><td>PKCS12</td><td>192</td><td>16 bit chars</td></tr>
|
||
|
|
<tr><td>PBEWithSHAAnd128BitRC2-CBC</td><td>PKCS12</td><td>128</td><td>16 bit chars</td></tr>
|
||
|
|
<tr><td>PBEWithSHAAnd40BitRC2-CBC</td><td>PKCS12</td><td>40</td><td>16 bit chars</td></tr>
|
||
|
|
<tr><td>PBEWithSHAAnd128BitRC4</td><td>PKCS12</td><td>128</td><td>16 bit chars</td></tr>
|
||
|
|
<tr><td>PBEWithSHAAnd40BitRC4</td><td>PKCS12</td><td>40</td><td>16 bit chars</td></tr>
|
||
|
|
<tr><td>PBEWithSHAAndTwofish-CBC</td><td>PKCS12</td><td>256</td><td>16 bit chars</td></tr>
|
||
|
|
<tr><td>PBEWithSHAAndIDEA-CBC</td><td>PKCS12</td><td>128</td><td>16 bit chars</td></tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<h3>5.3 Certificates</h3>
|
||
|
|
<p>
|
||
|
|
The Bouncy Castle provider will read X.509 certficates (v2 or v3) as per the examples in
|
||
|
|
the java.security.cert.CertificateFactory class. They can be provided either
|
||
|
|
in the normal PEM encoded format, or as DER binaries.
|
||
|
|
<p>
|
||
|
|
The CertificateFactory will also read X.509 CRLs (v2) from either PEM or DER encodings.
|
||
|
|
<p>
|
||
|
|
In addition to the classes in the org.bouncycastle.asn1.x509 package for certificate, CRLs, and OCSP, CRMF, and CMP message
|
||
|
|
generation a more JCE "friendly" class is provided in the package org.bouncycastle.cert. The JCE "friendly" classes found in the jcajce
|
||
|
|
subpackages support RSA, DSA, GOST, DTSU, and EC-DSA.
|
||
|
|
<p>
|
||
|
|
<h3>5.4 Keystore</h3>
|
||
|
|
<p>
|
||
|
|
The Bouncy Castle package has three implementation of a keystore.
|
||
|
|
<p>
|
||
|
|
The first "BKS" is a keystore that will work with the keytool in the same
|
||
|
|
fashion as the Sun "JKS" keystore. The keystore is resistent to tampering
|
||
|
|
but not inspection.
|
||
|
|
<p>
|
||
|
|
The second, <b>Keystore.BouncyCastle</b>, or <b>Keystore.UBER</b> will only work with the keytool
|
||
|
|
if the password is provided on the command line, as the entire keystore
|
||
|
|
is encrypted
|
||
|
|
with a PBE based on SHA1 and Twofish. <b>PBEWithSHAAndTwofish-CBC</b>.
|
||
|
|
This makes the entire keystore resistant to tampering and inspection,
|
||
|
|
and forces verification.
|
||
|
|
The Sun JDK provided keytool will attempt to load a keystore even if no
|
||
|
|
password is given,
|
||
|
|
this is impossible for this version. (One might wonder about going to all
|
||
|
|
this trouble and then having the password on the command line! New keytool
|
||
|
|
anyone?).
|
||
|
|
<p>
|
||
|
|
In the first case, the keys are encrypted with 3-Key-TripleDES.
|
||
|
|
<p>
|
||
|
|
The third is a PKCS12 compatible keystore. PKCS12 provides a slightly
|
||
|
|
different situation from the regular key store, the keystore password is
|
||
|
|
currently the only password used for storing keys. Otherwise it supports
|
||
|
|
all the functionality required for it to be used with the keytool. In some
|
||
|
|
situations other libraries always expect to be dealing with Sun certificates,
|
||
|
|
if this is the case use PKCS12-DEF, and the certificates produced by the
|
||
|
|
key store will be made using the default provider. In the default case PKCS12 uses 3DES for key protection and 40 bit RC2 for protecting the certificates. It is also possible to use 3DES for both by using PKCS12-3DES-3DES or PKCS12-DEF-3DES-3DES as the KeyStore type.
|
||
|
|
<p>
|
||
|
|
There is an example program that produces PKCS12 files suitable for
|
||
|
|
loading into browsers. It is in the package
|
||
|
|
org.bouncycastle.jce.examples.
|
||
|
|
<p>
|
||
|
|
<p>
|
||
|
|
<h3>5.5 Additional support classes for Elliptic Curve.</h3>
|
||
|
|
<p>
|
||
|
|
There are no classes for supporting EC in the JDK prior to JDK 1.5. If you are using
|
||
|
|
an earlier JDK you can find classes for using EC in the following
|
||
|
|
packages:
|
||
|
|
<ul>
|
||
|
|
<li>org.bouncycastle.jce.spec</li>
|
||
|
|
<li>org.bouncycastle.jce.interfaces</li>
|
||
|
|
<li>org.bouncycastle.jce</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<h3>6.0 BouncyCastle S/MIME</h3>
|
||
|
|
|
||
|
|
To be able to fully compile and utilise the BouncyCastle S/MIME
|
||
|
|
package (including the test classes) you need the jar files for
|
||
|
|
the following APIs.
|
||
|
|
<ul>
|
||
|
|
<li>Junit - <a href="http://www.junit.org">http://www.junit.org</a></li>
|
||
|
|
<li>JavaMail - <a href="http://java.sun.com/products/javamail/index.html">http://java.sun.com/products/javamail/index.html</a></li>
|
||
|
|
<li>The Java Activation Framework - <a href="http://java.sun.com/products/javabeans/glasgow/jaf.html">http://java.sun.com/products/javabeans/glasgow/jaf.html</a></li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<h3>6.1 Setting up BouncyCastle S/MIME in JavaMail</h3>
|
||
|
|
|
||
|
|
The BouncyCastle S/MIME handlers may be set in JavaMail two ways.
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li> STATICALLY<br>
|
||
|
|
|
||
|
|
Add the following entries to the mailcap file:
|
||
|
|
<pre>
|
||
|
|
application/pkcs7-signature;; x-java-content-handler=org.bouncycastle.mail.smime.handlers.pkcs7_signature
|
||
|
|
application/pkcs7-mime;; x-java-content-handler=org.bouncycastle.mail.smime.handlers.pkcs7_mime
|
||
|
|
application/x-pkcs7-signature;; x-java-content-handler=org.bouncycastle.mail.smime.handlers.x_pkcs7_signature
|
||
|
|
application/x-pkcs7-mime;; x-java-content-handler=org.bouncycastle.mail.smime.handlers.x_pkcs7_mime
|
||
|
|
multipart/signed;; x-java-content-handler=org.bouncycastle.mail.smime.handlers.multipart_signed
|
||
|
|
</pre>
|
||
|
|
</li>
|
||
|
|
<li> DYNAMICALLY<br>
|
||
|
|
|
||
|
|
The following code will add the BouncyCastle S/MIME handlers dynamically:
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
import javax.activation.MailcapCommandMap;
|
||
|
|
import javax.activation.CommandMap;
|
||
|
|
|
||
|
|
public static void setDefaultMailcap()
|
||
|
|
{
|
||
|
|
MailcapCommandMap _mailcap =
|
||
|
|
(MailcapCommandMap)CommandMap.getDefaultCommandMap();
|
||
|
|
|
||
|
|
_mailcap.addMailcap("application/pkcs7-signature;; x-java-content-handler=org.bouncycastle.mail.smime.handlers.pkcs7_signature");
|
||
|
|
_mailcap.addMailcap("application/pkcs7-mime;; x-java-content-handler=org.bouncycastle.mail.smime.handlers.pkcs7_mime");
|
||
|
|
_mailcap.addMailcap("application/x-pkcs7-signature;; x-java-content-handler=org.bouncycastle.mail.smime.handlers.x_pkcs7_signature");
|
||
|
|
_mailcap.addMailcap("application/x-pkcs7-mime;; x-java-content-handler=org.bouncycastle.mail.smime.handlers.x_pkcs7_mime");
|
||
|
|
_mailcap.addMailcap("multipart/signed;; x-java-content-handler=org.bouncycastle.mail.smime.handlers.multipart_signed");
|
||
|
|
|
||
|
|
CommandMap.setDefaultCommandMap(_mailcap);
|
||
|
|
}
|
||
|
|
</pre>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</body>
|
||
|
|
</html>
|