HTTPS

This guide shows how to enable HTTPS protocol in Media Gateway. Both self-signed and signed by CA server certificates are supported. Certificates should be in PEM format.

Important

The protocol in url field in the client configuration must be updated to https.

Prerequisites

Docker
Docker Compose
openssl
curl

Using a self-signed certificate

Configuring Media Gateway

To use a self-signed certificate update server and client configurations.

server

"tls": {
    "identity": {
        "certificate": "server.crt",
        "key": "server.key"
    }
}

client

"tls": {
    "root_certificate": "server.crt"
}

where

server.crt is a file with the server certificate in PEM format.
server.key is a file with the server key in PEM format.

Generating certificates

Generate a private key and certificate signing request

mkdir certs

openssl genpkey -algorithm RSA -out certs/server.key

openssl req -new -key certs/server.key -out certs/server.csr -subj "/CN=media-gateway-server"

If the client connects to the server by IP generate a certificate with IP subject alternative name. Otherwise generate a certificate with DNS subject alternative name.

In commands below replace 192.168.0.108 and media-gateway-server with your values.

IP SAN

export HOST_IP="192.168.0.108"

openssl x509 -req -days 365 -key certs/server.key -in certs/server.csr -out certs/server.crt -extfile <(echo "subjectAltName=IP:${HOST_IP}")

DNS SAN

export MEDIA_GATEWAY_SERVER_DNS="media-gateway-server"

openssl x509 -req -days 365 -key certs/server.key -in certs/server.csr -out certs/server.crt -extfile <(echo "subjectAltName=DNS:${MEDIA_GATEWAY_SERVER_DNS}")

Testing

Server

To test the server only a certificate with IP SAN is used.

Prepare the configuration file

cat << EOF > media-gateway-server.json
{
    "ip": "0.0.0.0",
    "port": 8080,
    "tls": {
        "identity": {
            "certificate": "/etc/certs/server.crt",
            "key": "/etc/certs/server.key"
        }
    },
    "out_stream": {
        "url": "pub+bind:ipc:///tmp/server",
        "send_timeout": {
            "secs": 1,
            "nanos": 0
        },
        "send_retries": 3,
        "receive_timeout": {
            "secs": 1,
            "nanos": 0
        },
        "receive_retries": 3,
        "send_hwm": 1000,
        "receive_hwm": 1000,
        "fix_ipc_permissions": 511
    }
}
EOF

Launch the server (change the value of MEDIA_GATEWAY_PORT in the command below if required)

x86_64

export MEDIA_GATEWAY_PORT=8080

docker run -d \
    -v $(pwd)/media-gateway-server.json:/opt/etc/custom_config.json \
    -v $(pwd)/certs:/etc/certs \
    -p $MEDIA_GATEWAY_PORT:8080 \
    --name media-gateway-server \
    ghcr.io/insight-platform/media-gateway-server-x86:latest \
    /opt/etc/custom_config.json

ARM64

export MEDIA_GATEWAY_PORT=8080

docker run -d \
    -v $(pwd)/media-gateway-server.json:/opt/etc/custom_config.json \
    -v $(pwd)/certs:/etc/certs \
    -p $MEDIA_GATEWAY_PORT:8080 \
    --name media-gateway-server \
    ghcr.io/insight-platform/media-gateway-server-arm64:latest \
    /opt/etc/custom_config.json

Send the request to the server

curl --cacert certs/server.crt -v https://$HOST_IP:$MEDIA_GATEWAY_PORT/health

HTTP response with 200 OK status code and the body as below should be returned.

{"status": "healthy"}

Clean up after testing

docker stop media-gateway-server

docker rm media-gateway-server

rm -rf certs media-gateway-server.json

e2e

To test both server and client based on Usage example

generate a certificate with DNS SAN
update server_config.json and client_config.json in the downloaded archive as described above
add volumes for media-gateway-client` (a certificate file) and media-gateway-server (key and certificate files) in docker-compose-x86.yaml and docker-compose-arm64.yaml in the downloaded archive

Clean up after testing

rm -rf certs

Using a certificate signed by a private CA

Configuring Media Gateway

To use a certificate signed by a private CA update server and client configurations.

server

"tls": {
    "identity": {
        "certificate": "server.crt",
        "key": "server.key"
    }
}

client

"tls": {
    "root_certificate": "ca.crt"
}

where

server.crt is a file with the server certificate in PEM format.
server.key is a file with the server key in PEM format.
ca.crt is a file with the CA certificate in PEM format.

Generating certificates

Generate a private key and a certificate for CA and a private key and certificate signing request for the server

mkdir certs

openssl genpkey -algorithm RSA -out certs/ca.key

openssl req -new -x509 -days 365 -key certs/ca.key -out certs/ca.crt -subj "/CN=media-gateway-ca"

openssl genpkey -algorithm RSA -out certs/server.key

openssl req -new -key certs/server.key -out certs/server.csr -subj "/CN=media-gateway-server"

If the client connects to the server by IP generate a certificate with IP subject alternative name. Otherwise generate a certificate with DNS subject alternative name.

In commands below replace 192.168.0.108 and media-gateway-server with your values.

IP SAN

export HOST_IP="192.168.0.108"

openssl x509 -req -days 365 -in certs/server.csr -CA certs/ca.crt -CAkey certs/ca.key -CAcreateserial -out certs/server.crt -extfile <(echo "subjectAltName=IP:${HOST_IP}")

DNS SAN

export MEDIA_GATEWAY_SERVER_DNS="media-gateway-server"

openssl x509 -req -days 365 -in certs/server.csr -CA certs/ca.crt -CAkey certs/ca.key -CAcreateserial -out certs/server.crt -extfile <(echo "subjectAltName=DNS:${MEDIA_GATEWAY_SERVER_DNS}")

Testing

Testing is the same as for a self-signed certificate except the request to the server for checking

curl --cacert certs/ca.crt -v https://$HOST_IP:$MEDIA_GATEWAY_PORT/health

Using a certificate signed by a public CA

Configuring Media Gateway

To use a certificate signed by a public CA update the server configuration.

server

"tls": {
    "identity": {
        "certificate": "server.crt",
        "key": "server.key"
    }
}

where

server.crt is a file with a sequence of certificates, the first being the leaf certificate, and the remainder forming the chain of certificates up to and including the trusted root certificate.
server.key is a file with the server key in PEM format.