tls

NAME
SYNOPSIS
DESCRIPTION
CERTIFICATE REVOKE REASONS
SEE ALSO
AUTHOR
COPYRIGHT

NAME

tls - Manage TLS (SSL) certificates

SYNOPSIS

tls [(add | del) <tls-id> | revoke <tls-id> [<reason>] | raz]

tls [generate <tls-id> [sign]]

tls (key | certificate | chain | csr) <tls-id> (load | save) (ftp | sftp | tftp) <file-server> <file-name> [<days>]

tls [(certificate | chain | csr | key) <tls-id> show | fingerprint <tls-id>]

tls [days [<days>]]

tls ca [(generate | fingerprint | (certificate | key) show)]

tls ca [(key | certificate) (load | save) (ftp | sftp | tftp) <file-server> <file-name>]

tls ca [(add <ca-id> [on | off] | del <ca-id> | show <ca-id> | fingerprint <ca-id>) | (import <ca-id> (ftp | sftp | tftp) <file-server> <file-name>) | raz]

tls client [(add [<days>] | generate [cancel] | del | show | fingerprint) <tls-id> | revoke <tls-id> [<reason>] | raz]

tls client [save <tls-id> (key | certificate | pkcs12 | pfx | password) (ftp | sftp | tftp) <file-server> <file-name>]

tls client [days [<days>]]

tls ocsp [host [(<ip> | <name>)] | days [<days>] | tls [raz | set <tls-id>]]

tls [report]

DESCRIPTION

This command allows you to manage TLS (SSL v3) objects. A TLS object regroups different components that can be as follows: a private RSA key, an X.509 certificate, a CSR (Certificate Signing Request) and a CA (Certificate Authority) chain. We distinguish different types X.509 certificates: CA certificates, server certificates and client certificates. You can generate a TLS object or import its components from a file server. Prior to using a TLS object, it should be created in the system. A TLS object is created in two stages: an empty object represented by a unique identifier is created first and then TLS components are generated or loaded from the file server.

Usage forms from the first to the fifth allow you to manage server certificates and associated TLS object components. To create a new TLS object use the keyword add followed by a unique TLS object identifier (<tls-id>). To delete a TLS object use the keyword del followed by the TLS object identifier to remove. To erase all TLS objects use the keyword raz. To revoke a certificate use the keyword revoke followed by the TLS object identifier to revoke and an optionally revoke reason (refer to the CERTIFICATE REVOKE REASONS section below for allowed reasons). Please note that you can only revoke a certificate that has been signed with the system’s CA certificate (see below).

The second usage form allows you to generate TLS object components. To generate a TLS object use the keyword generate followed by the identifier of a previously added TLS object. During the process of generation you will be asked questions related to the generated certificate. The first information to provide is the common name for the generated certificate. If more than one name is given, a SAN (Subject Alternate Names) certificate will be created. If a name contains the character "*" wildcard certificate will be created. The wildcard "*" can replace any allowed charters in a domain name. For instance the name "*.example.com" will create a certificate for all "example.com" sub domains. Provided names should be separated by a blank. If the optional sign argument is specified the certificate is signed by the system’s CA (see below).

The third usage form allows you to save/load private RSA keys, X.509 certificates (in PEM format), certificate chains and CSR on/from a file server. Only trusted file servers are allowed. Trusted file servers are defined with the command access. Please note that: 1- Loaded files should be in PEM format. 2- Private keys should be in an unencrypted format. If the only loaded component is a CSR, a certificate is generated and signed with the system’s CA certificate (see below). In this case you can’t use the generated certificate by the present system as its associated private key won’t be known. The generated certificate can then be saved on a file server and used on other systems. The generated certificate will be valid for the number of days specified as the last argument. If no number of days is specified, the certificate will be valid for the number of days specified by the usage form days (the fifth usage form).

A CA chain is the concatenation of the server certificate, all intermediate certificates and finally the CA root certificate. Please note that the chain certificate starts with the server certificate and ends with the CA root certificate. If the server certificate is not part of the loaded chain certificate, it is automatically concatenated to the chain certificate by the system.

The fourth usage form allows you to show an existing TLS X.509 certificate, a TLS CA chain or a CSR. For security reasons a private key can’t be shown so this usage form shows only its fingerprint. The keyword fingerprint followed by a <tls-id> prints the SHA256 and SHA1 fingerprints of a certificate. Prior to trust and use a saved TLS object component it is highly recommended to compare its fingerprint (SHA1, SHA256) against the fingerprint of the same component displayed by the system using the CLI (with the tls command) or the Web GUI.

Note that the generated TLS components are not part of the configuration and thus are not saved when saving the configuration with the command conf. To save the configuration including TLS objects you can backup the system using the command system.

The sixth and seventh usage form allow you to manage the system’s CA certificate (in PEM format) and private key. The system’s CA certificate is used to sign server and client certificates generated by the present system. It is also used by the SSL mediation module (see the command sslmediate) to sign dynamically generated SSL certificates for browsed HTTPS websites. The system’s CA certificate is available at: http://<internal-ip-address> (or http://<web-ip-address> if the vlan mode is activated). Please note that a) Loaded files should be in PEM format. b) The private key should be in an unencrypted format. c) In case where the system’s CA certificate is an intermediate CA certificate (signed with another CA certificate), it is best practice to specify an OCSP URL for it. Otherwise some browsers refuse to import the intermediate CA certificate. The system’s CA certificate is identified in the system by the certificate ID system (you can’t use this ID for other CA certificates).

The eighth usage form of the tls command allows you to add and import other CA certificates. CA certificates can be used for Web browsing when the SSL mediation mode is activated and/or for other purposes (such as VPN peers authentication). When adding a CA certificate the last optional argument allows you to turn on or off the usage of the added CA certificate for Web browsing. Trusted CA root certificates for Web browsing are regularly updated with new OS releases but in the case where a CA root certificate is missing, you have the possibility to add it to the system yourself with this usage form. The imported CA certificate can be a root or an intermediate certificate. CA intermediate certificates are useful to verify server certificates in case where a server does not properly send the full certificate chain (including all CA intermediate certificates).

The usage forms ninth to eleventh allow you to manage cient SSL certificates signed by the system’s CA root certificate. Client certificates are used to authenticate VPN peers and clients. To add a new SSL client certificate, use the keyword add followed by a unique TLS object ID. To delete an existing SSL client certificate use the keyword del. To erase all SSL client certificates (and its associated TLS components) use the keyword raz. To revoke an existing SSL client certificate use the keyword revoke. To generate SSL client certificates and other related TLS components the apply command should be used. You can regenerate an existing client certificate by using the keyword generate followed by its TLS object ID (to cancel the regeneration use the keyword cancel as the last argument). Main TLS components are the signed certificate itself and its related private RSA key. Other components are pkcs12, pfx and password. The pkcs12 component is a file storing both the private key and the signed client certificate protected by an automatically generated strong password. The pfx component is the base 64 encoded form of the pkcs12 component. All TLS components can be saved on a trusted file server using the keyword save. Client TLS components are generated using the following rules:

• The certificate common name is formed by concatenating the client certificate ID, the character "." (dot) and the system’s domain name (see the command domainname).

• The length of the RSA private key associated to the certificate is 2048.

• The pkcs12 and pfx password is in the form XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX where X is an alphanumeric character.

A new generated client certificate will be valid for the number of days specified by the optional argument <days>. If the number of days is not specified, the client certificate will be valid for the number of days configured with the usage form client days (the eleventh usage form). If you regenerate an existing client certificate, it will be valid for the same number of days as the number of days specified during its first generation.

The twelfth usage form allows you to configure the embedded OCSP server. OCSP stands for Online Certificate Status Protocol. It’s a protocol used for obtaining the revocation status of an X.509 digital certificate. You can use this OCSP server to revoke server and client certificates signed by the system’s CA certificate. To set the OCSP host name use the keyword host followed by an OCSP network name or IP address. To set the validity days for an OCSP response use the keyword days followed by a number of days. OCSP responses are signed/checked using a [private key/SSL certificate] pair. The keyword tls is used to set the TLS object to use to that end. If no TLS object is specified (by using the raz keyword), the system’s CA TLS object is used. If another TLS object is to be set (by using the keyword set) the TLS object to use should be associated to a certificate that has been signed with the system’s CA certificate. To activate the embedded OCSP server use the command mode ocsp on.

The last usage form (with the keywork report allows you to display a report on the status of certificates with respects to their expiration dates.

CERTIFICATE REVOKE REASONS

When revoking a signed certificate a reason can be specified. Allowed revoking reasons are as follows:

keyCompromise: the token or disk location where the private key associated with the certificate has been compromised and is in the possession of an unauthorized individual. This can include the case where a laptop is stolen, or a smart card is lost.

CACompromise: the token or disk location where the CA’s private key is stored has been compromised and is in the possession of an unauthorized individual. When a CA’s private key is revoked, this results in all certificates issued by the CA that are signed using the private key associated with the revoked certificate being considered revoked.

affiliationChanged: the user has terminated his or her relationship with the organization indicated in the Distinguished Name attribute of the certificate. This revocation code is typically used when an individual is terminated or has resigned from an organization. You do not have to revoke a certificate when a user changes departments, unless your security policy requires different certificate be issued by a departmental CA.

superseded: a replacement certificate has been issued to a user, and the reason does not fall under the previous reasons. This revocation reason is typically used when a smart card fails, the password for a token is forgotten by a user, or the user has changed their legal name.

cessationOfOperation: if a CA is decommissioned, no longer to be used, the CA’s certificate should be revoked with this reason code. Do not revoke the CA’s certificate if the CA no longer issues new certificates, yet still publishes CRLs for the currently issued certificates.

unspecified: no reason has been specified.

cancel: this is not intrinsically a revoke reason but if the revoke operation has not yet been applied, you can cancel it by using this keyword.

SEE ALSO

access (1) admin (1) apply (1) mode (1) domainname (1) port (1) rweb (1) sslmediate (1) system (1) vpn (1)

AUTHOR

CacheGuard Technologies Ltd <www.cacheguard.com>

Send bug reports or comments to the above author.

COPYRIGHT

Copyright (C) 2009-2021 CacheGuard - All rights reserved