Secure transports with JSSE and JCE programming interfaces


 

Overview

JSSE provides the transport security for WAS. JSSE provides the API framework and the implementation of the APIs for SSL and TLS protocols, including functionality for data encryption, message integrity, and authentication.

JSSE APIs are integrated into J2SDK V5. The API package for JSSE APIs is...

javax.net.ssl.*

Documentation for using JSSE APIs can be found in the J2SE 6 API documentation

Several JSSE providers ship with the Java 2 SDK V5 that comes with WAS. The IBMJSSE provider is used in previous WAS releases. Associated with the IBMJSSE provider is the IBMJSSEFIPS provider, which is used when FIPS is enabled on the server. Both of these providers do not work with the JMS and HTTP transports in WAS V7.0. These transports take advantage of the J2SDK Verison 5 network input/output (NIO) asynchronous channels.

There is a new IBMJSSE2 provider.

 

Customizing JSSE

We can customize a number of aspects of JSSE by plugging in different implementations of Cryptography Package Provider, X509Certificate and HTTPS protocols, or specifying different default keystore files, key manager factories, and trust manager factories.

The following table summarizes which aspects can be customized, what the defaults are, and which mechanisms are used to provide customization. We can customize the following key aspects:


Table 1. Customizable items

Customizable item Default Property
X509Certificate X509Certificate implementation from IBM cert.provider.x509v1
HTTPS protocol Implementation from IBM java.protocol.handler.pkgs
Cryptography Package Provider IBMJSSE2 security.provider.n=
Default keystore None javax.net.ssl.keyStore
Default truststore jssecacerts, if it exists. Otherwise, cacerts javax.net.ssl.trustStore
Default key manager factory IbmX509 ssl.KeyManagerFactory.algorithm
Default trust manager factory IbmX509 ssl.TrustManagerFactory.algorithm

For aspects that we can customize by setting a system property, statically set the system property by using the -D option of the Java command. We can set the system property using the admin console, or set the system property dynamically by calling the java.lang.System.setProperty method in the code:

System.setProperty(propertyName,"propertyValue")

For aspects that we can customize by setting a Java security property, statically specify a security property value in the java.security properties file. The security property is propertyName=propertyValue. Dynamically set the Java security property by calling the java.security.Security.setProperty method in the code.

The java.security properties file is located in the following directory:

APP_ROOT/java/jre/lib/security directory.

 

Application Programming Interface

The JSSE provides a standard API that is available in packages of the javax.net file, javax.net.ssl file, and the javax.security.cert file. The APIs cover:

We can find more information documented for the JSSE APIs if we access the following information:

Version 1.6

  1. Access the http://www.ibm.com/developerworks/java/jdk/security/ Web site.

  2. Click Java 1.6.

  3. Click Java doc HTML documentation in the JSSE Guide section.

 

Samples using JSSE

The JSSE also provides samples to demonstrate its functionality. The JSSE also provides samples to demonstrate its functionality. We can access the samples in the following location:

Version 1.6

  1. Access the http://www.ibm.com/developerworks/java/jdk/security/ Web site.

  2. Click Java 1.6.

  3. Click jssedocs_samples.zip in the JSSE Guide section.
Look for the following files:


Table 2. Extracted files

Files Description
ClientJsse.java Demonstrates a simple client and server interaction using JSSE. All enabled cipher suites are used.
OldServerJsse.java Back-level samples
ServerPKCS12Jsse.java Demonstrates a simple client and server interaction using JSSE with the PKCS12 keystore file. All enabled cipher suites are used.
ClientPKCS12Jsse.java Demonstrates a simple client and server interaction using JSSE with the PKCS12 keystore file. All enabled cipher suites are used.
UseHttps.java Demonstrates accessing an SSL or non-SSL Web server using the Java protocol handler of the com.ibm.net.ssl.www.protocol class. The URL is specified with the http or https prefix. The HTML that is returned from this site is displayed.

See more instructions in the source code. Follow these instructions before you run the samples.

 

Permissions for Java 2 security

We might need the following permissions to run an application with JSSE: This list is for reference only.

For the IBMJSSE provider:

For the SUNJSSE provider:

 

Debugging

By configuring through the javax.net.debug system property, JSSE provides the following dynamic debug tracing: -Djavax.net.debug=true.

A value of true turns on the trace facility, provided that the debug version of JSSE is installed.

 

Documentation

See the Security: Resources for learning topic for documentation references to JSSE.

 

JCE

JCE provides cryptographic, key and hash algorithms for WAS. JCE provides a framework and implementations for encryption, key generation, key agreement, and Message Authentication Code (MAC) algorithms. Support for encryption includes symmetric, asymmetric, block and stream ciphers.

 

IBMJCE

The IBM version of the Java Cryptography Extension (IBMJCE) is an implementation of the JCE cryptographic service provider used in WAS. The IBMJCE is similar to SunJCE, except that the IBMJCE offers more algorithms:

The IBMJCE belongs to the com.ibm.crypto.provider.* packages.

For further information, see the information on JCE on the following web site: http://www.ibm.com/developerworks/java/jdk/security/60/.

 

IBMJCEFIPS

The IBM version of the Java Cryptography Extension FIPS (IBMJCEFIPS) is an implementation of the JCE cryptographic service provider used in WAS. The IBMJCEFIPS service provider implements the following:

 

Application Programming Interface

JCE has a provider-based architecture. Providers can be plugged into the JCE framework by implementing the APIs defined by the JCE. The JCE APIs cover:

There is more information documented for the JCE APIs on the http://www.ibm.com/developerworks/java/jdk/security/ Web site.

 

Samples using Java Cryptography Extension

There are samples located on the http://www.ibm.com/developerworks/java/jdk/security/ Web site in the jceDocs_samples.zip file. Unzip the file and locate the following samples in the jceDocs/samples directory:

File Description
SampleDSASignature.java Generate a pair of DSA keys (a public key and a private key) and use the key to digitally sign a message using the SHA1withDSA algorithm
SampleMarsCrypto.java Generate a Mars secret key, and how to do Mars encryption and decryption
SampleMessageDigests.java Use the message digest for MD2 and MD5 algorithms
SampleRSACrypto.java Generate an RSA key pair, and how to do RSA encryption and decryption
SampleRSASignatures.java Generate a pair of RSA keys (a public key and a private key) and use the key to digitally sign a message using the SHA1withRSA algorithm
SampleX509Verification.java Verify X509 certificates

 

Documentation

Refer to the Security: Resources for learning topic for documentation on JCE.



 

Related tasks

Develop extensions to the WebSphere security infrastructure

 

Related

Security: Links