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.p12. and is protected by the password storepwd .

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)

Configuration of SSL Settings

The configuration of SSL is done in the main AVIX configuration file :
<installation dir>/configuration/se.solme.avix.prefs read more about how the configuration of AVIX works in the AVIX Operating manual here

[se.solme.avix.server]
# The path to the KeyStore used by the SSL acceptor
jetty.sslContext.keyStorePath = ssl/keystore.p12

# The password to the KeyStore file. If the password starts with OBF:
# it is considered as "obfuscated" by the Jetty password tool.
jetty.sslContext.keyStorePassword = storepwd

# Controls which port to use for the server SSL acceptor
# Default value is 45543
jetty.ssl.port = 45543

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 own domain.com, you want to specify CN=domain.com 

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].

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 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 AVIX server.

Modifying Keystore

This section covers the modification of Java Keystore entries, such as deleting or renaming aliases.

Change Keystore Password

This command is used to change the password of a keystore (keystore.p12):

keytool -storepasswd
        -keystore keystore.p12

You will be prompted for the current password, then the new password. You may also specify the new password in the command by using the -new newpass option, where “newpass” is the password.

Delete Alias

This command is used to delete an alias (domain) in a keystore (keystore.p12):

keytool -delete
        -alias domain
        -keystore keystore.p12

You will be prompted for the keystore password.

Rename Alias

This command will rename the alias (domain) to the destination alias (newdomain) in the keystore (keystore.p12):

keytool -changealias
        -alias domain
        -destalias newdomain
        -keystore keystore.p12

You will be prompted for the keystore password.

Back to top