Tip

This is the documentation for the 24.06 version. Looking for the documentation of the latest version? Have a look here.

Certificate Authority Management

As mentioned in Public Key Infrastructure, a Certificate Authority (CA) provides a starting point for a chain of trust between entities using certificates. A CA will sign a certificate showing that it is valid, and as long as an entity trusts the CA, it knows it can trust certificates signed by that CA.

By creating or importing a CA into TNSR, TNSR can use that CA to validate other certificates or sign new certificate requests. These certificates can then be used to identify clients connecting to the RESTCONF service or other similar purposes.

A CA can be managed in several ways in TNSR. For example:

  • Import a CA generated by another device by copy/paste in the CLI

  • Import a CA generated by another device from a file

  • Generate a new private key and CSR, then self-sign the CSR and set the CA property. The resulting CA is automatically available as a TNSR CA.

Import a CA

TNSR can import a CA from the terminal with copy/paste, or from a file. When importing a CA, the key is optional for validation but required for signing. To import the key, see Key Management. Import the key with the same name as the CA.

To import a CA from the terminal, use the enter command. In this example, a CA named tnsrca will be imported from the terminal by TNSR:

# pki ca tnsrca enter
Type or paste a PEM-encoded certificate.
Include the lines containing 'BEGIN CERTIFICATE' and 'END CERTIFICATE'
-----BEGIN CERTIFICATE-----
<cert data>
-----END CERTIFICATE-----
tnsr(config)#

Next, import the private key using the same name:

tnsr(config)# pki private-key tnsrca enter
Type or paste a PEM-encoded private key.
Include the lines containing 'BEGIN PRIVATE KEY' and 'END PRIVATE KEY'
-----BEGIN PRIVATE KEY-----
<key data>
-----END PRIVATE KEY-----

Alternately, import the CA and key from the filesystem:

tnsr(config)# pki ca otherca import otherca.crt
tnsr(config)# pki private-key otherca import otherca.key

Creating a Self-Signed CA

TNSR can also create a self-signed CA instead of importing an external CA. For internal uses, this is generally a good practice since TNSR does not need to rely on public CA entries to determine trust for its own clients.

First, generate a new private key for the CA:

tnsr(config)# pki private-key selfca generate
-----BEGIN PRIVATE KEY-----
<key data>
-----END PRIVATE KEY-----

Next, create a new CSR for the CA:

tnsr(config)# pki signing-request settings clear
tnsr(config)# pki signing-request set common-name selfca
tnsr(config)# pki signing-request set subject-alt-names add hostname selfca
tnsr(config)# pki signing-request set digest sha256
tnsr(config)# pki signing-request selfca generate
-----BEGIN CERTIFICATE REQUEST-----
<csr data>
-----END CERTIFICATE REQUEST-----

Finally, have TNSR self-sign the CSR while setting the CA flag on the resulting certificate:

tnsr(config)# pki signing-request selfca sign self purpose ca
-----BEGIN CERTIFICATE-----
<cert data>
-----END CERTIFICATE-----

After signing, the newly created CA is ready for immediate use:

tnsr(config)# pki ca list
    tnsrca:     [Not after: Apr  4 12:51:22 2032 GMT] [days left: 3337, valid]
    selfca:     [Not after: Feb 13 15:17:19 2024 GMT] [days left: 364, valid]

Intermediate CAs

In some cases a CA may rely on another CA. For example, if a root CA signs an intermediate CA and the intermediate CA signs a certificate, then both the root CA and intermediate CA are required by the validation process.

To show this relationship in TNSR, a CA may be appended to another CA:

tnsr(config)# pki ca <root ca name> append <intermediate ca name>

In the above command, both CA entries must be present in TNSR before using the append command.

Using a CA to sign a CSR

A CA in TNSR with a private key present can also sign a client certificate. The typical use case for this is for RESTCONF clients which must have a certificate recognized by a known CA associated with the RESTCONF service.

First, generate a client private key and CSR:

tnsr(config)# pki private-key tnsrclient generate
-----BEGIN PRIVATE KEY-----
<key data>
-----END PRIVATE KEY-----
tnsr(config)# pki signing-request settings clear
tnsr(config)# pki signing-request set common-name tnsrclient.example.com
tnsr(config)# pki signing-request set subject-alt-names add hostname tnsrclient.example.com
tnsr(config)# pki signing-request set digest sha256
tnsr(config)# pki signing-request tnsrclient generate
-----BEGIN CERTIFICATE REQUEST-----
<csr data>
-----END CERTIFICATE REQUEST-----

Then, sign the certificate:

tnsr(config)# pki signing-request tnsrclient sign ca-name tnsrca days-valid 365 digest sha512 purpose client
-----BEGIN CERTIFICATE-----
<cert data>
-----END CERTIFICATE-----

The sign command takes several parameters, each of which has a default safe for use with client certificates in this context. The above example uses these defaults, but specifies them manually to show how the parameters function. The available parameters are:

days-valid <days>:

The number of days the resulting certificate will be valid. The default is 365 days (one year). When the certificate expires, it must be signed again for a new term. Certificates with a shorter lifetime are more secure, but longer lifetimes are more convenient.

Warning

When creating a certificate with purpose server it is important to not use a days-valid value greater than 398. Several operating systems, browsers, and other certificate consumers consider server certificates with lifetimes over 398 days to be invalid.

digest (sha224|sha256|sha384|sha512):

The hash algorithm used to sign the certificate. The default value is sha512.

purpose (ca|client|server):

Declares the purpose of the certificate being signed. This allows TNSR to assign the appropriate flags and extended key usage (EKU) attributes in the certificate data so that software utilizing the certificate can properly validate it is being used for its intended purpose.

ca:

Marks the certificate as a certificate authority (CA). Sets the CA flag as well as “Certificate Sign” and “CRL Sign” extended key usage values.

If a CSR is signed as a CA, the resulting certificate can then be used to sign other certificates. This is not necessary for server and client certificates.

client:

Marks the certificate as a client certificate with the “TLS Web Client Authentication” extended key usage attribute.

server:

Marks the certificate as a server certificate with the “TLS Web Server Authentication”, “TLS Web Client Authentication”, and “1.3.6.1.5.5.8.2.2” (“iKEIntermediate”) extended key usage attributes.

Other CA Operations

The remaining basic CA operations allow management of CA entries.

To view a list of all CA entries, including the CA validity times and status:

tnsr(config)# pki ca list
    tnsrca:     [Not after: Apr  4 12:51:22 2032 GMT] [days left: 3337, valid]
    selfca:     [Not after: Feb 13 15:17:19 2024 GMT] [days left: 364, valid]

To view the CA certificate PEM data:

tnsr(config)# pki ca selfca get
-----BEGIN CERTIFICATE-----
<cert data>
-----END CERTIFICATE-----

To view a brief summary of the CA details, use get short:

tnsr(config)# pki ca selfca get short
Issuer:
   commonName: selfca
Subject:
   commonName: selfca
X509v3 Subject Alternative Name
   DNS:selfca
NotBefore: Feb 13 15:17:19 2023 GMT
NotAfter: Feb 13 15:17:19 2024 GMT

To view the full CA details, use get full:

tnsr(config)# pki ca selfca get full
Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number:
            d9:ee:51:9c:f9:53:c3:c5
        Signature Algorithm: sha512WithRSAEncryption
        Issuer: CN=selfca
        Validity
            Not Before: Feb 13 15:17:19 2023 GMT
            Not After : Feb 13 15:17:19 2024 GMT
        Subject: CN=selfca
        Subject Public Key Info:
            Public Key Algorithm: rsaEncryption
                Public-Key: (2048 bit)
                Modulus:
                   [data]
                Exponent: 65537 (0x10001)
        X509v3 extensions:
            X509v3 Subject Alternative Name:
                DNS:selfca
            X509v3 Subject Key Identifier:
                7D:F6:11:29:52:DF:10:94:93:C4:8F:82:F1:54:AD:9C:A3:E8:19:53
            X509v3 Authority Key Identifier:
                7D:F6:11:29:52:DF:10:94:93:C4:8F:82:F1:54:AD:9C:A3:E8:19:53
            X509v3 Basic Constraints: critical
                CA:TRUE, pathlen:0
            X509v3 Key Usage:
                Certificate Sign, CRL Sign
    Signature Algorithm: sha512WithRSAEncryption
    Signature Value:
       [data]

To delete a CA entry:

tnsr(config)# pki ca selfca delete