Security information

The following pages contain documentation, example code, and ancillary files relating to IBM's SDKs. The documentation covers IBM-specific features of IBM's offerings. A platform-specific Security User Guide is included in each download. For information about the SDK for z/OS product and security components specific to that platform, see this Web site.

Before you can download code, you will need an IBM Registration ID. You can read about IBM Registration here.

Java^TM Secure Socket Extension (JSSE) (1.0.3)

Reference Guide

for the Java 2 SDK, Standard Edition, v 1.4.2

Copyright Information

Note: Before using this information and the product it supports, be sure to read the general information under Notices.

(c) Copyright Sun Microsystems, Inc. 1998, 2004, 901 San Antonio Rd., Palo Alto, CA 94303 USA. All rights reserved.

(c) Copyright International Business Machines Corporation, 1998, 2004. All rights reserved.

U.S. Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

Contents

Introduction

Features and Benefits

JSSE Standard API

IBMJSSE Provider

What's New

What's New in JSSE in the Java 2 SDK, v 1.4.2

What's New in JSSE in the Java 2 SDK, 1.4

Known Differences Between IBM's JSSE and Sun's JSSE

Related Documentation

Terms and Definitions

Secure Sockets Layer (SSL) Protocol Overview

Why Use SSL?

How SSL Works

Key Classes

Relationship Between Classes

Core Classes and Interfaces

SocketFactory and ServerSocketFactory Classes

SSLSocket and SSLServerSocket Classes

SSLSocketFactory and SSLServerSocketFactory Classes

SSLSession Interface

HttpsURLConnection Class

Support Classes and Interfaces

SSLContext Class

TrustManager Class

TrustManagerFactory Class

X509TrustManager Interface

KeyManager Class

KeyManagerFactory Class

X509KeyManager Interface

Relationships between TrustManagers and KeyManagers

Secondary Support Classes and Interfaces

SSLSessionContext Interface

SSLSessionBindingListener Interface

SSLSessionBindingEvent Class

HandShakeCompletedListener Interface

HandShakeCompletedEvent Class

HostnameVerifier Interface

X509Certificate Class

Previous (JSSE 1.0.x) Implementation Classes and Interfaces

Customizing JSSE

The Installation Directory <java-home>

Customization

Additional Keystore Formats

Debugging Utility

Appendix A: Standard Names

Notices

Introduction

Data that travels across a network can easily be accessed by someone who is not the intended recipient. When the data includes private information, such as passwords and credit card numbers, steps must be taken to make the data unintelligible to unauthorized parties. It is also important to ensure that the data has not been modified, either intentionally or unintentionally, during transport. The Secure Sockets Layer (SSL) and Transport Layer Security (TLS) protocols were designed to help protect the privacy and integrity of data while it is transferred across a network.

The Java Secure Socket Extension (JSSE) enables secure Internet communications. It provides a framework and an implementation for a Java version of the SSL and TLS protocols and includes functionality for data encryption, server authentication, message integrity, and optional client authentication. Using JSSE, developers can provide for the secure passage of data between a client and a server running any application protocol, such as Hypertext Transfer Protocol (HTTP), Telnet, or FTP, over TCP/IP. (For an introduction to SSL, see Secure Sockets Layer (SSL) Protocol Overview.)

By abstracting the complex underlying security algorithms and "handshaking" mechanisms, JSSE minimizes the risk of creating subtle, but dangerous security vulnerabilities. Furthermore, it simplifies application development by serving as a building block that developers can integrate directly into their applications.

JSSE was previously an optional package (standard extension) to the Java 2 SDK, Standard Edition (J2SDK) versions 1.2 and 1.3. JSSE has now been integrated into the J2SDK, v 1.4.

JSSE provides both an application programming interface (API) framework and an implementation of that API. The JSSE API supplements the "core" cryptographic services defined in the Java 2 SDK, v 1.4 java.security and java.net packages by providing extended networking socket classes, trust managers, key managers, SSLContexts, and a socket factory framework for encapsulating socket creation behavior. It also provides a limited public key certificate API that is compatible with Java Development Kit (JDK) 1.1-based platforms. However, keep in mind that this limited javax.security.cert certificate API is provided only for backward compatibility with JSSE 1.0.x and should not be used. Instead, use the standard java.security.cert certificate API.

The JSSE API is capable of supporting SSL versions 2.0 and 3.0 and Transport Layer Security (TLS) 1.0. These security protocols encapsulate a normal bidirectional stream socket and the JSSE API adds transparent support for authentication, encryption, and integrity protection. The JSSE implementation in the J2SDK, v 1.4 implements SSL 2.0, SSL 3.0, and TLS 1.0.

As mentioned above, JSSE is a security component of the Java 2 platform, and is based on the same design principles found elsewhere in the Java Cryptography Architecture (JCA) framework. This framework for cryptography-related security components allows them to have implementation independence and, whenever possible, algorithm independence. JSSE uses the same "provider" architecture defined in the JCA.

Other security components in the Java 2 platform include the Java Cryptography Extension (JCE), the Java Authentication and Authorization Service (JAAS), and the Java Security Tools. JSSE encompasses many of the same concepts and algorithms as those in JCE but automatically applies them underneath a simple stream socket API.

The JSSE APIs were designed to allow other SSL/TLS protocol and Public Key Infrastructure (PKI) implementations to be plugged in seamlessly. Developers can also provide alternate logic for determining if remote hosts should be trusted or determining what authentication key material should be sent to a remote host.

Features and Benefits

JSSE includes the following important features:

• Implemented in 100% Pure Java
• Can be exported to most countries
• Provides API support and an implementation for SSL 2.0, SSL 3.0, and TLS 1.0
• Includes classes that can be instantiated to create secure channels (SSLSocket and SSLServerSocket)
• Provides support for cipher suite negotiation, which is part of the SSL handshaking used to initiate or verify secure communications
• Provides support for client and server authentication, which is part of the normal SSL handshaking
• Provides support for the Hypertext Transfer Protocol (HTTP) encapsulated in the SSL protocol (HTTPS), which allows access to data such as Web pages using HTTPS.
• Provides server session management APIs to manager memory-resident SSL sessions
• Provides RSA support for the signature-related JCA features of the Java 2 platform

JSSE Standard API

The JSSE standard API, available in the javax.net, javax.net.ssl and javax.security.cert packages, covers:

• Secure (SSL) sockets and server sockets.
• Factories for creating sockets, server sockets, SSL sockets, and SSL server sockets.  Using socket factories you can encapsulate socket creation and configuration behavior.
• A class representing a secure socket context that acts as a factory for secure socket factories.
• Key and trust manager interfaces (including X.509-specific key and trust managers), and factories for creating them.
• A class for secure HTTP URL connections.
• A public-key-certificate API that is compatible with JDK 1.1-based platforms.

IBMJSSE Provider

The J2SDK, v 1.4 release comes with a JSSE provider named "IBMJSSE", which comes pre-installed and pre-registered with the JCA. This provider supplies the following cryptographic services:

• RSA support for the signature-related JCA features of the Java 2 platform.
• An implementation of the SSL 2.0, SSL 3,0, and TLS 1.0 security protocols.
• An implementation of the most common SSL and TLS cipher suites that encompass a combination of authentication, key agreement, encryption, and integrity protection.
• An implementation of an X.509-based key manager that chooses appropriate authentication keys from a standard JCA KeyStore.
• An implementation of an X.509-based trust manager that implements a subset of the RFC 2459 rules for certificate chain path validation.
• Support for PKCS12 keystore type.

* Note:  Although anonymous cipher suites are enabled, the IBM JSSE TrustManager does not allow anonymous cipher suites.  The default implementation can be overridden by providing your own TrustManager that allows anonymous cipher suites.  See section Accepting Anonymous Cipher Suites in creating your own X509TrustManager.

What’s New

This section highlights the differences between the JSSE in releases 1.4.2 and 1.4 of the Java 2 Platform and earlier releases.

What's New in JSSE in the J2SDK, v 1.4.2

The following change was introduced in the JSSE in version 1.4.2 SR8 of the Java 2 platform:

• When IBM JSSE is used as a server, if the SSLv3 protocol is to be used for the handshake, it will no longer agree to use any of the AES cipher suites. Previously, the selection of the cipher suite was independent of the protocol selected so one could do an old-style SSLv3 handshake but a more modern AES cipher suite. The TLS protocol is not affected by this change. This change was required in order to support Microsoft Vista clients.
  

The following changes were introduced in the JSSE in version 1.4.2 of the Java 2 platform:

• The IBMJSSE implementation now supports a number of additional cipher suites. They include cipher suites using AES as a symmetric cipher and one new ephemeral Diffie-Hellman with an RSA authentication cipher. For more information, see the table of “Supported Cipher Suites” in the section IBMJSSE Provider.

What's New in JSSE in the J2SDK, v 1.4

Here are the differences between JSSE 1.0.3 and the JSSE within the J2SDK, v 1.4:

• JSSE Is Now in J2SDK
• javax.security.cert Should Not Be Used
• IBMJSSE Provider Can Use Secure Tokens
• Classes Formerly in com.ibm.net.ssl Are Now in javax.net.ssl
• New Methods and Interface
• Changed Classes and Methods
• Documentation Improvements

JSSE Is Now in J2SDK

JSSE was previously an optional package (extension) to the Java 2 SDK, Standard Edition (J2SDK), versions 1.2 and 1.3. JSSE has now been integrated into the J2SDK, v 1.4. The IBMJSSE provider is also included and is pre-registered in the java.security security properties file included with the J2SDK, v 1.4.

javax.security.cert Should Not Be Used

JSSE was developed before the java.security.cert package was widely available, so a supplemental certificate package called was introduced in earlier versions of JSSE. JSSE is now bundled into the J2SDK itself and takes advantage of the more complete certificate API available in the java.security.cert package. All new applications should use java.security.cert. The javax.security.cert package exists only for backward compatibility with previous JSSE releases, and should no longer be used.

IBMJSSE Provider Can Use Secure Tokens

The IBMJSSE provider can use secure tokens containing certificates, keys, and CRLs in an SSLContext. Secure tokens of type PKCS#7, PKCS#11, PKCS#12, and MSCAPI (only on Windows platforms) are supported.

Classes Formerly in com.ibm.net.ssl Are Now in javax.net.ssl

All of the classes and interfaces formerly (in JSSE 1.0.x) in the com.ibm.net.ssl package have been promoted to the javax.net.ssl package. The old com.ibm.net.ssl classes and interfaces still exist and are unchanged, but are included in the IBMJSSE provider only for backward compatibility and "wrappers" are provided that reference the new javax.net.ssl classes/interfaces.

New Methods and Interfaces

New methods setWantClientAuth and getWantClientAuth were added to SSLSocket and SSLServerSocket (in javax.net.ssl) to enable optional client authentication.

The method SSLContext.getInstance(protocol) returns socket factories that support the specified protocol. New methods setEnabledProtocols and getEnabledProtocols were added to SSLSocket and SSLServerSocket to further refine which protocols are enabled for use on this connection. Another new method getSupportedProtocols was added to SSLSocket and SSLServerSocket; getSupportedProtocols can be used to obtain the protocol versions that can be enabled for use on an SSL connection. The new method getProtocol was added to SSLSession for retrieving the standard name of the protocol used in the session.

SocketFactory and ServerSocketFactory have new methods createSocket and createServerSocket, respectively, for creating unconnected sockets.

New methods getServerSessionContext and getClientSessionContext were added to SSLContext. They allow developers to obtain the set of SSL client or server sessions that are available for reuse during handshaking.

New methods setSessionTimeout and getSessionTimeout were added to SSLSessionContext. They allow developers to control when sessions timeout and are no longer valid. New methods setSessionCacheSize and getSessionCacheSize were also added to control how many sessions should be cached for reuse by future connections.

New methods were added to HttpsURLConnection, SSLSession, and HandshakeCompletedEvent (all in javax.net.ssl) that allow you to get generic Java 2 java.security.cert.Certificate certificates in addition to the javax.security.cert.X509Certificate certificates returned by previously existing methods. The new methods are:

SSLSession.getPeerCertificates
HandshakeCompletedEvent.getPeerCertificates
HttpsURLConnection.getServerCertificates

A getLocalCertificates method was added to SSLSession, HandshakeCompletedEvent, and HttpsURLConnection. This method returns the certificates that were sent to the peer during handshaking. This action provides a way to determine what certificate chain was actually used to authenticate the local side of a given SSL session.

A new interface ManagerFactoryParameters was added as a base interface that providers can extend if they need KeyManagerFactory, or TrustManagerFactory (or both) initialization parameters other than the ones that can be passed to the KeyStore-based init methods of those classes. The KeyManagerFactory and TrustManagerFactory classes each have a new init method that takes a ManagerFactoryParameters argument. Users of a particular provider are expected to pass an implementation of the appropriate ManagerFactoryParameters as defined by the provider.

Changed Classes and Methods

When the com.ibm APIs were prepared for inclusion in the javax namespace, some API limitations were corrected in the javax version. The old com.ibm.* APIs found in the previous JSSE optional packages are still the same and have not changed. The changes described in the paragraphs below apply only to the new javax.* classes of the same name.

HttpsURLConnection

The HttpsURLConnection constructor has been changed to be protected. This change was done for consistency with other similar classes such as URLConnection, JarURLConnection, and HttpURLConnection, all in the java.net package. Another change to the HttpsURLConnection class is that the method that returned javax.security.cert certificates was removed.

isClientTrusted and isServerTrusted

The X509TrustManager isClientTrusted and isServerTrusted methods were renamed checkClientTrusted and checkServerTrusted, respectively. If the certificate chain is not trusted by this TrustManager, the checkClientTrusted and checkServerTrusted methods throw an exception rather than return a boolean (like the former methods did). This method allows implementations to ascertain the underlying cause for failure of the trust decision. The checks done by checkClientTrusted and checkServerTrusted include verifying that the certificate is used for an operation that complies with the certificate's key usage extension. To properly perform this check, it is necessary to pass the authentication type to these methods, and so a String authType argument has been added.

chooseClientAlias and chooseServerAlias

One parameter has been added and one changed for the X509KeyManager chooseClientAlias and chooseServerAlias methods. A Socket parameter was added to both methods for specifying the socket to be used for the connection. The keytype parameter for the chooseClientAlias method was changed from a single String to an array of Strings specifying the key algorithm type names, ordered with the most-preferred type first. For example, the chooseClientAlias method signature used to be:

chooseClientAlias(String keyType, Principal[] issuers)

and now it is:

chooseClientAlias(String[] keyType, Principal[] issuers, Socket socket)

The parameters help decide which certificates to use when connecting to a remote host.

Default Factory Algorithms

The default key manager factory algorithm name has been changed from javax.net.ssl.KeyManagerFactory.type to ssl.KeyManagerFactory.algorithm. Similarly, the default trust manager factory algorithm name has been changed from javax.net.ssl.TrustManager.type to ssl.TrustManagerFactory.algorithm.

Documentation Improvements

This JSSE Reference Guide was updated and expanded.

There were a number of minor clarifications made to the JSSE javadocs, primarily when discussing illegal arguments and implied behavior.

Known Differences between the IBM JSSE and the Sun JSSE

Known differences between the IBM JSSE and the Sun JSSE implementation are described below.  These differences do not affect API specifications or JSSE architecture.  See the appropriate sections of the document for details.

• IBM JSSE Provider is called “com.ibm.jsse.IBMJSSEProvider”.
• IBM KeyManagerFactory is called “IbmX509”.
• IBM TrustManagerFactory is called “IbmX509”.
• IBM HTTPS protocol handler is called “com.ibm.net.ssl.www.protocol.Handler”.
• Classes that Sun has in com.sun.net.ssl are in com.ibm.net.ssl in the IBM JSSE implementation.
• IBM implementation supports the following protocols: “SSL”, “SSLv3”, “SSLv2”, “TLS”, “TLSv1”, and “SSL_TLS” for engine class SSLContext or the API setEnabledProtocols in the SSLSocket or SSLServerSocket classes. The IBM implementation does not support “SSLv2Hello” protocol. The IBM implementation supports the SSL v2 protocol. The IBM SSLContext getInstance factory method can be used to control which protocols actually get enabled for an SSL connection. Using the SSLContext getInstance or the setEnabledProtocols method give the same result. However the Sun JSSE controls the actual protocol which is enabled through the setEnabledProtocols method.
• IBM and Sun support different ciphers.  See Supported Cipher Suites for a list of ciphers that the IBM JSSE supports.
• IBM JSSE framework allows the addition of other JSSE providers.  The Sun framework currently does not.
• The IBM JSSE implementation uses an internal cryptographic provider.
• The IBM JSSE TrustManager does not allow anonymous ciphers.  In order to handshake on an anonymous cipher, a custom TrustManager that allows anonymous ciphers must be provided.  See section Accepting Anonymous Cipher Suites in creating your own X509TrustManager.
• When a null KeyManager is passed to SSLContext, theIBM JSSE KeyManagerFactory implementation will check system properties, then jssecacerts if it exists, and finally use cacerts file to find the key material.  The Sun JSSE will create an empty KeyManager.  See KeyManager Class for further information.
• The IBM JSSE X509TrustManager and X509KeyManager will throw an exception if the TrustStore or KeyStore specified by system properties does not exist, if the password is incorrect or if the keystore type is inappropriate for the actual keystore.  The Sun X509TrustManager will create a default TrustManager or KeyManager with an empty keystore.
• The IBM JSSE requires you to have the trusted certificate in your Trusted Keystore. The Sun JSSE considers a certificate trusted if you have the private key.
• The IBM JSSE implementation will verify the entire server or client certificate chain, including trusted certificates.  For example, if a trusted certificate has expired, the handshake will fail, even though the expired certificate is trusted.  The Sun JSSE will verify the certificate chain up to the trusted certificate.  Verification will stop when it reaches a trusted certificate and the trusted certificate and beyond will not be verified.
• With the IBM JSSE implementation, tracing is turned on by “javax.net.debug=true”. Complete tracing requires the debug version of IBMJSSE.
• The IBM JSSE implementation returns the same set of supported ciphers for the methods getDefaultCiphersSuites and getSupportedCipherSuites.  The Sun JSSE getDefaultCipherSuites returns the list of cipher suites that provide confidentiality, protection, and server authentication (that is, no anonymous cipher suites).  The Sun getEnabledCipherSuites returns the entire list of cipher suites that Sun supports.
• For the Sun implementation, DSA server certificates can use only *_DH*_* cipher suites.  For the IBM implementation, if the Server has a DSA certificate only and only RSA* ciphers are enabled, the connection succeeds with an RSA cipher.  DSA will be used for authentication and ephemeral RSA will be used for the key exchange.
• The IBM JSSE implementation does not support the new TrustManager that implements rules for certificate chain path validation that Sun added to 1.4.2.  The new IBMJSSE Provider2 contains this support.

Related Documentation

Java Secure Socket Extension Documentation

JSSE API documentation:

• javax.net package
• javax.net.ssl package
• javax.security.cert package

Java 2 Platform Security Documentation

• Java 2 security homepage:
  http://java.sun.com/security/
• Links to more Java 2 platform security documents:
  http://java.sun.com/j2se/1.4.2/docs/guide/security/index.html
• Tutorial for Java 2 platform security:
  http://java.sun.com/docs/books/tutorial/security1.2/
• Book on Java 2 platform security:
  Inside Java 2 Platform Security: Architecture, API Design, and Implementation by Li Gong. Addison Wesley Longman, Inc., 1999. ISBN: 0201310007.

Export Issues Related to Cryptography

For information on U.S. encryption policies, refer to these Web sites:

• U.S. Department of Commerce:
  http://www.commerce.gov/
• Export Policy Resource Page:
  http://www.crypto.com/
• Computer Systems Public Policy:
  http://www.cspp.org/
• Federal Information Processing Standards Publications (FIPS PUBS) homepage, which has links to the Data Encryption Standard (DES):
  http://www.itl.nist.gov/fipspubs/
• Revised U.S. Encryption Export Control Regulations:
  http://www.epic.org/crypto/export_controls/regs_1_00.html

Cryptography Documentation

Online resources:

• Dr. Rivest's Cryptography and Security page:
  http://theory.lcs.mit.edu/~rivest/crypto-security.html

Books:

• Applied Cryptography, Second Edition by Bruce Schneier. John Wiley and Sons, Inc., 1996.
• Cryptography Theory and Practice by Doug Stinson. CRC Press, Inc., 1995.
• Cryptography & Network Security: Principles & Practice by William Stallings. Prentice Hall, 1998.

Secure Sockets Layer Documentation

Online resources:

• The SSL Protocol version 3.0 Internet Draft:
  http://wp.netscape.com/eng/ssl3/ssl-toc.html
• The TLS Protocol version 1.0 Internet Draft:
  http://www.ietf.org/rfc/rfc2246.txt
• "HTTP Over TLS" Information RFC:
  http://www.ietf.org/rfc/rfc2818.txt

Books:

• SSL and TLS: Designing and Building Secure Systems by Eric Rescorla. Addison Wesley Professional, 2000.
• SSL and TLS Essentials: Securing the Web by Stephen Thomas. John Wiley and Sons, Inc., 2000.
• Java 2 Network Security, Second Edition, by Marco Pistoia, Duane F Reller, Deepak Gupta, Milind Nagnur, and Ashok K Ramani. Prentice Hall, 1999. Copyright 1999 International Business Machines.
• Enterprise Java Security: Building Secure J2EE Applications, by Marco Pistoia, Nataraj Nagaratnam, Larry Koved, and Anthony Nadalin.  Addison Wesley, 2004.

Terms and Definitions

There are several terms relating to cryptography that are used within this document. This section defines some of these terms.

Authentication

Authentication is the process of confirming the identity of a party with whom you are communicating.

Cipher Suite

A cipher suite is a combination of cryptographic parameters that define the security algorithms and key sizes used for authentication, key agreement, encryption, and integrity protection.

Certificate

A certificate is a digitally signed statement vouching for the identity and public key of an entity (person, company, and so on.). Certificates can either be self-signed or issued by a Certification Authority (CA). Certification Authorities are entities that are trusted to issue valid certificates for other entities. Well-known CAs include VeriSign, Entrust, and GTE CyberTrust. X509 is a common certificate format, and certificates in this format can be managed by the JDK keytool.

Cryptographic Hash Function

A cryptographic hash function is similar to a checksum. Data is processed with an algorithm that produces a relatively small string of bits called a hash. A cryptographic hash function has three primary characteristics: it is a one-way function, meaning that it is not possible to produce the original data from the hash; a small change in the original data produces a large change in the resulting hash; and it does not require a cryptographic key.

Cryptographic Service Provider

In the JCA, implementations for various cryptographic algorithms are provided by cryptographic service providers, or "providers" for short. Providers are essentially packages that implement one or more engine classes for specific algorithms. An engine class defines a cryptographic service in an abstract fashion without a concrete implementation.

Digital Signature

A digital signature is the digital equivalent of a handwritten signature. It is used to ensure that data transmitted over a network was sent by whoever claims to have sent it and that the data has not been modified in transit. For example, an RSA-based digital signature is calculated by first computing a cryptographic hash of the data and then encrypting the hash with the sender's private key.

Encryption and Decryption

Encryption is the process of using a complex algorithm to convert an original message, or cleartext, to an encoded message, called ciphertext, that is unintelligible unless it is decrypted. Decryption is the process of producing cleartext from ciphertext. The algorithms used to encrypt and decrypt data typically come in two categories: secret key (symmetric) cryptography and public key (asymmetric) cryptography.

Handshake Protocol

The negotiation phase during which the two socket peers agree to use a new or existing session. The handshake protocol is a series of messages exchanged over the record protocol. At the end of the handshake new connection-specific encryption and integrity protection keys are generated based on the key agreement secrets in the session.

Key Agreement

Key agreement is a protocol by which 2 or more parties can establish the same cryptographic keys, without having to exchange any secret information in the clear. Examples include RSA and Diffie-Hellman.

Key Managers and Trust Managers

Key managers (see KeyManagerFactory) and trust managers (see TrustManagerFactory) use keystores for their key material. A key manager manages a keystore and supplies public keys to others as needed, for example, for use in authenticating the user to others. A trust manager makes decisions about who to trust based on information in the truststore it manages.

Keystores and Truststores

A keystore is a database of key material. Key material is used for a variety of purposes, including authentication and data integrity. There are various types of keystores available, including "PKCS12" and the IBM "JKS."

Generally speaking, keystore information can be grouped into two different categories: key entries and trusted certificate entries. A key entry consists of an entity's identity and its private key, and can be used for a variety of cryptographic purposes. In contrast, a trusted certificate entry only contains a public key in addition to the entity's identity. Therefore, a trusted certificate entry cannot be used where a private key is required, such as in a javax.net.ssl.KeyManager. In the J2SDK implementation of "JKS", a keystore can contain both key entries and trusted certificate entries.

A truststore is a keystore that is used when making decisions about what to trust. If you receive some data from an entity that you already trust, and if you can verify that the entity is the one it claims to be, then you can assume that the data really came from that entity.

An entry should be added to a truststore only if the user makes a decision to trust that entity. By importing a certificate, the user has given trust to that entry, and as a result any entry in the keystore is considered a trusted entry.

It might be useful to have two different keystore files: one containing just your key entries, and the other containing your trusted certificate entries, including Certification Authority (CA) certificates. The former contains private information, while the latter does not. Using two different files instead of a single keystore file provides for a cleaner separation of the logical distinction between your own certificates (and corresponding private keys) and others' certificates. You could provide more protection for your private keys if you store them in a keystore with restricted access, while providing the trusted certificates in a more publicly accessible keystore if needed.

Message Authentication Code (MAC)

A message authentication code (MAC) provides a way to check the integrity of information transmitted over or stored in an unreliable medium, based on a secret key. Typically, MACs are used between two parties that share a secret key in order to validate information transmitted between these parties.

A MAC mechanism that is based on cryptographic hash functions is referred to as HMAC. HMAC can be used with any cryptographic hash function, such as Message Digest 5 (MD5) and Secure Hash Algorithm (SHA), in combination with a secret shared key. HMAC is specified in RFC 2104.

Public Key Cryptography

Public key cryptography uses an encryption algorithm in which two keys are produced. One key is made public while the other is kept private. The public key and the private key are cryptographic inverses; what one key encrypts only the other key can decrypt. Public key cryptography is also called asymmetric cryptography.

Record Protocol

The record protocol packages all data whether application-level or as part of the handshake process into discrete records of data much like a TCP stream socket converts an application byte stream into network packets. The individual records are then protected by the current encryption and integrity protection keys.

Secret Key Cryptography

Secret key cryptography uses an encryption algorithm in which the same key is used both to encrypt and decrypt the data. Secret key cryptography is also called symmetric cryptography.

Session

A session is a named collection of state information including authenticated peer identity, cipher suite, and key agreement secrets that are negotiated through a secure socket handshake and that can be shared among multiple secure socket instances.

Trust Managers

See Key Managers and Trust Managers.

Truststore

See Keystores and Truststores.

Secure Sockets Layer (SSL) Protocol Overview

Secure Sockets Layer (SSL) is the most widely used protocol for implementing cryptography on the Web. SSL uses a combination of cryptographic processes to provide secure communication over a network. This section provides an introduction to SSL and the cryptographic processes it uses.

SSL provides a secure enhancement to the standard TCP/IP sockets protocol used for Internet communications. As shown in the "TCP/IP Protocol Stack With SSL" figure below, the secure sockets layer is added between the transport layer and the application layer in the standard TCP/IP protocol stack. The application most commonly used with SSL is Hypertext Transfer Protocol (HTTP), the protocol for Internet Web pages. Other applications, such as Net News Transfer Protocol (NNTP), Telnet, Lightweight Directory Access Protocol (LDAP), Interactive Message Access Protocol (IMAP), and File Transfer Protocol (FTP), can be used with SSL as well.

Note: There is currently no standard for secure FTP.

SSL was developed by Netscape in 1994, and with input from the Internet community, has evolved to become a standard. It is now under the control of the international standards organization, the Internet Engineering Task Force (IETF). The IETF has renamed SSL to Transport Layer Security (TLS), and released the first specification, version 1.0, in January 1999. TLS 1.0 is a modest upgrade to the most recent version of SSL, version 3.0. The differences between SSL 3.0 and TLS 1.0 are minor.

Why Use SSL?

Transferring sensitive information over a network can be risky due to the following three issues:

• You cannot always be sure that the entity with whom you are communicating is really who you think it is.
• Network data can be intercepted, so it is possible that it can be read by an unauthorized third party, sometimes known as an attacker.
• If an attacker can intercept the data, the attacker might be able to modify the data before sending it on to the receiver.

SSL addresses each of these issues. It addresses the first issue by optionally allowing each of two communicating parties to ensure the identity of the other party in a process called authentication. After the parties are authenticated, SSL provides an encrypted connection between the two parties for secure message transmission. Encrypting the communication between the two parties provides privacy and therefore addresses the second issue. The encryption algorithms used with SSL include a secure hash function, which is similar to a checksum. This function ensures that data is not modified in transit. The secure hash function addresses the third issue of data integrity.

Note, both authentication and encryption are optional, and depend on the negotiated cipher suites between the two entities.

The most obvious example of when you would use SSL is in an e-commerce transaction. In an e-commerce transaction, it would be foolish to assume that you can guarantee the identity of the server with whom you are communicating. It would be easy enough for someone to create a phony Web site promising great services if only you enter your credit card number. SSL allows you, the client, to authenticate the identity of the server. It also allows the server to authenticate the identity of the client, although in Internet transactions, this is seldom done.

After the client and the server are comfortable with each other's identity, SSL provides privacy and data integrity through the encryption algorithms it uses. This integrity allows sensitive information, such as credit card numbers, to be transmitted securely over the Internet.

While SSL provides authentication, privacy, and data integrity, it does not provide non-repudiation services. Non-repudiation means that an entity that sends a message cannot later deny that they sent it. When the digital equivalent of a signature is associated with a message, the communication can later be proved. SSL alone does not provide non-repudiation.

How SSL Works

One of the reasons SSL is effective is that it uses several different cryptographic processes. SSL uses public key cryptography to provide authentication, and secret key cryptography and digital signatures to provide for privacy and data integrity. Before you can understand SSL, it is helpful to understand these cryptographic processes.

Cryptographic Processes

The primary purpose of cryptography is to make it difficult for an unauthorized third party to access and understand private communication between two parties. It is not always possible to restrict all unauthorized access to data, but private data can be made unintelligible to unauthorized parties through the process of encryption. Encryption uses complex algorithms to convert the original message, or cleartext, to an encoded message, called ciphertext. The algorithms used to encrypt and decrypt data that is transferred over a network typically come in two categories: secret key cryptography and public key cryptography. These forms of cryptography are explained in the following subsections.

Both secret key cryptography and public key cryptography depend on the use of an agreed-upon cryptographic key or pair of keys. A key is a string of bits that is used by the cryptographic algorithm or algorithms during the process of encrypting and decrypting the data. A cryptographic key is like a key for a lock: only with the right key can you open the lock.

Safely transmitting a key between two communicating parties is not a trivial matter. A public key certificate allows a party to safely transmit its public key, while ensuring the receiver of the authenticity of the public key. Public key certificates are described in a later section.

In the descriptions of the cryptographic processes that follow, we use the conventions used by the security community: we label the two communicating parties with the names Alice and Bob. We call the unauthorized third party, also known as the attacker, Charlie.

Secret Key Cryptography

With secret key cryptography, both communicating parties, Alice and Bob, use the same key to encrypt and decrypt the messages. Before any encrypted data can be sent over the network, both Alice and Bob must have the key and must agree on the cryptographic algorithm that they will use for encryption and decryption.

One of the major problems with secret key cryptography is the logistical issue of how to get the key from one party to the other without allowing access to an attacker. If Alice and Bob are securing their data with secret key cryptography, and if Charlie gains access to their key, Charlie can understand any secret messages he intercepts between Alice and Bob. Not only can Charlie decrypt Alice's and Bob's messages, but he can also pretend that he is Alice and send encrypted data to Bob. Bob will not know that the message came from Charlie, not Alice.

When the problem of secret key distribution is solved, secret key cryptography can be a valuable tool. The algorithms provide excellent security and encrypt data relatively quickly. The majority of the sensitive data sent in an SSL session is sent using secret key cryptography.

Secret key cryptography is also called symmetric cryptography because the same key is used to both encrypt and decrypt the data. Well-known secret key cryptographic algorithms include the Data Encryption Standard (DES), triple-strength DES (3DES), Rivest Cipher 2 (RC2), and Rivest Cipher 4 (RC4).

Public Key Cryptography

Public key cryptography solves the logistical problem of key distribution by using both a public key and a private key. The public key can be sent openly through the network while the private key is kept private by one of the communicating parties. The public and the private keys are cryptographic inverses of each other; what one key encrypts, the other key will decrypt.

Let's assume that Bob wants to send a secret message to Alice using public key cryptography. Alice has both a public key and a private key, so she keeps her private key in a safe place and sends her public key to Bob. Bob encrypts the secret message to Alice using Alice's public key. Alice can later decrypt the message with her private key.

If Alice encrypts a message using her private key and sends the encrypted message to Bob, Bob can be sure that the data he receives comes from Alice; if Bob can decrypt the data with Alice's public key, the message must have been encrypted by Alice with her private key, and only Alice has Alice's private key. The problem is that anybody else can read the message as well because Alice's public key is public. While this scenario does not allow for secure data communication, it does provide the basis for digital signatures. A digital signature is one of the components of a public key certificate, and is used in SSL to authenticate a client or a server. Public key certificates and digital signatures are described in later sections.

Public key cryptography is also called asymmetric cryptography because different keys are used to encrypt and decrypt the data. A well known public key cryptographic algorithm often used with SSL is the Rivest Shamir Adleman (RSA) algorithm. Another public key algorithm used with SSL that is designed specifically for secret key exchange is the Diffie-Hellman (DH) algorithm. Public key cryptography requires extensive computations, making it very slow. It is therefore typically used only for encrypting small pieces of data, such as secret keys, rather than for the bulk of encrypted data communications.

A Comparison Between Secret Key and Public Key Cryptography

Both secret key cryptography and public key cryptography have strengths and weaknesses. With secret key cryptography, data can be encrypted and decrypted quickly, but because both communicating parties must share the same secret key information, the logistics of exchanging the key can be a problem. With public key cryptography, key exchange is not a problem because the public key does not need to be kept secret, but the algorithms used to encrypt and decrypt data require extensive computations, and are therefore very slow.

Public Key Certificates

A public key certificate provides a safe way for an entity to pass on its public key to be used in asymmetric cryptography. The public key certificate avoids the following situation: if Charlie creates his own public key and private key, he can claim that he is Alice and send his public key to Bob. Bob will be able to communicate with Charlie, but Bob will think that he is sending his data to Alice.

A public key certificate can be thought of as the digital equivalent of a passport. It is issued by a trusted organization and provides identification for the bearer. A trusted organization that issues public key certificates is known as a certificate authority (CA). The CA can be likened to a notary public. To obtain a certificate from a CA, one must provide proof of identity. When the CA is confident that the applicant represents the organization it says it represents, the CA signs the certificate attesting to the validity of the information contained within the certificate.

A public key certificate contains several fields, including:

• Issuer - The issuer is the CA that issued the certificate. If a user trusts the CA that issues a certificate, and if the certificate is valid, the user can trust the certificate.
• Period of validity - A certificate has an expiration date, and this date is one piece of information that should be checked when verifying the validity of a certificate.
• Subject - The subject field includes information about the entity that the certificate represents.
• Subject's public key - The primary piece of information that the certificate provides is the subject's public key. All the other fields are provided to ensure the validity of this key.
• Signature - The certificate is digitally signed by the CA that issued the certificate. The signature is created using the CA's private key and ensures the validity of the certificate. Because only the certificate is signed, not the data sent in the SSL transaction, SSL does not provide for non-repudiation.

If Bob accepts only Alice's public key as valid when she sends it in a public key certificate, Bob will not be fooled into sending secret information to Charlie when Charlie masquerades as Alice.

Multiple certificates can be linked in a certificate chain. When a certificate chain is used, the first certificate is always that of the sender. The next is the certificate of the entity that issued the sender's certificate. If there are more certificates in the chain, each is that of the authority that issued the previous certificate. The final certificate in the chain is the certificate for a root CA. A root CA is a public certificate authority that is widely trusted. Information for several root CAs is typically stored in the client's Internet browser. This information includes the CA's public key. Well-known CAs include VeriSign, Entrust, and GTE CyberTrust.

Cryptographic Hash Functions

When sending encrypted data, SSL typically uses a cryptographic hash function to ensure data integrity. The hash function prevents Charlie from tampering with data that Alice sends to Bob.

A cryptographic hash function is similar to a checksum. The main difference is that while a checksum is designed to detect accidental alterations in data, a cryptographic hash function is designed to detect deliberate alterations. When data is processed by a cryptographic hash function, a small string of bits, known as a hash, is generated. The slightest change to the message typically makes a large change in the resulting hash. A cryptographic hash function does not require a cryptographic key. Two hash functions often used with SSL are Message Digest 5 (MD5) and Secure Hash Algorithm (SHA). SHA was proposed by the U.S. National Institute of Science and Technology (NIST).

Message Authentication Code

A message authentication code (MAC) is similar to a cryptographic hash, except that it is based on a secret key. When secret key information is included with the data that is processed by a cryptographic hash function, the resulting hash is known as an HMAC.

If Alice wants to be sure that Charlie does not tamper with her message to Bob, she can calculate an HMAC for her message and append the HMAC to her original message. She can then encrypt the message plus the HMAC using a secret key that she shares with Bob. When Bob decrypts the message and calculates the HMAC, he will be able to tell if the message was modified in transit. With SSL, an HMAC is used with the transmission of secure data.

Digital Signatures

When a cryptographic hash is created for a message, the hash is encrypted with the sender's private key. This encrypted hash is called a digital signature.

The SSL Process

Communication using SSL begins with an exchange of information between the client and the server. This exchange of information is called the SSL handshake.

The three main purposes of the SSL handshake are:

• Negotiate the cipher suite
• Authenticate identity (optional)
• Establish information security by agreeing on encryption mechanisms

Negotiating the Cipher Suite

The SSL session begins with a negotiation between the client and the server as to which cipher suite they will use. A cipher suite is a set of cryptographic algorithms and key sizes that a computer can use to encrypt data. The cipher suite includes information about available public key exchange algorithms, secret key encryption algorithms, and cryptographic hash functions. The client tells the server which cipher suites it has available, and the server chooses the best mutually acceptable cipher suite.

Authenticating the Server

In SSL, the authentication step is optional, but in the example of an e-commerce transaction over the Web, the client will generally want to authenticate the server. Authenticating the server allows the client to be sure that the server represents the entity that the client believes the server represents.

To prove that a server belongs to the organization that it claims to represent, the server presents its public key certificate to the client. If this certificate is valid, the client can be sure of the identity of the server.

The client and server exchange information that allows them to agree on the same secret key. For example, with RSA, the client uses the server's public key, obtained from the public key certificate, to encrypt the secret key information. The client sends the encrypted secret key information to the server. Only the server can decrypt this message because the server's private key is required for this decryption.

Sending the Encrypted Data

Both the client and the server now have access to the same secret key. With each message, they use the cryptographic hash function, agreed upon in the first step of this process, and shared secret information, to compute an HMAC that they append to the message. They then use the secret key and the secret key algorithm negotiated in the first step of this process to encrypt the secure data and the HMAC. The client and server can now communicate securely using their encrypted and hashed data.

The SSL Protocol

The previous section provides a high-level description of the SSL handshake, which is the exchange of information between the client and the server prior to sending the encrypted message. This section provides more detail.

The "SSL Messages" figure below shows the sequence of messages that are exchanged in the SSL handshake. Messages that are sent only in certain situations are noted as optional. Each of the SSL messages is described in the following figure:

The SSL messages are sent in the following order:

1. Client hello - The client sends the server information including the highest version of SSL it supports and a list of the cipher suites it supports. (TLS 1.0 is indicated as SSL 3.1.) The cipher suite information includes cryptographic algorithms and key sizes.
2. Server hello - The server chooses the highest version of SSL and the best cipher suite that both the client and server support and sends this information to the client.
3. Certificate - The server sends the client a certificate or a certificate chain. A certificate chain typically begins with the server's public key certificate and ends with the certificate authority's root certificate. This message is optional, but is used whenever server authentication is required.
4. Certificate request - If the server needs to authenticate the client, it sends the client a certificate request. In Internet applications, this message is rarely sent.
5. Server key exchange - The server sends the client a server key exchange message when the public key information sent in step 3 above is not sufficient for key exchange.
6. Server hello done - The server tells the client that it is finished with its initial negotiation messages.
7. Certificate - If the server requests a certificate from the client in message 4, the client sends its certificate chain, just as the server did in message 3.
   Note: Only a few Internet server applications ask for a certificate from the client.
8. Client key exchange - The client generates information used to create a key to use for symmetric encryption. For RSA, the client then encrypts this key information with the server's public key and sends it to the server.
9. Certificate verify - In Internet applications, this message is rarely sent. Its purpose is to allow the server to complete the process of authenticating the client. When this message is used, the client sends information that it digitally signs using a cryptographic hash function. When the server decrypts this information with the client's public key, the server is able to authenticate the client.
10. Change cipher spec - The client sends a message telling the server to change to encrypted mode.
11. Finished - The client tells the server that it is ready for secure data communication to begin.
12. Change cipher spec - The server sends a message telling the client to change to encrypted mode.
13. Finished - The server tells the client that it is ready for secure data communication to begin. This is the end of the SSL handshake.
14. Encrypted data - The client and the server communicate using the symmetric encryption algorithm and the cryptographic hash function negotiated in Messages 1 and 2, and using the secret key that the client sent to the server in Message 8.

If the parameters generated during an SSL session are saved, these parameters can sometimes be re-used for future SSL sessions. Saving SSL session parameters allows encrypted communication to begin much more quickly.

SSL References

For a list of resources containing more information about SSL, see Secure Sockets Layer Documentation .

Key Classes

Relationship Between Classes

To communicate securely, both sides of the connection must be SSL-enabled. In the JSSE API, the endpoint class of the connection is the SSLSocket. In the diagram below, the major classes used to create SSLSockets are laid out in a logical order.

An SSLSocket is created either by an SSLSocketFactory or by an SSLServerSocket accepting an in-bound connection. (In turn, an SSLServerSocket is created by an SSLServerSocketFactory.) Both SSLSocketFactory and SSLServerSocketFactory objects are created by an SSLContext.

There are two ways to obtain and initialize an SSLContext:

• The simplest way is to call the static getDefault method on either the SSLSocketFactory or SSLServerSocketFactory class. These methods create a default SSLContext with a default KeyManager, TrustManager, and a secure random number generator. (A default KeyManagerFactory and TrustManagerFactory are used to create the KeyManager and TrustManager, respectively.) The key material used is found in the default keystore or truststore, as determined by the system properties described in Customizing the Default Key and Trust Stores, Store Types, and Store Passwords.  Be careful when using getDefault. It is dependent upon system properties that can be changed by anyone on the JVM.
• The approach that gives the caller the most control over the behavior of the created context is to call the static method getInstance on the SSLContext class, and then initialize the context by calling the instance's proper init method. One variant of the init method takes three arguments: an array of KeyManager objects, an array of TrustManager objects, and a SecureRandom random number generator. The KeyManager and TrustManager objects are created by either implementing the appropriate interfaces or using the KeyManagerFactory and TrustManagerFactory classes to generate implementations. The KeyManagerFactory and TrustManagerFactory can then each be initialized with key material contained in the KeyStore that is passed as an argument to the TrustManagerFactory and KeyManagerFactory init method. Finally, the getTrustManagers method (in TrustManagerFactory) and getKeyManagers method (in KeyManagerFactory) can be called to obtain the array of trust or key managers, one for each type of trust or key material.

After an SSL connection is established, an SSLSession is created that contains various information, such as identities established, cipher suite used, and so on. The SSLSession is then used to describe an ongoing relationship and state information between two entities. Each SSL connection involves one session at a time, but that session can be used on many connections between those entities, simultaneously or sequentially.

Core Classes and Interfaces

The core JSSE classes are part of the javax.net and javax.net.ssl packages.

SocketFactory and ServerSocketFactory Classes

The abstract javax.net.SocketFactory class is used to create sockets. It must be subclassed by other factories, which create particular subclasses of sockets and therefore provide a general framework for the addition of public socket-level functionality. (See, for example, SSLSocketFactory.)

The javax.net.ServerSocketFactory class is analogous to the SocketFactory class, but is used specifically for creating server sockets.

Socket factories are a simple way to capture a variety of policies related to the sockets being constructed, producing such sockets in a way that does not require special configuration of the code that asks for the sockets:

• Due to polymorphism of both factories and sockets, different kinds of sockets can be used by the same application code just by passing different kinds of factories.
• Factories can themselves be customized with parameters used in socket construction. So for example, factories could be customized to return sockets with different networking timeouts or security parameters already configured.
• The sockets returned to the application can be subclasses of java.net.Socket (or javax.net.ssl.SSLSocket), so that they can directly expose new APIs for features such as compression, security, record marking, statistics collection, or firewall tunneling.

SSLSocket and SSLServerSocket Classes

The javax.net.ssl.SSLSocket class is a subclass of the standard Java java.net.Socket class. It supports all of the standard socket methods and adds additional methods that are specific to secure sockets. Instances of this class encapsulate the SSLContext under which they were created. There are APIs to control the creation of secure socket sessions for a socket instance but trust and key management are not directly exposed.

The javax.net.ssl.SSLServerSocket class is analogous to the SSLSocket class, but is used specifically for creating server sockets.

Obtaining an SSLSocket

Instances of SSLSocket can be obtained in two ways. First, an SSLSocket can be created by an instance of SSLSocketFactory using one of the several createSocket methods on that class. The second way to obtain SSLSockets is through the accept method on the SSLServerSocket class.

SSLSocketFactory and SSLServerSocketFactory Classes

A javax.net.ssl.SSLSocketFactory acts as a factory for creating secure sockets. This class is an abstract subclass of javax.net.SocketFactory.

Secure socket factories encapsulate the details of creating and initially configuring secure sockets. This encapsulation includes authentication keys, peer certificate validation, enabled cipher suites, and so on.

The javax.net.ssl.SSLServerSocketFactory class is analogous to the SSLSocketFactory class, but is used specifically for creating server sockets.

Obtaining an SSLSocketFactory

There are three primary ways of obtaining an SSLSocketFactory:

• Get the default factory by calling the SSLSocketFactory.getDefault static method.
• Receive a factory as an API parameter. That is, code that needs to create sockets but that does not care about the details of how the sockets are configured can include a method with an SSLSocketFactory parameter that can be called by clients to specify which SSLSocketFactory to use when creating sockets. (For example, javax.net.ssl.HttpsURLConnection.)
• Construct a new factory with specifically configured behavior.

The default factory is typically configured to support server authentication only so that sockets created by the default factory do not leak any more information about the client than a normal TCP socket would.

Many classes that create and use sockets do not need to know the details of socket creation behavior. Creating sockets through a socket factory that is passed in as a parameter is a good way of isolating the details of socket configuration, and increases the reusability of classes that create and use sockets.

You can create new socket factory instances either by implementing your own socket factory subclass or by using another class that acts as a factory for socket factories. One example of such a class is SSLContext, which is provided with the JSSE implementation as a provider-based configuration class.

SSLSession Interface

A javax.net.ssl.SSLSession represents a security context negotiated between the two peers of an SSLSocket connection. When a session has been arranged, it can be shared by future SSLSockets that are connected between the same two peers. The session contains the cipher suite that will be used for communications over a secure socket as well as a non-authoritative hint as to the network address of the remote peer, and management information such as the time of creation and last use. A session also contains a shared master secret that is negotiated between the peers and that is used to create cryptographic keys for encrypting and guaranteeing the integrity of the communications over an SSLSocket. The value of this master secret is known only to the underlying secure socket implementation and is not exposed through the SSLSession API.

HttpsURLConnection Class

The https protocol is similar to http, but https first establishes a secure channel using SSL or TLS sockets before requesting or receiving data. The javax.net.ssl.HttpsURLConnection class extends the java.net.HttpsURLConnection class, and adds support for https-specific features. See the java.net.URL, java.net.URLConnection, and java.net.HttpURLConnection classes for more information about how http URLs are constructed and used.

After obtaining a HttpsURLConnection, you can configure a number of http or https parameters before actually initiating the network connection using the method URLConnection.connect.

Support Classes and Interfaces

The classes and interfaces in this section are provided to support the creation and initialization of SSLContext objects, which are used to create SSLSocketFactory and SSLServerSocketFactory objects. The support classes and interfaces are part of the javax.net.ssl package.

Three of the classes described in this section ( SSLContext, KeyManagerFactory, and TrustManagerFactory) are engine classes. An engine class is an API class for specific algorithms (or protocols, in the case of SSLContext), for which implementations can be provided in one or more Cryptographic Service Provider (provider) packages. For more information on providers and engine classes, see the "Design Principles" and "Concepts" sections of the Java Cryptography Architecture API Specification & Reference.

The IBMJSSE provider that comes standard with JSSE provides SSLContext, KeyManagerFactory, and TrustManagerFactory implementations. The implementations supplied by IBMJSSE are:

SSLContext Class

The javax.net.ssl.SSLContext is an engine class for an implementation of a secure socket protocol. An instance of this class acts as a factory for SSL socket factories. An SSLContext holds all of the state information shared across all sockets created under that context. For example, session state is associated with the SSLContext when it is negotiated through the handshake protocol by sockets created by socket factories provided by the context. These cached sessions can be reused and shared by other sockets created under the same context.

Each instance is configured through its init method with the keys, certificate chains, and trusted root CA certificates that it needs to perform authentication. This configuration is provided in the form of key and trust managers. These managers provide support for the authentication and key agreement aspects of the cipher suites supported by the context.

Currently, only X.509-based managers are supported.

Creating an SSLContext Object

Like other JCA provider-based "engine" classes, SSLContext objects are created using the getInstance factory methods of the SSLContext class. These static methods each return an instance that implements at least the requested secure socket protocol. The returned instance can implement other protocols too. For example, getInstance("SSLv3") returns an instance that implements SSLv3. The getInstance("SSL") returns an instance that will implement SSLv2 or SSLv3.  The getSupportedProtocols method returns a list of supported protocols when an SSLSocket or SSLServerSocket is created from a socket factory obtained from this context. You can also control which protocols are actually enabled for an SSL connection by using the method setEnabledProtocols(String[] protocols). (Refer to the API documention for this method in the SSLSocket and the SSLServerSocket classes for more information.)

Note: An SSLContext object is automatically created, initialized, and statically assigned to the SSLSocketFactory class when you call SSLSocketFactory.getDefault. Therefore, you don't have to directly create and initialize an SSLContext object (unless you want to override the default behavior). An SSLContext object will be created with a protocol of “SSL” meaning SSLv2 or SSLv3.

To create an SSLContext object by calling a getInstance factory method, you must specify the protocol name. You can also specify which provider you want to supply the implementation of the requested protocol:

public static SSLContext getInstance(String protocol);
public static SSLContext getInstance(String protocol, String provider);
public static SSLContext getInstance(String protocol, Provider provider);

If only a protocol name is specified, the system will determine if there is an implementation of the requested protocol available in the environment.  If there is more than one, it will determine if there is a preferred one.

If both a protocol name and a provider are specified, the system will determine if there is an implementation of the requested protocol in the provider requested, and throw an exception if there is not.

A protocol is a string (such as "SSL") that describes the secure socket protocol desired. Common protocol names for SSLContext objects are defined in Appendix A.

Here is an example of obtaining an SSLContext:

SSLContext sc = SSLContext.getInstance("SSL");

A newly created SSLContext should be initialized by calling the init method:

public void init(KeyManager[] km, TrustManager[] tm, SecureRandom random);

The IBMJSSE Provider implementation has a second way of initializing a SSLContext by calling the alternate init method:

public void init(String tokenType, String tokenName, String password);

This init method is from the com.ibm.jsse.SSLContext class that extends the javax.net.ssl.SSLContext class.

For the first init method, if the KeyManager[] paramater is null, then an empty KeyManager will be defined for this context. If the TrustManager[] parameter is null, the installed security providers will be searched for the highest-priority implementation of the TrustManagerFactory, from which an appropriate TrustManager will be obtained. Likewise, the SecureRandom parameter might be null.

If the internal default context is used, (for example, a SSLContext is created in the internals of JSSE), a default KeyManager and a TrustManager are created.

The second way is with a 3-String init call. These three strings are interpreted by the IBM-provided SSLContext to be a tokenType, a token name and a passphrase. This init method can be called several times to use multiple secure tokens containing certificates, keys, and CRLs in a SSLContext. The following token types are supported by the IBM implementation of JSSE: PKCS#7, PKCS#11, PKCS#12, MSCAPI (only on Windows platforms).

Here's an example that initializes a PKCS#12 token using the IBMJSSE provider 3-string init call:

static com.ibm.jsse.SSLContext sslContext;
// Open up the commonly shared KeyStore to obtain the Trusted and Personal Certificates
// KeyStore is of type "PKCS12".  Filename is "testkeys.pfx" and password is "passphrase".
private static void initContext()
sslContext = (SSLContext) SSLContext.getInstance("SSL","IBMJSSE");
sslContext.init("PKCS#12","testkeys.pfx", "passphrase");

TrustManager Interface

The primary responsibility of the TrustManager is to determine whether the presented authentication credentials should be trusted. If the credentials are not trusted, the connection will be terminated. To authenticate the remote identity of a secure socket peer, you need to initialize an SSLContext object with one or more TrustManager objects. You need to pass one TrustManager for each authentication mechanism that is supported. If null is passed into the SSLContext initialization, a trust manager will be created for you. Typically, there is a single trust manager that supports authentication based on X.509 public key certificates. Some secure socket implementations might also support authentication based on shared secret keys, Kerberos, or other mechanisms.

TrustManagerFactory Class

The javax.net.ssl.TrustManagerFactory is an engine class for a provider-based service that acts as a factory for one or more types of TrustManager objects. The IBMJSSE provider implements a factory that can return a basic X.509 trust manager. Because it is provider-based, additional factories can be implemented and configured to provide additional or alternate trust managers that provide more sophisticated services or that implement installation-specific authentication policies.

Creating a TrustManagerFactory

You create an instance of this class in a similar manner to SSLContext, except for passing an algorithm name string instead of a protocol name to the getInstance me