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 and the MLS library both make use of additional open source code:

BC Example Code

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.mail.smime.examples

  • org.bouncycastle.openpgp.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 more uptodate documentation and examples in Java Cryptography: Tools and Techniques. A copy of the source code for the examples in the book is in java-crypto-tools-src.zip.

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

BC FIPS Example Code

Example code for the Bouncy Castle FIPS jars can be found in the tests and also the "BC FIPS in 100" mini-book.

BC FIPS in 100 mini-book BCFipsIn100.pdf
BC FIPS in 100 examples bc-fips-100-java.tar.gz or bc-fips-100-java.zip

BC/BCFIPS Documentation

Java Cryptography: Tools and Techniques
David Hook, Jon Eaves - Leanpub
 
Finished in 2022 and written by two founders of the Bouncy Castle project, as a successor to "Beginning Cryptography with Java", the book covers the recent features introduced in the JCA/JCE as well the latest changes to the BC APIs and the BCFIPS Java module including the recent introduction of Post-Quantum algorithms to the BC APIs. Coverage of certificate generation, CMS, S/MIME, OpenPGP, and the TLS APIs is also included. Also available as a Paperback Edition and a Kindle Tablet Edition

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.15 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)

BC FIPS documentation

Security Policy BC-FJA-SecurityPolicy-1.0.2.pdf
User Guides BC-FJA-UserGuide-1.0.2.pdf
BC-FJA-(D)TLSUserGuide-1.0.13.pdf

BCFIPS JavaDoc

Provider bc-fips-1.0.2-javadoc.jar
CMS/EAC/OCSP/PKIX/PKCS/TSP bcpkix-fips-1.0.3-javadoc.jar
S/MIME bcmail-fips-1.0.1-javadoc.jar
OpenPGP/BCPG bcpg-fips-1.0.3-javadoc.jar
TLS bctls-fips-1.0.9-javadoc.jar

General documentation

The current release notes for this package are here.

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

JDK 1.8 and later documentation

JDK 1.5 to 1.8 documentation

JDK 1.4 documentation

JDK 1.3 documentation

Enjoy!