TLS Security

Configuring for TLS security

Edge Xpert Manager runs without TLS encryption by default. To enable TLS security for Edge Xpert, you must do the following steps:

1. Create a private key and certificate. For information on generating these, see Generate self-signed TLS certificates

2. Make a local copy of docker-compose-security.yml found at /etc/edgexpert/

3. Find and update the xpert-manager entry as follows:

   xpert-manager:
       image: iotechsys/${EDGEXPERT_IMAGE_REPO}-iotech-manager:${EDGEXPERT_IMAGE_VERSION}
       container_name: xpert-manager
       hostname: xpert-manager
       ports:
         - "9090:9090"
       networks:
         - edgex-network
       user: 2002:2001
       environment:
         <<: *common-variables
         SERVICE_HOST: xpert-manager
         TLS_ENABLE: "true"
         TLS_KEY_PATH: /xpert-manager/key.pem
         TLS_CERT_PATH: /xpert-manager/cert.pem
       volumes:
         - xpert-manager-data:/xpert-manager/data
         - <path-to-cert>/cert.pem:/xpert-manager/cert.pem
         - <path-to-key>/key.pem:/xpert-manager/key.pem
   

   Note the following modifications:

   • TLS_ENABLE: "true" sets Edge Xpert Manager to serve HTTPS

   • Private key and certificate paths are specified with TLS_KEY_PATH and TLS_CERT_PATH respectively

   • Volumes added to mount the private key and certificate from the host into the container, directing Edge Xpert Manager to their locations

[Optional] Configuring for TLS security without Specified TLS Certificates

When TLS_ENABLE is "true" and the TLS_KEY_PATH or TLS_CERT_PATH environment variables are blank, Edge Xpert Manager will auto-generate TLS certificates for the user.

1. Make a local copy of docker-compose-security.yml found at /etc/edgexpert/

2. Find and update the xpert-manager entry as follows:

   xpert-manager:
       image: iotechsys/${EDGEXPERT_IMAGE_REPO}-iotech-manager:${EDGEXPERT_IMAGE_VERSION}
       container_name: xpert-manager
       hostname: xpert-manager
       ports:
         - "9090:9090"
       networks:
         - edgex-network
       user: 2002:2001
       environment:
         <<: *common-variables
         SERVICE_HOST: xpert-manager
         TLS_ENABLE: "true"
         XPERT_MANAGER_HOST: localhost
         ...
       volumes:
         ...
   

   Note the following modifications:

   • TLS_ENABLE: "true" sets Edge Xpert Manager to serve HTTPS

   • XPERT_MANAGER_HOST: localhost sets the host for a local test, the XPERT_MANAGER_HOST should match your domain name

When Edge Xpert Manager starts up, it will check for existing TLS certificates. If no certificates are found, Edge Xpert Manager will create new certificates and store them in the /xpert-manager/data folder.

$ docker exec -it xpert-manager ls /xpert-manager/data
ca.pem      cert.pem  key.pem

$ docker cp xpert-manager:/xpert-manager/data/cert.pem .

Starting Edge Xpert Manager with TLS

Deploy with the following command:

edgexpert up --secret xpert-manager

Verifying the service has started

Open the browser and navigate to https://localhost:9090 to verify and access the service.

Client sent an HTTP request to an HTTPS server

Another way we can verify the service is with logs:

$ docker logs xpert-manager
...
level=INFO ts=2021-08-13T02:48:08.535714839Z app=edgexpert-manager source=server.go:110 msg="Web server starting (xpert-manager:9090)"
level=INFO ts=2021-08-13T02:48:08.535749843Z app=edgexpert-manager source=message.go:50 msg="Service dependencies resolved..."
level=INFO ts=2021-08-13T02:48:08.535757989Z app=edgexpert-manager source=message.go:51 msg="Starting edgexpert-manager 1.0.0 "
level=INFO ts=2021-08-13T02:48:08.535763037Z app=edgexpert-manager source=message.go:55 msg="This is the Xpert Manger NEW UI Microservice"
level=INFO ts=2021-08-13T02:48:08.535768787Z app=edgexpert-manager source=message.go:58 msg="Service started in: 86.703618ms"
level=INFO ts=2021-08-13T02:48:08.535783455Z app=edgexpert-manager source=server.go:122 msg="EdgeXpert Manager Served with HTTPS"

Finally, we can also verify it via curl command:

$ curl --cacert cert.pem https://localhost:9090/api/v2/ping
{"apiVersion":"v2","timestamp":"Fri Aug 13 08:36:23 UTC 2021"}

Generate self-signed TLS certificates

You can generate self-signed TLS certificates through OpenSSL or Go. Both of these options will create key.pem and cert.pem files in your working directory. You should include the path to this directory in your docker-compose-security.yml.

OpenSSL

Self-signed TLS certificates can be installed with the following OpenSSL command:

openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes -subj '/CN=localhost'

Go tool

Go comes with a tool to generate self-signed certificates, which is packaged in the standard installation. If you do not have Go and wish to use this option, you can find installation instructions at Go.dev

Retrieve a list of options that can be used when creating the certificates with the following:

$ go run /usr/local/go/src/crypto/tls/generate_cert.go -help
Usage of /tmp/go-build3424364339/b001/exe/generate_cert:
  -ca
        whether this cert should be its own Certificate Authority
  -duration duration
        Duration that certificate is valid for (default 8760h0m0s)
  -ecdsa-curve string
        ECDSA curve to use to generate a key. Valid values are P224, P256 (recommended), P384, P521
  -ed25519
        Generate an Ed25519 key
  -host string
        Comma-separated hostnames and IPs to generate a certificate for
  -rsa-bits int
        Size of RSA key to generate. Ignored if --ecdsa-curve is set (default 2048)
  -start-date string
        Creation date formatted as Jan 1 15:04:05 2011

You can create a command based on these options. For example:

$ go run /usr/local/go/src/crypto/tls/generate_cert.go -ca -ecdsa-curve P256 -host localhost
2021/08/13 03:09:59 wrote cert.pem
2021/08/13 03:09:59 wrote key.pem

Troubleshooting

The key.pem and cert.pem files must have the correct permission code (644). If you encounter any errors on starting Edge Xpert Manager with TLS, ensure these have the correct permissions with the following:

chmod 644 key.pem
chmod 644 cert.pem