How to setup SSL

Up until now, all requests were made using regular HTTP. We need to switch to HTTPS to prevent wiretapping and man-in-the-middle attacks. We’ll start with setting up a test certificate.

Setting Up SSL

1. Locate the keytool utility, the Java keytool utility is a tool for creation and management of Javakeystores. A keystore is a central repository for private/public key pairs and certficates used by the underlying Java SSL implementation.

In some cases the keytool utility will be in your path so in a command line prompt simply type keytool and press Enter, in response you should see the message:

Key and Certificate Management Tool followed by some usage information. message Plain text message.

messageIsText Should be set to the string “true” if text.

messageToEncrypt Plain text message that should be encrypted.

messageToEncryptIsText Should be set to the string “true” if text.

If keytool is not found in your path, then you should locate the Java JRE installation folder and run it from there, for example on my VPS node the path to keytool is /usr/lib/jvm/java-7-openjdk-amd64/jre/bin/keytool and on my Windows workstation it's c:\Program Files\Java\jre7\bin\keytool.exe.

2. From the command line cd to the keystash folder and issue the following command:

keytool -genkey -keystore keystore

Enter a keystore password, save it somewhere and don't lose it since you'll need it later.

Specify the server domain name correctly in reply to the confusing “What is your first and last name” prompt.

Fill the rest of the parameters, confirm and then enter a key password which should be the same as the keystore password.

Once you are done, verify that a file named keystore has been created in the root folder of your KeyStash server.

3. List the content of your keystore file and verify that the information is correct:

keytool -list -v -keystore keystore

4. In the keystash/conf folder create or edit the file keystash.properties and add the following entries:

keystash.apiSSL=true

keystash.keyStorePath=keystore

keystash.keyStorePassword=<same password you provided in step 2>

5. Restart your KeyStash node and wait for the “Started API server at 127.0.0.1:7801” message.

6. Test your connection by pointing your browser to the following address: https://localhost:7801

Dismiss the browser warning to start your KeyStash client using encrypted communication.

Trusted SSL

Now that that’s working, let’s switch to a trusted certification authority issued SSL certificate. Creating a certified keystore requires following the procedures documented by Java JSSE, I recommend that you start with understanding the keytool command: http://docs.oracle.com/javase/ 7/docs/technotes/tools/solaris/keytool.html and work from there using the specific instructions provided by your certificate authority to familiarize yourself with the process. I'd like to underscore the following common mistakes when managing the keystore file and certificate:

1. When you create a keystore and a private key, using the keytool -genkey command, makesure to specify the fully qualified server domain name correctly in reply to the mis-leading “What is your first and last name” question.

For example “www.mydomain.com” is a fully qualified domain name you should possess. “John Smith” is not such domain name.

Once the keystore is created, generate a certificate signing request (CSR), using the keytool - certreq command, and send it to the certification authority of your choice.

See for example documentation from Verisign: https://knowledge.verisign.com/support/ssl-certificates-support/index?page=content&actp=CROSSLINK&id=AR227

Note that you can use any certification authority which support Java, JKS and X509 formats for this process.

Here is how your keystore should look when you list it using keytool -list -v

The keystore information:

Keystore type: JKS

Keystore provider: SUN

Your keystore contains 1 entry

Alias name: myalias

Creation date: 11/11/2012

Entry type: PrivateKeyEntry

Certificate chain length: 1

Certificate1:

Owner: CN=www.mydomain.com, …

Issuer: CN=www.mydomain.com, …

2. Submit your CSR (certificate signing request) for the specific domain to the certificate authority of your choice to get a “Certificate Reply”. This process takes time and costs money. Expect to pay at least 100$ annually.

3. Import the certificate reply. Using the keytool -import -trustcacerts command, import the certification authority primary and secondary intermediate certificates into the same keystore used for generating the CSR then import the certificate reply into the same keystore using the same alias you gave the private key when generating the keystore and the CSR.

Make sure you receive the message Certificate reply was installed in keystore when importing the certificate reply.

See for more information: https://search.thawte.com/support/ssl-digital-certificates/index?page=content&actp=CROSSLINK&id=SO15518

Your keystore should now look like this (notice the PrivateKeyEntry and the two intermediate trustedCertEntry)

keytool -list -keystore keystore

Enter keystore password:

Keystore type: JKS

Keystore provider: SUN

Your keystore contains 3 entries

secondary, 12/11/2012, trustedCertEntry,

myalias, 12/11/2012, PrivateKeyEntry,

primary, 12/11/2012, trustedCertEntry,

If things do not work as expected, use the -Djavax.net.debug=all Java command line option

to generate diagnostic information.

See the following link for more information: http://docs.oracle.com/javase/1.5.0/docs/guide/security/jsse/ReadDebug.html

References:

Print/export