Using Java Secure Socket Extension and Java Cryptography Extension with Servlets and enterprise bean files

Java Secure Socket Extension

Java Secure Socket Extension (JSSE) provides the transport security for WebSphere Application Server. It provides application programming interface (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. With the JSSE APIs, other SSL or TLS protocols, and Public Key Infrastructure (PKI), implementations can plug in.

IBM Java Secure Socket Extension

The WebSphere Application Server uses the IBMJSSE provider, which is pre-installed and pre-registered with the Java Cryptography Architecture (JCA) of the Java 2 platform. IBMJSSE supports the following cryptographic services:

• Rivest Shamir Adleman (RSA) public key cryptography support

• SSL and TLS security protocols and common cipher suites

• X.509-based key and trust managers

• PKCS12 as JCA keystore type

The IBMJSSE provider is pre-registered in the java.security properties file located at install_root/java/jre/lib/security directory. It also supports cryptographic token types PKCS#7, PKCS#11, PKCS#12 and MSCAPI (only on Windows platforms) for cryptographic token support.

Note: The IBM Java Secure Socket Extension (JSSE) is currently not supported within applets.

Note: The IBM JSSE is not available on the HP-UX platform. On the HP-UX platform, use the Sun JSSE instead.

Customizing Java Secure Socket Extension

Note: Make sure you understand the implication to your application before you begin customizing.

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. A provided table summarizes which aspects can be customized, what the defaults are, and which mechanisms are used to provide customization. Some of the key customizable aspects follow:

Customizable item	Default	How to customize
X509Certificate	X509Certificate implementation from IBM	cert.provider.x509v1 security property
HTTPS protocol	Implementation from IBM	java.protocol.handler.pkgs system property
Cryptography Package Provider	IBMJSSE	A security.provider.n= line in security properties file. See description.
Default keystore	None	* javax.net.ssl.keyStore system property
Default truststore	jssecacerts, if it exists. Otherwise, cacerts	* javax.net.ssl.trustStore system property
Default key manager factory	IbmX509	ssl.KeyManagerFactory.algorithm security property
Default trust manager factory	IbmX509	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 located in the install_root/java/jre/lib/security directory. The security property is propertyName=propertyValue. Dynamically set the Java security property by calling the java.security.Security.setProperty method in your code.

Application Programming Interface

The JSSE provides a standard application programming interface (API) 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 UTL connection classes

• Public key certificate API

There is more information documented for the JSSE APIs in the http://www.ibm.com/developerworks/java/jdk/security/jsseDocs.zip file.

Samples using Java Secure Socket Extension

The Java Secure Socket Extension (JSSE) also provides samples to demonstrate its functionality. The samples are included in install_root/web/docs/jsse/samplejsse.jar. Unzip the file. The following files display:

The Java Secure Socket Extension (JSSE) also provides samples to demonstrate its functionality. Download and unzip the samples included in the http://www.ibm.com/developerworks/java/jdk/security/jsseDocs.zip file. Look in jsseDocs/samples/ directory for the following files:

Files	Description
ClientJsse.java	Demonstrates a simple client and server interaction using JSSE. All enabled cipher suites are used.
ClientJsseProvider.java	Demonstrates a simple client and server interaction using JSSE. All enabled cipher suites are used.
ServerJsse.java ServerJsseProvider.java OldClientJsse.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.
OldClientPKCS12Jsse.java	Back-level samples
OldServerPKCS12Jsse.java	Back-level samples
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 returned from this site displays.
HTTPTest.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 returned from this site is displayed.
HTTPSPanel.java OldHTTPTest.java	Back-level sample

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 is a reference list 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. Use the administrative console to set the system property for debugging the application server.

Documentation

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

JCE

Java Cryptography Extension (JCE) provides cryptographic, key and hash algorithms for WebSphere Application Server. It 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 Java Cryptography Extension (IBMJCE) is an implementation of the JCE cryptographic service provider 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)

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

Read install_root/web/docs/jce/readme.jce.ibm.html for further details.

For further information, see the http://www-106.ibm.com/developerworks/java/jdk/security/jceDocs.zip file.

The IBM JCE is not available on the HP-UX platform. On the HP-UX platform, use the SunJCE instead.

Application Programming Interface

Java Cryptography Extension (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 covers:

• 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

Refer to install_root/web/docs/jce/api_users_guide.html and install_root/web/docs/jce/CryptoSpec.html for more information about Java Cryptography Extension technology. Locate the Javadoc for the JCE APIs by unzipping install_root/web/docs/jce/jcedocs.jar.

For more information about Java Cryptography Extension technology including the JavaDoc for JCE APIs, see the http://www.ibm.com/developerworks/java/jdk/security/jceDocs.zip file.

Samples using Java Cryptography Extension

There are samples provided in SampleJCE.jar file located in the install_root/web/docs/jce directory. Unzip the file. The following source code displays:

There are samples located in http://www.ibm.com/developerworks/java/jdk/security/jceDocs.zip file. Unzip the file and locate the following samples in thejceDocs/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 SHA1with DSA 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 Integrating IBM WebSphere Application Server security with existing security systems for documentation on JCE.

---

Configuring to use cryptographic tokens
    

 

---