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 two jar files, lcrypto.jar which contains the light weight crypto API, and crypto.jar which contains the JCE provider, clean room API, and the light weight API. Consequently if you only wish to use the light weight API just have lcrypto.jar in your class path, otherwise have crypto.jar.
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:
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.
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);
}
The light-weight API has built in support for the following:
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) |
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 |
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 | |
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 |
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 |
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. |
The base interface is Digest and has the following implementations
Name | Output (in bits) | Notes |
---|---|---|
MD2Digest | 128 | |
MD4Digest | 128 | |
MD5Digest | 128 | |
RipeMD128Digest | 160 | basic RipeMD |
RipeMD160Digest | 160 | enhanced version of RipeMD |
SHA1Digest | 160 | |
SHA256Digest | 256 | Draft version from FIPS 180-2 |
SHA384Digest | 384 | Draft version from FIPS 180-2 |
SHA512Digest | 512 | Draft version from FIPS 180-2 |
TigerDigest | 192 | The Tiger Digest. |
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 |
The base class is PBEParametersGenerator and has the following sub-classes
Name | Constructor | Notes |
---|---|---|
PKCS5S1ParametersGenerator | Digest | |
PKCS5S2ParametersGenerator | Uses SHA1/Hmac as defined | |
PKCS12ParametersGenerator | Digest |
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.
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.
DSA, ECDSA 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 (as defined in the standard) you'll also need to make use of the SHA1 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.
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.
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.
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).
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.
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 | |
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 |
Note: default key sizes are in bold.
Name | KeySizes (in bits) | Notes |
---|---|---|
RC4 | 40 .. 2048 bits (128) |
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;
Name | KeySizes (in bits) | Notes |
---|---|---|
RSA | any multiple of 8 bits large enough for the encryption(2048) |
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.
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.
Name | Output (in bits) | Notes |
---|---|---|
MD2 | 128 | |
MD4 | 128 | |
MD5 | 128 | |
RipeMD128 | 128 | basic RipeMD |
RipeMD160 | 160 | enhanced version of RipeMD |
SHA1 | 160 | |
SHA-256 | 256 | Draft version from FIPS 180-2 |
SHA-384 | 384 | Draft version from FIPS 180-2 |
SHA-512 | 512 | Draft version from FIPS 180-2 |
Tiger | 192 |
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) | |
MD2/HMac | 128 | |
MD4/HMac | 128 | |
MD5/HMac | 128 | |
RipeMD128/HMac | 128 | |
RipeMD160/HMac | 160 | |
SHA1/HMac | 160 | |
Tiger/HMac | 192 |
Examples:
Schemes:
Schemes:
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 |
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.
The Bouncy Castle package has two implementation of a keystore.
The first, 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 second 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.
There is an example program that produces PKCS12 files suitable for loading into browsers. It is in the package org.bouncycastle.jce.examples.
Currently there are no classes for supporting EC keys and parameters in the JCE or JCA. Classes for supporting these can be found in the following packages: