© Copyright International Business Machines Corporation 2003. All rights reserved.

Introduction

The Java^TM Cryptography Extension (JCE) provides a framework and implementation methods for the following cryptography features:

• Encryption
• Key generation
• Key agreement
• Message authentication code (MAC) algorithms
• Secure streams
• Sealed objects

Within the JCE framework, qualified cryptography from other libraries can be plugged in as service providers. The Sun JCE Service Provider is included in the download package of JCE. Other vendors, including IBM©, also have their implementation of JCE service providers that you can plug into the JCE framework.

An earlier version of this article focused on using JCE with WebSphere© Studio Application Developer (hereafter called Application Developer) Version 4.03. This article focuses on using JCE with Application Developer Version 5. The Java Runtime Environment (JRE) of Application Developer Version 5 is at the Java 2 SDK 1.3.x level. Therefore this article will focus on JCE 1.2, which is an optional package in Java 2 SDK 1.2.x and 1.3.x.

Both the Version 4 and Version 5 WebSphere Runtimes (WebSphere Test Environments) are included in Application Developer Version 5. The Sun JCE Framework 1.2.1 (ibmjcefw.jar) and the IBM JCE provider (ibmjceprovider.jar) are included in both the Version 4 and Version 5 WebSphere Test Environments. The IBM JCE provider is similar to Sun JCE, except that the IBM JCE offers more algorithms in:

• Cipher algorithm
• Signature algorithm
• Message digest algorithm
• Message authentication code (MAC)
• Key agreement algorithm
• Random number generation algorithm
• Key Store

No configuration is needed to use IBM JCE provider in a server-side application except that you need to use the corresponding JAR files to compile the application. You do need additional configuration if you want to use other JCE providers such as Sun JCE provider. For using JCE in a client-side Java application with the Application Developer Workbench JRE, some limitations apply. This article will show you:

• The different Java Runtime Environments in Application Developer Version 5
• How to use IBM JCE and Sun JCE for a server-side application
• How to use IBM JCE and Sun JCE for a standalone Java application

Back to top

Java Runtime Environments in Application Developer

Before going into the details of configuring Application Developer for JCE programming, it is useful to know more about the JREs shipped with it. Depending on the installation options you choose, Application Developer ships up to four copies of the JRE, all of which are at the 1.3.x level. For detailed version information on the JRE, use the java -version command.

The first JRE is located in x:\Ws_installdir\eclipse\jre (x:\Ws_installdir refers to the installation drive and folder of Application Developer). This version of JRE is for the Application Developer Workbench (the tool itself), and by default, for standalone client-side Java applications such as a GUI application in a Java project. However, you can easily switch to another JRE such as the WebSphere runtime JRE for client-side Java applications. This version of the Application Developer Workbench JRE is J2RE 1.3.1, Windows© 32 Build cn131-20020710.

Important: If you want to use the JCE API with this copy of the JRE, the installation folder of Application Developer, x:\Ws_installdir, can't have space. For example, you can't use the default installation folder, C:\Program File\IBM\WebSphere Studio, to install Application Developer. If there is a space in the installation folder, you will get the following error:

java.lang.ExceptionInInitializerError: java.lang.SecurityException: 
Cannot set up certs for trusted CAs

The second JRE is located in x:\Ws_installdir\runtimes\base_v5\java\jre. This version of the JRE is for the WebSphere Base Server Version 5 Runtime that is J2EE 1.3 compliant, and all server-side components including servlets, JSPs, and EJBs targeted at the Version 5 platform run on it. The version of this JRE is J2RE 1.3.1, Windows 32 Build cn131-20021107.

The third JRE is located in x:\Ws_installdir\runtimes\express_v5\java\jre. This version of the JRE is for the WebSphere Express Server Version 5 Runtime. You might not have this copy of JRE if you haven't chosen the option for WebSphere Express Server Runtime during the installation. WebSphere Express Server is a subset of WebSphere Base Server and it doesn't have the EJB container. The version of this JRE is the same as the one for WebSphere Base Server, J2RE 1.3.1, Windows 32 Build cn131-20021107.

The forth JRE is located in x:\Ws_installdir\runtimes\aes_v4\java\jre. This version of the JRE is for the WebSphere Advanced Edition Single Server Version 4 Runtime that is J2EE 1.2 compliant, and all server-side components including servlets, JSPs, and EJBs targeted at the Version 4 platform run on it. You might not have this copy of JRE if you haven't chosen the option for Version 4 WebSphere Runtime during the installation. The version of JRE is J2RE 1.3.1, Windows 32 Build cn131w-20020710 ORB130.

Next, you need to decide which JCE provider you are going to use for your applications, and whether you want to use JCE for a standalone client-side Java application or for server-side components. For server-side components, you need to decide what platform the components are targeted for, so that you know how to configure the java.policy and java.security files in the corresponding JRE, as described below.

Back to top

IBM JCE Support in the WebSphere Runtime

As pointed out in the Introduction, the WebSphere Runtime has a built-in Sun JCE 1.2.1 framework and an IBM JCE service provider, which is similar to Sun JCE service provider except that IBM JCE service provider offers more algorithms. The JAR file for Sun JCE 1.2.1 framework resides in x:\wte_jre_installdir\lib\ext\ibmjcefw.jar, and the JAR file for IBM JCE service provider resides in x:\wte_jre_installdir\lib\ext\ibmjceprovider.jar, where x:\wte_jre_installdir is either:

• x:\Ws_installdir\runtimes\base_v5\java\jre, or
• x:\Ws_installdir\runtimes\express_v5\java\jre, or
• x:\Ws_installdir\runtimes\aes_v4\java\jre,

depending on which platform your application is targeted on.

If you open the java.security file in x:\wte_jre_installdir\lib\security, you can see the IBM JCE service provider has already been registered as one of the service providers, as shown below:

 
security.provider.1=sun.security.provider.Sun 
security.provider.2=com.ibm.crypto.provider.IBMJCE 
security.provider.3=com.ibm.jsse.IBMJSSEProvider 
security.provider.4=com.ibm.security.cert.IBMCertPath 
security.provider.5=com.ibm.crypto.pkcs11.provider.IBMPKCS11 

And if you open the java.policy file in x:\wte_jre_installdir\lib\security, you can see that both ibmjcefw.jar and ibmjceprovider.jar have all the security permissions, as shown below:

 
grant codeBase "file:${java.home}/lib/ext/*" { 
   permission java.security.AllPermission; 
}; 

As a result, you can use the JCE API with IBM JCE service provider seamlessly in your server-side components. All you need to do is include ibmjcefw.jar and ibmjceprovider.jar into the build path of your projects.

Back to top

Using Sun JCE Provider in the WebSphere Runtime

Follow these steps to configure the WebSphere Runtime in Application Developer to use Sun JCE provider. Because the Sun JCE 1.2.1 Framework has been included in the JRE for the WebSphere Runtime, it's best, for compatibility reasons, to use Sun JCE provider that comes with the Sun JCE 1.2.1 download. In this section, x:\wte_jre_installdir is the JRE installation folder of the WebSphere Runtime, as discussed in the previous section.

1. Download Sun JCE.
2. Unzip the download file. This will create a directory named X:\Sun_JCE_dir with subdirectories doc and lib. The lib subdirectory contains the JCE framework, for example jce1_2_1.jar, and Sun JCE provider, sunjce_provider.jar. The lib subdirectory also contains the JAR files for the jurisdiction policy files: US_export_policy.jar and local_policy.jar.
3. Grant the permission to sunjce_provider.jar. The following permissions should be granted to Sun JCE provider (and other JCE providers if you are using another vendor's implementation):
   • java.io.FilePermission to read the sunjce_provider.jar file
   • java.lang.RuntimePermission to get class protection domains
   • java.security.SecurityPermission to put (set) provider properties

   Edit the java.policy file in x:\wte_jre_installdir\lib\security and add this statement:

   grant codeBase "file:///X:\Sun_JCE_dir\lib\sunjce_provider.jar" { permission java.io.FilePermission "X:\Sun_JCE_dir\lib\sunjce_provider.jar", "read"; permission java.lang.RuntimePermission "getProtectionDomain"; permission java.security.SecurityPermission "putProviderProperty.SunJCE"; };

   
   

   All JAR files in x:\wte_jre_installdir\lib\ext have been granted java.security.AllPermission. Therefore, if you copy sunjce_provider.jar to x:\wte_jre_installdir\lib\ext, you may skip Step 3. You don't need to grant permission to jce1_2_1.jar because the built-in JCE framework will be used.

4. Register Sun JCE provider, which you can do either statically or dynamically:

   Static registration

   Add Sun JCE provider to your list of approved providers by editing the security properties file java.security in x:\wte_jre_installdir\lib\security\. The java.security file should have a statement for each provider to be registered statically. Each such statement declares a provider and specifies its preference order n, which is the order in which providers are searched for requested algorithms when no specific provider is requested. Preference order 1 is the most preferred, followed by 2, and so on.

   In the JRE for the WebSphere Test Environment, these five static providers have been pre-configured:

   security.provider.1=sun.security.provider.Sun security.provider.2=com.ibm.crypto.provider.IBMJCE security.provider.3=com.ibm.jsse.IBMJSSEProvider security.provider.4=com.ibm.security.cert.IBMCertPath security.provider.5=com.ibm.crypto.pkcs11.provider.IBMPKCS11

   
   

   These five security providers may have implemented the algorithms you need. Therefore, you may not need another security provider for your applications. These five security providers are needed for the WebSphere Runtime. Do not replace or remove these five lines, or the WebSphere Runtime may fail to start up properly.

   To configure other providers, follow those five security providers with other lines of the proper format, replacing the class name with the fully qualified master class name you obtain from the provider vendor, and entering the priority that you want to assign to the provider. For example, to configure Sun JCE as your #6 preferred provider, add the following line to the java.security file after the line for Sun JCE provider:

   security.provider.6=com.sun.crypto.provider.SunJCE

   
   

   Dynamic registration

   To register Sun JCE provider dynamically, add the following lines of code at the beginning of your program:

   Security.addProvider( new com.sun.crypto.provider.SunJCE());

   
   

   The above code will add Sun JCE provider as the last-approved security provider in the security registry. Since different providers may implement the same algorithms, if Sun JCE provider is the last one in the preference order, and no specific provider is requested, Sun JCE provider may not be picked as the service provider for algorithms that are also implemented by other providers. Therefore, you may want to add Sun JCE provider as the first one in the approved list by using this code:

   Security.insertProviderAt( new com.sun.crypto.provider.SunJCE(),1);

   
   

Back to top

Using IBM JCE Provider for standalone Java applications

IBM JCE provider is not pre-configured in the default JRE for standalone Java applications. You can either configure IBM JCE provider for the default JRE for standalone Java supplications, or choose the WebSphere Runtime JRE for standalone Java applications to avoid further configuration.

Following these steps to choose the WebSphere Runtime JRE for a standalone Java application:

1. Open the Java perspective and select Run => Run from the menu.
2. From the Launch configurations window, select Java Application.
3. Click New to create a new configuration.
4. Provide a name for the new configuration, for example, JCETest.
5. From the Main tab, select the project and the main class name of the Java application.
6. Switch to the JRE tab, and choose one of the WebSphere runtime JREs from the drop-down list, as shown in Figure 1 below.
7. Click Apply so that the configuration takes effect immediately.
8. Click Run to run the Java application.

Back to top

Using Sun JCE Provider for standalone Java applications

Because the JCE framework exists in the default JRE for Java applications, you may use any version of the Sun JCE download. In this section, Sun JCE 1.2.2 is used and x:\Ws_installdir\eclipse\jre stands for the JRE install directory as discussed in the previous section. Follow these steps to configure Sun JCE provider for standalone Java applications. If you copy jce_1_2_2.jar and sunjce_provider.jar to x:\Ws_installdir\eclipse\jre\lib\ext, you can skip Steps 4 and 5.

1. Make sure that the installation folder of Application Developer doesn't have space as described in the section titled Java Run Environments in Application Developer.
2. Download JCE 1.2.2.
3. Unzip the download file jce-1_2_2.zip. This will create a directory named JCE1.2.2 with subdirectories doc and lib. This article assumes that the full path of the directory is D:\JCE1.2.2. The lib subdirectory contains jce1_2_2.jar and sunjce_provider.jar. The lib subdirectory also contains the JAR files for the jurisdiction policy files: US_export_policy.jar and local_policy.jar.
4. Grant the permission to jce1_2_2.jar. Grant the java.security.AllPermission to the JCE 1.2.2 framework (jce1_2_2.jar). Edit the java.policy file in x:\Ws_installdir\eclipse\jre\lib\security and add this statement:

   grant codeBase "file:///D:\JCE1.2.2\lib\jce1_2_2.jar" { permission java.security.AllPermission; };

   
   
5. Grant the permission to sunjce_provider.jar. The following permissions should be granted to Sun JCE provider (and other JCE providers if you are using another vendor's implementation):
   • java.io.FilePermission to read the sunjce_provider.jar file
   • java.lang.RuntimePermission to get class protection domains
   • java.security.SecurityPermission to put (set) provider properties
   Edit the java.policy file in x:\Ws_installdir\eclipse\jre\lib\security and add this statement:

   grant codeBase "file:///D:\JCE1.2.2\lib\sunjce_provider.jar" { permission java.io.FilePermission "D:\JCE1.2.2\lib\sunjce_provider.jar", "read"; permission java.lang.RuntimePermission "getProtectionDomain"; permission java.security.SecurityPermission "putProviderProperty.SunJCE"; };

   
   
6. Register Sun JCE provider, which you can do either statically or dynamically:

   
   Static registration

   Add Sun JCE provider to your list of approved providers by editing the security properties file java.security in x:\Ws_installdir\eclipse\jre\lib\security\. The java.security file should have a statement for each provider to be registered statically. Each such statement declares a provider and specifies its preference order n, which is the order in which providers are searched for requested algorithms when no specific provider is requested. Preference order 1 is the most preferred, followed by 2, and so on.

   In the JRE for the standalone/client-side applications, Sun and IBMJCA have already been configured as static providers:

   security.provider.1=sun.security.provider.Sun security.provider.2=com.ibm.crypto.provider.IBMJCA

   
   

   Sun shouldn't be removed from the provider list. You may want to configure Sun JCE as your #3 preferred provider by adding the following line to the java.security file:

   security.provider.3=com.sun.crypto.provider.SunJCE

   
   

   Dynamic registration

   To register Sun JCE provider dynamically, add the following lines of code at the beginning of your program:

   Security.addProvider( new com.sun.crypto.provider.SunJCE());

   
   

   The above code will add Sun JCE provider as the last-approved security provider in the security registry. Since different providers may implement the same algorithms, if Sun JCE provider is the last one in the preference order, and no specific provider is requested, Sun JCE provider may not be picked as the service provider for algorithms that are also implemented by other providers. Therefore, you may want to add Sun JCE provider as the first one in the approved list by using this code:

   Security.insertProviderAt( new com.sun.crypto.provider.SunJCE(),1);

   
   

Back to top

Set the Java build path of your projects

You need to add jce1_2_2.jar (or ibmjcefw.jar) and sunjce_provider.jar into the Java build path of your projects that will use Sun JCE provider. You need to add ibmjcefw.jar and ibmjceprovider.jar into the Java build path of your project that will use IBM JCE provider. If you are using JCE providers other than Sun JCE and IBM JCE, you also need to add the JAR files of those JCE providers to the Java build path. To set the Java build path of your projects:

1. From the Navigator view, right-click the project and select Properties.
2. From the Properties dialog, click Java build path from the left panel and Libraries from the right panel.
3. Select Add External JARs from the Select JAR file dialog. Navigate to D:\JCE1.2.2\lib\, and select both jce1_2_2.jar and sunjce_provider.jar.
4. Click OK to close the Properties dialog.

Back to top

Set the classpath of the server instance

If you are using Sun JCE provider for the server-side component, you also need to add sunjce_provider.jar into the classpath of the server instance with the following steps. You don't need to include the Sun JCE framework into the classpath of the server instance because Sun JCE framework 1.2.1 already exists in the WebSphere runtime JRE. Follow these steps to add sunjce_provider.jar into the classpath of the server instance:

1. Open the Server perspective. From the Server Configuration view, double-click the server instance you defined for unit testing. The default server instance is named WebSphere Test Environment.
2. After the editor for the server instance opens, click the Paths tab. From the ws.ext.dirs panel, click Add External JARS.
3. From the Select JAR file dialog, navigate to D:\JCE1.2.2\lib\ and select sunjce_provider.jar.
4. Save the change.

Back to top

Run the sample code

You can download the sample code (sample.zip). It uses dynamic registration for Sun JCE provider. The sample.zip file contains two files: SampleTest.jar, which is a standalone application, and jceweb.ear, which is an enterprise application archive (EAR) file. The sample code generates a new secret key and uses it to encrypt and decrypt data. Remember that you need to modify java.policy before you test the sample code.

Use SampleTest.jar

1. Create a Java project and import SampleTest.jar into it.
2. Modify the classpath of the project accordingly.
3. Open the Java perspective. Click jce.test.SimpleTest.java.
4. Select Run => Run.
5. From the Launch Configurations window, select Java Application.
6. Click New to create a new configuration.
7. Provide a name for the new configuration, for example, SimpleEncryptionTest.
8. From the Main tab, you can see the Project and Main class information has been filled in automatically. If you haven't clicked jce.test.SimpleTest.java before Step 4, you need to fill in the information manually.
9. Switch to the Arguments tab and enter -e HelloWorld as the Program arguments. This will encrypt the string HelloWorld with the generated secret key.
10. Click Apply to allow the configuration to take effect immediately.
11. Click Run to run the Java application. The output of this program should be similar to:

    the encrypted data is:q5PzaXaKB0//0LMiGV2hLQ==

    
    
    A secret key is generated at the first time you run jce.test.SimpleTest.java. This secret key will be serialized into a file and will be used for the subsequent launch of jce.test.SimpleTest.java. Since the secret key is generated dynamically, it is normal that the encrypted data you get after you launch jce.test.SimpleTest.java is different from the above.
12. Repeat Steps 4 through 8 to create a new configuration named SimpleDecryptonTest. From the Arguments tab, enter -d and enter the encrypted string you got from Step 11 (for example, -d q5PzaXaKB0//0LMiGV2hLQ==) as the program arguments.
13. Run jce.test.SimpleTest.java again. The output will be:

    the decrypted data is: HelloWorld

    
    
14. You might want to replace HelloWorld with other data (perhaps including a space as in Good Morning) and test the encryption/decryption algorithm again.

Use jceweb.ear

1. Import jceweb.ear into the workspace and use any name you want for the enterprise project. A Web project named JCEWeb is created. The enterprise project and Web project are J2EE 1.3 compliant.
2. Change the Java build path of the Web project accordingly.
3. Create a Version 5 server instance and configuration from the Server perspective and make sure you have included the sunjce_provider.jar in the classpath of the server instance.
4. Make sure that the server configuration editor is closed. Add the enterprise project to the server configuration.
5. Right-click JCETestBeanInputForm.html in the folder Web Content under the Web project JCEWeb and select Run on server. You should see the browser open with a page like this:
   Figure 2
   
   
6. Click Submit and you will see output as in Figure 3. The output data may be different because of the secret key generated the first time you run this application.
   Figure 3
   
   
7. From the result page, select Decrypt from the Combo box and click Submit as shown in Figure 4:
   Figure 4
   
   
8. You will see the encrypted text will be decrypted to the original text as in Figure 5:
   Figure 5
   
   
9. You might want to replace HelloWorld with other data (perhaps including a space as in Good Morning) and test the encryption/decryption algorithms in a server component again.

Back to top

Download

Name	Size	Download method
sample.zip	15 KB	FTP|HTTP

Information about download methods

About the author

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Java Runtime Environments in Application Developer
• IBM JCE Support in the WebSphere Runtime
• Using Sun JCE Provider in the WebSphere Runtime
• Using IBM JCE Provider for standalone Java applications
• Using Sun JCE Provider for standalone Java applications
• Set the Java build path of your projects
• Set the classpath of the server instance
• Run the sample code
• Download
• About the author
• Comments

Local resources

• IBM Innovation Center - Austin, TX
• IBM Innovation Center - Chicago, IL
• IBM Innovation Center - Dallas, TX
• IBM Innovation Center - San Mateo, CA
• IBM Innovation Center - Waltham, MA
• Technical Briefings in North America

Dig deeper into WebSphere on developerWorks

Try IBM PureSystems. No charge.

Experience today!

---

Get started with the cloud-based trial and pattern development kit.

Special offers