Tip

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

Certificate Signing Request Management

A certificate signing request, or CSR, combines the public key along with a list of attributes that uniquely identify an entity such as a TNSR router. Once created, the CSR is exported and sent to the Certificate Authority (CA). The CA will sign the request and return a certificate.

Set Certificate Signing Request Attributes

The first step in creating a CSR is to set the attributes which identify this firewall. These attributes will be combined to form the certificate Subject:

tnsr# pki signing-request settings clear
tnsr# pki signing-request set common-name tnsr.example.com
tnsr# pki signing-request set subject-alt-names add hostname tnsr.example.com
tnsr# pki signing-request set subject-alt-names add ipv4-address 203.0.113.2
tnsr# pki signing-request set country US
tnsr# pki signing-request set state Texas
tnsr# pki signing-request set city Austin
tnsr# pki signing-request set org Example Co
tnsr# pki signing-request set org-unit IT

The attributes include:

common-name:

The common name of the entity the certificate will identify, typically the fully qualified domain name of this host, or a username.

subject-alt-names:

Subject Alternative Name (SAN) entries which are alternate ways to identify the owner of the certificate. Some modern clients ignore the common-name and use the contents of the SAN list to validate the identity.

Note

SAN entries are technically optional but the best practice is to at least define one with a hostname, similar to the common-name attribute.

TNSR supports the following SAN types:

email:

An e-mail address.

hostname:

A hostname or fully qualified domain name.

ipv4-address:

An IPv4 address, typically a static address assigned to the host which will use the certificate.

ipv6-address:

An IPv6 address.

uri:

A Uniform Resource Identifier (URI) string.

country:

The country in which the entity is located.

state:

The state or province in which the entity is located.

city:

The city in which the entity is located.

org:

The company name associated with the entity.

org-unit:

The department or division name inside the company.

Note

At a minimum, a common-name must be set to generate a CSR.

Next, set the required digest algorithm which will be used to create a hash of the certificate data:

tnsr# pki signing-request set digest sha256

This algorithm can be any of the following choices, from weakest to strongest: sha224, sha256, sha384, or sha512.

Note

SHA-256 is the recommended minimum strength digest algorithm.

Before generating the CSR, review the configured attributes for the CSR:

tnsr# pki signing-request settings show
Certificate signing request fields:
      common-name: tnsr.example.com
          country: US
            state: Texas
             city: Austin
              org: Example Co
         org-unit: IT
           digest: sha256
subject-alt-names:
         hostname: tnsr.example.com
     ipv4-address: 203.0.113.2

If any attributes are incorrect, change them using the commands shown previously.

Generate a Certificate Signing Request

If the attributes are all correct, generate the CSR using the same name as the private key created previously. TNSR will output CSR data to the terminal in PEM format:

tnsr# pki signing-request mycert generate

-----BEGIN CERTIFICATE REQUEST-----
<csr data>
-----END CERTIFICATE REQUEST-----

The CSR data is stored in a file at /etc/pki/tls/tnsr/certs/<name>.csr

Note

Remember that the private key, CSR, and certificate must all use identical names!

The CSR data for existing entries can be displayed in PEM format:

tnsr# pki signing-request mycert get
-----BEGIN CERTIFICATE REQUEST-----
<csr data>
-----END CERTIFICATE REQUEST-----

Copy and paste the CSR data, including the armor lines (BEGIN, END), from the terminal into a local file, and submit that copy of the CSR to the CA for signing.

Warning

Remember, the private key for the CSR is not required for signing. Do not send the private key to the CA.

Other CSR Operations

A CSR entry may be deleted once the certificate has been imported to TNSR:

tnsr# pki signing-request <name> delete

To view a list of all CSR entries known to TNSR:

tnsr# pki signing-request list

To delete a specific SAN entry:

tnsr# pki signing-request set subject-alt-names delete <name>

To clear all SAN entries:

tnsr# pki signing-request set subject-alt-names clear

To reset all CSR attribute contents:

tnsr# pki signing-request settings clear