Secure transports with JSSE and JCE programming interfaces

Operating Systems: i5/OS
Personalize the table of contents and search results

Secure transports with JSSE and JCE programming interfaces

This topic provides detailed information about transport security using Java Secure Socket Extension (JSSE) and Java Cryptography Extension (JCE) programming interfaces. Within this topic, there is a description of the IBM version of the Java Cryptography Extension Federal Information Processing Standard (IBMJCEFIPS).

Java Secure Socket Extension

Java Secure Socket Extension (JSSE) provides the transport security for WebSphere Application Server. JSSE provides the API framework and the implementation of the APIs for Secure Sockets Layer (SSL) and Transport Layer Security (TLS) protocols, including functionality for data encryption, message integrity, and authentication.

JSSE APIs are integrated into the Java 2 SDK, Standard Edition (J2SDK), V5. The API package for JSSE APIs is javax.net.ssl.*. Documentation for using JSSE APIs can be found in the J2SE 5 API documentation that is located at http://java.sun.com/j2se/1.5.0/docs/api/index.html.

Several JSSE providers ship with the J2SDK V5 that comes with WebSphere Application Server. The IBMJSSE provider is used in previous WebSphere Application Server 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 Java Message Service (JMS) and HTTP transports in WebSphere Application Server V6.1. These transports take advantage of the J2SDK Verison 5 network input/output (NIO) asynchronous channels.

For more information on the new IBMJSSE2 provider, please review the documentation located in the http://www.ibm.com/developerworks/java/jdk/security/142/jsse2docs.zip file. After it is unzipped, the JSSE2 Reference Guide can be found at jsse2Docs/JSSE2RefGuide.html, the JSSE2 API documentation can be found at jsse2Docs/api/index.html and finally, the JSSE2 samples can be found at jsse2Docs/samples.

Customizing Java Secure Socket Extension

You 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. You can customize the following key aspects:

Customizable item Default How to customize
X509Certificate X509Certificate implementation from IBM The cert.provider.x509v1 security property
HTTPS protocol Implementation from IBM The java.protocol.handler.pkgs system property
Cryptography Package Provider IBMJSSE2 A security.provider.n= line in security properties file. See description.
Default keystore None The * javax.net.ssl.keyStore system property
Default truststore jssecacerts, if it exists. Otherwise, cacerts The * javax.net.ssl.trustStore system property
Default key manager factory IbmX509 The ssl.KeyManagerFactory.algorithm security property
Default trust manager factory IbmX509 The ssl.TrustManagerFactory.algorithm security property


Customizable item	Default	How to customize
X509Certificate	X509Certificate implementation from IBM	The cert.provider.x509v1 security property
HTTPS protocol	Implementation from IBM	The java.protocol.handler.pkgs system property
Cryptography Package Provider	IBMJSSE2	A security.provider.n= line in security properties file. See description.
Default keystore	None	The * javax.net.ssl.keyStore system property
Default truststore	jssecacerts, if it exists. Otherwise, cacerts	The * javax.net.ssl.trustStore system property
Default key manager factory	IbmX509	The ssl.KeyManagerFactory.algorithm security property
Default trust manager factory	IbmX509	The ssl.TrustManagerFactory.algorithm security property

For aspects that you can customize by setting a system property, statically set the system property by using the -D option of the Java command. You can set the system property using the administrative console, or set the system property dynamically by calling the java.lang.System.setProperty method in your code: System.setProperty(propertyName,"propertyValue").

For aspects that you 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 your code.

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

profile_root/properties 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:

Sockets and SSL sockets
Factories to create the sockets and SSL sockets
Secure socket context that acts as a factory for secure socket factories
Key and trust manager interfaces
Secure HTTP URL connection classes
Public key certificate API

You can find more information documented for the JSSE APIs if you access the following information:

V1.4.2

Access the http://www.ibm.com/developerworks/java/jdk/security/ Web site.
Click Java 1.4.2.
Click Javadoc HTML documentation in the Java Secure Socket Extension (JSSE) Guide section.

Samples using Java Secure Socket Extension

The Java Secure Socket Extension (JSSE) also provides samples to demonstrate its functionality. The Java Secure Socket Extension (JSSE) also provides samples to demonstrate its functionality. You can access the samples in the following location:

V1.4.2

Access the http://www.ibm.com/developerworks/java/jdk/security/ Web site.
Click Java 1.4.2.
Click jssedocs_samples.zip in the Java Secure Socket Extension (JSSE) Guide section.

Look for the following 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.


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

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

java.util.PropertyPermission "java.protocol.handler.pkgs", "write"
java.lang.RuntimePermission "writeFileDescriptor"
java.lang.RuntimePermission "readFileDescriptor"
java.lang.RuntimePermission "accessClassInPackage.sun.security.x509"
java.io.FilePermission "${user.install.root}${/}etc${/}.keystore", "read"
java.io.FilePermission "${user.install.root}${/}etc${/}.truststore", "read"

For the IBMJSSE provider:

java.security.SecurityPermission "putProviderProperty.IBMJSSE"
java.security.SecurityPermission "insertProvider.IBMJSSE"

For the SUNJSSE provider:

java.security.SecurityPermission "putProviderProperty.SunJSSE"
java.security.SecurityPermission "insertProvider.SunJSSE"

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

Java Cryptography Extension (JCE) provides cryptographic, key and hash algorithms for WebSphere Application Server. 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 that is used in WebSphere Application Server. The IBMJCE is similar to SunJCE, except that the IBMJCE offers more algorithms:

Cipher algorithm (AES, DES, TripleDES, PBEs, Blowfish, and so on)
Signature algorithm (SHA1withRSA, MD5withRSA, SHA1withDSA)
Message digest algorithm (MD5, MD2, SHA1, SHA-256, SHA-384, SHA-512)
Message authentication code (HmacSHA1, HmacMD5)
Key agreement algorithm (DiffieHellman)
Random number generation algorithm (IBMSecureRandom, SHA1PRNG)
Key store (JKS, JCEKS, PKCS12, JCERACFKS [z/OS only])
Key store (JKS, JCEKS, PKCS12, JCERACFKS [z/OS only])

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

For further information, see the information on JCE on the following web site:

IBMJCEFIPS

The IBM version of the Java Cryptography Extension Federal Information Processing Standard (IBMJCEFIPS) is an implementation of the JCE cryptographic service provider that is used in WebSphere Application Server. The IBMJCEFIPS service provider implements the following:

Signature algorithms (SHA1withDSA, SHA1withRSA)
Cipher algorithms (AES, TripleDES, RSA)
Key agreement algorithm (DiffieHellman)
Key (pair) generator (DSA, AES, TripleDES, HmacSHA1, RSA, DiffieHellman)
Message authentication code (MAC) (HmacSHA1)
Message digest (MD5, SHA-1, SHA-256, SHA-384, SHA-512)
Algorithm parameter generator (DiffieHellman, DSA)
Algorithm parameter (AES, DiffieHellman, DES, TripleDES, DSA)
Key factory (DiffieHellman, DSA, RSA)
Secret key factory (AES, TripleDES)
Certificate (X.509)
Secure random (IBMSecureRandom)

Application Programming Interface

Java Cryptography Extension (JCE) has a provider-based architecture. Providers can be plugged into the JCE framework by implementing the APIs that are defined by the JCE. The JCE APIs cover:

Symmetric bulk encryption, such as DES, RC2, and IDEA
Symmetric stream encryption, such as RC4
Asymmetric encryption, such as RSA
Password-based encryption (PBE)
Key agreement
Message authentication codes

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 Demonstrates how to 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 Demonstrates how to generate a Mars secret key, and how to do Mars encryption and decryption
SampleMessageDigests.java Demonstrates how to use the message digest for MD2 and MD5 algorithms
SampleRSACrypto.java Demonstrates how to generate an RSA key pair, and how to do RSA encryption and decryption
SampleRSASignatures.java Demonstrates how to 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 Demonstrates how to verify X509 certificates


File	Description
SampleDSASignature.java	Demonstrates how to 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	Demonstrates how to generate a Mars secret key, and how to do Mars encryption and decryption
SampleMessageDigests.java	Demonstrates how to use the message digest for MD2 and MD5 algorithms
SampleRSACrypto.java	Demonstrates how to generate an RSA key pair, and how to do RSA encryption and decryption
SampleRSASignatures.java	Demonstrates how to 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	Demonstrates how to verify X509 certificates

Documentation

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