|Skip Navigation Links|
|Exit Print View|
|Configuring Oracle Java CAPS for SSL Support Java CAPS Documentation|
You can use the Secure Sockets Layer (SSL) protocol to protect communication between clients and servers over the Internet. SSL provides such features as server authentication, client authentication, and data encryption. Authentication confirms the identity of a server or client. Encryption converts data into an unreadable form before the data is sent.
When performing authentication, SSL uses a technique called public-key cryptography. Public-key cryptography is based on the concept of a key pair, which consists of a public key and a private key. Data that has been encrypted with a public key can be decrypted only with the corresponding private key. Conversely, data that has been encrypted with a private key can be decrypted only with the corresponding public key.
The owner of the key pair makes the public key available to anyone, but keeps the private key secret. A certificate verifies that an entity is the owner of a particular public key. Certificates that follow the X.509 standard contain a data section and a signature section. The data section includes such information as:
The Distinguished Name of the entity that owns the public key
The Distinguished Name of the entity that issued the certificate
The period of time during which the certificate is valid
The public key itself
You can obtain a certificate from a Certificate Authority (CA) such as VeriSign. Alternately, you can create a self-signed certificate, in which the owner and the issuer are the same. An organization that issues certificates can establish a hierarchy of CAs. The root CA has a self-signed certificate. Each subordinate CA has a certificate that is signed by the next highest CA in the hierarchy. A certificate chain is the certificate of a particular CA, plus the certificates of any higher CAs up through the root CA.
The keytool program is a security tool included in the bin directory of the Java SDK. This tool manages a type of database called a keystore. Keystores contain two types of entries:
A key entry consists of a private key and the certificate chain for the associated public key.
A trusted certificate entry is a public key certificate that belongs to another entity and that the owner of the keystore has determined to be trustworthy.
The available commands of the keytool program include the following:
The genkey command generates a key pair. If you specify a keystore that does not exist, then the keystore is created.
The import command adds a certificate to a keystore. If you specify a keystore that does not exist, then the keystore is created.
The export command exports a certificate to a file.
The list command prints the contents of a keystore entry.
The OpenSSL Project is an effort to develop an open-source toolkit that implements the SSL and TLS protocols, as well as a cryptographic library. The toolkit includes the openssl command-line tool, which enables you to use various functions of the cryptographic library.
The available commands of the openssl tool include the following:
The pkcs12 command parses or generates a PKCS #12 file.
The req command creates and processes certificate requests in PKCS #10 format.
You can download the current version of OpenSSL at http://www.openssl.org.
The use of SSL with HTTP, LDAP, and WebSphere MQ enables data exchanges that are secure from unauthorized interception from hackers or other entities. The adapter's SSL feature provides a secure communications channel for the data exchanges.
The following diagram illustrates the use of SSL with the LDAP Adapter.
This SSL feature is supported through the use of Java Secure Socket Extension (JSSE) version 1.0.3.
Currently, the JSSE reference implementation is used. JSSE is a provider-based architecture, which means there is a set of standard interfaces for cryptographic algorithms, hashing algorithms, secured-socket-layered URL stream handlers, and so on.
Because the user is interacting with JSSE through these interfaces, the different components can be mixed and matched as long as the implementation is programmed under the published interfaces. However, some implementations might not support a particular algorithm.
The JSSE 1.0.3 API can support SSL versions 2.0 and 3.0 and TLS version 1.0. These security protocols encapsulate a normal bidirectional stream socket. The JSSE 1.0.3 API adds transparent support for authentication, encryption, and integrity protection. The JSSE reference implementation implements SSL version 3.0 and TLS version 1.0.
The following options available for setting up SSL connectivity with a web server:
Server-side Authentication. The majority of e-commerce web sites are configured for server-side authentication. The adapter requests a certificate from the web server and authenticates the web server by verifying that the certificate can be trusted. Essentially, the adapter performs this operation by looking into its TrustStore for a CA certificate with a public key that can validate the signature on the certificate received from the web server.
Dual Authentication. This option requires authentication from both the adapter and web server. The server side (web server) of the authentication process is the same as that described previously. In addition, the web server requests a certificate from the adapter. The adapter sends its certificate to the web server. The server authenticates the adapter by looking into its TrustStore for a matching trusted CA certificate. The communication channel is established by the process of both parties requesting certificate information.
The JSSE makes use of files called KeyStores and TrustStores. The KeyStore is used by the adapter for client authentication, while the TrustStore is used to authenticate a server in SSL authentication.
A KeyStore consists of a database containing a private key and an associated certificate, or an associated certificate chain. The certificate chain consists of the client certificate and one or more certification authority (CA) certificates.
A TrustStore contains only the certificates trusted by the client (a “trust” store). These certificates are CA root certificates, that is, self-signed certificates. The installation of GlassFish includes a TrustStore file named cacerts.jks in the location:
where JavaCAPS_Home is the directory where Java CAPS is installed and MyDomain is the name of your domain. This file is recommended as the TrustStore for the Oracle Java CAPS Adapters.
Both KeyStores and TrustStores are managed by means of a utility called keytool, which is a part of the Java SDK installation.
The following sections explain how to create both a KeyStore and a TrustStore (or import a certificate into an existing TrustStore such as the default GlassFish TrustStore in the location:
where JavaCAPS_Home is the directory where Java CAPS is installed and MyDomain is the name of your domain. The primary tool used is keytool, but openssl is also used as a reference for generating pkcs12 KeyStores.
For more information on openssl and available downloads, visit the following web site:
This section explains how to create a KeyStore using the JKS format as the database format for both the private key, and the associated certificate or certificate chain. By default, as specified in the java.security file, keytool uses JKS as the format of the key and certificate databases (KeyStore and TrustStores). A CA must sign the certificate signing request (CSR). The CA is therefore trusted by the server-side application to which the Adapter is connected.
where JavaCAPS_Home is the directory where Java CAPS is installed and MyDomain is the name of your domain.
keytool -keystore clientkeystore -genkey -alias client
Enter keystore password: javacaps What is your first and last name? [Unknown]: development.oracle.com What is the name of your organizational unit? [Unknown]: Development what is the name of your organization? [Unknown]: Oracle What is the name of your City or Locality? [Unknown]: Monrovia What is the name of your State or Province? [Unknown]: California What is the two-letter country code for this unit? [Unknown]: US Is<CN=development.oracle.com, OU=Development, O=Oracle, L=Monrovia, ST=California, C=US> correct? [no]: yes Enter key password for <client> (RETURN if same as keystore password):
If the KeyStore password is specified, then the password must be provided for the adapter.
This operation creates a KeyStore file clientkeystore in the current working directory. You must specify a fully qualified domain for the “first and last name” question. The reason for this use is that some CAs such as VeriSign expect this properties to be a fully qualified domain name.
There are CAs that do not require the fully qualified domain, but it is recommended to use the fully qualified domain name for the sake of portability. All the other information given must be valid. If the information cannot be validated, a CA such as VeriSign does not sign a generated CSR for this entry.
This KeyStore contains an entry with an alias of client. This entry consists of the generated private key and information needed for generating a CSR as follows:
keytool -keystore clientkeystore -certreq -alias client -keyalg rsa -file client.csr
This command generates a certificate signing request which can be provided to a CA for a certificate request. The file client.csr contains the CSR in PEM format.
Some CA (one trusted by the web server to which the adapter is connecting) must sign the CSR. The CA generates a certificate for the corresponding CSR and signs the certificate with its private key. For more information, visit the following web sites:
If the certificate is chained with the CA’s certificate, perform step 4; otherwise, perform step 5 in the following list:
keytool -import -keystore clientkeystore -file client.cer -alias client
The command imports the certificate and assumes the client certificate is in the file client.cer and the CA’s certificate is in the file CARoot.cer.
keytool -import -keystore clientkeystore -file CARoot.cer -alias theCARoot
keytool -import -keystore clientkeystore -file client.cer -alias client
The generated file clientkeystore contains the client’s private key and the associated certificate chain used for client authentication and signing. The KeyStore and/or clientkeystore, can then be used as the adapter’s KeyStore.
This section explains how to create a PKCS12 KeyStore to work with JSSE. In a real working environment, a customer could already have an existing private key and certificate (signed by a known CA). In this case, JKS format cannot be used, because it does not allow the user to import/export the private key through keytool. It is necessary to generate a PKCS12 database consisting of the private key and its certificate.
The generated PKCS12 database can then be used as the Adapter’s KeyStore. The keytool utility is currently lacking the ability to write to a PKCS12 database. However, it can read from a PKCS12 database.
Note - There are additional third-party tools available for generating PKCS12 certificates, if you want to use a different tool.
For the following example, openssl is used to generate the PKCS12 KeyStore:
cat mykey.pem.txt mycertificate.pem.txt>mykeycertificate.pem.txt
The existing key is in the file mykey.pem.txt in PEM format. The certificate is in mycertificate.pem.txt, which is also in PEM format. A text file must be created which contains the key followed by the certificate as follows:
openssl pkcs12 -export -in mykeycertificate.pem.txt -out mykeystore.pkcs12 -name myAlias -noiter -nomaciter
This command prompts the user for a password. The password is required. The KeyStore fails to work with JSSE without a password. This password must also be supplied as the password for the Adapter’s KeyStore password.
This command also uses the openssl pkcs12 command to generate a PKCS12 KeyStore with the private key and certificate. The generated KeyStore is mykeystore.pkcs12 with an entry specified by the myAlias alias. This entry contains the private key and the certificate provided by the -in argument. The noiter and nomaciter options must be specified to allow the generated KeyStore to be recognized properly by JSSE.
For demonstration purposes, suppose you have the following CAs that you trust: firstCA.cert, secondCA.cert, thirdCA.cert, located in the directory C:\cascerts. You can create a new TrustStore consisting of these three trusted certificates.
keytool -import -file C:\cascerts\firstCA.cert -alias firstCA -keystore myTrustStore
The first entry creates a KeyStore file named myTrustStore in the current working directory and imports the firstCA certificate into the TrustStore with an alias of firstCA. The format of myTrustStore is JKS.
For the second entry, substitute secondCA to import the secondCA certificate into the TrustStore, myTrustStore.
For the third entry, substitute thirdCA to import the thirdCA certificate into the TrustStore.
Once completed, myTrustStore is available to be used as the TrustStore for the adapter.