PKI/TLS Certificates

Introduction

Akeyless can act as a Certificate Authority (CA) for the internal environment. This page focuses on PKI/TLS certificates, if you wish to see how to create and work with SSH certificates, please follow this link.

To start building your own chain of trust using Akeyless PKI Issuer, you can either bring your own CA certificate with the signing RSA key or simply generate your CA certificate as part of the signing key creation.

In case you want to use your existing key, upload your RSA private key with the matching certificate for signing intermediate CA or leaf certificates based on your chain of trust, using the following command:

akeyless upload-rsa \
--name <Key Name> \
--alg <RSA2048> \
--rsa-key-file-path </path/to/RSAKey.pem> \
--cert </path/to/CACert>

Alternatively, you can create a new RSA key with a self-signed certificate:

akeyless create-dfc-key \
--name <RSA-key-name> \
--alg <RSA2048> \
--generate-self-signed-certificate true \
--certificate-ttl 365 \
--certificate-common-name AkeylessCA 

You can find the complete list of parameters for this command in the CLI-Reference-Encryption-Keys section.

πŸ‘

Note

You can work with Classic Keys as well to generate a signing key with a self-signed certificate.

Creating a Certificate Issuer

A PKI Issuer enables you to issue certificates while the certificate templates are well-defined at the issuer level. To create the PKI Issuer, use the following command:

akeyless create-pki-cert-issuer \
--name <my_pki_cert_issuer> \
--signer-key-name <RSA-key-name> \
--ttl 86400 \
--destination-path /path/to/store/issued/certificates \
--create-public-crl \
--gw-cluster-url <https://Gateway URL:8000> \
--expiration-event-in 30 \
--allowed-extra-extensions '{"OID":["Value"]}'

Where:

  • name: The name that will be assigned to the new Cert Issuer

  • signer-key-name: The CA private key which contains the root certificate to be used for certificate signing

  • ttl: The time (in seconds) to the expiration of the certificate

  • destination-path: A path in Akeyless to save generated certificates, to work with automatic expiration events.

  • create-public-crl: Optional, to maintain a public CRL at https://vault.akeyless.io/crl/<account-id>/<cert-issuer-display-id>. Can be used in addition to create-private-crl which creates the CRL on the Gateway under https://<gatewayURL>/crl/<cert-issuer-display-id>. Must be set with a Gateway using thegw-cluster-url and destination-path parameters.

  • expiration-event-in: How many days before the expiration of the certificate would you like to be notified. To specify multiple events, use the argument multiple times: --expiration-event-in 30 --expiration-event-in 60 to get events 60 and 30 days in advance.

  • allowed-extra-extensions: A json string that defines the allowed extra extensions for the PKI cert issuer, e.g. '{"1.2.3":["test"]}'

For additional optional parameters like flags, allowed domains, and others, please check the CLI Reference

πŸ‘

Note

Automatically store issued certificate
Set the PKI Issuer item to automatically store any issued certificate with default expiration events to gain full automation of your PKI environments.

Creating a Certificate Signing Request

You can generate a Certificate Signing Request in Akeyless, with which, you will be able to issue a new certificate in Akeyless using the PKI Issuer.

It is possible to either use an existing Classic Key or create a new one.

Generate a new Certificate Signing Request:

akeyless generate-csr \
--name <name/of/new/Classic-Key> \
--generate-key
--alg <RSA1024> \
--common-name <common name to be included in the CSR certificate>
--gateway-url <https://Akeyless-Gateway-URL:8000>

Where:

  • name: Full path to the Classic Key that will sign the CSR
  • generate-key: Use this flag to generate a new classic key to sign the CSR - A name must be specified for the new key
  • alg: Algorithm to use for generating the new key (RSA1024, RSA2048, RSA3072, RSA4096, EC256, EC384)
  • common-name: Common name to be included in the CSR certificate
  • certificate-type: Certificate type to be included in the CSR certificate (ssl-client/ssl-server/certificate-signing)
  • gateway-url: Akeyless Gateway Configuration Manager URL (port 8000). to generate the classic key, relevant only when using generate-key option

For additional optional parameters like flags, certificate data, and others, please check the CLI Reference

Issuing a Certificate

To issue and sign a new certificate, use the following command:

akeyless get-pki-certificate \
--cert-issuer-name <my_pki_cert_issuer> \
--key-file-path <path to public/private key> \
--csr-file-path <path to CSR file> \
--outfile pki-certificate.pem

Where:

  • cert-issuer-name: (Mandatory) The name of the PKI certificate issuer
  • key-file-path: The client public or private key (PEM format) file path (in case of a private key, it will be used to extract the public key)
  • csr-file-path: Alternatively, you can use the path to the Certificate Signing Request file to generate the certificate with.
  • outfile: Output file path with the certificate. If not provided, the file with the certificate will be created in the same location as the provided public key with the -cert extension

For alternative and additional parameters, please go to the command reference.

Revoke a Certificate

To revoke an existing certificate run the following command:

akeyless revoke-certificate \
--name <certificate name>

Here you can provide a certificate full name, or use theitem-id or the certificate serial-number instead. In case a CRL (Certificate Revocation List) is maintained, the certificate will be added to the revocation list.

πŸ“˜

Note

In order to view the Certificate Revocation List, the PKI Cert Issuer's signing key must include the cRLSign extention.

Working with Certificates in the Console

Prerequisites

Creating a CA private key and root certificate to build your chain of trust:

  1. Log in to the Akeyless Console, and go to Items > New > Encryption Key > DFC.

  2. Define a Name of the key, and specify the Location as a path to the virtual folder where you want to create the new key, using slash / separators. If the folder does not exist, it will be created together with the key.

  3. Define the remaining parameters as follows:

  • Description: General description of the key (optional).

  • Tags: Assign tags to the key (optional).

  • Delete Protection: When enabled, protects the secret from accidental deletion.

  • Type: The encryption algorithm used for the key.

  • Customer Fragment: If you have an existing customer fragment, you may attach it to the key. If you wish to generate one, please refer to these instructions.

  • Generate-Self-Signed-Certificate: Enable this option to generate your root CA certificate as part of the key creation.

Creating a Certificate Issuer

  1. Go to Items > New > PKI Cert Issuer

  2. Define a Name of the cert issuer, and specify the Location as a path to the virtual folder where you want to create it, using slash / separators. If the folder does not exist, it will be created together with the cert issuer.

  3. Define the remaining parameters as follows:

  • Description: General description of the key (optional).

  • Tags: Assign tags to the key (optional).

  • Delete Protection: When enabled, protects the secret from accidental deletion.

  • Signer Key: The name of the signer key you defined in advance.

  • Certificate TTL: The time to the expiration of the certificate.

  • Allowed domains list: Specify the allowed domains for the certificates issued.

  • Allowed URI sans: Specify the allowed URI for the certificates issued.

  1. The description for the advanced and location parameters can be found here.

Issuing a Certificate

To issue a certificate using an existing PKI issuer through the console, go through the following steps:

  1. Go to the folder in which your certificate issuer is located and select it.

  2. Under the key details, you will see a button reading Generate PKI Certificate, tap it.

  3. Fill in the public key (PEM format), which can be either copied in or uploaded from a file.

  4. Tap generate, and if all parameters are valid, you will get a certificate.


What’s Next