Rhino VoLTE TAS VMs 4.0.0 :: RVT VM Install Guide (GSM)

Table of Contents

About HTTPS certificates for REM, XCAP and BSF
Self-signed certificates
HTTPS certificate specification
Uploading a certificate chain and private key for REM and XCAP during configuration
Changing the certificate

About HTTPS certificates for REM, XCAP and BSF

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.

Using 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 3gppnetwork.org domain, and can be obtained from any known CA. The DNS domain must be delegated from GSMA to the operator, and the CAs will typically want to see proof of ownership of the domain before they’d sign the cert for a domain. The same applies for the BSF. Refer to the certificate specification below.

For internal use in a lab deployment, a self-signed certificate can be automatically generated and used in place of a real certificate.

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

HTTPS certificate specification

If you have an in-house Certificate Authority, they can issue you with a signed certificate for your REM and XCAP 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 DNS (also known as IA5 dNSName) type for hostnames and IP (IA5 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 xcap. The standard form of a 3GPP XCAP URI is xcap.ims.mnc001.mcc001.pub.3gppnetwork.org, with the MNC and MCC padded to three digits.

Domain names in the BSF certificate must be identical to those in the XCAP certificate, except that the initial xcap string is replaced with bsf - for example bsf.ims.mnc001.mcc001.pub.3gppnetwork.org.

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:
```
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.
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 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 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.

Uploading a certificate chain and private key for REM and XCAP during configuration

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 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.
For XCAP, the certificate chain file must have the filename xcap-cert.crt, and the private key file must have the filename xcap-cert.key.
For BSF, the certificate chain file must have the filename bsf-cert.crt, and the private key file must have the filename bsf-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