On the MAG 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.
The MAG VMs accept connections from UEs to the Bootstrapping Server Function (BSF) and XCAP applications over both HTTP and HTTPS. For HTTPS, a server-side certificate is presented to the UE when the UE initiates a connection.
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.
rvtconfig, you can upload certificates and private keys to the
MAG nodes, and
initconf will automatically set up Tomcat to use them.
Alternatively, you can opt to have
initconf generate self-signed certificates.
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.
The XCAP server is accessed by UEs, and is therefore available only over the access interface,
i.e. the public Internet. Per the XCAP specification, XCAP URLs should be in the
For internal use in a lab deployment, a self-signed certificate can be automatically generated and used in place of a real certificate.
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.
Similarly, if no certificate is uploaded for XCAP or the BSF,
initconf will create a self-signed certificate.
Depending on the UE, requests might be rejected.
If you have an in-house Certificate Authority, they can issue you with a signed certificate for your
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
, XCAP or the BSF
must be specified in the certificate as a
Subject Alternative Name (SAN), and not as the Common Name (CN). SANs must be of
(also known as IA5
dNSName) type for hostnames and
iPAddress) type for IP addresses.
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.
On the contary, the XCAP and BSF hostnames should resolve to all nodes, to ensure proper load balancing and failover.
Domain names in the XCAP certificate must start with
Domain names in the BSF certificate must be identical to those in the XCAP certificate,
except that the initial
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:
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 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
Validityfields to ensure all certificates in the bundle are valid. For
initconfto accept them, they must all be valid for at least 30 days from the day you upload them.
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.
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
catutility as follows:
cat my_certificate.crt intermediate_certificate.crt root_certificate.crt >chain.crt
which will create a file
chain.crtcontaining the entire certificate chain and suitable for uploading to the MAG nodes.
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 MAG 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.
When uploading the YAML configuration files using
rvtconfig, you can also include
the certificate chains and private keys 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
For REM, the certificate chain file must have the filename
rem-cert.crt, and the private key file must have the filename
For XCAP, the certificate chain file must have the filename
xcap-cert.crt, and the private key file must have the filename
For BSF, the certificate chain file must have the filename
bsf-cert.crt, and the private key file must have the filename
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 CDS and installed
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
initconf will generate a self-signed certificate). If you provide only one,
rvtconfig will fail.
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.