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.

Except where otherwise stated, this software is distributed under a license based on the MIT X Consortium license. To view the license, see here. The OpenPGP library also includes a modified BZIP2 library which is licensed under the Apache Software License, Version 2.0.

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:

To verify the packages, run the following Java programs with the appropriate classpath:

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, 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.

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

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.

NameConstructorNotes
BufferedBlockCipherBlockCipher 
CBCBlockCipherBlockCipher 
CFBBlockCipherBlockCipher, block size (in bits) 
CCMBlockCipherBlockCipherPacket mode - requires all data up front.
EAXBlockCipherBlockCipher 
OFBBlockCipherBlockCipher, block size (in bits) 
SICBlockCipherBlockCipher, block size (in bits)Also known as CTR mode
OpenPGPCFBBlockCipherBlockCipher 
GOFBBlockCipherBlockCipherGOST OFB mode

BufferedBlockCipher has a further sub-classes

NameConstructorNotes
PaddedBufferedBlockCipherBlockCiphera buffered block cipher that can use padding - default PKCS5/7 padding
CTSBlockCipherBlockCipherCipher Text Stealing

The following paddings can be used with the PaddedBufferedBlockCipher.

NameDescription
PKCS7PaddingPKCS7/PKCS5 padding
ISO10126d2PaddingISO 10126-2 padding
X932PaddingX9.23 padding
ISO7816d4PaddingISO 7816-4 padding (ISO 9797-1 scheme 2)
ZeroBytePaddingPad with Zeros (not recommended)

The following cipher engines are implemented that can be used with the above modes.

NameKeySizes (in bits) Block SizeNotes
AESEngine0 .. 256 128 bit 
AESWrapEngine0 .. 256 128 bitImplements FIPS AES key wrapping
BlowfishEngine0 .. 448 64 bit 
CamelliaEngine128, 192, 256128 bit 
CamelliaWrapEngine128, 192, 256128 bit 
CAST5Engine0 .. 128 64 bit 
CAST6Engine0 .. 256 128 bit 
DESEngine6464 bit 
DESedeEngine128, 19264 bit 
DESedeWrapEngine128, 19264 bitImplements Draft IETF DESede key wrapping
GOST28147Engine25664 bitHas a range of S-boxes
IDEAEngine12864 bit 
NoekeonEngine128128 bit 
RC2Engine0 .. 1024 64 bit 
RC532Engine0 .. 128 64 bitUses a 32 bit word
RC564Engine0 .. 128 128 bitUses a 64 bit word
RC6Engine0 .. 256 128 bit 
RijndaelEngine0 .. 256 128 bit, 160 bit, 192 bit, 224 bit, 256 bit 
SEEDEngine128128 bit 
SEEDWrapEngine128128 bit 
SerpentEngine128, 192, 256 128 bit 
SkipjackEngine0 .. 128 64 bit 
TEAEngine12864 bit 
TwofishEngine128, 192, 256 128 bit 
XTEAEngine12864 bit 

Symmetric (Stream)

The base interface is StreamCipher and has the following implementations which match the modes the stream cipher can be operated in.

NameConstructorNotes
BlockStreamCipherBlockCipher 

The following cipher engines are implemented that can be used with the above modes.

NameKeySizes (in bits) Notes
RC4Engine40 .. 2048 
HC128Engine128 
HC256Engine256 
Salsa20Engine128/256 
ISAACEngine32 .. 8192 
VMPCEngine8 .. 6144 
Grainv1Engine8064 bit IV
Grain128Engine12896 bit IV

Block Asymmetric

The base interface is AsymmetricBlockCipher and has the following implementations which match the modes the cipher can be operated in.

NameConstructorNotes
BufferedAsymmetricBlockCipherAsymmetricBlockCipher 
OAEPEncodingAsymmetricBlockCipher 
PKCS1EncodingAsymmetricBlockCipher 
ISO9796d1EncodingAsymmetricBlockCipherISO9796-1

The following cipher engines are implemented that can be used with the above modes.

NameKeySizes (in bits)Notes
RSAEngineany multiple of 8 large enough for the encoding. 
ElGamalEngineany multiple of 8 large enough for the encoding. 

Digest

The base interface is Digest and has the following implementations

NameOutput (in bits)Notes
MD2Digest128 
MD4Digest128 
MD5Digest128 
RipeMD128Digest128basic RipeMD
RipeMD160Digest160enhanced version of RipeMD
RipeMD256Digest256expanded version of RipeMD128
RipeMD320Digest320expanded version of RipeMD160
SHA1Digest160 
SHA224Digest224FIPS 180-2
SHA256Digest256FIPS 180-2
SHA384Digest384FIPS 180-2
SHA512Digest512FIPS 180-2
SHA3Digest224, 256, 288, 384, 512
TigerDigest192The Tiger Digest.
GOST3411Digest256The GOST-3411 Digest.
WhirlpoolDigest512The Whirlpool Digest.

MAC

The base interface is Mac and has the following implementations

NameOutput (in bits)Notes
CBCBlockCipherMacblocksize/2 unless specified 
CFBBlockCipherMacblocksize/2, in CFB 8 mode, unless specified 
HMacdigest length 

PBE

The base class is PBEParametersGenerator and has the following sub-classes

NameConstructorNotes
PKCS5S1ParametersGeneratorDigest 
PKCS5S2ParametersGenerator Uses SHA1/Hmac as defined
PKCS12ParametersGeneratorDigest 
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, DSTU-4145-2002, 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:

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:

When placed together this gives a specification for an algorithm as;

Note: default key sizes are in bold.

NameKeySizes (in bits) Block SizeNotes
AES0 .. 256 (192)128 bit 
AESWrap0 .. 256 (192)128 bitA FIPS AES key wrapper
Blowfish0 .. 448 (448)64 bit 
Camellia128, 192, 256128 bit 
CamelliaWrap128, 192, 256128 bit 
CAST50 .. 128(128)64 bit 
CAST60 .. 256(256)128 bit 
DES6464 bit 
DESede128, 19264 bit 
DESedeWrap128, 192128 bitA Draft IETF DESede key wrapper
GOST2814725664 bit 
IDEA128 (128)64 bitOnly included in extended provider jar.
Noekeon128(128)128 bit 
RC20 .. 1024 (128)64 bit 
RC50 .. 128 (128)64 bitUses a 32 bit word
RC5-640 .. 256 (256)128 bitUses a 64 bit word
RC60 .. 256 (128)128 bit 
Rijndael0 .. 256 (192)128 bit 
SEED128(128)128 bit 
SEEDWrap128(128)128 bit 
Serpent128, 192, 256 (256)128 bit 
Skipjack0 .. 128 (128)64 bit 
TEA128 (128)64 bit 
Twofish128, 192, 256 (256)128 bit 
XTEA128 (128)64 bit 

Symmetric (Stream)

Note: default key sizes are in bold.

NameKeySizes (in bits)Notes
RC440 .. 2048 bits (128) 
HC128(128) 
HC256(256) 
Salsa20128/256(128) 
VMPC128/6144(128) 
Grainv18064 bit IV
Grain12812896 bit IV

Block Asymmetric

Encoding:

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;

NameKeySizes (in bits)Notes
RSAany multiple of 8 bits large enough for the encryption(2048) 
ElGamalany 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

NameOutput (in bits)Notes
GOST3411256 
MD2128 
MD4128 
MD5128 
RipeMD128128basic RipeMD
RipeMD160160enhanced version of RipeMD
RipeMD256Digest256expanded version of RipeMD128
RipeMD320Digest320expanded version of RipeMD160
SHA1160 
SHA-224224FIPS 180-2
SHA-256256FIPS 180-2
SHA-384384FIPS 180-2
SHA-512512FIPS 180-2
SHA3-224224 
SHA3-256256 
SHA3-384384 
SHA3-512512 
Tiger192 
Whirlpool512 

MAC

NameOutput (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) 
VMPC-MAC128 
HMac-MD2128 
HMac-MD4128 
HMac-MD5128 
HMac-RipeMD128128 
HMac-RipeMD160160 
HMac-SHA1160 
HMac-SHA224224 
HMac-SHA256256 
HMac-SHA384384 
HMac-SHA512512 
HMac-Tiger192 

Examples:

Signature Algorithms

Schemes:

PBE

Schemes:

Defined in Bouncy Castle JCE Provider
NameKey Generation SchemeKey Length (in bits)
PBEWithMD2AndDESPKCS5 Scheme 164
PBEWithMD2AndRC2PKCS5 Scheme 1128
PBEWithMD5AndDESPKCS5 Scheme 164
PBEWithMD5AndRC2PKCS5 Scheme 1128
PBEWithSHA1AndDESPKCS5 Scheme 164
PBEWithSHA1AndRC2PKCS5 Scheme 1128
PBEWithSHAAnd2-KeyTripleDES-CBCPKCS12128
PBEWithSHAAnd3-KeyTripleDES-CBCPKCS12192
PBEWithSHAAnd128BitRC2-CBCPKCS12128
PBEWithSHAAnd40BitRC2-CBCPKCS1240
PBEWithSHAAnd128BitRC4PKCS12128
PBEWithSHAAnd40BitRC4PKCS1240
PBEWithSHAAndTwofish-CBCPKCS12256
PBEWithSHAAndIDEA-CBCPKCS12128

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.asn1.x509 package for certificate generation a more JCE "friendly" class is provided in the package org.bouncycastle.x509. 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 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.

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:

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.