Securing Voice Gateway

Configuring key and truststore files on Docker

By default, Voice Gateway uses a self-signed certificate to protect the exposed REST APIs. Use the following instructions, if you want to change the default keystore and truststore.

In the SIP Orchestrator configuration, mount the files on a Docker volume. For more information about volumes, see the Docker documentation. In the following example, $PWD resolves to the current working directory and mounts it to the /sslConf/ path on the container.

    volumes:
      - $PWD:/sslConf/
      # $PWD resolves to the working directory and
      # mounts it to the /sslConf/ path on the container

For both the truststore and keystore, specify the file location, file type, and its corresponding passphrase on the following environment variables. If you generated the keystore and truststore in a single file, specify the same file on both sets of environment variables.

services:
  sip.orchestrator:
 ...
    environment:
 ...
 # Trust store
  - SSL_KEY_TRUST_STORE_FILE=/sslConf/myTrustJKSFile.jks
  - SSL_FILE_TYPE=JKS
  - SSL_PASSPHRASE=myPassphrase

  # Key store
  - SSL_KEY_STORE_FILE=/sslConf/myKeyJKSFile.jks
  - SSL_KEY_FILE_TYPE=JKS
  - SSL_KEY_PASSPHRASE=myPassphrase

Redeploy Voice Gateway for your changes to take effect.

Adding trusted certificate authorities and self-signed certificates

For encrypted connections, you can define a set of trusted certificate authorities (CAs) and self-signed certificates, which are used to verify the identities of parties involved in the connection.

How you define these trusted certificates differs for each container: The SIP Orchestrator requires a JKS, JCEKS, or PKCS #12 file, but the Media Relay can use any PEM-formatted file.

Configuring mutual authentication

If you're connecting to the Watson services through a gateway server that requires mutual authentication, you'll have to configure mutual authentication in the Voice Gateway.

The simplest way to configure mutual authentication is by generating a single PKCS #12 file, which can then be used for both the SIP Orchestrator and the Media Relay. The file must contain the private key and its certificate as well as the certificate authorities to trust.

To generate the PKCS #12 file, you need the following PEM-formatted files:

• Private key, typically a .pem or .key file
• Certificate, typically a .pem, .crt, .cer, or .cert file
• Certificate authority (CA) certificate, typically a .pem, .crt, .cer, or .cert file
• Certificate chain, which is a concatenated list of certificates, typically a .pem file

Note: This single PKCS #12 file can be used only if mutual authentication is configured. If you configure SSL or TLS without mutual authentication, you'll need separate files for the SIP Orchestrator and Media Relay as described in the Configuring SSL and TLS encryption section.

1. Generate the PKCS #12 file from the private key, its certificate, and the certificate chain. The following example generates the file by using the OpenSSL tool.

   openssl pkcs12 -export \
   -in <certificate file> \
   -inkey <private key file> \
   -CAfile <certificate chain> \
   -chain -out <filename>.p12
   

2. Add the trusted certificates to the PKCS #12 file, specifying the CA certificate on the keytool command.

   keytool -importcert \
    -file <CA certificate to trust> \
    -alias <alias for the certificate> \
    -keystore <name of the trustore> \
    -storepass <password for the truststore> \
    -storetype pkcs12
   

3. Mount the file on a Docker volume. For more information, see the Docker documentation.

   volumes:
     - $PWD:/sslConf/
     # $PWD will resolve to the working directory and
     # will mount it to the /sslConf/ path on the container
   

4. In the configuration for each container, specify the file location, file type, and its corresponding passphrase on the following environment variables.

   • For the SIP Orchestrator:

   environment:
     ...
     - SSL_KEY_TRUST_STORE_FILE=/sslConf/myPKCS12File.p12
     - SSL_FILE_TYPE=PKCS12
     - SSL_PASSPHRASE=myPassphrase
   

   • For the Media Relay:

   environment:
     ...
     - SSL_CLIENT_PKCS12_FILE=/sslConf/myPKCS12File.p12
     - SSL_CLIENT_PASSPHRASE=myPassphrase
   

Configuring SSL and TLS encryption from the Media Relay to the Speech to Text Adapter

If you connect from the Media Relay to the Speech to Text Adapter over the public internet, it's recommended to establish a secure connection between the microservices. To secure the connection, you generate a PKCS #12 file for the Speech to Text Adapter and then add the certificate to the Media Relay truststore.

To generate the PKCS #12 file, you need the following PEM-formatted files:

* Private key, typically a .pem or .key file
* Certificate, typically a .pem, .crt, .cer, or .cert file
* Certificate authority (CA) certificate, typically a .pem, .crt, .cer, or .cert file
* Certificate chain, which is a concatenated list of certificates, typically a .pem file

1. Generate the PKCS #12 file from the private key, its certificate, and the certificate chain. The following example generates the file by using the OpenSSL tool.

   openssl pkcs12 -export \
   -in <certificate file> \
   -inkey <private key file> \
   -CAfile <certificate chain> \
   -chain -out <filename>.p12
   

2. Mount the file on a Docker volume. For more information, see the Docker documentation.

   volumes:
     - $PWD:/sslConf/
     # $PWD will resolve to the working directory and
     # will mount it to the /sslConf/ path on the container
   

3. In the configuration for the Speech to Text Adapter container, specify the file location and its corresponding passphrase on the following environment variables.

   environment:
     ...
     - SSL_SERVER_PKCS12_FILE=/sslConf/myPKCS12File.p12
     - SSL_SERVER_PASSPHRASE=myPassphrase
   

4. Create a trust certificate file that contains the PEM-formatted CA certificates from the Speech to Text Adapter and the Text to Speech service. You can extract the certificate for the Text to Speech service by using a tool such as OpenSSL.

   To concatenate the certificates into a single PEM-formatted file, run the cat command with the following syntax:

   cat <stt-adapter ca certificate> <text-to-speech certificate> > <trusted certificates>
   

   For example:

   cat stt-adapter-ca.pem DigiCertGlobalRootCa.pem > ca-bundle.pem
   

5. Mount the file on a Docker volume. For more information, see the Docker documentation.

   volumes:
     - $PWD:/sslConf/
     # $PWD resolves to the working directory and
     # mounts it to the /sslConf/ path on the container
   

6. In the Media Relay configuration, specify the PEM file location on the SSL_CLIENT_CA_CERTIFICATE_FILE environment variable. In the following example, the PEM file is named ca-bundle.pem.

   environment:
     ...
     - SSL_CLIENT_CA_CERTIFICATE_FILE=/sslConf/ca-bundle.pem
   

Whitelisting by SIP URI

When a caller attempts to reach Voice Gateway, the caller's SIP URI is passed, which contains information such as the phone number and host in the following format:

sip:number_or_username@host_domain_or_IP[:port]

Example:
sip:12345556789@myhost.com

To whitelist calls to or from certain SIP URIs, define the following SIP Orchestrator environment variables.

For example, the following configuration allows only calls with 2345556789 in the SIP To URI, such as a sip:12345556789@myhost.com phone number from a SIP trunk. In Version 1.0.0.3 or later, if 2345556789 can't be found in the To URI, Voice Gateway next checks the Request-URI value and allows calls that contain 2345556789 in that field.

- WHITELIST_TO_URI=2345556789

Whitelisting by fields in a SIPREC metadata

To whitelist SIPREC calls based on a field in the SIPREC metadata, define the following SIP Orchestrator environment variables.

For example, the following configuration allows only SIPREC calls where the SIPREC metadata contains the aor attribute with the value matching 111111111.

- WHITELIST_SIPREC_ATTR_NAME=aor
- WHITELIST_SIPREC_ATTR_VALUE=111111111

<?xml version="1.0" encoding="UTF-8"?>
<tns:recording
	xmlns:tns='urn:ietf:params:xml:ns:recording'>
	<tns:datamode>complete</tns:datamode>
	<tns:group group_id="YTIyYWRmNjAtMGZhNi0xMA==">
		<tns:associate-time>2016-06-08T12:58:34Z</tns:associate-time>
		<callData
			xmlns='urn:ietf:params:xml:ns:callData'>
			<fromhdr>&lt;sip:111111111@115.110.121.1&gt;;tag=gK0c638f27</fromhdr>
			<tohdr>&lt;sip:222222222@10.0.0.6&gt;;tag=gK08ddd5f7</tohdr>
			<callid>1292673994_41860201@115.110.121.1</callid>
			<gcid>239610873</gcid>
		</callData>
	</tns:group>
	<tns:session session_id="YTIyYWRmNjEtMGZhNi0xMA==">
		<tns:group-ref>YTIyYWRmNjAtMGZhNi0xMA==</tns:group-ref>
		<tns:start-time>2016-06-08T12:58:34Z</tns:start-time>
	</tns:session>
	<tns:participant participant_id="YTIyYWRmNjItMGZhNi0xMA==">
		<tns:nameID aor="111111111@115.110.121.1">
			<tns:name xml:lang="en"></tns:name>
		</tns:nameID>
	</tns:participant>
	<tns:participant participant_id="YTIyYWRmNjMtMGZhNi0xMA==">
		<tns:nameID aor="222222222@10.0.0.6">
			<tns:name xml:lang="en"></tns:name>
		</tns:nameID>
	</tns:participant>
	<tns:stream stream_id="YTIyYWRmNjQtMGZhNi0xMA==" session_id="YTIyYWRmNjEtMGZhNi0xMA==">
		<tns:label>1</tns:label>
		<tns:associate-time>2016-06-08T12:58:34Z</tns:associate-time>
	</tns:stream>
	<tns:stream stream_id="YTIyYWRmNjUtMGZhNi0xMA==" session_id="YTIyYWRmNjEtMGZhNi0xMA==">
		<tns:label>2</tns:label>
		<tns:associate-time>2016-06-08T12:58:34Z</tns:associate-time>
	</tns:stream>
	<tns:sessionrecordingassoc session_id="YTIyYWRmNjEtMGZhNi0xMA==">
		<tns:associate-time>2016-06-08T12:58:34Z</tns:associate-time>
	</tns:sessionrecordingassoc>
	<tns:participantsessionassoc participant_id="YTIyYWRmNjItMGZhNi0xMA==" session_id="YTIyYWRmNjEtMGZhNi0xMA==">
		<tns:associate-time>2016-06-08T12:58:34Z</tns:associate-time>
	</tns:participantsessionassoc>
	<tns:participantsessionassoc participant_id="YTIyYWRmNjMtMGZhNi0xMA==" session_id="YTIyYWRmNjEtMGZhNi0xMA==">
		<tns:associate-time>2016-06-08T12:58:34Z</tns:associate-time>
	</tns:participantsessionassoc>
	<tns:participantstreamassoc participant_id="YTIyYWRmNjItMGZhNi0xMA==">
		<tns:send>YTIyYWRmNjUtMGZhNi0xMA==</tns:send>
		<tns:recv>YTIyYWRmNjQtMGZhNi0xMA==</tns:recv>
	</tns:participantstreamassoc>
	<tns:participantstreamassoc participant_id="YTIyYWRmNjMtMGZhNi0xMA==">
		<tns:send>YTIyYWRmNjQtMGZhNi0xMA==</tns:send>
		<tns:recv>YTIyYWRmNjUtMGZhNi0xMA==</tns:recv>
	</tns:participantstreamassoc>
</tns:recording>

Whitelisting by IP address

When you whitelist certain IP addresses, Voice Gateway accepts calls only from the defined IPs. All communication from other IP addresses is rejected, including not only calls but also, for example, OPTIONS messages that are sent to monitor Voice Gateway.

To configure whitelisting by IP address, define a comma-separated list of IP addresses on the TRUSTED_IP_LIST environment variable in the SIP Orchestrator configuration.

- TRUSTED_IP_LIST=192.0.4.128,123.4.5.67,198.7.6.234

For more information about configuration, see Configuration environment variables for Voice Gateway.

Setting host directory permissions for volumes

Note: These instructions are only applicable for Linux.

Starting with version 1.0.2, containers do not run as root, for security reasons. Instead, containers run as user default with the UID 1001.

For volumes mounted on containers, make sure the proper permissions are applied to the mounted directory on the host machine. If you're deploying by using Docker or Kubernetes (hostPath Volumes), apply the permissions that will allow the user to write on the volume-mounted directory on host.

To do this, you need to run the following commands:

chown -R 1001:0 <path to volume mounted dir on host>
chmod -R g+rw <path to volume mounted dir on host>

If you need to run the container as root, specify that in the deployment file as follows:

For Docker docker-compose.yaml:

• Specify user for all images you want to run as root:
• For example:

  services:
    sip.orchestrator:
      image: icr.io/voice-gateway/sip-orchestrator:1.0.2.0
      user: root
  

For Kubernetes:

• Specify runAsUser at pod spec level or container spec level depending on your need. For more information, see Kubernetes documentation
• For example:

  spec:
    securityContext:
      runAsUser: 0
  

In this case, 0 is the UID of root user.

Note: Running containers as root user is not recommended in production environments.

1001 user ID: The containers internally run as the 1001 user ID by default. The user ID does not need to exist in the cluster and does not need to exist in the worker nodes. For persistent volumes to work, the 1001 user ID must own the directory.

To check the user ID of the containers, you can run the kubetcl exec command into the pod:

kubectl exec -it <podName> bash

Then, run the following command to print the user ID of the container:

id -u

The output displays the following user ID:

1001