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.
|
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. |
|
|
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 |
HTTPS certificate specification
A Certificate Authority can issue you with a signed certificate for your
REM
, XCAP and BSF
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 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.
|
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. 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 |
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 for each certificate
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.netbsf_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 = bsf.ims.mnc001.mcc001.pub.3gppnetwork.org
[req_ext]
subjectAltName = @alt_names
[alt_names]
DNS.1 = bsf.ims.mnc001.mcc001.pub.3gppnetwork.orgxcap_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 = xcap.ims.mnc001.mcc001.pub.3gppnetwork.org
[req_ext]
subjectAltName = @alt_names
[alt_names]
DNS.1 = xcap.ims.mnc001.mcc001.pub.3gppnetwork.orgThere 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 commands, please change the keysize as desired:
openssl req -newkey rsa:2048 -keyout rem.key -out rem.csr -nodes -config rem_csr.cnf
openssl req -newkey rsa:2048 -keyout xcap.key -out xcap.csr -nodes -config xcap_csr.cnf
openssl req -newkey rsa:2048 -keyout bsf.key -out bsf.csr -nodes -config bsf_csr.cnfThe output files are the certificate signing request (rem.csr, xcap.csr, bsf.csr) and your private key (rem.key, xcap.key, bsf.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:
-
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 -nooutIf 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. Forinitconfto 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. 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.
-
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
catutility as follows:cat my_certificate.crt intermediate_certificate.crt root_certificate.crt >chain.crtthis will create a file
chain.crtcontaining the entire certificate chain which is 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, XCAP and BSF during configuration
To upload the certificate chains and private keys to the nodes, you will need to put the certificate chains and private keys
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 filenamerem-cert.key. -
For XCAP, the certificate chain file must have the filename
xcap-cert.crt, and the private key file must have the filenamexcap-cert.key. -
For BSF, the certificate chain file must have the filename
bsf-cert.crt, and the private key file must have the filenamebsf-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 -nooutThis 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 = UKThe 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 = UKValidate the XCAP and BSF certificate chain
Repeat the check performed on the REM certificate, on the XCAP and BSF certificates:
openssl crl2pkcs7 -nocrl -certfile xcap-cert.crt | openssl pkcs7 -print_certs -noout
openssl crl2pkcs7 -nocrl -certfile bsf-cert.crt | openssl pkcs7 -print_certs -nooutEnsuring they also meet the criteria above.
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 MAG nodes. An example command is shown below:
./rvtconfig upload-config -c <cds-address> -t mag -i <config-dir> --vm-version-source this-rvtconfigwhere <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.
