Configuring Java CAPS for SSL Support

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.

ProcedureTo 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) []:Sun
    Organizational Unit Name (eg, section) []:Development
    Common Name (eg, your websites domain name) []
        :development.sun.com
    Email Address []:development@sun.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.


Note –

No details are given here for the keytool commands. See Creating a KeyStore in JKS Format for more information.


ProcedureTo 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.sun.com
    What is the name of your organizational unit?
    [Unknown]:  Development
    What is the name of your organization?
    [Unknown]:  Sun
    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.sun.com, OU=Development, O=Sun, 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@sun.com, CN=development.sun.com, OU=Development,
     O=Sun, L=Monrovia, ST=California, C=US
    Issuer: EmailAddress=development@sun.com, CN=development.sun.com, 
    OU=Development, O=Sun, 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 – 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 ]

Note –

The following copyright notices apply: Copyright © 2004-2008 The OpenSSL Project. All rights reserved.Copyright © 2005-2008 World Wide Web Consortium, (Massachusetts Institute of Technology, Institut National de Recherche en Informatique et en Automatique, Keio University). All Rights Reserved. http://www.w3.org/Consortium/Legal/