This is the original Bouncy Castle 1.34 specification.
Bouncy Castle Crypto Package
Bouncy Castle Crypto Package
1.0 Introduction
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.
This software is distributed under a license based on the MIT X
Consortium license. To view the license,
see here
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.
Note: if you are using JDK 1.0, you will just find a class hierarchy in
the classes directory.
To view examples, look at the test programs in the packages:
- org.bouncycastle.crypto.test
- org.bouncycastle.jce.provider.test
To verify the packages, run the following Java programs with the
appropriate classpath:
- java org.bouncycastle.crypto.test.RegressionTest
- java org.bouncycastle.jce.provider.test.RegressionTest
2.0 Patents
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 at the request of the patent
holder.
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
www.mediacrypt.com for
further details.
3.0 Specifications
- clean room implementation of the JCE API
- light-weight cryptographic API consisting of support for
- BlockCipher
- BufferedBlockCipher
- AsymmetricBlockCipher
- BufferedAsymmetricBlockCipher
- StreamCipher
- BufferedStreamCipher
- KeyAgreement
- IESCipher
- Digest
- Mac
- PBE
- Signers
- JCE compatible framework for a Bouncy Castle provider
4.0 Light-weight API
This API has been specifically developed for those circumstances
where the rich API and integration requirements of the JCE are
not required.
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.
4.1 Example
To utilise the light-weight API in a program, the fundamentals
are as follows;
/*
* 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);
}
4.2 Algorithms
The light-weight API has built in support for the following:
Symmetric (Block)
The base interface is BlockCipher and has the following
implementations which match the modes the block cipher can
be operated in.
| Name | Constructor | Notes |
|---|
| BufferedBlockCipher | BlockCipher | |
| CBCBlockCipher | BlockCipher | |
| CFBBlockCipher | BlockCipher, block size (in bits) | |
| OFBBlockCipher | BlockCipher, block size (in bits) | |
| SICBlockCipher | BlockCipher, block size (in bits) | Also known as CTR mode |
| OpenPGPCFBBlockCipher | BlockCipher | |
| GOFBBlockCipher | BlockCipher | GOST OFB mode |
BufferedBlockCipher has a further sub-classes
| Name | Constructor | Notes |
|---|
| PaddedBufferedBlockCipher | BlockCipher | a buffered block cipher that can use padding - default PKCS5/7 padding |
| CTSBlockCipher | BlockCipher | Cipher Text Stealing |
The following paddings can be used with the PaddedBufferedBlockCipher.
| Name | Description |
|---|
| PKCS7Padding | PKCS7/PKCS5 padding |
| ISO10126d2Padding | ISO 10126-2 padding |
| X932Padding | X9.23 padding |
| ISO7816d4Padding | ISO 7816-4 padding (ISO 9797-1 scheme 2) |
| ZeroBytePadding | Pad with Zeros (not recommended) |
The following cipher engines are implemented that can be
used with the above modes.
| Name | KeySizes (in bits) | Block Size | Notes |
|---|
| AESEngine | 0 .. 256 | 128 bit | |
| AESWrapEngine | 0 .. 256 | 128 bit | Implements FIPS AES key wrapping |
| BlowfishEngine | 0 .. 448 | 64 bit | |
| CAST5Engine | 0 .. 128 | 64 bit | |
| CAST6Engine | 0 .. 256 | 128 bit | |
| DESEngine | 64 | 64 bit | |
| DESedeEngine | 128, 192 | 64 bit | |
| DESedeWrapEngine | 128, 192 | 64 bit | Implements Draft IETF DESede key wrapping |
| IDEAEngine | 128 | 64 bit | |
| RC2Engine | 0 .. 1024 | 64 bit | |
| RC532Engine | 0 .. 128 | 64 bit | Uses a 32 bit word |
| RC564Engine | 0 .. 128 | 128 bit | Uses a 64 bit word |
| RC6Engine | 0 .. 256 | 128 bit | |
| RijndaelEngine | 0 .. 256 | 128 bit, 160 bit, 192 bit, 224 bit, 256 bit | |
| SkipjackEngine | 0 .. 128 | 64 bit | |
| TwofishEngine | 128, 192, 256 | 128 bit | |
| SerpentEngine | 128, 192, 256 | 128 bit | |
| GOST28147Engine | 256 | 64 bit | Has a range of S-boxes |
| CamelliaEngine | 128, 192, 256 | 128 bit | |
Symmetric (Stream)
The base interface is StreamCipher and has the following
implementations which match the modes the stream cipher can
be operated in.
| Name | Constructor | Notes |
|---|
| BlockStreamCipher | BlockCipher | |
The following cipher engines are implemented that can be
used with the above modes.
| Name | KeySizes (in bits) | Notes |
|---|
| RC4Engine | 40 .. 2048 | |
Block Asymmetric
The base interface is AsymmetricBlockCipher and has the following
implementations which match the modes the cipher can be operated in.
| Name | Constructor | Notes |
|---|
| BufferedAsymmetricBlockCipher | AsymmetricBlockCipher | |
| OAEPEncoding | AsymmetricBlockCipher | |
| PKCS1Encoding | AsymmetricBlockCipher | |
| ISO9796d1Encoding | AsymmetricBlockCipher | ISO9796-1 |
The following cipher engines are implemented that can be
used with the above modes.
| Name | KeySizes (in bits) | Notes |
|---|
| RSAEngine | any multiple of 8 large enough for the encoding. | |
| ElGamalEngine | any multiple of 8 large enough for the encoding. | |
Digest
The base interface is Digest and has the following
implementations
| Name | Output (in bits) | Notes |
|---|
| MD2Digest | 128 | |
| MD4Digest | 128 | |
| MD5Digest | 128 | |
| RipeMD128Digest | 128 | basic RipeMD |
| RipeMD160Digest | 160 | enhanced version of RipeMD |
| RipeMD256Digest | 256 | expanded version of RipeMD128 |
| RipeMD320Digest | 320 | expanded version of RipeMD160 |
| SHA1Digest | 160 | |
| SHA224Digest | 224 | FIPS 180-2 |
| SHA256Digest | 256 | FIPS 180-2 |
| SHA384Digest | 384 | FIPS 180-2 |
| SHA512Digest | 512 | FIPS 180-2 |
| TigerDigest | 192 | The Tiger Digest. |
| GOST3411Digest | 256 | The GOST-3411 Digest. |
| WhirlpoolDigest | 512 | The Whirlpool Digest. |
MAC
The base interface is Mac and has the following
implementations
| Name | Output (in bits) | Notes |
|---|
| CBCBlockCipherMac | blocksize/2 unless specified | |
| CFBBlockCipherMac | blocksize/2, in CFB 8 mode, unless specified | |
| HMac | digest length | |
PBE
The base class is PBEParametersGenerator and has the following
sub-classes
| Name | Constructor | Notes |
|---|
| PKCS5S1ParametersGenerator | Digest | |
| PKCS5S2ParametersGenerator | | Uses SHA1/Hmac as defined |
| PKCS12ParametersGenerator | Digest | |
| OpenSSLPBEParametersGenerator | | Uses MD5 as defined |
Key Agreement
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.
The agreement APIs are in the org.bouncycastle.crypto.agreement package.
Classes for generating Diffie-Hellman parameters can be found in the
org.bouncycastle.crypto.params and org.bouncycastle.crypto.generators packages.
IESCipher
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.
Note: 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.
Signers
DSA, ECDSA, ISO-9796-2, GOST-3410-94, GOST-3410-2001, and RSA-PSS are supported by the org.bouncycastle.crypto.signers
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
org.bouncycastle.crypto.params and org.bouncycastle.crypto.generators packages.
4.3 ASN.1 package
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.
5.0 Bouncy Castle Provider
The Bouncy Castle provider is a JCE compliant provider that
is a wrapper built on top of the light-weight API.
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.
5.1 Example
To utilise the JCE provider in a program, the fundamentals
are as follows;
/*
* 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
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:
security.provider.<n>=org.bouncycastle.jce.provider.BouncyCastleProvider
Where <n> is the preference you want the provider at (1 being the most prefered).
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.
Note: 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:
java.lang.SecurityException: Unsupported keysize or algorithm parameters
at javax.crypto.Cipher.init(DashoA6275)
The policy files can be found at the same place you downloaded the JDK.
5.2 Algorithms
Symmetric (Block)
Modes:
- ECB
- CBC
- OFB(n)
- CFB(n)
- SIC (also known as CTR)
- OpenPGPCFB
- CTS (equivalent to CBC/WithCTS)
- GOFB
Where (n) 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.
Padding Schemes:
- No padding
- PKCS5/7
- ISO10126/ISO10126-2
- ISO7816-4/ISO9797-1
- X9.23/X923
- TBC
- ZeroByte
- withCTS (if used with ECB mode)
When placed together this gives a specification for an algorithm
as;
- DES/CBC/X9.23Padding
- DES/OFB8/NoPadding
- IDEA/CBC/ISO10126Padding
- IDEA/CBC/ISO7816-4Padding
- SKIPJACK/ECB/PKCS7Padding
- DES/ECB/WithCTS
Note: default key sizes are in bold.
| Name | KeySizes (in bits) | Block Size | Notes |
|---|
| AES | 0 .. 256 (192) | 128 bit | |
| AESWrap | 0 .. 256 (192) | 128 bit | A FIPS AES key wrapper |
| Blowfish | 0 .. 448 (448) | 64 bit | |
| CAST5 | 0 .. 128(128) | 64 bit | |
| CAST6 | 0 .. 256(256) | 128 bit | |
| DES | 64 | 64 bit | |
| DESede | 128, 192 | 64 bit | |
| DESedeWrap | 128, 192 | 128 bit | A Draft IETF DESede key wrapper |
| IDEA | 128 (128) | 64 bit | |
| RC2 | 0 .. 1024 (128) | 64 bit | |
| RC5 | 0 .. 128 (128) | 64 bit | Uses a 32 bit word |
| RC5-64 | 0 .. 256 (256) | 128 bit | Uses a 64 bit word |
| RC6 | 0 .. 256 (128) | 128 bit | |
| Rijndael | 0 .. 256 (192) | 128 bit | |
| Skipjack | 0 .. 128 (128) | 64 bit | |
| Twofish | 128, 192, 256 (256) | 128 bit | |
| Serpent | 128, 192, 256 (256) | 128 bit | |
| GOST28147 | 256 | 64 bit | |
| Camellia | 128, 192, 256 | 128 bit | |
Symmetric (Stream)
Note: default key sizes are in bold.
| Name | KeySizes (in bits) | Notes |
|---|
| RC4 | 40 .. 2048 bits (128) | |
Block Asymmetric
Encoding:
- OAEP - Optimal Asymmetric Encryption Padding
- PCKS1 - PKCS v1.5 Padding
- ISO9796-1 - ISO9796-1 edition 1 Padding
Note: except as indicated in PKCS 1v2 we recommend you use OAEP, as
mandated in X9.44.
When placed together with RSA this gives a specification for an algorithm
as;
- RSA/NONE/NoPadding
- RSA/NONE/PKCS1Padding
- RSA/NONE/OAEPWithMD5AndMGF1Padding
- RSA/NONE/OAEPWithSHA1AndMGF1Padding
- RSA/NONE/OAEPWithSHA224AndMGF1Padding
- RSA/NONE/OAEPWithSHA256AndMGF1Padding
- RSA/NONE/OAEPWithSHA384AndMGF1Padding
- RSA/NONE/OAEPWithSHA512AndMGF1Padding
- RSA/NONE/ISO9796-1Padding
| Name | KeySizes (in bits) | Notes |
|---|
| RSA | any multiple of 8 bits large enough for the encryption(2048) | |
| ElGamal | any multiple of 8 bits large enough for the encryption(1024) | |
Key Agreement
Diffie-Hellman key agreement is supported using the "DH", "ECDH", and
"ECDHC" (ECDH with cofactors) key agreement instances.
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.
ECIES
An implementation of ECIES (stream mode) as described in IEEE P 1363a.
Note: 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.
Digest
| Name | Output (in bits) | Notes |
|---|
| GOST3411 | 256 | |
| MD2 | 128 | |
| MD4 | 128 | |
| MD5 | 128 | |
| RipeMD128 | 128 | basic RipeMD |
| RipeMD160 | 160 | enhanced version of RipeMD |
| RipeMD256Digest | 256 | expanded version of RipeMD128 |
| RipeMD320Digest | 320 | expanded version of RipeMD160 |
| SHA1 | 160 | |
| SHA-224 | 224 | FIPS 180-2 |
| SHA-256 | 256 | FIPS 180-2 |
| SHA-384 | 384 | FIPS 180-2 |
| SHA-512 | 512 | FIPS 180-2 |
| Tiger | 192 | |
| Whirlpool | 512 | |
MAC
| Name | Output (in bits) | Notes |
|---|
| Any MAC based on a block cipher, CBC (the default) and CFB modes. | half the cipher's block size (usually 32 bits) | |
| HMac-MD2 | 128 | |
| HMac-MD4 | 128 | |
| HMac-MD5 | 128 | |
| HMac-RipeMD128 | 128 | |
| HMac-RipeMD160 | 160 | |
| HMac-SHA1 | 160 | |
| HMac-SHA224 | 224 | |
| HMac-SHA256 | 256 | |
| HMac-SHA384 | 384 | |
| HMac-SHA512 | 512 | |
| HMac-Tiger | 192 | |
Examples:
- DESMac
- DESMac/CFB8
- DESedeMac
- DESedeMac/CFB8
- DESedeMac64
- SKIPJACKMac
- SKIPJACKMac/CFB8
- IDEAMac
- IDEAMac/CFB8
- RC2Mac
- RC2Mac/CFB8
- RC5Mac
- RC5Mac/CFB8
- ISO9797ALG3Mac
Signature Algorithms
Schemes:
- GOST3411withGOST3410 (GOST3411withGOST3410-94)
- GOST3411withECGOST3410 (GOST3411withGOST3410-2001)
- MD2withRSA
- MD5withRSA
- SHA1withRSA
- RIPEMD128withRSA
- RIPEMD160withRSA
- RIPEMD256withRSA
- SHA1withDSA
- SHA1withECDSA
- SHA224withECDSA
- SHA256withECDSA
- SHA384withECDSA
- SHA512withECDSA
- SHA224withRSA
- SHA256withRSA
- SHA384withRSA
- SHA512withRSA
- SHA1withRSAandMGF1
- SHA256withRSAandMGF1
- SHA384withRSAandMGF1
- SHA512withRSAandMGF1
PBE
Schemes:
- PKCS5S1, any Digest, any symmetric Cipher, ASCII
- PKCS5S2, SHA1/HMac, any symmetric Cipher, ASCII
- PKCS12, any Digest, any symmetric Cipher, Unicode
Defined in Bouncy Castle JCE Provider
| Name | Key Generation Scheme | Key Length (in bits) |
|---|
| PBEWithMD5AndDES | PKCS5 Scheme 1 | 64 |
| PBEWithMD5AndRC2 | PKCS5 Scheme 1 | 128 |
| PBEWithSHA1AndDES | PKCS5 Scheme 1 | 64 |
| PBEWithSHA1AndRC2 | PKCS5 Scheme 1 | 128 |
| PBEWithSHAAnd2-KeyTripleDES-CBC | PKCS12 | 128 |
| PBEWithSHAAnd3-KeyTripleDES-CBC | PKCS12 | 192 |
| PBEWithSHAAnd128BitRC2-CBC | PKCS12 | 128 |
| PBEWithSHAAnd40BitRC2-CBC | PKCS12 | 40 |
| PBEWithSHAAnd128BitRC4 | PKCS12 | 128 |
| PBEWithSHAAnd40BitRC4 | PKCS12 | 40 |
| PBEWithSHAAndTwofish-CBC | PKCS12 | 256 |
| PBEWithSHAAndIDEA-CBC | PKCS12 | 128 |
5.3 Certificates
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.
The CertificiateFactory will also read X.509 CRLs (v2) from either PEM or DER encodings.
In addition to the classes in the org.bouncycastle.ans1.x509 package for certificate
generation a more JCE "friendly" class is provided in the package org.bouncycastle.jce. The JCE "friendly" class supports RSA, DSA, and EC-DSA.
5.4 Keystore
The Bouncy Castle package has three implementation of a keystore.
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.
The second, Keystore.BouncyCastle, or Keystore.UBER 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. PBEWithSHAAndTwofish-CBC.
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?).
In the first case, the keys are encrypted with 3-Key-TripleDES.
The third is a PKCS12 compatabile 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.
There is an example program that produces PKCS12 files suitable for
loading into browsers. It is in the package
org.bouncycastle.jce.examples.
5.5 Additional support classes for Elliptic Curve.
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:
- org.bouncycastle.jce.spec
- org.bouncycastle.jce.interfaces
- org.bouncycastle.jce
6.0 BouncyCastle S/MIME
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.
6.1 Setting up BouncyCastle S/MIME in JavaMail
The BouncyCastle S/MIME handlers may be set in JavaMail two ways.
- STATICALLY
Add the following entries to the mailcap file:
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
- DYNAMICALLY
The following code will add the BouncyCastle S/MIME handlers dynamically:
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);
}
