Using the OpenSSL Utility for the LDAP and HTTPS Adapters

The OpenSSL utility is a free implementation of cryptographic, hashing, and public key algorithms such as 3DES, SHA1, and RSA respectively. This utility has many options including certificate signing, which keytool does not provide. You can download OpenSSL from the following Web site:

http://www.openssl.org

Follow the build and installation instruction for OpenSSL.

Creating a Sample CA Certificate

The sample given in this section demonstrates the use of the OpenSSL utility to create a CA. This generated CA is then used to sign a CSR (see Signing Certificates With Your Own CA), whether it is generated from keytool or OpenSSL.

To Create a Sample CA Certificate

For testing purposes, a sample CA can be generated. To avoid spending additional funds to have a commercial CA sign test certificates, a sample is generated and used to sign the test certificate.

1. Perform the following operations from the command line:

   openssl  req  -config c:\openssl\bin\openssl.cnf 
    -new  -x509  -keyout  ca-key.pem.txt -out  ca-certificate.pem.txt  -days  365
   
   Using properties from c:\openssl\bin\openssl.cnf
   Loading ’screen’ into random state: done
   Generating a 1024 bit RSA private key
   .................++++++
   .....................++++++
   writing new private key to ’ca-key.pem.txt’
   Enter PEM pass phrase:
   Verifying password: Enter PEM pass phrase:
   -----
   You are about to be asked to enter information that will be 
       incorporated into your certificate request.
   What you are about to enter is what is called a Distinguished Name 
       or a DN.
   There are quite a few fields but you can leave some blank
   For some fields there will be a default value,
   If you enter ’.’, the field will be left blank.
   -----
   Country Name (2 letter code) []:US
   State or Province Name (full name) []:California
   Locality Name (eg, city) []:Monrovia
   Organization Name (eg, company) []:Oracle
   Organizational Unit Name (eg, section) []:Development
   Common Name (eg, your websites domain name) []
       :development.oracle.com
   Email Address []:development@oracle.com  

   You are prompted for password information.

2. Enter a password and remember this password for signing certificates with the CA’s private key.

   This command creates a private key and the corresponding certificate for the CA. The certificate is valid for 365 days starting from the date and time it was created.

   The properties file C:\openssl\bin\openssl.cnf is needed for the req command. The default config.cnf file is in the OpenSSL package under the apps sub-directory.

   ---

   Note - To use this file in Windows, you must change the paths to use double back-slashes. See Windows OpenSSL.cnf File Example for a complete Config.cnf file example, which is known to work in a Windows environment.

   ---

Signing Certificates With Your Own CA

The example in this section shows how to create a Certificate Signing Request with keytool and generate a signed certificate for the Certificate Signing Request with the CA created in the previous section. The steps shown in this section, for generating a KeyStore and a Certificate Signing Request, were already explained under Creating a KeyStore in JKS Format.

To Create a CSR with keytool and Generate a Signed Certificate for the Certificate Signing Request

1. Perform the following operations from the command line.

   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):

2. Generate the Certificate Signing Request.

   keytool –keystore clientkeystore –certreq –alias client –keyalg rsa 
   –file client.csr

3. Generate a signed certificate for the associated Certificate Signing Request.

   openssl  x509  -req  -CA 
       ca-certificate.pem.txt -CAkey ca-key.pem.txt 
       -in client.csr -out client.cer  -days 365  -CAcreateserial

4. Use the keytool to import the CA certificate into the client keystore.

   keytool -import -keystore clientkeystore -file ca-certificate.pem.txt  
   -alias theCARoot 
   
   Enter keystore password:  javacaps
   Owner: EmailAddress=development@oracle.com, CN=development.oracle.com, OU=Development,
    O=Oracle, L=Monrovia, ST=California, C=US
   Issuer: EmailAddress=development@opracle.com, CN=development.oracle.com, 
   OU=Development, O=Oracle, L=Monrovia, ST=California, C=US
   Serial number: 0
   Valid from: Tue May 08 15:09:07 PDT 2007 until: Wed May 08 
       15:09:07 PDT 2008
   Certificate fingerprints:
   MD5:  60:73:83:A0:7C:33:28:C3:D3:A4:35:A2:1E:34:87:F0
   SHA1: C6:D0:C7:93:8E:A4:08:F8:38:BB:D4:11:03:C9:E6:CB:9C:D0:72:D0
   Trust this certificate? [no]:  yes
   Certificate was added to keystore

5. Use the keytool to import the signed certificate for the associated client alias in the keystore.

   keytool –import –keystore clientkeystore –file client.cer –alias client
   
   Enter keystore password: javacaps
   Certificate reply was installed in keystore

   ---

   Caution - The following error will be generated if there is no certificate chain in the client certificate. keytool -import -keystore clientkeystore -file client.cer -alias client Enter keystore password: javacaps keytool error: java.lang.Exception: Failed to establish chain from reply This error is because the CA’s certificate was not imported into the KeyStore first. You must import the CA's certificate (step 4), then import the client.cer file itself to form a certificate chain (step 5).

   ---

   Now that we have a private key and an associating certificate chain in the KeyStore clientkeystore, we can use it as a KeyStore for client (adapter) authentication. The only warning is that the CA certificate must be imported into the trusted certificate store of the web server to which you will be connecting. Moreover, the web server must be configured for client authentication (httpd.conf for Apache, for example).

Windows OpenSSL.cnf File Example

This section contains the contents of the openssl.cnf file that can be used on Windows. Be sure to make the appropriate changes to the directories.

#
# SSLeay example properties file.
# This is mostly being used for generation of certificate requests.
#

RANDFILE        = .rnd

####################################################################
[ ca ]
default_ca    = CA_default        # The default ca section

####################################################################
[ CA_default ]

dir        = G:\\openssl\\\bin\\demoCA    # Where everything is kept
certs        = $dir\\certs                # Where the issued certs are kept
crl_dir    = $dir\\crl                # Where the issued crl are kept
database    = $dir\\index.txt            # database index file.
new_certs_dir    = $dir\\newcerts            # default place for new certs.

certificate    = $dir\\cacert.pem                # The CA certificate
serial        = $dir\\serial                # The current serial number
crl        = $dir\\crl.pem                # The current CRL
private_key    = $dir\\private\\cakey.pem       # The private key
RANDFILE    = $dir\\private\\private.rnd     # private random number file

x509_extensions    = x509v3_extensions    # The extentions to add to the cert
default_days        = 365            # how long to certify for
default_crl_days    = 30            # how long before next CRL
default_md        = md5            # which md to use.
preserve        = no            # keep passed DN ordering

# A few difference way of specifying how similar the request should look
# For type CA, the listed attributes must be the same, and the optional
# and supplied fields are just that :-)
policy        = policy_match

# For the CA policy
[ policy_match ]
countryName            = match
stateOrProvinceName        = match
organizationName        = match
organizationalUnitName    = optional
commonName            = supplied
emailAddress            = optional

# For the ’anything’ policy
# At this point in time, you must list all acceptable ’object’
# types.
[ policy_anything ]
countryName        = optional
stateOrProvinceName    = optional
localityName        = optional
organizationName    = optional
organizationalUnitName    = optional
commonName            = supplied
emailAddress            = optional

####################################################################
[ req ]
default_bits        = 1024
default_keyfile     = privkey.pem
distinguished_name    = req_distinguished_name
attributes        = req_attributes

[ req_distinguished_name ]
countryName            = Country Name (2 letter code)
countryName_min        = 2
countryName_max        = 2

stateOrProvinceName        = State or Province Name (full name)

localityName            = Locality Name (eg, city)

0.organizationName        = Organization Name (eg, company)

organizationalUnitName    = Organizational Unit Name (eg, section)

commonName            = Common Name (eg, your website’s domain name)
commonName_max        = 64

emailAddress            = Email Address
emailAddress_max        = 40

[ req_attributes ]
challengePassword        = A challenge password
challengePassword_min    = 4
challengePassword_max    = 20

[ x509v3_extensions ]