K15462: Managing SSL certificates for BIG-IP systems using tmsh

Non-Diagnostic

Original Publication Date: Aug 11, 2014

Update Date: May 23, 2018

Topic

This article applies to the TMOS Shell (tmsh). For information about using the Configuration utility, refer to
the following article:

K14620: Managing SSL certificates for BIG-IP systems using the Configuration utility

You should consider using this procedure under the following condition:

You want to use tmsh to manage new or existing Secure Sockets Layer (SSL) keys and certificates
for BIG-IP SSL profiles.

Description

BIG-IP software offers features that allow you to control SSL traffic that is destined for BIG-IP virtual
servers. One of those features, SSL profiles, enables you to maintain secure connections between the client
system and the BIG-IP system, and between the BIG-IP system and a target web server. Before you can
configure an SSL profile, you must install at least one SSL certificate on the BIG-IP system. The SSL
certificate can be either a self-signed certificate or a trusted Certificate Authority (CA) certificate.

A self-signed SSL certificate is a certificate that has been signed by its own private key. BIG-IP software
includes a self-signed SSL certificate named default, which the SSL profile can use to terminate SSL traffic.
You can also use tmsh to import, create, or renew additional self-signed certificates.

A Certificate Authority (CA) certificate is an SSL certificate that is signed by a CA's private key. Using a CA
certificate allows you to replace the self-signed certificate on each BIG-IP system with a trusted CA
certificate (that is, a certificate that is signed by a third party). Authenticating BIG-IP systems using trusted
CA certificates is more secure than using self-signed certificates. tmsh provides a set of commands that
allows you to create certificate signing requests (CSRs). The requests can then be sent to the CA for a
signature.

Note: When renewing an SSL certificate from a CA, F5 recommends that you generate a new CSR and
private key. Although some CAs allow you to renew a certificate by using the existing key, this method is
less secure as it retains the existing private key. To generate a new CSR, refer to the Creating an SSL CSR
procedure.

Prerequisites

You must meet the following prerequisite to use this procedure:

 You have Administrator or Certificate Manager access to tmsh.

Procedures

When managing SSL certificates on the BIG-IP system, you may need to perform one or more of the
following tasks:

Working with new SSL certificates/keys

Creating a self-signed SSL certificate

Creating an SSL CSR and private key
Importing an SSL certificate
Importing an SSL private key
Importing a PKCS 12 file
Importing a CRL

Working with existing SSL certificates/keys

Deleting an SSL certificate

Deleting an SSL private key
Viewing properties of an SSL certificate
Viewing properties of an SSL private key
Renewing an SSL certificate using an existing key (12.x and later)
Renewing a self-signed SSL certificate using an existing certificate and key
Renewing a CA-signed SSL certificate using an existing certificate and key

Working with new SSL certificates and keys

Creating a self-signed SSL certificate

A self-signed SSL certificate is a certificate that has been signed by its own private key. Self-signed
certificates can be used for client or server-side SSL processing; however, they are normally used for
testing purposes.

Note: When performing this procedure to create a new private key and certificate, you must choose a
unique name. Consider appending the current year for easier accountability. For example, name the private
key and certificate example_2017.

Impact of procedure: Performing the following procedure should not have a negative impact on your system.

1. Log in to tmsh by typing the following command:

tmsh

2. To create the new self-signed SSL certificate and private key, use the following command syntax:

create sys crypto key <key name>.key key-size <size in bits> gen-certificate country <country code>
city <city> state <state> organization <company> ou <group within company> common-name <web
site domain> email-address <admin email> lifetime <number of days>
 For example, to create a new 2048 bit key and self-signed SSL certificate named example_2017 that
expires in ten years, type the following command:

create sys crypto key example_2017 key-size 2048 gen-certificate country US city Seattle state WA
organization 'Example, Inc.' ou 'Documentation Team' common-name www.example.com email-
address admin@example.com lifetime 3650

3. Save the new certificate and key by typing the following command:

save sys config

Creating an SSL CSR and private key

CA signed SSL certificates are typically valid for one or two years. To avoid warning messages or
connectivity issues that may be caused by expired SSL certificates, you must renew SSL certificates prior to
their expiration. To renew a CA signed SSL certificate, perform the following procedure.

Note: For more information about monitoring SSL certificate expiration, refer to K14318: Monitoring SSL
certificate expiration on the BIG-IP system (11.x - 13.x).

Impact of procedure: Performing the following procedure should not have a negative impact on your system.

Note: When performing this procedure to generate a new CSR and private key, you must choose a unique
name. Consider appending the current year for easier accountability. For example, name the CSR and
private key example_2017.

1. Log in to tmsh by typing the following command:

tmsh

2. To create the new self-signed SSL certificate and key, use the following command syntax:

create sys crypto key <key name>.key key-size <size in bits> gen-csr country <country code> city
<city> state <state> organization <company> ou <group within company> common-name <web site
domain> email-address <admin email>

For example, to create a new 2048 bit key named example_2017.key and a certificate signing request
(CSR) named example_2017.csr, type the following command:

create sys crypto key example_2017.key key-size 2048 gen-csr country US city Seattle state WA
organization 'Example, Inc.' ou 'Documentation Team' common-name www.example.com email-
address admin@example.com

3. The CSR automatically appears at the command prompt in version 11.6.0 and earlier. In version
12.0.0 and later, use the following command to obtain the CSR.

list sys crypto csr <csr name>

For example, to list the CSR named example_2017.csr, type the following command:
 list sys cryptocsr example_2017.csr

Copy the CSR lines beginning with and including -----BEGIN CERTIFICATE REQUEST----- and
ending with and including -----END CERTIFICATE REQUEST-----. Upload the CSR to your CA for
signing.

The text file should appear similar to the following example:

-----BEGIN CERTIFICATE REQUEST-----

   
[encoded data]
   
-----END CERTIFICATE REQUEST-----

4. Save the new key by typing the following command:

save sys config

5. After the CSR has been signed and returned by the CA, continue to the next section, Importing an
SSL certificate.

Important: Once imported, you must associate the new SSL certificate and key with the appropriate
SSL profile.

Importing an SSL certificate

The signed CSR is returned as an SSL certificate. CAs typically send SSL certificates by email. The
certificate may be included as an attachment or embedded in the body of the email. After you save the
certificate to a text file, you can use tmsh to import the SSL certificate. To do so, perform the following
procedure:

Note: When performing this procedure to import a new SSL certificate, you must choose a unique name.
Consider appending the current year for easier accountability. For example, name the SSL certificate
example_2017.

Impact of procedure: Performing the following procedure should not have a negative impact on your system.

1. Log in to tmsh by typing the following command:

tmsh

2. To copy the CA-signed certificate including the lines -----BEGIN CERTIFICATE----- and -----END
CERTIFICATE----, use the following command syntax:

install sys crypto cert <certificate name>.crt from-editor

For example, to import the SSL certificate and name it example_2017.crt, type the following command:

install sys crypto cert example_2017.crt from-editor

 3. Type "i" for insert, and paste the new SSL certificate. The text file should appear similar to the
following example:

-----BEGIN CERTIFICATE-----
 
[encoded data]
 
-----END CERTIFICATE-----

4. Save the new certificate to memory by pressing the Esc key and typing the following:

:wq!

5. When the vi editor prompts you with the save confirmation message, type y to confirm.

For example:

Save changes? (y/n/e) y

6. Save the new certificate to disk by typing the following command:

save sys config

Importing an SSL private key

You can import SSL private keys in the same manner as SSL certificates. To do so, perform the following
procedure:

Note: When performing this procedure to import a new SSL key, you must choose a unique name. Consider
appending the current year for easier accountability. For example, name the SSL key example_2017.

Impact of procedure: Performing the following procedure should not have a negative impact on your system.

1. Log in to tmsh by typing the following command:

tmsh

2. To copy the SSL private key including the lines -----BEGIN RSA PRIVATE KEY----- and -----END RSA
PRIVATE KEY----, use the following command syntax:

install sys crypto key <key name>.key from-editor

For example, to import the SSL key and name it example_2017.key, type the following command:

install sys crypto key example_2017.key from-editor

3. Type "i" for insert, and paste the SSL private key. The text file should appear similar to the following
example:
 -----BEGIN RSA PRIVATE KEY-----
 
[encoded data]
  
-----END RSA PRIVATE KEY-----

4. Save the new key to memory by pressing the Esc key and typing the following:

:wq!

5. When the vi editor prompts you with the save confirmation message, type y to confirm.

For example:

Save changes? (y/n/e) y

6. Save the new key to disk by typing the following command:

save sys config

Importing a PKCS 12 file

PKCS 12 is a specifically formatted archive file that is used for storing both the SSL key and certificate in a
single file.

Note: PKCS 12 files are typically passphrase-protected and have an extension of .p12 or .PFX.

If you plan to import the PKCS 12 file using the tmsh utility, you must first securely copy using SCP, or use
SFTP to transfer the file to the /shared/tmp directory. To import the PKCS 12 file, perform the following
procedure.

Note: The BIG-IP system automatically converts PKCS 12 certificates to PEM format when the file is
imported.

Impact of procedure: Performing the following procedure should not have a negative impact on your system.

1. Log in to tmsh by typing the following command:

tmsh

2. Import the PKCS 12 file using the following command syntax, depending on the BIG-IP version:

11.5.0 and later:

install sys crypto pkcs12 <pkcs name>.p12 from-local-file /shared/tmp/<pkcs name>.p12 passphrase
<pkcs12 passphrase>
 For example, to import the SSL PKCS 12 file named example.p12 and name the key example_2017.
key and certificate example_2017.crt, type the following command:

install sys crypto pkcs12 example_2017 from-local-file /shared/tmp/example.p12 passphrase abc123

11.0.0 - 11.4.1:

install sys crypto pkcs12 <pkcs name>.p12 from-local-file /shared/tmp/<pkcs name>.p12 prompt-for-
password

For example, to import the SSL PKCS 12 file named example.p12 and name the key example_2017.
key and certificate example_2017.crt, type the following command:

install sys crypto pkcs12 example_2017 from-local-file /shared/tmp/example.p12 prompt-for-password

3. When tmsh prompts for the PKCS 12 passphrase, enter the passphrase twice.

For example:

enter password:
password again:

4. Save the SSL key and certificate by typing the following command:

save sys config

 

Importing a CRL

A certificate revocation list (CRL) is a PEM formatted list of certificates that have been revoked. CRL files
typically have an extension of .pem.

If you plan to upload the CRL file using tmsh, you must first securely copy the file using SCP, or use SFTP
to transfer the file to the /shared/tmp directory. To import the CRL, perform the following procedure.

Impact of procedure: Performing the following procedure should not have a negative impact on your system.

1. Log in to tmsh by typing the following command:

tmsh

2. To import the CRL file, use the following command syntax:

create sys file ssl-crl <crl name>.pem source-path file:/shared/tmp/<crl name>.pem

For example, to import the SSL CRL file named example.pem and name it example.pem, type the
following command:

create sys file ssl-crl example.pem source-path file:/shared/tmp/example.pem

3.
 3. Save the SSL key and certificate by typing the following command:

save sys config

Working with existing SSL certificates and keys

Deleting an SSL certificate

Note: You cannot delete certificates that are referenced by other objects in the system's configuration, such
as Client or Server SSL profiles.

Impact of procedure: Performing the following procedure could have a negative impact on your system if
you delete the wrong certificate.

Important: Consider creating a password-protected user configuration set (UCS) prior to deleting SSL
certificates. For more information, refer to K13132: Backing up and restoring BIG-IP configuration files (11.x
- 12.x).

1. Log in to tmsh by typing the following command:

tmsh

2. To delete the SSL certificate, use the following command syntax:

delete sys crypto cert <cert name>.crt

For example, to delete the SSL certificate named example_2016.crt, type the following command:

delete sys crypto cert example_2014.crt

3. Save the configuration by typing the following command:

save sys config

Deleting an SSL private key

Note: You cannot delete keys that are referenced by other objects in the system's configuration, such as
Client or Server SSL profiles.

Impact of procedure: Performing the following procedure could have a negative impact on your system if
you delete the wrong private key.

Important: Consider creating a password-protected UCS prior to deleting SSL certificates. For more
information, refer to K13132: Backing up and restoring BIG-IP configuration files (11.x - 12.x).

1. Log in to tmsh by typing the following command:

tmsh

2. To delete the SSL private key, use the following command syntax:
 2.

delete sys crypto key <key name>.key

For example, to delete an SSL private key named example_2016.key, type the following command:

delete sys crypto key example_2016.key

3. Save the configuration by typing the following command:

save sys config

Viewing properties of an SSL certificate

Impact of procedure: Performing the following procedure should not have a negative impact on your system.

1. Log in to tmsh by typing the following command:

tmsh

2. To view the SSL certificate properties, use the following command syntax:

list sys crypto cert <cert name>

For example, to view the properties for an SSL certificate named example_2017.crt, type the following
command:

list sys crypto cert example_2017.crt

The system displays certificate properties similar to the following example:

sys sys crypto cert example_2017.crt {

    cert-validation-options none
    cert-validators
    certificate-key-size 2048
    city Seattle
    common-name example.com
    country US
    email-address root@example.com
    expiration Jan 21 20:52:46 2027 GMT
    issuer emailAddress=root@exampleca.com,CN=exampleca.com,OU=IT,O=MyCompany,L=Seattle,
ST=WA,C=US
    issuer-certificate
    organization MyCompany
    ou IT
    public-key-type RSA
    state WA
    subject-alternative-name
}

Viewing properties of an SSL private key

Impact of procedure: Performing the following procedure should not have a negative impact on your system.

1. Log in to tmsh by typing the following command:

tmsh

2. To view the SSL private key properties, use the following command syntax:

list sys crypto key <key name>

For example, to view the properties for an SSL private key named example_2017.key, type the
following command:

list sys crypto key example_2017.key

The system displays certificate properties similar to the following example:

sys crypto key example_2017.key {

    key-size 2048
    key-type rsa-private
    security-type normal
}

Renewing an SSL certificate using an existing key (12.x and later)

A CA is a trusted entity that issues digital certificates. CA certificates are signed by the CA's private key.

Impact of procedure: Performing the following procedure should not have a negative impact on your system.

Note: When performing this procedure to renew an SSL certificate, you must choose a unique name.
Consider appending the current year for easier accountability. For example, name the SSL certificate
example_2017.

1. Log in to tmsh by typing the following command:

tmsh

2. To create the CSR using an existing key, use the following command syntax:

create sys crypto csr <csr name> key <key name>.key country <country code> city <city> state
<state> organization <company> ou <group within company> common-name <web site domain>
email-address <admin email>

For example, to create a new CSR named example_2017.csr using the previous year's key
example_2016.key, type the following command:

create sys crypto csr example_2017 key example_2016.key country US city Seattle state WA
organization 'Example, Inc.' ou 'Documentation Team' common-name www.example.com email-
address admin@example.com

3.
 3. To obtain the newly created CSR, type the following command:

list sys crypto csr <csr name>

For example, to list the CSR named example_2017.csr, type the following command:

list sys crypto csr example_2017.csr

Copy the CSR lines beginning with and including -----BEGIN CERTIFICATE REQUEST----- and
ending with and including -----END CERTIFICATE REQUEST-----. Upload the CSR to your CA for
signing.

The text file should appear similar to the following example:

-----BEGIN CERTIFICATE REQUEST-----

   
[encoded data]
   
-----END CERTIFICATE REQUEST-----

4. Once a newly signed SSL certificate has been returned to you, follow the Importing an SSL certificate
procedure.
 

Renewing a self-signed SSL certificate using an existing certificate and key

SSL certificates and keys are stored in the BIG-IP system's filestore directory. The BIG-IP filestore adds a
unique identifier to each SSL certificate and key file name. For this reason, the SSL certificate and key
filestore name will not be identical to the tmsh file name.

Impact of procedure: Performing the following procedure should not have a negative impact on your system.

Note: When performing this procedure to renew an SSL certificate, you must choose a unique name.
Consider appending the current year for easier accountability. For example, name the SSL certificate
example_2017.

1. Log in to the BIG-IP command line and change to the filestore directory.

For example, if the certificate and key exist in the Common partition, type the following command:

cd /config/filestore/files_d/Common_d

2. To find the correct filestore key and certificate names, use the following command syntax:

ls certificate_d/* certificate_key_d/* | grep <key and cert name> | awk -F ':' '{print $3}'

For example, to locate the correct filestore key and certificate for example_2016.key and
example_2016.crt, type the following command:
 ls certificate_d/* certificate_key_d/* | grep example_2016 | awk -F ':' '{print $3}'
example_2016.crt_145377_1
example_2016.key_145375_1

3. To create the new CSR, use the following command syntax:

openssl x509 -x509toreq -in certificate_d/\:<partition>\:<existing cert> -signkey certificate_key_d/\:

<partition>\:<existing key> -out /shared/tmp/<csr name>

For example, to create a new CSR named example_2017.csr using the existing key example_2016.
key and the information from existing certificate example_2016.crt in the Common partition, type the
following command:

openssl x509 -x509toreq -in certificate_d/\:Common\:example_2016.crt_145377_1 -signkey

certificate_key_d/\:Common\:example_2016.key_145375_1 -out /shared/tmp/example_2017.csr

4. To sign the new CSR with the existing key, use the following command syntax:

openssl x509 -req -in /shared/tmp/<csr name> -signkey certificate_key_d/\:<partition>\:<existing key> -

days <num of days> -out /shared/tmp/<new cert>

For example, to sign the CSR named example_2017.crt using the existing key example_2016.key,
and name the new certificate example_2017.crt to be valid for one year, type the following command:

openssl x509 -req -in /shared/tmp/example_2017.csr -signkey certificate_key_d/\:Common\:

example_2016.key_145375_1 -days 365 -out /shared/tmp/example_2017.crt

5. To import the newly signed certificate back into the filestore, first switch to tmsh by typing the
following command:

tmsh

6. To import the certificate which can be found in the /shared/tmp directory, use the following command
syntax:

install sys crypto cert <new cert name> from-local-file /shared/tmp/<new certificate>

For example, to import the new SSL certificate named example_2017.crt, type the following command:

install sys crypto cert example_2017.crt from-local-file /shared/tmp/example_2017.crt

7. Save the SSL key and certificate by typing the following command:

save sys config

Renewing a CA-signed SSL certificate using an existing certificate and key

SSL certificates and keys are stored in the BIG-IP system's filestore directory. The BIG-IP filestore adds a
unique identifier to each SSL certificate and key file name. For this reason, the SSL key and certificate
filestore name will not be identical to the tmsh file name.

Impact of procedure: Performing the following procedure should not have a negative impact on your system.

Note: F5 recommends that you generate a new CSR and private key to mitigate against potential SSL
vulnerabilities, such as the Heartbleed vulnerability. For more information about the Heartbleed vulnerability,
refer to K15159: OpenSSL vulnerability CVE-2014-0160.

Note: To generate a new CSR and key, refer to the Creating an SSL CSR procedure.

Note: When performing this procedure to renew an SSL certificate, you must choose a unique name.
Consider appending the current year for easier accountability. For example, name the SSL certificate 
example_2017.

1. Log in to the BIG-IP command line and change to the filestore directory.

For example, if the certificate and key exist in the Common partition, type the following command:

cd /config/filestore/files_d/Common_d

2. To find the correct filestore key and certificate names, use the following command syntax:

ls certificate_d/* certificate_key_d/* | grep <key and cert name> | awk -F ':' '{print $3}'

For example, to locate the correct filestore key and certificate for example_2016.key and
example_2016.crt, type the following command:

ls certificate_d/* certificate_key_d/* | grep example_2016 | awk -F ':' '{print $3}'

example_2016.crt_145377_1
example_2016.key_145375_1

3. To create the new CSR, use the following command syntax:

openssl x509 -x509toreq -in certificate_d/\:<partition>\:<existing cert> -signkey certificate_key_d/\:

<partition>\:<existing key> -out /shared/tmp/<csr name>

For example, to create a new CSR named example_2017.csr using the existing key example_2016.
key and the information from the existing certificate example_2016.crt in the Common partition, type
the following command:

openssl x509 -x509toreq -in certificate_d/\:Common\:example_2016.crt_145377_1 -signkey

certificate_key_d/\:Common\:example_2016.key_145375_1 -out /shared/tmp/example_2017.csr

4. Find the newly signed CSR in the /shared/tmp directory, and then securely copy the new CSR to your
local host, and upload the file to your CA for signing.
 After the file has been signed by the CA, securely copy the file back to the /shared/tmp directory, and
continue to step 5.

5. To import the newly signed certificate back into the filestore, first switch to tmsh by typing the
following command:

tmsh

6. To import the certificate that can be found in the /shared/tmp directory, use the following command
syntax:

install sys crypto cert <new cert name> from-local-file /shared/tmp/<new certificate>

For example, to import the new SSL certificate named example_2017.crt, type the following command:

install sys crypto cert example_2017.crt from-local-file /shared/tmp/example_2017.crt

7. Save the SSL key and certificate by typing the following command:

save sys config

Supplemental Information

K14318: Monitoring SSL certificate expiration on the BIG-IP system (11.x - 13.x)
K14783: Overview of the Client SSL profile (11.x - 13.x)
K6353: Updating an SSL device certificate on a BIG-IP system
K13471: Creating SSL SAN certificates and CSRs using the Configuration utility or tmsh
K13349: Verifying SSL certificate and key pairs from the command line (11.x - 13.x)
K13831: Missing or corrupt default SSL certificate and key pair may generate errors (11.x)
K14499: Using OpenSSL to create CA and client certificates (11.x - 12.x)