====== SSL Commands ======

===== openssl =====

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

<code>
    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 
</code>

decrypt private key

<code>
    openssl rsa -in MYKEY.key >> MYKEY-NOCRYPT.key 
</code>

generate a certificate siging request for an existing private key

<code>
    openssl req -out MYCSR.csr -key MYKEY.key -new 
</code>

generate a certificate signing request based on an existing x509 certificate

<code>
    openssl x509 -x509toreq -in MYCRT.crt -out MYCSR.csr -signkey MYKEY.key 
</code>

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

<code>
    openssl req -x509 -new -out MYCERT.crt -keyout MYKEY.key -days 365 
</code>

sign a Certificate Signing Request

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

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

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

<code>
    openssl x509 -inform der -in MYCERT.cer -out MYCERT.pem 
</code>

convert PEM to DER

<code>
    openssl x509 -outform der -in MYCERT.pem -out MYCERT.der 
</code>

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

<code>
    openssl pkcs12 -in KEYSTORE.pfx -out KEYSTORE.pem -nodes 
    add -nocerts for private key only; add -nokeys for certificates only 
</code>

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

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

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)

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

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


check a private key

<code>
    openssl rsa -in MYKEY.key -check 
    add -noout to not disclose the key 
</code>

check a Certificate Signing Request

<code>
    openssl req -text -noout -verify -in MYCSR.csr 
</code>

check a certificate

<code>
    openssl x509 -in MYCERT.crt -text -noout 
</code>

check a PKCS#12 keystore

<code>
    openssl pkcs12 -info -in KEYSTORE.p12 
</code>

check a trust chain of a certificate

<code>
    openssl verify -CAfile MYCHAINFILE.pem -verbose MYCERT.crt 
</code>

    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]

<code>
    openssl s_client -connect idp.example.be:443 
</code>

debug an SSL connection with mutual certificate authentication

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

    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 

===== keytool =====

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

<code>
    keytool -genkey -alias foo -keystore truststore.jks
    keytool -delete -alias foo -keystore truststore.jks 
</code>

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

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

    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.

<code>
    keytool -genseckey -alias "secret_key" -keystore KEYSTORE.jks -storepass "secret" -storetype "JCEKS" 
</code>

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

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

Import a (signed) certificate into a JKS keystore

<code>
    keytool -import -keystore KEYSTORE.jks -storepass "secret" -file MYCERT.crt 
</code>

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

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

    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:

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

    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)

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

    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

<code>
    keytool -list -v -keystore KEYSTORE.jks 
    -storetype pkcs12 can be used 
</code>

Get information about a stand-alone certificate

<code>
    keytool -printcert -v -file MYCERT.crt 
</code>


===== notes: =====


openssl for win32 can be downloaded at http://www.slproweb.com/products/Win32OpenSSL.html. Version v0.9.8 is known to cause problems in combination with Shibboleth SP v1.3!

keytool is a part of each Sun Java distribution (binary). You need it to manipulate the Java KeyStore (JKS) format.

hash format: the -CApath directory should contain each certificate that needs to be trusted. The name of each certificate has to be its hashed value and a number. When running unix, execute "$ c_rehash ./" to create symlinks with the correct names. You can also do this manually with the -hash option of openssl (see "openssl verify").

please send remarks, corrections and other often used commands to shib@kuleuven.net