Certificate management (Machine identity)

Available in manifest version 19.0 and later.

Introduction

Enclave certificate management allows you to distribute x509 TLS certificates to agents. These certificates can be used for various PKI purposes, such as hosting/authenticating TLS/mTLS services or to serve as a source for machine identity.

How it works

The Enclave certificate management system is a bring your own root platform. This means that you must provide your own root and intermediate signing certificates. This allows you to utilize already trusted roots within your organization. The enclave agent then uses a SCEP (Simple Certificate Enrollment Protocol) client to request a certificate from a certificate authority (CA) that is established with the client provided certificates and keys. The CA then signs the certificate (based on a verified challenge) and returns it to the agent for use.

An agent will check it's certificate state every 20 minutes. If the certificate is going to expire in the hour, the agent will attempt to renew their machine certificate. You can also manually renew the certificate using the CLI and invoke a renewal from the EMC.

CLI commands

The following CLI commands are available for managing certificates in the enclave agent:

enclave ca status --help
View the status of the device certificate.

Usage:
  ca status [flags]

Flags:
  -h, --help   help for status

Renew the device certificate.

Usage:
  ca renew [flags]

Flags:
      --force   Force the renewal of the device certificate.
  -h, --help    help for renew

Requirements

Since we utilize the SCEP protocol, your CA must use an RSA intermediate CA. The RSA intermediate is needed to decrypt the contents of the SCEP CSR (certificate signing request). Unfortunately this means that ECDSA intermediate CAs are not supported at this time.

Example key generation (using smallstep)

bash

cat <<EOF > rsa_root_ca.tpl
{
  "subject": {{ toJson .Subject }},
  "issuer": {{ toJson .Subject }},
  "keyUsage": ["certSign", "crlSign"],
  "basicConstraints": {
    "isCA": true,
    "maxPathLen": 1
  }
  {{- if typeIs "*rsa.PublicKey" .Insecure.CR.PublicKey }}
    , "signatureAlgorithm": "SHA256-RSAPSS"
  {{- end }}
}
EOF

cat <<EOF > rsa_intermediate_ca.tpl
{
  "subject": {{ toJson .Subject }},
  "issuer": {{ toJson .Subject }},
  "keyUsage": ["certSign", "crlSign"],
  "basicConstraints": {
    "isCA": true,
    "maxPathLen": 0
  }
  {{- if typeIs "*rsa.PublicKey" .Insecure.CR.PublicKey }}
    , "signatureAlgorithm": "SHA256-RSAPSS"
  {{- end }}
}
EOF

step certificate create "Example CA" \
    ./root_ca.crt \
    ./root_ca_key \
    --template rsa_root_ca.tpl \
    --kty RSA \
    --not-after 87660h \
    --size 3072

step certificate create "Example Intermediate CA" \
    ./intermediate_ca.crt \
    ./intermediate_ca_key \
    --ca ./root_ca.crt \
    --ca-key ./root_ca_key \
    --template rsa_intermediate_ca.tpl \
    --kty RSA \
    --not-after 87660h \
    --size 3072

Future improvements

Support for multiple signing CAs
Support for an Enclave provided CA
Automatically distributing the root certificate to a machine trust store using the Enclave agent

Certificate management (Machine identity) ​

Introduction ​

How it works ​

CLI commands ​

Requirements ​

Example key generation (using smallstep) ​