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 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
CityO - Organization name
company nameOU - 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
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
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
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
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
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
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/
<Set name="KeyStorePath"><SystemProperty name="jetty.home" default="." /> /app/config/keystore</Set><Set name="KeyStorePassword">corpus</Set>
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
<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 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"/>
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"/>
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
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
rename an alias within the keystore:
keytool -changealias -alias <current-alias> -destalias <new-alias> -keystore ~corpus/cscs/app/config/keystore
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
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
export a certificate from a keystore:
keytool -export -alias <cert_alias> -file mycert.crt -keystore keystore
change password:
keytool -storepasswd -new <new_password> -keystore keystore
list existing CAs in Java's default truststore:
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:
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
# 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
# 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
# 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
openssl x509 -in mycert.crt -outform der -out mycert.der
Convert DER to PEM
openssl x509 -inform der -in mycert.der -out mycert.pem
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
Convert pkcs7 and pkcs12 into PEM
openssl pkcs7 -in mycert.p7b -print_certs -out mycert.pemopenssl pkcs12 -in myce