By default, Twistlock uses an internal, self-managed certificate authority for all x.509 cryptographic functions. Twistlock self-managed certificates are used for TLS access to Console’s web UI, for Defenders to authenticate to Console, and for users to authenticate to Defenders.

Twistlock lets you use your own certificates for some functions. For example, if you want to make access to the web UI more seamless, you can use certificates from an implicitly trusted CA for securing the TLS connection. You can also use custom certificates to authenticate to Defenders using the Docker and Kubernetes clients. Your custom certificates are used in place of those generated by Twistlock.

1. Setting up your custom certs

To set up your custom certs:

Procedure

  1. Open Console, and go to Manage > Authentication > Certificates.

  2. Set Advanced certificate configuration to Show.

  3. Under Console Authentication (section 2), upload the CA certificate(s) in PEM format, then click Save.

    If you have multiple CAs, such as a root CA and several issuing CAs, you must add all these certificates into the PEM file. The order of certificates in the PEM file should be from the lowest tier of the hierarchy to the root. For example, if you have a 3 tier hierarchy that looks like this:

    ->RootCA
         ->IntermediateCA
              ->IssuingCA1
              ->IssuingCA2

    Your PEM file should be ordered as IssuingCA1, IssuingCA2, IntermediateCA, RootCA. To create such a PEM file, you’d get the public keys of each CA in PEM format and concatenate them together:

    $ cat IssuingCA1.pem IssuingCA2.pem IntermediateCA.pem RootCA.pem > CAs.pem

    Once this configuration is enabled, users must copy their keys (both public and private) to the host they’re using to run commands with docker or kubectl. Though the path can be referenced in each command, it’s usually simpler to place them in the default directory that docker looks in for certificates (~/.docker).

    Each user certificate used with Twistlock must have the user’s CN embedded in the Subject field of the certificate. You can validate these settings by running the following command against the certificate:

    $ openssl x509 -in .docker/cert.pem -text | grep Subj
    Subject: CN=username

    Finally, Docker requires that the CA certificate used to sign the server certificate on the nodes Twistlock is protecting must also be in the ~/.docker folder, in a file called ca.pem. Because the 'server' certificate used in this deployment model is still generated by Twistlock, this means that on each host where you’re running docker or kubectl commands, you must also add the CA certificate to this folder.

2. Explicit certificate trust list

You also have an option to create a list of explicitly trusted custom certificates. A typical use case of this feature would be when may have multiple certificates issued to a given user but only want specific ones to be available for use with Twistlock. By adding an explicit trust list, you can control what certificates can be used because Twistlock compares any certificates presented to it against the allowed trusted-certificates-list. This way, a user having certificate not in the explicitly allowed list will not be able to use the certificate with Twistlock, even if it was issued by a trusted CA. Note that this feature is valid only when custom CA is configured. When enabled, it allows users to add new certificates to a table by uploading entire public certificates in PEM format.

use custom certs auth 793632

NOTES:

  • External certification authority section will be visible only to an Admin role user.

  • All trusted certs information will be retrieved from the certificate itself, so the user doesn’t have to manually add info such as CN, issuer etc.

  • Only the public portion of a user certificate should be added to the explicit trust list. Private keys are not required and should be excluded from this process.

3. Setting up

To set up:

Procedure

  1. Under Authentication to Defenders (section 1a), upload CA certificate to trust.

    use custom certs auth 795121
  2. Set Enable authentication with only an explicit list of trusted certificates to ON.

  3. Click Add certificate, copy the PEM-formatted public certificate which was issued by the trusted CA, then click Add.

    use custom certs auth 795123

When a custom cert is provided to authenticate to Twistlock, it first checks the certificate against this list. If the cert is matched to an entry in the list, then the previously existent flow continues. If the cert is not in the trusted list, then the authentication fails with an error 'Certificate not in certificate trust list configured in Twistlock'.