Configuring SSL in the Web Services SSM

When you create a Web Services SSM instance, it accessible via HTTP. This is appropriate for development and for debugging purposes, but production environments should use SSL.

This section contains procedures to enable one-way SSL communication or two-way SSL communication between a Web Services SSM and its client. It is assumed that the reader has basic knowledge of the SSL protocol, certificate authorities, X.509 certificates and Java keystores (JKS). The procedures are:

Configuring One-Way SSL

With one-way SSL, the SSM sends its identity certificate to the client, therefore the client must trust the certificate authority (CA) that signed the identity certificate. (The client does not have to have its own certificate as it is not authenticated by the Web Services SSM.)

Stop the Web Services SSM if it is running.
Delete the contents of the %SSM_INST_HOME%\apps directory.
Run the following command to regenerate the content of the apps directory:

%SSM_INST_HOME%\adm\ssmwsInstance.bat -m

Restart the Web Services SSM.

After performing the above, copy the trust.jks to the client and specify the following system properties when running the client:

-Djavax.net.ssl.trustStore=C:\jks\trust.jks
-Djavax.net.ssl.trustStorePassword="secretword"

Configuring Two-Way SSL

To set up two-way SSL communication, both the Web Services SSM server and the client must trust each other. Follow the procedures to configure both the server side and the client side. Additionally, the client has to supply its certificate upon the Web Services SSM server's request. The JKS that stores the certificate is defined as the value of the javax.net.ssl.keyStore system property and the password of the JKS is defined as the value of the javax.net.ssl.keyStorePassword system property.

Define the certificate authority that signed the Web Services SSM server's certificate as trusted by adding its certificate to the client's truststore.
The truststore file is defined as the value of the system property javax.net.ssl.trustStore. The truststore's password is defined as the value of the javax.net.ssl.trustStorePassword property.

Create a certificate and accompanying keystore for the client.
This sample procedure uses the keytool utility shipped with the standard Java Development Kit (JDK). See the JDK documentation for more information.
1. Create a private/public key pair, a self-signed certificate and a keystore file.
  keytool -genkey -keyalg RSA -alias "WS-SSM Client" -keystore clientkeystore.jks -validity 365
2. Create a certificate signing request (CSR).
  This CSR will be sent to a certificate authority for signing.
  keytool -certreq -alias "WS-SSM Client" -file WS-SSM-Client.csr -keystore clientkeystore.jks
3. Send the WS-SSM-Client.csr file to a certificate authority for signing.
  The certificate authority will return a signed .crt file. Alternately, you can sign it as your own certificate authority. See Using OpenSSL To Become A Certificate Authority.
4. Update clientkeystore.jks with the certificate authority's root certificate and the signed certificate returned by the certificate authority.
  1. Import the certificate authority's root certificate into clientkeystore.jks.
    This is a requirement when using keytool. We will remove it after importing the signed certificate.
```
keytool -import -file CA.crt -alias Trusted-CA
-keystore clientkeystore.jks
```
  2. Remove the certificate authority's root certificate from the clientkeystore.jks.
    keytool -delete -alias Trusted-CA -keystore clientkeystore.jks

Confirm that the certificates were successfully imported into the key store.

keytool -list -keystore clientkeystore.jks -v

You should see something similar to this output.

Keystore type: JKS
Keystore provider: SUN

Your keystore contains 1 entry

Alias name: wsssmclient
Creation date: Mar 11, 2010
Entry type: PrivateKeyEntry
Certificate chain length: 2
Certificate[1]:
Owner: CN=wsssm_client, OU=ORACLE, O=ORACLE, L=BJ, ST=BJ, C=CN
Issuer: CN=TEMP_CA, OU=ORACLE, O=ORACLE, L=BJ, ST=BJ, C=CN
Serial number: 1
Valid from: Thu Mar 11 10:24:01 CST 2010 until: Fri Mar 11 10:24:01 CST 2011
Certificate fingerprints:
         MD5:  2A:E5:BB:DF:93:8E:5C:8A:F7:AA:FB:9B:F4:0D:BE:70
         SHA1: 9F:A3:1E:5F:64:DF:62:E9:CD:CF:EC:A7:D8:0C:3F:77:87:70:59:E9
         Signature algorithm name: MD5withRSA
         Version: 3

Extensions:

#1: ObjectId: 2.5.29.15 Criticality=true
KeyUsage [
  DigitalSignature
  Key_Encipherment
]

#2: ObjectId: 2.5.29.19 Criticality=false
BasicConstraints:[
  CA:false
  PathLen: undefined
]

Certificate[2]:
Owner: CN=TEMP_CA, OU=ORACLE, O=ORACLE, L=BJ, ST=BJ, C=CN
Issuer: CN=TEMP_CA, OU=ORACLE, O=ORACLE, L=BJ, ST=BJ, C=CN
Serial number: c22a7e48f34351bd
Valid from: Thu Mar 11 10:10:52 CST 2010 until: Fri Mar 11 10:10:52 CST 2011
Certificate fingerprints:
         MD5:  F1:0D:D7:86:04:96:00:8F:6C:81:F1:42:0F:B1:08:7A
         SHA1: 2E:8D:CA:2E:62:B4:3B:FA:15:E4:93:88:B5:B9:C6:16:47:E0:46:3C
         Signature algorithm name: MD5withRSA
         Version: 3

Extensions:

#1: ObjectId: 2.5.29.15 Criticality=true
KeyUsage [
  Key_CertSign
]

#2: ObjectId: 2.5.29.19 Criticality=true
BasicConstraints:[
  CA:true
  PathLen:2
]

Define the certificate authority that signed the client's certificate as trusted by adding its certificate to the Web Services SSM server's certificate authority truststore using the following command:
keytool -import -file cacert.crt -alias Trusted-CA -keystore %ALES32-SHARED%/keys/trust.jks
The server's trusted certificate authority file is defined in the <trust> element of the %SSM_INST_HOME%\apps\ssmws-asi\SAR-INF\config.xml file. By default, this is %ALES32-SHARED%/keys/trust.jks.

Define the client as trusted by adding its certificate to the Web Services SSM server's peer truststore.
keytool -import -file WS-SSM-Client.crt -alias Trusted-WS-Client -keystore %ALES32-SHARED%/keys/peer.jks
The server's trusted peers file is defined in the <peer> element of the %SSM_INST_HOME%\apps\ssmws-asi\SAR-INF\config.xml file. By default, this is the %ALES32-SHARED%/keys/peer.jks file.

Stop the WS-SSM Server if it is running.

Delete the contents of the %SSM_INST_HOME%\apps directory.

Run the %SSM_INST_HOME%\adm\ssmwsInstance.bat -s command to regenerate the contents of the apps directory.

Restart the WS-SSM Server.
You should now be able to establish secure communications between the Web Services SSM server and the client.

Using OpenSSL To Become A Certificate Authority

Following is the procedure to become your own certificate authority using OPENSSL. After completion, you can sign the CSR for the Web Services SSM client and generate a signed .crt file..

Download and install OpenSSL.
See The OpenSSL Project for more information.

Modify the openssl.conf file with the X.509 extensions that are compatible with the WS-SSM server.
- Use the following definitions for generating a certificate authority certificate:
```
 
[ v3_ca ]
basicConstraints = critical,CA:true, pathlen:2
keyUsage = critical, keyCertSign
```
- Use the following definitions for signing authorized certificates:
```
[ v3_req ]
basicConstraints = CA:FALSE
keyUsage = critical, digitalSignature, keyEncipherment
```
Create a certificate authority root certificate using the following sub procedure.
1. Generate a 1024-bit public/private key pair in the .pem format.
  openssl genrsa -out keys\cakey.pem 1024
2. Generate a certificate authority root certificate in the .pem format.
  openssl req -config openssl.conf -new -x509 -days 365 -key keys/cakey.pem -out certs/cacert.pem

Sign the WS-SSM-Client.csr request using the certificate authority root certificate created in the previous step.

openssl ca -policy policy_anything -config openssl.conf -cert certs/cacert.pem 
-in WS-SSM-Client.csr -keyfile keys/cakey.pem -days 365 -out certs/WS-SSM-Client.pem

Convert the certificate authority root certificate and the signed certificate from the .pem format to the .crt (DER) format for use with keytool.
- For the certificate authority root certificate use the following command:
  
  openssl x509 -outform der -in certs\cacert.pem -out certs\cacert.crt
- For the signed certificate use the following command:
```
openssl x509 -outform der -in certs\WS-SSM-Client.pem -out certs\WS-SSM-Client.crt
```

Securing OES Production Environments

Configuring SSL in the Web Services SSM

Configuring One-Way SSL

Configuring Two-Way SSL

Using OpenSSL To Become A Certificate Authority