SSH Tectia

Configuring Internal CA

SSH Tectia Manager has a preconfigured Internal CA (certification authority) setup Internal Root CA which is ready to be used in server certificate enrollment and authentication.

The CA-related configuration options for Internal and External CA Settings are defined in Settings → PKI Settings and require superuser administrator rights.

Under Settings → PKI Settings, there is a hierarchical menu tree with three categories. The first one, Internal CAs, contains the automatically created internal CA settings. The other two categories are for external automatic and manual PKCS#10 enrollment.

Internal CA Settings

Selecting the Internal Root CA entry will allow the operator to edit internal PKI settings. Configuration is divided into several tabbed controls as follows.

General - Certificate authority settings

Contains generic CA specific parameters. In case of an internal CA, contains only the CA symbolic name (different than the subject name in the CA certificate). The name is used in the SSH Tectia Manager administration interface only.

The validity period of Internal CA certificate itself can be set when a new CA instance is created but it cannot be changed afterwards.

Host certificate parameters
Configuring Host certificate settings of Internal Root CA

Figure 8.30. Configuring Host certificate settings of Internal Root CA

Host certificate validity period

Validity period for issued host certificates.

Certificate renew marginal

A time marginal for certificate renewal. For example, if the marginal is 15 days, the system will try to renew all host certificates issued by this CA 15 days before their expiration.

Certificate signature algorithm

Algorithm for certificate signing. SHA-1 is the default. Note that option RSA with SHA-256 is not supported with 4.x clients.

CRL parameters
Configuring CRL settings of Internal Root CA

Figure 8.31. Configuring CRL settings of Internal Root CA

CRL update period

A new CRL is generated once per period, in general. Revocations cause also unscheduled CRL generations.

CRL next update marginal

A time marginal added to the nextUpdate time in the issued CRL. Clients usually trust a CRL only to its nextUpdate time after which they will try to fetch a new CRL. Making the CRL validity longer by adjusting nextUpdate will provide extra marginal for clients with inaccurate time settings and will allow longer downtime for the CA itself, if needed. The downside is that some caching clients might not fetch a new CRL when the previous one is still valid. This reduces the propagation speed for revocation information.

Example: A CA issues a new CRL once per hour but has the next update marginal set to 24 hours. This means that the CA will issue a new CRL once per hour with nextUpdate set to 25 hours in future. Now if a certificate is revoked 2 hours later, it will be added to all newly issued CRLs but if a client still uses the original CRL (which is still valid for 23 hours) it will not reject that certificate.

However, if the Management Server machine has to be shut down for maintenance (perhaps quite quickly) it will allow for at least 24 hours of downtime until CRL checks will start to fail. Changing the marginal dynamically is also possible but then administrators have to wait until a new, longer CRL has been propagated to all clients.

CRL signature algorithm

Algorithm used in CRL signing. The default is SHA-1. Note that option RSA with SHA-256 is not supported with 4.x clients.

CRL publishing methods

A list of CRL publishing (distribution) methods. The default is internal HTTP based method which uses the Manager HTTP server in port 80. The operator can also add one or more external publishing methods by pressing the Add button.

External CRL publishing uses arbitrary commands to publish the CRL and thus has two parameters:

Command line

Command to run. Command line is processed for special fields before it is passed to the operating system and executed:

${crl}

SSH Tectia Manager writes the new CRL into a temporary file and the ${crl} field in the command line is replaced with the file name.

${dpid}

As the internal CA uses multiple dynamically created CRL distribution points, the CRLs must usually be distributed from several separate locations. The CRL distribution point ID number is used for that purpose. The field is replaced with the ID number directly.

${crlnumber}

The sequence number of CRL. Normally not needed in publishing.

${cacertificate}

The CA certificate is written to a temporary file and the field on the command line is replaced with the file name. Some commonly used CRL distribution methods also distribute the CA certificate in the same place or the CRL distribution location can be derived from the CA subject name (as in LDAP).

${uri}

The URI which will be encoded to issued certificates. Can be useful with a publishing script but usually not needed. The field is replaced with the URI directly.

URL

The URL which will be encoded to issued certificates. As in command line, this should also contain the ${dpid} field to identify the different distribution points.

Note that the CA can only have one internal HTTP CRL distribution point entry in the configuration but it can also be removed. CA has to have at least one CRL distribution point entry on some type.

If an internal HTTP CRL distribution point is used, the issued certificates will contain a CRL distribution point extension with the following URL format:

http://hostname:80/internal-ca/crldp${dpid}.crl

In the URL, hostname is taken from SSH Tectia Manager configuration file server-config.dat. If the host name is changed, the system does not automatically issue a new CRL on startup. Also note that all previously issued certificates will have invalid CRL distribution point extensions and probably will have to be re-enrolled.

Automatic External PKI Settings

As in internal CA, this configuration is separated in three parts.

General - Certificate authority settings
Name

The symbolic name for internal use in the SSH Tectia Manager administration interface.

CA certificate

Binary field to contain the CA certificate for both enrollment purposes and for host configuration deployment. Use the Upload button to upload a certificate in PEM, base64, or binary format. After a CA certificate has been uploaded it can be changed only by first deleting it.

Host certificate parameters
Requested host certificate validity period

The validity period set in request. However, the external CA will probably reset the validity period according to its own policy.

Certificate renew marginal

Same as in the internal CA case, except that No automatic renewal is also an option.

Enrollment parameters
CA address

CA address. Usable in enrollment scripts.

Enrollment command line

Command line uses replaceable fields. Some larger field values are written to temporary files and the field itself is replaced with a file name. The available fields are:

${pkcs10}

The PKCS#10 request in PEM format. Writes the request to a temporary file.

${pkcs10-bin}

PKCS#10 request in binary format, written to a temporary file.

${ca-cert}

CA certificate written to a temporary file in binary format.

${ca-address}

CA address field from the configuration.

${ca-subject-name}

Subject name from the CA certificate.

${certificate}

Old certificate. Only in renew and revoke.

${subject-name}

Subject name of the old certificate. Only in renew and revoke.

${issuer-name}

Issuer name of the old certificate. Only in renew and revoke.

${serial-number}

Serial number of the old certificate. Only in renew and revoke.

${reference-number}

If a valid PSK has been provided for host, its reference number part is given as command-line parameter.

${psk}

If a valid PSK has been provided for host, its secret part is given as a command-line parameter.

Polling command line

Similar to enrollment command line. The same options are usable and in addition the polling state (if any) can be given.

${pollstate}

The polling state data returned by a previous enrollment command is written to a temporary file.

Revocation command line

Revocation command line.

Poll interval in seconds

Polling interval in seconds.

Requires PSK

If enabled, each host requires a separate pre-shared key (PSK) for enrollment. This means that enrollment job is put on hold until the operator provides a PSK.

Manual External PKI Settings

As in other PKI types, this configuration is divided into three parts.

General - Certificate authority settings
Name

The symbolic name for internal use in the SSH Tectia Manager administration interface.

CA certificate

Binary field to contain the CA certificate for both enrollment and host configuration deployment purposes. Use the Upload button to upload a certificate in PEM, base64, or binary format. After a CA certificate has been uploaded it can be changed only by first deleting it.

Host certificate parameters
Requested host certificate validity period

Validity period set in the request. However the external CA usually resets the validity period according to its own policy.

Certificate renew marginal

Same as in the internal CA case, except that No automatic renewal is also an option.

Enrollment parameters
CA address

CA address. Currently not used; only a reminder for the operator.

Enrollment batch file size limit

Maximum number of requests in batch file when it is downloaded.

Use directory polling

Enable file-based request processing. SSH Tectia Manager writes requests to a specific directory ('request directory') as separate PEM-encoded PKCS#10 files. When a CA operator (or an automated process) has enrolled a certificate, it is written to a second directory ('incoming'). SSH Tectia Manager scans the incoming directory periodically and automatically imports any valid certificates it finds there. Polling is done once per minute.

Request directory path

Request directory for directory polling. Pending PKCS#10 requests will be written here in PEM format. Operator (or other request processing party) can either remove the request themselves or leave it there in which case the system will remove it when the corresponding certificate is received (or removed as rejected).

Incoming directory path

Directory for enrolled certificates. Polled once per minute. Any readable file will be decoded and inserted into the database provided that a matching open request can be found. Accepts certificates either in binary, PEM, or plain base64 formats.

Remove old unprocessed requests

Automatically closes requests older than the selected ones. Removes them from both the database and the request directory.

Requires PSK

Same as in automatic PKCS#10 processing.

Apart from the configuration itself, the most important parts of manual PKCS#10 handling are request queue download and certificate import. These options are located on the PKI configuration main page.

The Download request queue button allows the operator to download a batch of pending requests in PEM-encoded PKCS#10 format. Multiple requests are returned in a single file, separated with normal PEM headers.

After the operator has downloaded the queue, the requests have been transferred to external CA, and they have been issued as certificates, the issued certificates must be imported back to SSH Tectia Manager. This is done by clicking the Upload certificates button. The operator then uploads one certificate at a time in binary, plain base64, or PEM format. Alternatively all issued certificates can be imported simultaneously in a single file if they are in PEM format, separated by normal PEM headers.

When an issued certificate is imported, the corresponding request will be closed and the enrollment for that host continues with the certificate installation phase. Before the certificates are imported, the request queue can be downloaded multiple times.

If the request queue contains older requests which will not be issued, the queue can be cleared either totally or by rejecting the old requests.