Documentation

The Bouncy Castle Crypto package is a Java implementation of cryptographic algorithms, it was developed by the Legion of the Bouncy Castle - with a little help!

The Legion also gratefully acknowledges the contributions made to this package by others.

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

To view some examples, look at the test programs in the packages:

  • org.bouncycastle.crypto.test

  • org.bouncycastle.jce.provider.test

  • org.bouncycastle.cms.test

  • org.bouncycastle.mail.smime.test

  • org.bouncycastle.openpgp.test

  • org.bouncycastle.tsp.test

There are also some specific example programs for dealing with Attribute Certificates, PKCS12, SMIME and OpenPGP. They can be found in:

  • org.bouncycastle.jce.examples

  • org.bouncycastle.mail.smime.examples

  • org.bouncycastle.openpgp.examples

  • org.bouncycastle.x509.examples

Finally there are also code examples from Beginning Cryptography with Java which demonstrate both the use of the JCE/JCA and also some of the Bouncy Castle APIs such as for certificate generation, CMS and S/MIME. Note: the book was written to cover J2SE 5.0, while many of the examples will work with earlier JDKs, some will not compile if you are not using J2SE 5.0 or later.

Unfortunately some examples in the book are now out of date (for 1.46 and above). You can also find some more uptodate documentation and examples at the guide project.

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

Important Notes

  1. In order to keep the size of the signed jar files down the regression tests are no longer included in them. See the bctest*.jar file for the appropriate JDK.

  2. The JCE classes are only distributed with the JDK 1.1, JDK 1.2, and JDK 1.3 JCE releases. The JDK 1.4-1.7 release just contains the provider and lightweight API. The JDK 1.0, J2ME, and the JDK 1.1 and later lightweight releases only include the Bouncy Castle lightweight cryptography API.

  3. If you are using JDK 1.4, or later, you must use the signed jar for the provider and you must download the unrestricted policy files for the Sun JCE if you want the provider to work properly. The policy files can be found at the same place as the JDK download. Further information on this can be found in the Sun documentation on the JCE. If you have not installed the policy files you will see something like:

java.lang.SecurityException: Unsupported keysize or algorithm parameters
		at javax.crypto.Cipher.init(DashoA6275)
		

General documentation

The current release notes for this package are here.

The current specifications (including installation instructions) for this package are here.

JDK 1.5-1.7 documentation

JDK 1.4 documentation

JDK 1.3 documentation

Enjoy!