Getting started with certificate manager

As part of the Enclave platform, the certificate manager provides a way to manage certificates for your assets. This guide will help you get started with using the certificate manager. This example will show you how to add a new root certificate, create a signing certificate, issue a certificate to a node, distribute trust to users, and then use that certificate to run a TLS server.

Prerequisites

• An Enclave account with access to the certificate manager.
• Manifest version of 1.22.0 or higher.
• A node with the Enclave agent installed and running. Docker must also be installed for the purpose of this guide.
• A user with the Enclave agent installed and running.
• Access to a domain name that you can use for the web server. This domain name should be resolvable to the public IP of the node where you will run the web server.

Step 1: Add a certificate field to the node

In order for the issued certificate to be use for TLS, we need to add in a certificate field that includes the DNS name to be included in the certificate.

1. Navigate to Agents > Nodes and select the node you want to issue the certificate to.
2. Click on the Certificates tab and then click on the Manage fields sub-tab.
3. Click Add field and add DNS name that matches the domain name you will use for the web server. This is used in the TLS handshake to verify the identity of the server. The DNS name should match the domain name you will use for the web server

Step 2: Create a trust chain

A trust chain is a grouping of root certificates that you can use to issue certificates from or issue trust to. You may think of a trust chain like a certificate authority (CA) that you can use to issue certificates to your nodes or users.

To create a trust chain, follow these steps:

1. Log in to the Enclave console.
2. Navigate to Certificates > Trust chains.
3. Click on Create trust chain.

Step 3: Add a root certificate

In this step, you will create an Enclave managed root certificate that will be used to issue signing certificates. These certificates are fully managed by Enclave. We also support uploading you own root certificate and signing certificates, but for this example, we will use an Enclave managed root certificate.

1. On the left hand side of the trust chain view, click on Root & signing certificates.
2. Click on Add a root certificate and select Enclave managed.
3. Fill out the fields with any relevant information, such as the Common Name (CN), Organization (O), and Organizational Unit (OU).
4. Click Submit to create the root certificate.

Step 4: Add an intermediate signing certificate

In this step, you will create a signing certificate that will be used to issue certificates to nodes. This signing certificate will be managed by Enclave and will inherit the properties of the root certificate. Intermediate signing certificates are important for establishing a chain of trust, allowing you to issue certificates without directly using the root certificate.

1. On the next screen, select Add intermediate signing certificate.
2. For an Enclave managed root certificate, the information for the certificate will be inherited from the root certificate and the Common Name (CN) will be automatically generated.
3. Click Submit to create the signing certificate.

Step 5: Issue a certificate to the node

In this step, you will issue a certificate to a node using the signing certificate you created in the previous step. This certificate will be used in to run TLS in a web server.

1. On the left hand side of the trust chain view, click on Issuance policies.
2. Press Create issuance policy.
3. For the certificate output path, input whoami.crt for the certificate file output name and whoami_key for the key file output name.
4. Select Apply to to Node and select the node you want to issue the certificate to.
5. Press Submit to create the issuance policy.
6. Your certificate will be issued to the node and the files will be saved to the node's file system at one of these paths:

• Linux/MacOS: /etc/enclave/certs/whoami.crt and /etc/enclave/certs/whoami_key
• Windows: C:\ProgramData\Enclave\certificates\whoami.crt and C:\ProgramData\Enclave\certificates\whoami_key

Step 6: Distribute trust to users

In this step, you will distribute the root certificate to all users in the Enclave platform. This will allow users to trust the certificates issued by this trust chain.

1. On the left hand side of the trust chain view, click on Trust policies.
2. Press Create trust policy.
3. Select the Apply to of All users and Submit the trust policy.
4. This will distribute the root certificate to all users in the Enclave platform, allowing them to trust the certificates issued by this trust chain. The Enclave agent automatically installs the root certificate to the user's system, so no further action is required.

Step 7: Run a web server with TLS

We will use traefik to run a web server with TLS using the certificate we issued in step 4. Traefik is a modern reverse proxy and load balancer that makes deploying microservices easy. This example will use the traefik/whoami image, which is a simple web server that returns information about the request it receives.

1. Create a /opt/whoami directory on your node for the purpose of this example. Navigate to it.
2. Create a /opt/whoami/docker-compose.yml file with the following content:

version: "3.3"

services:

  traefik:
    image: "traefik:v3.4"
    container_name: "traefik"
    command:
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      - "--entryPoints.websecure.address=:443"
      - "--providers.file.directory=/dynamic"
    ports:
      - "80:80"
      - "443:443"
      - "8080:8080"
    volumes:
      - "/var/run/docker.sock:/var/run/docker.sock:ro"
      - "/opt/whoami/dynamic:/dynamic:ro"
      - "/etc/enclave/certs:/certs:ro"

  whoami:
    image: "traefik/whoami"
    container_name: "simple-service"
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.whoami.rule=Host(`<your-domain>`)
      - "traefik.http.routers.whoami.entrypoints=websecure"
      - "traefik.http.routers.whoami.tls=true"

2. Replace <your-domain> with the domain you want to use for the web server.
3. Create a /opt/whoami/dynamic directory.
4. Create a /opt/whoami/dynamic/traefik.yml file with the following content:

tls:
  certificates:
    - certFile: /certs/whoami.crt
      keyFile: /certs/whoami_key

5. Navigate to the /opt/whoami directory and run the following command to start the web server:

docker compose up -d

Step 8: Access the web server

Go to the user agent and open a web browser. Navigate to the domain you specified in the docker-compose.yml file. You should see a page that displays information about the request, confirming that the web server is running with TLS.

Alternatively, you can use the curl command to test the web server:

curl -k https://<your-domain>

You should see a response similar to the following:

Hostname: 5364a3e77294
IP: 127.0.0.1
IP: ::1
IP: ...
RemoteAddr: ...
GET / HTTP/1.1
Host: <your-domain>
User-Agent: curl/7.81.0
Accept: */*
Accept-Encoding: gzip
X-Forwarded-For: ...
X-Forwarded-Host: <your-domain>>
X-Forwarded-Port: 443
X-Forwarded-Proto: https
X-Forwarded-Server: a73d64b6ea22
X-Real-Ip: ...

Step 9: Add an on-issued script (optional)

In order for the web server to be automatically restarted when a new certificate is issued, you can add an on-issued script into the host that will be executed when a new certificate is issued. This script can be used to restart the web server or perform any other actions you need.

1. On the host of the node, navigate to the directory where on-issued scripts are stored:

• Linux/MacOS: /etc/enclave/certs/on-issued.d/
• Windows: C:\ProgramData\Enclave\certificates\on-issued.d\

2. Create a new script called reload-traefik.sh with the following content:

#!/bin/bash
docker restart traefik

3. Make the script executable:

chmod +x /etc/enclave/certs/on-issued.d/reload-traefik.sh

4. Now, whenever a new certificate is issued to the node, the reload-traefik.sh script will be executed, restarting the Traefik service and applying the new certificate.

Conclusion

You have successfully set up the Enclave certificate manager to issue and manage certificates for your assets. You created a trust chain, added a root certificate, created a signing certificate, issued a certificate to a node, distributed trust to users, and ran a web server with TLS. You also learned how to add an on-issued script to automatically restart the web server when a new certificate is issued.

This guide provides a basic overview of how to use the certificate manager in Enclave. You can further explore the capabilities of the certificate manager, such as managing multiple trust chains, issuing certificates to users, and more advanced configurations.

Tasks to try next

• Create another issuance policy to issue certificates to a user and configure traefik to use mTLS. The user can then use their issued certificate to access the web server.

curl --cert /etc/enclave/certs/user.crt --key /etc/enclave/certs/user_key https://whoami.enclave.sidechannel.com

• Use Enclave DNS and instead of using the a public domain name, use the Enclave DNS name for the web server. This will allow you to access the web server using the Enclave DNS name over the Enclave network.