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. Alternatively, you can opt to have initconf generate self-signed certificates.

Note

REM, being a tool for network operators and available only over the management interface, should not be exposed to the public Internet. As such public CAs such as Let’s Encrypt will not be able to issue a certificate for it. To avoid any browser warnings for users accessing REM, you will need to set up a private CA and issue a certificate from that, and add the CA’s root certificate to the browser’s in-built list of trusted root certificates, for example, by using group policy settings.

If you do not have an in-house CA, use of a self-signed certificate is the recommended approach.

Self-signed certificates

If no certificate is uploaded for REM, initconf creates a self-signed certificate. This will be entirely functional, though users trying to log in to REM will see a browser warning stating that the certificate is self-signed, and will have to add a security exception in order to use REM.

HTTPS certificate specification

If you have an in-house Certificate Authority, they 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 as 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

If users are to connect to REM via hostname(s) rather than IP address(es), be sure the DNS entry for each hostname resolves to only one node. This ensures that all REM requests made in a single session are directed to a single node.

For the subject, specify at least the Country (C), Organisation (O), Organisational Unit (OU) and Common Name (CN) fields to match the details of your deployment.

Here is an example set of field values for a certificate request:

C = NZ
O = SomeTelco
OU = SomeCity Network Operations Center
CN = REM

SAN = DNS:rem.sometelco.com
SAN = IP:192.168.10.10

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

A certificate bundle issued by a CA generally contains your certificate, your private key, 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. Follow the steps below:

  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. 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. If there is more than one intermediate certificate then the CA can tell you which certificate is signed by which.

  3. Construct the chain by concatenating the files together in the correct order such that each certificate is signed by the next, starting with your certificate and ending with the root certificate. 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

    which will create a file chain.crt containing the entire certificate chain and 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

When uploading the YAML configuration files using rvtconfig, you can also include the certificate chain and private key and upload those at the same time.

To do this, place the certificate chain and private key files in the directory containing the YAML files before running rvtconfig.

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

No additional rvtconfig arguments are required; rvtconfig 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 will inform you of any errors. Correct these and try again.

Note that you must provide either both the certificate chain and private key, or neither (in which case initconf will generate a self-signed certificate). If you provide only one, rvtconfig 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.

If you are using a self-signed certificate, then subsequent reconfigurations will not recreate it. Self-signed certificates generated by initconf are valid for 5 years. If the certificate expires or you need to refresh it for some other reason (such as the private key being compromised), contact your Metaswitch Customer Care representative.

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. Providing a CA-issued certificate this way will also override any self-signed certificate currently in use.

Previous page Next page
Rhino VoLTE TAS VMs Version 4.0.0