Some ISDA web services require client authentication. In these cases, applications must obtain and install an Application certificate. This is not the same as your server certificate or a personal certificate. It identifies your application to the web service.

Using Application Client Certificates

INDEX:

1.   Acquiring an Application Client Certificate
a.   Generate an rsa key
b.   Generate a request for a certificate

2.   Creating a java keystore containing a Application Client Certificate

3.   Using the keystore in an application

1.  Acquiring a Application Client Certificate

a.  Generate an rsa key

For UNIX or LINUX systems:

On the system you want the certificate for:

1.  Create a directory which will be used to for generating the certificate request.

2.  cd to the newly created directory.

3.  Now generate some random stuff by doing the following command lines:

ps > foo
ps -elf >>  foo

4.  Execute the following command:

openssl genrsa -rand foo 1024  >  https-key.pem

For WINDOWS systems:

On the system you want the certificate for:

1. Create a directory which will be used to for generating the certificate request.

2.  cd to the newly created directory.

3.  Now generate some random stuff by doing the following command lines:

ps > foodir c:* * >>  foo

           

4. Execute the following command:

openssl genrsa -rand foo 1024 > https-key.pem

Do not misplace the https-key.pem file. This file contains the private key that you will need later on.

b.  Generate a request for a certificate

To generate a request for a certificate, execute to following command line:

openssl req -key https-key.pem -new  > req.pem

When prompted for input, use these answers: (or use the default answers for all but Common name and challenge password)

Country Name (2 letter code): US
State or Province Name (full name): Massachusetts
Locality Name (eg, city): Cambridge
Organization Name (eg, company): Massachusetts Institute of Technology
Organizational Unit Name (eg, section): (e.g. Information Services & Technology)
Common Name (eg, YOUR name): name of the application certificate (<applicationName>.app.mit.edu)
Email Address: (no entry needed)
A challenge password: (anything you choose - you should remember in case jis challenges you)
An optional company name: (no entry required)

The file, req.pem, contains the information for your certificate.  Cut and paste the contents of this file into an email and sent it to mitcert@mit.edu.  When you paste the contents of the req.pem file into the email, be sure to include the BEGIN and END lines. 

The Subject line of the email should read: Request for an Application Client Certificate.

Also include in the body of the email, a short line stating that you are requesting an Application Client Certificate.  Stating that you want an Application Client Certificate is important.  If you do not do this, you may be sent a server certificate which will not work.

2.  Creating a java keystore containing an Application Client Certificate.

After a few days, you will receive an email that has your Application Client Certificate as an attachment.  Save the Application Client Certificate to the directory you created in 1a above.  You can change the name of the certificate file to something that is meaningful to you. In this document, the Application Client Certificate was assumed to be saved as ApplicationClientCertificate.pem.

View the Application Client Certificate to verify that you have the correct certificate.  To view the certificate, execute the following command line:

openssl x509 -in ApplicationClientCertificate.pem -text

Find the line that says: Netscape Cert Type.  The line immediately following this line should say:  SSL Client, SSL Server, S/MIME, Object Signing.  If this is not the case, then you have the wrong type of certificate.

Also verify that the issuer of the certificate is the MIT client certificate authority by finding the following line:

Issuer: C=US, ST=*Massachusetts, O=Massachusetts Instituteof* Technology*, OU=ClientCA *V1

Also verify that the certificate is for your machine by finding your application certificate name in the certificate's *Subject:*line.   It will be the CN entry and will be of the form <applicationName>.app.mit.edu

Finally verify the certificate's activation and expiration dates by looking at the two lines following Validity.

The Application Client Certificate must be converted from x509v3 format to a pkcs12 format.  To do this, obtain the mitClient.cer (this is the MIT client CA V1 public key) and place it in the directory you created in 1a.  You can get the mitClient.cer by going to http://ca.mit.edu/mitClient.crtand saving the certificate to your working directory as mitClient.cer.

To convert the Application Client Certificate to a pkcs12 format, execute the following command line:

openssl pkcs12 -in ApplicationClientCerticate.pem -inkey https-key.pem -export -out ApplicationClientCertificate.p12 -nodes -CAfile mitClient.cer

           

ApplicaitonClientCertificate.p12 now contains the new application client certificate.  This certificate must now be imported into a java keystore.  To do this, obtain a copy of PKCS12Import.jar and place it in your working directory.  Execute the following command line:

java -jar PKCS12Import.jar ApplicationClientCertificate.p12 <certificate name>.jks

The keystore password will be set to changeit.

For example:  If your certificate name is foo.app.mit.edu, the command line would be:

java -jar PKCS12Import ApplicationClientCertificate.p12 foo.app.mit.edu.jks

Verify that the keystore was created successfully by executing the following command line:

keytool -list -keystore <application name>.jks

If everything is correct, something similar to the following line should be displayed. (The keystore password is changeit.)

Keystore type: JKSKeystore provider: SUN

Your keystore contains 1 entry

<application name>.p12, Jan 8, 2007, PrivateKeyEntry,

Certificate fingerprint (MD5): 66:C1:4E:0D:B1:59:FB:4C:99:E8:1A:49:7D:F6:EF:32

The <application name>.jks keystore can now be used by your application as a java keystore.

NOTE:  the keystore that you have created must contain only 1 certificate.

3.  Using the keystore in an application.

To use the keystore in an application, add the following 2 lines of java code somewhere prior to making the first call to the web service.

System.setProperty("javax.net.ssl.keyStore", KeyStoreFile);System.setProperty("javax.net.ssl.keyStorePassword", KeystorePassword);

TheKeyStoreFile is a string containing the path to and filename of the keystore file. The KeystorePassword is a string containing the keystore's password (in this case the password is "changeit").

Finally, your application certificate name must be entered into the Web Server's access control database.  You can do this by providing your application certificate name in your request sent to  isda-ws-request @ mit.edu, or entered into the RT queue ISDA::WS-REQUEST.

click here to go to the Product Documentation.
click here to go to the Product Catalogue.
click here to go Home.

  • No labels