Certificates in censhare environments

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 of 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 information:

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

CODE

openssl genrsa -out mycert.key 4096

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

CODE

cat mycertinfo.cnf

CODE

[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

CODE

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

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

CODE

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

Request to renew an existing CRT

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

CODE

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

Request your CRT at your CA

The domain owner has to request a CRT. For this, 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.

CODE

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

HAProxy

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

CODE

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

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:

CODE

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>

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.

CODE

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>

keystore

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

CODE

<!-- 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"/>

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):

CODE

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

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:

CODE

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

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:

CODE

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

rename an alias within the keystore:

CODE

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

import certificates into the truststore:

CODE

# 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

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.

CODE

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

export a certificate from a keystore:

CODE

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

change password:

CODE

keytool -storepasswd -new <new_password> -keystore keystore

list existing CAs in Java's default truststore:

CODE

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

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:

CODE

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

Useful commands to check certificates

Check if the certificate's private key and certificate pair

CODE

# 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

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

CODE

# 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

Other useful checks

CODE

# 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

Change certificate file format

Convert PEM to DER

CODE

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

Convert DER to PEM

CODE

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

Convert PEM to pkcs7 or pkcs12

CODE

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

Convert pkcs7 and pkcs12 into PEM

CODE

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