Skip to main content

AVIX Server SSL configuration

AVIX Server is using an embedded version of the Jetty web server. Based on Java, it uses a KeyStore to store and manage public key certificates and private keys.

 The configuration of the Jetty server is placed in the /jetty/home/ folder at the root of the AVIX Server installation. The  AVIX server is shipped with a self-signed certificate which is stored in the KeyStore which is located at /jetty/home/ssl/keystore. 

A self-signed certificate is not trusted by default, and users of the server will see a warning message in their browser indicating that the certificate is not trusted. To avoid this, you might want to switch from the self-signed certificate to a certificate issued by a trusted Certificate Authority (CA)

Configuring SSL/TLS KeyStores

A KeyStore is a file on the file system that contains a private key and a public certificate, along with the certificate chain of the certificate authorities that issued the certificate. The private key, the public certificate, and the certificate chain, but more generally the items present in a KeyStore, are typically referred to as "cryptographic material".

Keystores may encode the cryptographic material with different encodings, the most common being  PKCS12, and are typically protected by a password.

Creating a KeyStore

KeyStores are created with the JDK tool $JAVA_HOME/bin/keytool

The following command creates a KeyStore file containing a private key and a self-signed certificate:

keytool
    -genkeypair 
    -alias mykey 
    -validity 90 
    -keyalg RSA 
    -keysize 2048 
    -keystore /path/to/keystore.p12 
    -storetype pkcs12 
    -dname "CN=domain.com, OU=Unit, O=Company, L=City, S=State, C=Country" 
    -ext san=dns:www.domain.com,dns:domain.org 
    -v
genkeypair the command to generate a key and certificate pair
alias the alias name of the key and certificate pair
validity specifies the number of days after which the certificate expires
keyalg the algorithm must be RSA (the DSA algorithm does not work for web sites)
keysize indicates the strength of the key
keystore the KeyStore file
storetype the KeyStore type, stick with the standard PKCS12
dname the distinguished name (more below) — customize it with your values for CN, OU, O, L, S and C
ext the extension with the subject alternative names (more below)
v verbose output

The command prompts for the KeyStore password that you must choose to protect access to the KeyStore.

The important parts of the command above are the Common Name (CN) part of the distinguished name, and the subject alternative names (SAN).

The CN value must be the main domain you own and that you want to use for your web applications. For example, if you have bought domains domain.com and domain.org, you want to specify CN=domain.com as your main domain.

Furthermore, to specify additional domains or subdomains within the same certificate, you must specify the SAN extension. In the example above, san=dns:www.domain.com,dns:domain.org specifies www.domain.com and domain.org as alternative names for your web applications (that you can configure using virtual hosts).

In rare cases, you may want to specify IP addresses, rather than domains, in the SAN extension. The syntax in such case is san=ip:127.0.0.1,ip:[::1], which specifies as subject alternative names IPv4 127.0.0.1 and IPv6 [::1].

KeyStores with Multiple Entries

A single KeyStore may contain multiple key/certificate pairs. This is useful when you need to support multiple domains on the same Jetty server (typically accomplished using virtual hosts).

You can create multiple key/certificate pairs as detailed in the previous section, provided that you assign each one to a different alias.

Compliant TLS clients will send the TLS SNI extension when creating new connections, and Jetty will automatically choose the right certificate by matching the SNI name sent by the client with the CN or SAN of certificates present in the KeyStore.

Creating a Certificate Signing Request

Self-signed certificates are not trusted by browsers and generic clients: you need to establish a trust chain by having your self-signed certificate signed by a certificate authority (CA).

Browsers and generic clients (e.g. Java clients) have an internal list of trusted certificate authorities root certificates; they use these trusted certificates to verify the certificate they received from the server when they connect to your web applications.

To have your self-signed certificate signed by a certificate authority you first need to produce a certificate signing request (CSR):

keytool
    -certreq 
    -file domain.com.csr 
    -keystore keystore.p12
certreq the command to generate a certificate signing request
file the file to save the CSR
keystore the keystore that contains the self-signed certificate

Then, you have to send the CSR file to the certificate authority of your choice, and wait for their reply (they will probably require a proof that you really own the domains indicated in your certificate).

Eventually, the certificate authority will reply to you with one or more files containing the CA certificate chain, and your certificate signed by their certificate chain.

Importing the Signed Certificate

The file you receive from the CA is typically in PEM format, and you must import it back into the same KeyStore file you used to generate the CSR. You must import both the certificate chain and your signed certificate.

First, import the certificate chain:

keytool
    -importcert 
    -alias ca 
    -file chain_from_ca.pem 
    -keystore keystore.p12 
    -trustcacerts 
    -v
importcert the command to import certificates
alias use the ca alias to differentiate from the alias of the server certificate
file the file containing the certificate chain received from the CA
keystore your KeyStore file
trustcacerts specify that you trust CA certificates
v verbose output

Then, import the signed certificate:

keytool
    -importcert
    -file signed_certificate.pem
    -keystore keystore.p12
    -trustcacerts
    -v

Now you have a trusted certificate in your KeyStore that you can use for the domains of your web applications.

TODO: Update this reference: Refer to the section about configuring secure protocols to configure the secure connector with your newly created KeyStore.

Back to top