A few frequently used Keytool commands

keytool does not support management of private keys inside a keystore. You need to use another tool for that. If you are using the JKS format, that means you need another java-based tool. extkeytool from the Shibboleth distribution can do this.

Create an empty keystore

keytool -genkey -alias foo -keystore truststore.jks keytool -delete -alias foo -keystore truststore.jks 

Generate a private key and an initial certificate as a JKS keystore

keytool -genkey -keyalg RSA -alias "selfsigned" -keystore KEYSTORE.jks -storepass "secret" -validity 360

you can also pass the data for the DN of the certificate as command-line parameters: -dname "CN=${pki-cn}, OU=${pki-ou}, O=${pki-o}, L=${pki-l}, S=${pki-s}, C=${pki-c}"

 

Generate a secret key that can be used for symmetric encryption. For this to work, you need to make use of a JCEKS keystore.

keytool -genseckey -alias "secret_key" -keystore KEYSTORE.jks -storepass "secret" -storetype "JCEKS" 

Generate a Certificate Signing Request for a key in a JKS keystore

keytool -certreq -v -alias "selfsigned" -keystore KEYSTORE.jks -storepass "secret" -file MYCSR.csr 

Import a (signed) certificate into a JKS keystore

keytool -import -keystore KEYSTORE.jks -storepass "secret" -file MYCERT.crt

add a public certificate to a JKS keystore, eg the JVM truststore

keytool -import -trustcacerts -alias "sensible-name-for-ca" -file CAcert.crt -keystore MYSTORE.jks

If the JVM truststore contains your certificate or the certificate of the root CA that signed your certificate, then the JVM will trust and thus might accept your certificate. The default truststore already contains the root certificates of most commonly used sommercial CA's. Use this command to add another certificate for trust:  

keytool -import -trustcacerts -alias "sensible-name-for-ca" -file CAcert.crt -keystore $JAVA_HOME/lib/security/cacerts

the default password of the Java truststore is "changeit". if $JAVA_HOME is set to the root of the JDK, then the truststore is it $JAVA_HOME/jre/lib/security/cacerts keytool does NOT support adding trust certificates to a PKCS12 keystore (which is very unfortunate but probably a good move to promote JKS)

 

delete a public certificate from a JAVA keystore (JKS; eg JVM truststore)

keytool -delete -alias "sensible-name-for-ca" -keystore $JAVA_HOME/lib/security/cacerts

the default password of the Java truststore is "changeit". if $JAVA_HOME is set to the root of the JDK, then the truststore is it $JAVA_HOME/jre/lib/security/cacerts  

List the certificates inside a keystore

keytool -list -v -keystore KEYSTORE.jks

-storetype pkcs12 can be used

 

Get information about a stand-alone certificate

keytool -printcert -v -file MYCERT.crt

 

Convert a JKS file to PKCS12 format (Java 1.6.x and above)

keytool -importkeystore -srckeystore KEYSTORE.jks -destkeystore KEYSTORE.p12 -srcstoretype JKS -deststoretype PKCS12 -srcstorepass mysecret -deststorepass mysecret -srcalias myalias -destalias myalias -srckeypass mykeypass -destkeypass mykeypass -noprompt

A few frequently used OpenSSL commands

generate a new private key and matching Certificate Signing Request (eg to send to a commercial CA)

openssl req -out MYCSR.csr -pubkey -new -keyout MYKEY.key 

add -nodes to create an unencrypted private key
add -config <openssl.cnf> if your config file has not been set in the environment 

 

decrypt private key

openssl rsa -in MYKEY.key >> MYKEY-NOCRYPT.key 

generate a certificate siging request for an existing private key

openssl req -out MYCSR.csr -key MYKEY.key -new 

generate a certificate signing request based on an existing x509 certificate

openssl x509 -x509toreq -in MYCRT.crt -out MYCSR.csr -signkey MYKEY.key 

create self-signed certificate (can be used to sign other certificates)

openssl req -x509 -new -out MYCERT.crt -keyout MYKEY.key -days 365 

sign a Certificate Signing Request

openssl x509 -req -in MYCSR.csr -CA MY-CA-CERT.crt -CAkey MY-CA-KEY.key -CAcreateserial -out MYCERT.crt -days 365

-days has to be less than the validity of the CA certificate 

convert DER (.crt .cer .der) to PEM

openssl x509 -inform der -in MYCERT.cer -out MYCERT.pem 

convert PEM to DER

openssl x509 -outform der -in MYCERT.pem -out MYCERT.der 

convert PKCS#12 (.pfx .p12) to PEM containing both private key and certificates

openssl pkcs12 -in KEYSTORE.pfx -out KEYSTORE.pem -nodes

add -nocerts for private key only; add -nokeys for certificates only 

 

convert (add) a seperate key and certificate to a new keystore of type PKCS#12

openssl pkcs12 -export -in MYCERT.crt -inkey MYKEY.key -out KEYSTORE.p12 -name "tomcat" 

convert (add) a seperate key and certificate to a new keystore of type PKCS#12 for use with a server that should send the chain too (eg Tomcat)

 

openssl pkcs12 -export -in MYCERT.crt -inkey MYKEY.key -out KEYSTORE.p12 -name "tomcat" -CAfile MY-CA-CERT.crt -caname myCA -chain

you can repeat the combination of "-CAfile" and "-caname" for each intermediate certificate

check a private key

openssl rsa -in MYKEY.key -check

add -noout to not disclose the key 

 

check a Certificate Signing Request

openssl req -text -noout -verify -in MYCSR.csr 

check a certificate

openssl x509 -in MYCERT.crt -text -noout 

check a PKCS#12 keystore

openssl pkcs12 -info -in KEYSTORE.p12 

check a trust chain of a certificate

openssl verify -CAfile MYCHAINFILE.pem -verbose MYCERT.crt

trust chain is in directory (hash format): replace -CAfile with -CApath /path/to/CAchainDir/
to check for server usage: -purpose sslserver
to check for client usage: -purpose sslient

debug an SSL connection [server doesn't require certificate authentication]

openssl s_client -connect idp.example.be:443

 

debug an SSL connection with mutual certificate authentication

openssl s_client -connect idp.example.be:8443 -CAfile MY-CA-CERT.crt -cert MYCERT.crt -key MYKEY.key

trust chain is in directory (hash format): replace -CAfile with -CApath /path/to/CAchainDir/
send the starttls command (smtp or pop3 style): -starttls smtp or -starttls pop3

 

Importing your Certificate/Private Key (from .pfx file format)

1. From the Start menu, select "Run...". Type "mmc" and hit Enter.
2. Under the File menu choose Add/Remove Snap in.
3. Click Add, then from the Add Standalone Snap-in panel choose Certificates, and click Add.
4. Choose Computer Account and click Next, then choose Local Computer and click Finish.
5. Close the Add Standalone Snap-In window by clicking Close.
6. Close the Add/Remove Snap-in window by clicking Ok.
7. Click the + to Expand the Certificates (Local Computer) Console Tree
8. Right click on the Personal Certificates Store (folder)
9. Choose > ALL TASKS > Import
10. Follow the Certificate Import Wizard to import your Primary Certificate from the .pfx file. When prompted, choose to automatically place the certificates in the certificate stores based on the type of the certificate.
11. Close the MMC console. In the case that you are prompted, it is not necessary to save the changes made to the MMC console.

Configuring Your Site - IIS 5/6

1. In your IIS manager, right-click on the site that you would like to use the certificate and select properties.
2. Click on the Directory Security Tab and hit the Server Certificate Button. This will start the server certificate wizard.
3. If given the option, Choose to 'Assign an existing certificate' to the site and choose the new certificate that you just imported.
   If you do not have that option, you should be asked what you want to do with the current certificate on the site, choose the option to "replace" your current certificate.
4. Browse to the .pfx file that you created earlier.
5. Finish the certificate wizard.

Occassionally a server or IIS restart is required before your server will recognize the new certificate.

Exporting/Backing up your certificate/Private Key (to .pfx file format)

1. From the Start menu, select "Run...". Type "mmc" and hit Enter.
2. Under the File menu choose Add/Remove Snap in.
   
   
3. Click Add, then from the Add Standalone Snap-in panel choose Certificates, and click Add.
   
   
   
4. Choose Computer Account and click Next, then choose Local Computer and click Finish.
5. Close the Add Standalone Snap-In window by clicking Close.
6. Close the Add/Remove Snap-in window by clicking Ok.
7. Click the + to Expand the Certificates (Local Computer) Console Tree
8. Look for the Personal directory/folder and expand Certificates.
9. Right Click on the Certificate you would like to backup and choose > ALL TASKS > Export
10. Follow the Certificate Export Wizard to backup your certificate to a .pfx file
11. Choose to 'Yes, export the private key'
12. Choose to include all certificates in certificate path if possible. (do NOT select the delete Private Key option)
13. Leave default settings > Enter Password (if required)
14. Choose to save file on a set location
15. Finish
16. You will receive a message > Export Successful
17. The .pfx file backup is now saved in the location you selected.

Installing your SSL Certificates in Apache

If you are installing an Extended Validation SSL Certificate, use our Apache EV SSL Certificate Installation Instructions. If you are installing any other certificate, follow the instructions below.

1. Copy the Certificate files to your server.
   Download your Intermediate (DigiCertCA.crt) and Primary Certificate (your_domain_name.crt) files from your Customer Area, then copy them to the directory on your server where you will keep your certificate and key files. Make them readable by root only.
   
2. Find the Apache config file to edit.
   The location and name of this file can vary from server to server -- Especially if you use a special interface to manage your server configuration.
   Apache configuration files are typically found in /etc/httpd. The main configuration file is usually named httpd.conf. In some cases the <VirtualHost> blocks will be at the bottom of this httpd.conf file. Sometimes you will find the <VirtualHost> blocks in their own files under a directory like /etc/httpd/vhosts.d/ or /etc/httpd/sites/ or in a file called ssl.conf.
   If you open the file with a text editor, you should be able to find <VirtualHost> blocks which contain Apache settings.
   
3. Identify the SSL <VirtualHost> block to configure.
   If you need your site to be accessible through both secure (https) and non-secure (http) connections, you will need a virtual host for each type of connection. Make a copy of the existing non-secure virtual host and configure it for SSL as described in step 4.
   If you only need your site to be accessed securely, configure the existing virtual host for SSL as described in step 4.
   
4. Configure the <VirtualHost> block for the SSL-enabled site.
   Below is a very simple example of a virtual host configured for SSL. The parts listed in bold are the parts that must be added for SSL configuration:
   

   <VirtualHost 192.168.0.1:443>
   DocumentRoot /var/www/html2
   ServerName www.yourdomain.com
   SSLEngine on
   SSLCertificateFile /path/to/your_domain_name.crt
   SSLCertificateKeyFile /path/to/your_private.key
   SSLCertificateChainFile /path/to/DigiCertCA.crt
   </VirtualHost>

   Adjust the file names to match your certificate files:
   
   • SSLCertificateFile should be your DigiCert certificate file (eg. your_domain_name.crt).
   • SSLCertificateKeyFile should be the key file generated when you created the CSR.
   • SSLCertificateChainFile should be the DigiCert intermediate certificate file (DigiCertCA.crt) If the SSLCertificateChainFile directive does not work, try using the SSLCACertificateFile directive instead.
5. Test your Apache config before restarting.
   It is always best to check your Apache config files for any errors before restarting, because Apache will not start again if your config files have syntax errors. Run the following command: (it is apache2ctl on some systems)
   apachectl configtest
   
6. Restart Apache.
   You can use apachectl commands to stop and start Apache with SSL support:
   apachectl stop
apachectl start
   Note: If Apache does not start with SSL support, try using "apachectl startssl" instead of "apachectl start". If SSL support only loads with "apachectl startssl" we recommend you adjust the apache startup configuration to include SSL support in the regular "apachectl start" command. Otherwise your server may require that you manually restart Apache using "apachectl startssl" in the event of a server reboot. This usually involves removing the <IfDefine SSL> and </IfDefine> tags that enclose your SSL configuration.
   

Troubleshooting:

1. If your web site is publicly accessible, our SSL Certificate Tester tool can help you diagnose common problems.
   
2. For help moving your certificates to additional servers or across server platforms, see our OpenSSL export instructions.
3. If you need to disable SSL version 2 compatibility in order to meet PCI Compliance requirements, you will need to add the following directive to your Apache configuration file:
       SSLCipherSuite HIGH:+MEDIUM:!SSLv2:!EXP:!ADH:!aNULL:!eNULL:!NULL
   If the directive already exists, you will probably need to modify it to disable SSL version 2.
   

Moving a Certificate from Apache to a Windows IIS Server

1. Back up your certificate: To import your certificate to Windows, you will first need to combine your primary certificate, Intermediate (CA) Certificate, and your private key file into a .pfx type backup file. To do this, use the following command:
   openssl pkcs12 -export -out DigiCertBackup.pfx -inkey your_private_key_file.txt -in your_domain_name.crt -certfile DigiCertCA.crt This creates a backup of your primary certificate called DigiCertBackup.pfx. Copy this file to your IIS Server.
   
2. Once the .pfx file is copied to your Windows server, follow these instructions to import your PFX file on Windows.

Importing an IIS .pfx file certificate into Apache or other non-Windows-based servers.

Most servers use plaintext certificate files. The certificate files that you download from your digicert account are already in this format. However, the private key that was generated on your IIS server is not yet in this format. This same private key is required for your certificate to function properly on your non-Windows-based server. To export the private key from the Windows IIS server to your non-windows-based machine, you must extract the private key from a Windows .pfx backup certificate. To do this you will use the OpenSSL utility to extract the private key from the .pfx backup file:

1. First backup the certificate you have working on your IIS server to a .pfx file using the instructions listed above.
2. Second, use the following OpenSSL command to create a new text file from which you can separate the Private Key: openssl pkcs12 -in mypfxfile.pfx -out outputfile.txt -nodes
   where mypfxfile.pfx is the certificate backup from your IIS server.
   
3. The above command would have created a text file named outputfile.txt. Open this file with a text editor and you will see the private key listed first: -----BEGIN RSA PRIVATE KEY-----
(Block of Random Text)
-----END RSA PRIVATE KEY-----
   
4. Copy and paste all of the private key, including the BEGIN and END tags to a new text file and save it as your_domain_name.key
5. Use the Digicert Certificate Installation Instructions to install the the .key file you just created and the other certificate files from your Digicert Account to your new server.

Convert PFX Certificate to PEM Format

For secure, trusted access you must install an SSL server certificate on the Access Gateway server. The uploaded certificate file must have the following characteristics:

The server certificate must be issued by a Certification Authority (CA) that is trusted by end users. For best results, use a commercial CA such as VeriSign, Thawte or GeoTrust.
The certificate must be in Privacy Enhanced Mail (PEM) format, a text-based format that is a Base64 encoding of the binary Distinguished Encoding Rules (DER) format.
The certificate file must include a private key and the private key must not be encrypted. There should be no password required to use the PEM file.
Any necessary intermediate certificates must also be appended to the end of the PEM file.

If you have requested and installed a certificate onto a Windows server using the Internet Information Service (IIS) certificate wizard, you can export that certificate with its private key to a Personal Information Exchange (PFX) file. To import this certificate onto the Access Gateway, you must convert the PFX file to the unencrypted PEM format.

You can use the open-source utility OpenSSL to perform the conversion from PFX to PEM. You can download a Win32 distribution of OpenSSL here:
http://www.slproweb.com/products/Win32OpenSSL.html


You might also need C++ re-distributable files if you want to use OpenSSL which can be obtained at the following URL: http://www.microsoft.com/downloads/details.aspx?FamilyID=9B2DA534-3E03-4391-8A4D-074B9F2BC1BF&displaylang=en

To convert a PFX file to a PEM file, follow these steps on a Windows machine: 

1. Download and install the Win32 OpenSSL (Win32 OpenSSL v0.9.8i) package from http://www.slproweb.com/products/Win32OpenSSL.html 
2. Create a folder c:\certs and copy the file yourcert.pfx into the c:\certs folder.
3. Open a command prompt and change into the OpenSSL\bin directory: cd %homedrive%\OpenSSL\bin
   
4. Type the following command to convert the PFX file to an unencrypted PEM file (all on one line): openssl pkcs12 -in c:\certs\yourcert.pfx -out c:\certs\cag.pem –nodes

When prompted for the import password, enter the password you used when exporting the certificate to a PFX file. You should receive a message that says MAC verified OK.

Point a browser to the Access Gateway administration portal or HTTPS port 9001: https://access-gateway-server:9001.
Log on as root. The default password is rootadmin.
Click the Maintenance link at the top of the page.
Click the Browse button next to the Upload Private Key + Certificate (.pem) field. Browse to the c:\certs\cag.pem file and click Upload.
Restart the Access Gateway for the new SSL certificate to be applied.