tls

NAME
SYNOPSIS
DESCRIPTION
CERTIFICATE REVOKE REASONS
SEE ALSO
AUTHOR
COPYRIGHT

NAME

tls - Manage TLS (SSL) certificates and other components

SYNOPSIS

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

[2] tls server [generate <tls-id> [[sign] [ocsp]]]

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

[5] tls server [days [<days>]]

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

[9] tls client [(add <tls-id> [<days> [no][ocsp] [<private-key-size>]]) | (del <tls-id> [private [cancel]]) | raz]

[10] tls client [(generate <tls-id> [cancel]) | (show (key | certificate) | fingerprint) <tls-id> | revoke <tls-id> [<reason>]]

[12] tls client [load <tls-id> certificate (ftp | sftp | tftp) <file-server> <file-name>]

[13] tls client [days [<days>]]

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

[15] 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 and a CSR (Certificate Signing Request). 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 one to five allow you to manage server certificates and associated TLS object components. To create a new server TLS object use the keyword server add followed by a unique TLS object identifier (<tls-id>). To delete a TLS object use the keyword server del followed by the TLS object identifier to remove. To erase all TLS objects use the keyword server raz. To revoke a certificate use the keyword server 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 server TLS object components. To generate server TLS components use the keyword server 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). Finally the optional ocsp argument can be used to specify the usage of OCSP in the generated server certificate.

The third usage form allows you to save/load private RSA keys, X.509 certificates (in PEM format) 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:

• Loaded files should be in PEM format.

• Private keys should be in an unencrypted format.

In case where a CSR is loaded, a certificate is generated and it is 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 RSA 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). Finally the optional ocsp argument can be used to specify the usage of OCSP in the generated server certificate.

The fourth usage form allows you to show a certificate or a CSR. For security reasons a private RSA 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 forms allow you to load and save the system’s CA certificate and private RSA key. Please note that the system’s CA certificate can be saved in both PEM and DER formats but it can be loaded only in PEM format. 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 in PEM and DER format at: http://<internal-ip-address> (or http://<web-ip-address> if the vlan mode is activated). Please note that:

• Loaded files should be in PEM format.

• The private RSA key should be in an unencrypted format and not protected by a password.

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 allows you to add and import third parties CA certificates. Third parties 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 are regularly updated but in case where a CA root certificate is missing in the system, you have the possibility to manually add it with this usage form. Imported CA certificates can be a root or an intermediate certificates. Intermediate CA certificates are useful to verify server certificates in case where a server does not properly send the full certificate chain (including all intermediate CA certificates).

Usage forms ninth to thirteenth 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. You can optionally delete private components only by specifying the optional private keyword. Private components are key, pkcs12, pfx and password. Keeping the public component part (certificate ) allows you to revoke the certificate and publish its revocation using the embedded OCSP server. 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 RSA 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. 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 default size of the RSA private key is 2048 bits.

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

The eleventh usage form allows you to save TLS client components on a trusted file server in order to distribute them to clients. If you completely delete a TLS client object (including its public certificate part), you will not be able to revoke the certificate. That’s why you have the possibility to load the certificate component using the twelfth usage in order to be able to revoke it. Please note that if the loaded client certificate is different than the existing client certificate in the system, all private components associated to that certificate are purged from the system.

A new generated client certificate will be valid for the number of days specified by the optional argument <days> (in the ninth usage form). If the number of days is not specified, the client certificate will be valid for the number of days configured with the thirteenth usage form (client days). The optional ocsp and noocsp arguments (in the ninth usage form) can be used to specify the usage or no usage of OCSP in the generated client certificate. Finally the last optional argument <private-key-size> allows you to specify the size of the generated private RSA key in number of bits. This size should be greater than or equal 512 and less than or equal to 4096. If you regenerate an existing client certificate (using the tenth usage form), it will be valid for the same number of days as the number of days specified during its first generation (and will use the same OCSP specification if any). In case where the existing certificate uses OCSP, the regenerated certificate will be updated using the OCSP URI in effect during the regeneration. In case where the existing certificate does not use OCSP, the regenerated certificate will do the same.

The fourteenth 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 the required validity days. OCSP responses are signed/checked using a [private RSA 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 (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 RSA 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 RSA key is stored has been compromised and is in the possession of an unauthorized individual. When a CA’s private RSA key is revoked, this results in all certificates issued by the CA that are signed using the private RSA 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.

AUTHOR

CacheGuard Technologies Ltd <www.cacheguard.com>

Send bug reports or comments to the above author.