Certificate management for gRPC/HTTPS using step-ca

In order to use TLS encryption for gRPC or the Mango web server you need a PKI (Public Key Infrastructure) so that you can issue X.509 certificates. This guide describes how to use Smallstep step-ca as a CA (Certificate Authority) for Mango.

Prerequisites

• Mango 5.0 installed in the cloud and edge.
• step-ca server installed somewhere that is accessible from the cloud instance of Mango and the edge instances of Mango
  • This guide assumes step-ca was installed in Docker via the manual installation steps
• step-cli client installed on your instances of Mango (cloud and edge)

Initialization of step-ca

• Run the init command step ca init --remote-management and answer the prompts or initialize and run directly via Docker e.g.

docker run -it -v step:/home/step \
    -p 9000:9000 \
    -e "DOCKER_STEPCA_INIT_NAME=Example Test CA" \
    -e "DOCKER_STEPCA_INIT_DNS_NAMES=localhost,$(hostname -f)" \
    -e "DOCKER_STEPCA_INIT_REMOTE_MANAGEMENT=true" \
    smallstep/step-ca

• Note the root fingerprint and store the password somewhere safe (password manager e.g. LastPass)

• Start the step-ca server e.g. step-ca $(step path)/config/ca.json or docker start <CONTAINER_ID>

Generate and install server certificates

• Run the following commands on the cloud Mango instance
• Bootstrap the step-cli client e.g.

step ca bootstrap --ca-url ca.example.com:9000 --fingerprint fac319855f4aa55c54ffca94e8d0cd27424af4b3b382a1dc6537df5953f20e68

• Change to your mango data directory e.g. cd /opt/mango-data
• Generate a server certificate for your servers hostname e.g. step ca certificate localhost server.crt server.key --kty RSA --size 4096
  • Enter your CA password when prompted
  • If you use the default key type of EC/P-256 you have to convert the key to PKCS #8 format
    step crypto key format server.key --out server.key --pkcs8 --pem --insecure --no-password
• Download the root certificate
  • step ca root root_ca.crt
• Edit your mango.properties file to use the certificates for gRPC

# Enable gRPC server
grpc.server.enabled=true
# gRPC server TCP port
grpc.server.port=9090
# Server X.509 certificate, including full certificate chain. Path to file (PEM encoded).
grpc.server.certChain=server.crt
# Server private key. Path to file (PEM encoded).
grpc.server.privateKey=server.key
# Root certificates for verification of client certificates (mTLS). Path to file (PEM encoded).
grpc.server.rootCerts=root_ca.crt
# Client authentication options (mTLS): NONE/OPTIONAL/REQUIRE
grpc.server.clientAuth=REQUIRE

• Create a PKCS #12 keystore if you wish to use this certificate as the HTTPS certificate

  • step certificate p12 server.p12 server.crt server.key
  • Enter a password
  • Edit your mango.properties file

ssl.on=true
ssl.port=8443
ssl.keystore.location=server.p12
ssl.keystore.password=mango

• Restart Mango

Generate and install client certificates

• Run the following commands on each edge Mango instance
• Bootstrap the step-cli client e.g.

step ca bootstrap --ca-url ca.example.com:9000 --fingerprint fac319855f4aa55c54ffca94e8d0cd27424af4b3b382a1dc6537df5953f20e68

• Change to your mango data directory e.g. cd /opt/mango-data
• Generate a client certificate for your each client using a unique id as the common name e.g.

step ca certificate client-1 client.crt client.key --kty RSA --size 4096

• Enter your CA password when prompted
• If you use the default key type of EC/P-256 you have to convert the key to PKCS #8 format

step crypto key format client.key --out client.key --pkcs8 --pem --insecure --no-password

• Download the root certificate

  • step ca root root_ca.crt

• Edit your mango.properties file to use the certificates for the gRPC client

# Client X.509 certificate, including full certificate chain. Path to file (PEM encoded).
grpc.client.certChain=client.crt
# Client private key. Path to file (PEM encoded).
grpc.client.privateKey=client.key
# Root certificates for verification of server certificate. Path to file (PEM encoded).
grpc.client.rootCerts=root_ca.crt

• Restart Mango

Installing the root certificate

If you are using the generated certificate as your web server TLS certificate for HTTPS you may wish to install the root certificate into your operating system so your browser trusts it. This is only recommended for development purposes.

Windows

• Locate your root_ca.crt or ca.crt file
• Double click the file and click “Install certificate”
• Choose 'Current User'
• Choose to place the certificate in the 'Trusted Root Certification Authorities' store
• Press 'Next' then 'Finish'
• You will be warned, press 'Yes'