tls

NAME
SYNOPSIS
DESCRIPTION
CERTIFICATE REVOKE REASONS
SEE ALSO
AUTHOR
COPYRIGHT

NAME

tls - Manage TLS (SSL) certificates

SYNOPSIS

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

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

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

tls (certificate | chain | csr | key) <tls-object-id> show

tls [(report | fingerprint <tls-object-id>)]

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

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

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

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

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

tls client [days [<days>]]

tls ocsp [host [(<ip> | <name>)] | days [<days>]]

DESCRIPTION

This command allows you to manage TLS (SSL v3) objects. A TLS object consist of a private RSA key, an X.509 certificate, a CSR (Certificate Signing Request) and optionally a CA (Certificate Authority) chain. You can generate a TLS object or import constituent elements 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.

To create a new TLS object use the keywords tls add followed by a unique identifier (<tls-object-id>). To remove a TLS object use the keywords tls del followed by TLS object identifier to remove. To erase all TLS objects use the keywords tls raz. To show all existing TSL objects use the keyword tls. To revoke a certificate use the keywords tls 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.

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), CA 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.

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.

Before trusting a certificate which is not signed by a CA, always compare its fingerprint against the fingerprint of the certificate obtained using a second communication channel (the console port or SSH or Phone...). The fifth usage form allows you to print the fingerprint of an existing TLS certificate.

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.

The fifth usage form allows you to display some useful information on TLS certificates. The keyword report allows you to display a report on the status of certificates with respects to their expiration dates. The keyword fingerprint followed by a <tls-object-id> prints the SHA256 and SHA1 fingerprints of a certificate.

The sixth and seventh usage form allows you to manage the CA certificate (in PEM format) and private key of the system. The system CA certificate is used by the SSL mediation to sign dynamically generated SSL certificates. The CA certificate of the system 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 CA certificate is a intermediate CA certificate (signed with another CA certificate), it is best practice to specify either a CRL (Certificate Revocation List) Distribution Point, or an OCSP URL when generating certificates. Otherwise some browsers refuse to import the intermediate CA certificate.

The SSL mediation mode requires that the system verifies certificates sent by Web servers using trusted CA root certificates. Trusted CA root certificates are regularly updated whenever a patch is applied. In the case where a CA root certificate is missing, you have the possibility to add it to the system yourself. The eighth usage form of the tls command allows you to add and import missing CA root certificates. This usage form can also be used to add and import CA intermediate certificates. Imported CA intermediate certificates are useful to verify server certificates if servers do not properly send full certificate chains (including 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. 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 client 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 RSA private key length is 2048.

• The client certificate validity period is <days> days (where <days> can be configured using the client days usage form).

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

The final 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. To activate the embedded OCSP server use the command mode ocsp on.

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)

AUTHOR

CacheGuard Technologies Ltd <www.cacheguard.com>

Send bug reports or comments to the above author.

COPYRIGHT

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