About HTTPS certificates for REM

On the REM VMs, REM runs on Apache Tomcat, where the Tomcat webserver is configured to only accept traffic over HTTPS. As such, Tomcat requires a server-side certificate, which is presented to the user’s browser to prove the server’s identity when a user accesses REM.

Certificates are generated and signed by a known and trusted Certificate Authority (CA). This is done by having a chain of certificates, starting from the CA’s root certificate, where each certificate signs the next in the chain - creating a chain of trust from the CA to the end user’s webserver.

Each certificate is associated with a private key. The certificate itself contains a public key which matches the private key, and these keys are used to encrypt and decrypt the traffic flowing over the HTTPS connection. While the certificate can be safely shared publicly, the private key must be kept safe and not revealed to anyone.

Using rvtconfig, you can upload certificates and private keys to the REM nodes, and initconf will automatically set up Tomcat to use them.

Note

To avoid any browser warnings for users accessing REM, you may need to add the CA’s root certificate to the browser’s in-built list of trusted root certificates, for example, by using group policy settings.

HTTPS certificate specification

A Certificate Authority can issue you with a signed certificate for your REM domain(s) and/or IP address(es). To ensure your certificate is compatible with initconf, it should conform to RFC 2818, that is to say that each domain name and/or IP address through which users will log in to REM must be specified in the certificate as a Subject Alternative Name (SAN), and not solely specified in the Common Name (CN). SANs must be of DNS (also known as IA5 dNSName) type for hostnames and IP (IA5 iPAddress) type for IP addresses.

Warning

Hostnames must be used for REM certificates as these direct IP addresses are private and should not be exposed to the public Internet.

The DNS entry for each of these REM hostnames must resolve to only one node. This ensures that all REM requests made in a single session are directed to a single node.

To obtain a certificate, you will need to generate a certificate signing request using openssl and send it to the CA.

When making this request, you will need to use an input file in the openssl command to specify the SAN. In this input file, specify at least the Country (C), Organisation (O), Organisational Unit (OU) and Common Name (CN) fields to match the details of your deployment. The CN must be equal to one of the SAN FQDNs.

Here is an example input file

rem_csr.cnf

[req]
distinguished_name = req_distinguished_name
req_extensions = req_ext
prompt = no

[req_distinguished_name]
C   = NZ
O   = SomeTelco
OU  = SomeCity Network Operations Center
CN  = mag01.telco.ims.network.net

[req_ext]
subjectAltName = @alt_names

[alt_names]
DNS.1 = mag01.telco.ims.network.net
DNS.2 = mag02.telco.ims.network.net
DNS.3 = mag03.telco.ims.network.net
DNS.4 = mag01-cs.telco.ims.network.net
DNS.5 = mag02-cs.telco.ims.network.net
DNS.6 = mag03-cs.telco.ims.network.net

There are also limits on key size of the certificate signing request. The min key size is 2048-bit and the max is 8192-bit. The desired key size can be specified in the openssl command using the -newkey rsa:<keysize> option.

To generate the certificate signing request, run the following command, please change the keysize as desired:

openssl req -newkey rsa:2048 -keyout rem.key -out rem.csr -nodes -config rem_csr.cnf

The output files are the certificate signing request (rem.csr) and your private key (rem.key). The certificate signing request should be sent to the CA, who will then issue a certificate bundle for you. DO NOT DIRECTLY UPLOAD ANY OF THE CERTIFICATES GIVEN TO YOU BY THE CA. THEY MUST BE FORMATTED USING THE STEPS OUTLINED BELOW

Ensure that the CA issues your certificates in PEM (Privacy-Enhanced Mail) format. In addition, the private key must not have a passphrase (even an empty one).

Formatting the certificate bundle

A certificate bundle issued by a CA generally contains your certificate, their root certificate, and possibly one or more intermediate certificates. All certificates in the chain need to be merged into a single file in order to be uploaded for use with Tomcat. To format this correctly, follow these steps:

  1. Ensure the files are in PEM format. You can do this by first checking that the contents of each file begins with this line

    ----- BEGIN CERTIFICATE -----

    and ends with this line

    ----- END CERTIFICATE -----

    (the exact number of hyphens in the line can vary). Then check the certificates are valid and not expired by using openssl:

    openssl x509 -in <filename> -inform pem -text -noout

    If the certificate is indeed in PEM format, this command will display the certificate details. You can check that for your certificate, the subject details (the C, OU and so on) match those you specified on the certificate request. Look at the Validity fields to ensure all certificates in the bundle are valid. For initconf to accept them, they must all be valid for at least 30 days from the day you upload them.

  2. Work out the order of the certificates. The certificates should be ordered so that each certificate is signed by the next. You can work out which certificate is signed by which by looking at the Issuer and Subject of the certificates. The Issuer of the first certificate in the chain should match the Subject of the second certificate in the chain. This indicates that the first certificate is signed by the second certificate. All subsequent certificates in the chain will follow this pattern. To take an example of a bundle containing your certificate, the root certificate and one intermediate certificate: your certificate is signed by the intermediate, and the intermediate certificate is signed by the root. So these should be ordered leaf, intermediate, root. If in doubt, contact your CA who can tell you which certificate is signed by which.

  3. Construct the chain by concatenating the files together in the order decided in the step above. For example, this can be done using the Linux cat utility as follows:

    cat my_certificate.crt intermediate_certificate.crt root_certificate.crt >chain.crt

    this will create a file chain.crt containing the entire certificate chain which is suitable for uploading to the REM nodes.

  4. Keep the private key safe - you should not reveal the contents of the file to anyone outside of your organisation, not even Metaswitch. You will however need to upload it to the REM nodes alongside the certificate chain. If you have multiple HTTPS certificates and private keys, ensure you can associate each private key with the certificate it refers to.

Uploading a certificate chain and private key for REM during configuration

To upload the certificate chain and private key to the nodes, you will need to put the certificate chain and private key in the directory containing the RVT YAML configuration files and upload these files using rvtconfig upload-config.

To do this, follow the following steps:

Copy the certificate chain and private key files to the SIMPL VM and rename them

On the SIMPL VM place the certificate chain and private key files in the directory containing the YAML files, ensuring the files follow this naming scheme:

  • For REM, the certificate chain file must have the filename rem-cert.crt, and the private key file must have the filename rem-cert.key.

Validate the REM certificate chain

Validate the REM certificate chain has been formatted correctly by running this command from the directory containing the RVT YAML configuration files:

openssl crl2pkcs7 -nocrl -certfile rem-cert.crt | openssl pkcs7 -print_certs -noout

This command will output the subject and the issuer of each certificate in the chain in order.

There must be at least two certificates in the chain (the leaf and the root). If only one subject and one issuer is shown in the output, this means the certificate file is not valid. Run through the steps in section "Formatting the certificate bundle" again, then re-run the command above to validate the certificate file is in the correct format.

If this command outputs an error, then the chain has not been formatted correctly. Ensure each certificate in the chain is in PEM format and starts on a new line.

Check that each issuer matches the subject directly below it. This indicates they are chained in the correct order. If this is not the case then follow the steps in section "Formatting the certificate bundle" to put them in the right order, then retry the command above.

An example of a successful output with three certificates (one intermediate cert) looks like this:

subject=CN = Mutual Identification Certificate, O = Metaswitch, L = Edinburgh, C = UK
issuer=CN = Intermediate Signing Certificate, O = Metaswitch, L = Edinburgh, C = UK
subject=CN = Intermediate Signing Certificate, O = Metaswitch, L = Edinburgh, C = UK
issuer=CN = Root Signing Certificate, O = Metaswitch, L = Edinburgh, C = UK
subject=CN = Root Signing Certificate, O = Metaswitch, L = Edinburgh, C = UK
issuer=CN = Root Signing Certificate, O = Metaswitch, L = Edinburgh, C = UK

The following example shows a failed output, where the issuer does not match the subject directly below it. In this case the root cert has been put before the leaf cert:

subject=CN = Root Signing Certificate, O = Metaswitch, L = Edinburgh, C = UK
issuer=CN = Root Signing Certificate, O = Metaswitch, L = Edinburgh, C = UK
subject=CN = Mutual Identification Certificate, O = Metaswitch, L = Edinburgh, C = UK
issuer=CN = Intermediate Signing Certificate, O = Metaswitch, L = Edinburgh, C = UK
subject=CN = Intermediate Signing Certificate, O = Metaswitch, L = Edinburgh, C = UK
issuer=CN = Root Signing Certificate, O = Metaswitch, L = Edinburgh, C = UK

Upload the configuration

The config can then be uploaded, as it would be done for any change to the YAML configuration, using rvtconfig upload-config to the REM nodes. An example command is shown below:

./rvtconfig upload-config -c <cds-address> -t mag -i <config-dir> --vm-version-source this-rvtconfig

where <cds-address> is the IP address of the CDS, <config-dir> is the path to the directory containing the YAML files.

This command will locate the files through the known filenames given above. It will then run a few basic checks on the files, such as checking whether the private key matches the certificate, and that the certificate is not due to expire in less than 30 days. If all checks pass, then the certificates will be uploaded to the CDS and installed by initconf. Otherwise, rvtconfig upload-config will inform you of any errors. Correct these and try again.

Note that you must provide both the certificate chain and private key. If you provide only one, rvtconfig upload-config will fail.

Changing the certificate

Once a certificate and key have been successfully uploaded to the nodes, there is no need to upload them again on subsequent reconfigurations. The node will continue to use the same certificate.

You can replace a CA-issued certificate at any time by following the same steps above with a new certificate chain file and private key file.

Previous page Next page
VM Build Container Version 3.2