Basic information about SSL Certificates. The information censhare requires for implementing your certificates. A do-it-yourself guide to requesting certificates.

Understanding SSL certificates - short reference

For secure and encrypted communication, censhare requires SSL certificates for Java RMI (for example, censhare Client), FTPS and HTTPS communication (for example, censhare REST interface, censhare Web.)

CSR - Certificate Signing Request

A CSR must be generated to request a certificate.

A certificate authority is where you request a certificate. You will also retrieve the corresponding root and intermediate certificates here.

Private Key

A private key is used to encrypt or decrypt the CSR. Do not share it with the certificate authority (CA). The private key is later needed for the implementation of the certificate (CRT).

CRT - Certificate

For certificates, different encodings might use different file extensions. For example, .cer, .pem, .der or simply .txt.

See DIY on how to change the encoding of different file types.

CA - Certificate Authority

A certificate authority is where you request a certificate. You will also retrieve the corresponding root and intermediate certificates here.

SAN - Subject Alternative Name

If more than one host must be covered within one certificate, SAN entries can be used.

Wildcard Certificate

Wildcard certificates cover one level for all subdomains of a certain domain. For example, a *.censhare.com wildcard certificate covers server1.censhare.com, server2.censhare.com, etc. But it does not cover www.server1.censhare.com.

Root Certificate (Root CA)

Root certificates ensure the validation of the CA and are commonly shipped as part of operating systems and web browsers.

However, for some parties such as NGINX or RMI, a certificate chain has to be built in order to fully trust the service. For this purpose, root certificates might be required.

Intermediate Certificate (Intermediate CA)

Intermediate certificates are usually used to sign CRTs for end-users. CRTs in turn are signed by the root CA. For a full certificate chain, all three certificates might be needed: end-user certificates, intermediate certificates, and root certificates.

Note: Root certificates and intermediate certificates usually differ, based on the requested CRT. For example, regular versus extended CRTs might have different root and/or intermediate certificates.

See DIY on how to ensure that the root and intermediate certificate fits the actual CRT.

What censhare needs to implement your certificates

CRT on a censhare installation implemented by censhare

For implementing your certificates on a censhare installation, we need one of the following:

  • all required files - private Key, CRT, as well as the corresponding root and intermediate CA

    a proper chain and keystore

I want censhare to create my CSR

In this case, we need the following informations:

  • C - Country
    In which country is the company located to which the requested domain certificate belongs.

  • S - State Name

    State or province

  • L - Locality name
    City

  • O - Organization name 
    company name

  • OU - Organization unit

    For example, department

  • CN - Common name
    usually the FQDN for the requested certificate

I want censhare to implement my existing CRT

Different services require different implementations of certificates: nginx and ha-proxy use the CRT files directly while Java-based applications require that the certificates are stored in a keystore format

See keystore and truststore on how to create the keystore file.

If censhare takes care of the entire implementation, we need the following:

  • the private key with which the CSR was created. for example, for nginx and keystore)

  • the CRT itself, preferably in PEM format

  • the CA's root and intermediate certificates that is compatible to the CRT

truststore versus keystore @censhare

The keystore is used by the application to deliver certificates, for example RMIs or FTPs.

The truststore is used by the application to trust other certificates for communication. For example to trust a 3rd party application, such as LDAPs or an E-mail server. The truststore is usually only needed if the 3rd party application, which censhare needs to trust, is not part of the default Java trusted root certificates.

Note: To activate a customized truststore automatically levers out the existing Java default trusted certificates. In this case, you must always add new certificates to the truststore. For more information, see DIY.

Create a certificate DIY

For the sake of convenience, this section requires an operating system based on *nix and the relevant tools installed.

Generate your private key 

openssl genrsa -out mycert.key 4096
CODE

Create a CSR

To create a CSR, you can either use OpenSSL interactively or create a file with all required information and point to it with the OpenSSL command.

Create a CSR by file

cat mycertinfo.cnf

[req]
default_bits = 4096
prompt = nodefault_md = sha256
req_extensions = req_ext
distinguished_name = dn

[ dn ]
C=DEST=BavariaL=Munich
O=censhare AG
OU=IT Services
CN=server.censhare.com

[ req_ext ]
subjectAltName = @alt_names

[ alt_names ]
DNS.1 = server.censhare.com
DNS.2 = www.server.censhare.com
DNS.3 = server-rmi.censhare.com

openssl req -new -sha256 -key mycert.key -out mycertrequest.csr -config mycertinfo.cnf
CODE

Note: The sections req_ext and alt_names are optional and only needed if SAN is used.

Create a CSR with a simple interactive CMD method

openssl req -new -sha256 -key mycert.key -out mycertrequest.csr
CODE


Request to renew an existing CRT

For renewal, you can also gain information from the old certificate:

openssl x509 -x509toreq -in your_current.crt -out your_new.csr -signkey mycert.key
CODE

Request your CRT at your CA

The domain owner has to request a CRT. For this, the CSR is required.

Implement the CRT in the different services

NGINX

If you use a proxy server such as NGINX, a certificate bundle as well as the certificate key is required. A bundle contains the actual certificate and the CA intermediate certificate.

cat mycert.cer my_CA_intermediate.cer > mycert.chain.cer
CODE

The certificate key is sourced separately in the NGINX configuration.


HAProxy

For HAProxy, your certificate chain must be combined with the private key and must be in .pem format.

cat mycert.cer my_CA_intermediate.cer mycert.key > myhaproxycert.pem
CODE

RMIs and FTPs

SSL for RMI and FTP communication requires the certificates in Java's keystore format. For more information, see keystore and truststore.


Embedded Jetty WebServer

censhare embedded Jetty WebServer requires a certificate in keystore format. You can either point to the server keystore file or use its own certificate.

Copy jetty.xml from the default area to your customizing and adapt the relevant section:

cp ~corpus/css/app/services/httpserver/jetty.xml ~corpus/cscs/app/services/httpserver/
CODE 
<Set name="KeyStorePath"><SystemProperty name="jetty.home" default="." /> /app/config/keystore</Set><Set name="KeyStorePassword">corpus</Set>
CODE

Note: if you use NGINX or HAProxy as a Proxy server, a certificate on the embedded Jetty WebServer is not required.


Keycloak service

Keycloak is located in /opt/jboss/keycloak/ and requires a certificate in keystore format.

Go to the Keycloak configuration area and adapt the relevant section in the configuration file.

cd /opt/jboss/keycloak/standalone/configuration/vi standalone.xml
CODE 
<server-identities>	 
  <ssl>		
    <keystore path="my/path/to/keystore" relative-to="jboss.server.config.dir" 
     keystore-password="corpus" alias="<my_cert_alias>" key-password="corpus" 
     generate-self-signed-certificate-host="localhost"/>	
  </ssl>
</server-identities>
CODE


keystore and truststore

keystore

Enable the keystore in the server.xml (~corpus/cscs/app/config/server.$CSS_ID.xml):

<!-- set in this section your keystore and its password -->
<sysproperty key="javax.net.ssl.keyStore" 
  value="@current.runtime.dir@config/keystore" enabled="true"/>
<sysproperty key="javax.net.ssl.keyStorePassword" 
  value="your_keystore_password" enabled="true"/>
<!-- set in this section the alias in the keystore for the RMI service -->
<sysproperty key="censhare.rmi.keystoreAlias" 
  value="your_alias_in_keystore" enabled="true"/>

<!-- alias in the keystore for the FTPs service -->
<property key="ftp.keyalias" value="your_alias_in_keystore"/>
CODE


truststore

If censhare has to securely connect with other services via SSL and those CAs either aren't part of the Java default trusted CAs or a truststore is ready enabled, you must import the certificate into the truststore.

All implemented services in censhare use this truststore, such as LDAP or E-Mail.

Enable the truststore in the server.xml (~corpus/cscs/app/config/server.$CSS_ID.xml):

<sysproperty key="javax.net.ssl.trustStore" value="@current.runtime.dir@config/truststore" enabled="true"/>
<sysproperty key="javax.net.ssl.trustStorePassword" value="your_truststore_password" enabled="true"/>
CODE


Obtain a certificate to implement it into your truststore

We recommend that you obtain a certificate from a known service over CMD with the openssl command:

openssl s_client -showcerts -connect server.censhare.com:443 </dev/null 2> /dev/null|openssl x509  -outform PEM > certificate.pem
CODE

For information on how to implement certificates into a keystore or truststore, see keytool.

keytool commands to handle keystores and truststores

Enable the keystore in the server.xml (~corpus/cscs/app/config/server.$CSS_ID.xml)

Commands in this section are valid for keystore and truststore.

list certificates in a keystore:

keytool -list -keystore ~corpus/cscs/app/config/keystore
# use -v option for full information; hereafter for a particular alias
keytool -list -keystore ~corpus/cscs/app/config/keystore -alias <my_alias> -v
CODE


rename an alias within the keystore:

keytool -changealias -alias <current-alias> -destalias <new-alias> -keystore ~corpus/cscs/app/config/keystore
CODE

import certificates into the truststore:

# use different aliases when importing multiple certificates
keytool -importcert -file ldapserverSSLcertificate.crt -keystore ~corpus/cscs/app/config/truststore -alias ldapservername.com
keytool -importcert -file mailserverSSLcertificate.crt -keystore ~corpus/cscs/app/config/truststore -alias mailservername.com
CODE

import your certificate into the keystore:

For a proper RMI certificate within the keystore, a full certificate chain is required. You need the root CA as well as the intermediate CA besides the actual certificate and its key to build this chain.

cat mycert.pem proper_root_ca.pem proper_intermediate_ca.pem > mycert_chain.pem
openssl pkcs12 -export -inkey mycert.key -in mycert_chain.pem -out mycert_chain.pkcs12
keytool -importkeystore -srckeystore mycert_chain.pkcs12 -srcstoretype PKCS12 -destkeystore keystore
CODE

export a certificate from a keystore:

keytool -export -alias <cert_alias> -file mycert.crt -keystore keystore
CODE

change password:

keytool -storepasswd -new <new_password> -keystore keystore
CODE

list existing CAs in Java's default truststore:

keytool -list -v -keystore $JAVA_HOME/jre/lib/security/cacerts-storepass changeit
CODE

Note: Once a custom truststore is activated, the default Java trusted CAs are disabled. You can import them into your custom truststore with the following command:

keytool -importkeystore -srckeystore $JAVA_HOME/jre/lib/security/cacerts -destkeystore ~/cscs/app/config/truststore -deststoretype jks -srcstorepass changeit -deststorepass <your_password> -noprompt
CODE

Useful commands to check certificates

Check if the certificate's private key and certificate pair

# command should return the same md5 hash
openssl x509 -noout -modulus -in mycert.crt | openssl md5
openssl rsa -noout -modulus -in mycert.key | openssl md5
CODE


Check if the Root CA and Intermediate CA (and CRT) pair

# command should returk 'OK'
openssl verify -verbose -CAfile my_CA_root.cer my_CA_intermediate.cer
# the whole chain can be verified with the '-untrusted' option
openssl verify -verbose -CAfile my_CA_root.cer-untrusted my_CA_intermediate.cer mycert.cer
CODE

Other useful checks

# simple check certificate
openssl s_client -showcerts -connect server.censhare.com:443 </dev/null 2>/dev/null

# check available ciphers on a server
nmap --script ssl-enum-ciphers -p 443 server.censhare.com

# check a specific cipher (e.g. TLS 1.2)
openssl s_client -connect server.censhare.com:443 -tls1_2
CODE

Change certificate file format

Convert PEM to DER

openssl x509 -in mycert.crt -outform der -out mycert.der
CODE

Convert DER to PEM

openssl x509 -inform der -in mycert.der -out mycert.pem
CODE

Convert PEM to pkcs7 or pkcs12

openssl crl2pkcs7 -nocrl -certfile mycert.pem -out mycert.p7b

# you can also combine it with the intermediate CA
openssl crl2pkcs7 -nocrl -certfile mycert.pem -certfile mycert_chain.pem -out mycert.p7b

# pkcs12 format including key file
openssl pkcs12 -inkey mycert.key -in mycert.pem -export -out mycert.pfx
CODE

Convert pkcs7 and pkcs12 into PEM

openssl pkcs7 -in mycert.p7b -print_certs -out mycert.pemopenssl pkcs12 -in myce
CODE