bouncy_castle
How to use Bouncy Castle Cryptographic API in NetBeans or Eclipse for Java JSE projects
The Bouncy Castle Crypto API for Java provides a lightweight cryptography API that works with everything from the J2ME to the JDK 1.6 platform and also a provider for the Java Cryptography Extension JCE (provides an implementation for JCE 1.2.1) and the Java Cryptography Architecture, JCA.
The API provides cryptographic functions for Java JDK 1.1 to 1.6 applications and for J2ME (mobile applications) MIDlets. The API can be downloaded from the Bouncy Castle latest releases page.
In this post we will see how to use Bouncy Castle Cryptographic API either as a JCA provider or as a lightweight API to develop Java J2SE projects in NetBeans 7 (works also on older versions) or Eclipse IDE.
If you want to develop Java applications based on the JSE framework that provide cryptographic services as:
generating hash values to check the integrity of the message or file;
encryption/decryption using symmetric key algorithms;
encryption/decryption using public certificates in a public key infrastructure;
generating message authentication codes for messages;
you must use a cryptographic API which provides the necessary classes and methods.
The Bouncy Castle API can be used in J2SE applications in two ways:
Each approach has its own advantages that are detailed in the next sections.
1. What is the Java Cryptography Architecture (JCA), the Java Cryptography Extension (JCE) and the Cryptographic Service Provider (CSP)
The basic functionality for using cryptographic techniques in Java is provided by the Java Cryptography Architecture (JCA) and its sibling, the Java Cryptography Extension (JCE). The JCA architecture is a provider-based-architecture because it has been defined as an intermediary layer, an interface, between the Java application and the cryptography provider (the actual framework that implements classes for the actual cryptographic algorithms).
Java Cryptography Architecture Overview
There are two terms, JCA and JCE, because prior to JDK 1.4 the JCE was an unbundled product. Because now it is included in the JDK, the two terms are used together to describe the same architecture.
The Java Cryptography Architecture has been defined as an independent layer. The JCA and the JCE provide a set of classes and interfaces (included in packages such as java.security, javax.crypto,javax.crypto.spec and javax.crypto.interfaces) used by the programmer to communicate with the provider of the actual cryptographic algorithms. That means that the encryption is not done by the JCA, but by the provider.
A Java cryptography provider or Cryptographic Service Provider (CSP) is Bouncy Castle but it is not the only one. The Java JDK includes also the standard Sun or SunJCE provider which is included in the JDK Java Cryptography Architecture (JCA) and that contains the cryptographic implementations.
The JCA architecture represents a simple and common mechanism for adding and using specific providers. The JCA allows programmers to write once, independently from the used provider. More, the programmer can use multiple providers at the same time or chose one at runtime. This is possible because the JCA was designed around these principles [description from java.oracle.com]:
implementation independence and interoperability because all the providers implement the same collection of interfaces;
algorithm independence and extensibility based on a generic high-level Application Programming Interface (API) used to access the provider.
The possibility to plug and use different providers in the JCA is done through the abstract layer that defines a set of factory classes used to generate instances of different engines/algorithms. One of these factory classes is Cipher which encapsulates all the cryptographic algorithms independently from the provider. For example, the Java syntax is very similar for instantiating a AES (Advanced Encryption Standard) or DES (Data Encryption Standard) engine:
import javax.crypto.*; ... //the first configured provider will respond //call the static factory method to create a DES instance Cipher desCipher = Cipher.getInstance("DES/CBC/PKCS5Padding"); //call the static factory method to create a AES instance Cipher aesCipher = Cipher.getInstance("AES/CBC/PKCS5Padding");
A detailed description of the Java Cryptography Architecture can be found on the Java Cryptography Architecture API Specification & Reference page on java.oracle.com.
2. How to install the Bouncy Castle API as a Cryptographic Service Provider (CSP) for the JCA (NetBeans or Eclipse)
There are two ways to install a provider for the JCE and JCA:
configure the Java Runtime (JRE) so the provider will be available by default to all Java applications; Advantage: you install it once on the machine and all the Java applications can use it without being forced to modify their source code; Disadvantage:you must configure the Java Runtime;
install it dynamically at the runtime, through the application source code; the provider will be available only for the applications that loads it; Advantage: you don’t need to configure the Java Runtime; Disadvantage: you must modify the source code of the application (if you didn’t done it from the beginning) so it can load the provider at runtime;
The both methods are simpler despite that for the first solution you must configure the Java Runtime.
The provider for the JSE platform is available on the Bouncy Castle latest releases page, in theSigned JAR Files category. You recognize the jar archive for your JSE version because it has thejdk word in its name, followed by the version. In this post I will use the Bouncy Castle provider for the Java 6 platform, so I need the bcprov-jdk16-146.jar file.
Solution 1. Install Bouncy Castle provider for the JCA by configuring the Java Runtime
Step 1. Download the Bouncy Castle provider for your JDK or JRE (bcprov-jdk16-146.jar for JDK 1.6);
Step 2. Copy the provider .jar file to the Java Runtime (JRE) extensions subfolder; for a Windows machine the JRE 1.6 (if it exists) is installed usually in:
C:\Program Files\Java\jre6\lib\ext
(if you look in the ext\ subfolder you will see the SunJCE provider – sunjce_provider.jar)
If you have installed also the JDK do not forget that it comes also with a JRE and you are mostly probably using it from the NetBeans or Eclipse IDE. In this case copy the .jar file also in:
Attention !
C:\Program Files\Java\jdk1.6.0_16\jre\lib\ext
(if you have installed the JDK in another location, modify the path accordingly)
Step 3. add the Bouncy Castle provider to the java.security file to enable it; the file is located in the \lib\security\ subfolder from the JRE location (Attention ! Both locations – the standalone JRE and the one from the JDK); edit the file and add the statement
security.provider.N=org.bouncycastle.jce.provider.BouncyCastleProvider
(N must be the next number in sequence) after the existing declarations:
# # List of providers and their preference orders (see above): # security.provider.1=sun.security.provider.Sun security.provider.2=sun.security.rsa.SunRsaSign security.provider.3=com.sun.net.ssl.internal.ssl.Provider security.provider.4=com.sun.crypto.provider.SunJCE security.provider.5=sun.security.jgss.SunProvider security.provider.6=com.sun.security.sasl.Provider security.provider.7=org.jcp.xml.dsig.internal.dom.XMLDSigRI security.provider.8=sun.security.smartcardio.SunPCSC security.provider.9=sun.security.mscapi.SunMSCAPI
In my example, I should add the line
security.provider.10=org.bouncycastle.jce.provider.BouncyCastleProvider
Attention !
The N value must be the next number in sequence (the existing sequence may vary from the presented scenario) and DO NOT alter the existing sequence by adding the Bouncy Castle provider on the first position or somewhere in the middle because you my alter the execution of other Java applications. DO NOT FORGET to modify the java.security file on both JRE locations (the standalone JRE and the one from the JDK).
Test Bouncy Castle provider in NetBeans or Eclipse
If the previous installation of the Bouncy Castle provider went without problems then create a simple console Java application in either NetBeans or Eclipse IDE:
import java.security.Security; public class Main { public static void main(String[] args) { //BC is the ID for the Bouncy Castle provider; if (Security.getProvider("BC") == null){ System.out.println("Bouncy Castle provider is NOT available"); } else{ System.out.println("Bouncy Castle provider is available"); } }}
If you run it and everything is ok, you should see the next message:
Bouncy Castle provider is available
otherwise go back and check steps 1-3. Also DO NOT install multiple versions of the Bouncy Castle provider.
Solution 2. Install Bouncy Castle provider for the JCA at runtime for a JSE application in NetBeans and Eclipse
In this solution you DON’T need to modify the java.security file or to add the .jar file to the JRE library. You must reference the Bouncy Castle .jar file and install the provider at runtime for a particular Java application.
Step 1. Download the Bouncy Castle provider for your JDK or JRE (bcprov-jdk16-146.jar for JDK 1.6);
Step 2. Copy the provider .jar file to the JSE application folder or at a fixed location.
Step 3. Add the .jar file reference to the Java project:
For NetBeans:
Add Bouncy Castle JCA provider in NetBeans
Select your Java project and open the ProjectProperties dialog (Right-Click in the project name in Project panel and select Properties from the contextual menu; another way is to select the project and File –> Project Properties from NetBeans menu) and go to the Librariescategory.
Click Add JAR/Folder button and indicate the .jar file.
For Eclipse:
Add Bouncy Castle JCA Provider in Eclipse
Select your Java project and open the ProjectProperties dialog (select the project name in Project Explorer panel and hit Alt+Enter; another way is to select the project and File –> Propertiesfrom Eclipse menu) and go to the Java Build Path category.
Click Add External JARs… button and indicate the .jar file.
Test Bouncy Castle provider in NetBeans or Eclipse by installing it at runtime
If the previous reference of the Bouncy Castle provider .jar file was added without problems then create a simple console Java application in either NetBeans or Eclipse IDE:
import java.security.Security;//add the provider packageimport org.bouncycastle.jce.provider.BouncyCastleProvider; public class Test { public static void main(String[] args) { //add at runtime the Bouncy Castle Provider //the provider is available only for this application Security.addProvider(new BouncyCastleProvider()); //BC is the ID for the Bouncy Castle provider; if (Security.getProvider("BC") == null){ System.out.println("Bouncy Castle provider is NOT available"); } else{ System.out.println("Bouncy Castle provider is available"); } }}
If you run it and everything is ok, you should see the next message:
Bouncy Castle provider is available
otherwise go back and check steps 1-3. Also DO NOT reference multiple versions of the Bouncy Castle provider.
3. How to install the lightweight Bouncy Castle API in NetBeans and Eclipse IDE for Java JSE applications
If you don’t want to install Bouncy Castle as a Cryptographic Service Provider for the JCA then you can use it as simple lightweight independent API just any other external library.
In this case you will not benefit from the advantages of the JCA and its interfaces and factory classes. For example you can’t use anymore the Cipher class and you must deal with classes defined for each cryptographic engine (i.e. for AES there are 3 classes: ……..). The programing style is the same as for using Bouncy Castle API for J2ME applications.
The lightweight API for the JSE platform is available on the Bouncy Castle latest releases page, in theSigned JAR Files category. You recognize the .jar (Attention ! The .jar file is for the Bouncy Castle provider, but it contains also the lightweight API) archive for your JSE version because it has the jdk word in its name, followed by the version. In this post I will use the Bouncy Castle lightweight API for the Java 6 platform, so I need the bcprov-jdk16-146.jar file.
Also, the Bouncy Castle API will be available only for the current Java project.
If you want to build your own customized API you could get the source files of the Bouncy Castle lightweight API and keep only needed algorithms. The source files are available in the Sources and Javadoc section of the Bouncy Castle latest releases page. For the JDK 1.6 the source files of the lightweight API is in crypto-jdk16-146.zip.
The steps needed to add the Bouncy Castle lightweight API in your Java application, either in NetBeans or Eclipse IDE, are the same as in the Solution 2. Install Bouncy Castle provider for the JCA at runtime for a JSE application in NetBeans and Eclipse section (without the installation of the provider).
Here is the summary (without the above images):
Step 1. Download the Bouncy Castle lightweight API for your JDK or JRE (bcprov-jdk16-146.jarfor JDK 1.6);
Step 2. Copy the provider .jar file to the JSE application folder or at a fixed location.
Step 3. Add the .jar file reference to the Java project:
For NetBeans:
Select your Java project and open the ProjectProperties dialog (Right-Click in the project name in Project panel and select Properties from the contextual menu; another way is to select the project and File –> Project Properties from NetBeans menu) and go to the Librariescategory.
Click Add Library… button and indicate the .jar file.
For Eclipse:
Select your Java project and open the ProjectProperties dialog (select the project name in Project Explorer panel and hit Alt+Enter; another way is to select the project and File –> Propertiesfrom Eclipse menu) and go to the Java Build Path category.
Click Add Library… button and indicate the .jar file.
Test Bouncy Castle provider in NetBeans or Eclipse
If the previous reference of the Bouncy Castle provider .jar file was added without problems then create a simple console Java application in either NetBeans or Eclipse IDE:
import org.bouncycastle.crypto.BlockCipher;import org.bouncycastle.crypto.engines.AESEngine;import org.bouncycastle.crypto.modes.CBCBlockCipher;import org.bouncycastle.crypto.paddings.PaddedBufferedBlockCipher; public class Main { public static void main(String[] args) { //test the API by creating an AES cipher // in CBC mode with padding BlockCipher engine = new AESEngine(); PaddedBufferedBlockCipher encryptCipher; encryptCipher = new PaddedBufferedBlockCipher( new CBCBlockCipher(engine)); }}
If there not compiler errors, it means that the API was added successfully.
When using the Bouncy Castle as a lightweight API and not as a provider, you must know the classes for each cryptographic engine and you will not benefit from the simple framework of the JCA which encapsulates all the details. The documentation of the API is very helpful and it is found in Bouncy Castle latest releases page in Sources and Javadoc section (for the JDK 1.6 the source files of the lightweight API documentation are in crypto-jdk16-146.zip)
More information on how to use the Bouncy Castle API as a provider or as an independent library to develop Java applications in NetBeans or Eclipse:
If you are interested in developing Java mobile applications (MIDlets) using J2ME platform and Bouncy Castle you can read: