K12522815: Modifying the BIG-IP device SSL certificate configuration using the iControl REST API
Non-Diagnostic
Original Publication Date: Apr 30, 2019
Update Date: Aug 6, 2021
Topic
You want to use the iControl REST API to generate and apply a new self-signed SSL device certificate and key. You want to use the iControl REST API to apply an uploaded SSL certificate and key as the device certificate.
Description
You can use the iControl REST API to administer the SSL certificate and key that the Configuration utility uses.
You can use the procedures in this article to generate a new self-signed certificate and key, which you can apply as the certificate and key used by the Configuration utility. Additionally, you can use a subset of the procedures to upload a certificate and key to the appropriate directories and then apply these as the certificate and key used by the Configuration utility.
Typographic conventions
The following typographic conventions are used in the command syntax examples:
Note: If you are a new user of the iControl REST API, refer to K13225405: Common iControl REST API command examples.
POST = curl -sk -u admin:
Prerequisites
You must meet the following prerequisites to use this procedure:
The BIG-IP system is licensed, provisioned, and configured with a management IP address. You have administrative access to the BIG-IP LTM Configuration utility. You have command line access to a Linux system (or an alternate BIG-IP system) with the curl and jq (command line JSON processor) utilities installed.
Procedures
Generating a SSL self-signed certificate and key Uploading a SSL certificate and key Specifying the device SSL certificate and key Restarting the httpd service Viewing the device SSL certificate configuration
Generating a SSL self-signed certificate and key
Using the iControl REST API, you can generate a new SSL self-signed device certificate and key.
Impact of procedure: Performing the following procedure should not have a negative impact on your system.
At the Linux command line, use the following command syntax:
For example:
SSL certificate and key generation REST command options
You can use the following command options to generate your SSL certificate and key.
--name | -n --commonname | -h --country | -c --state | -s --city | -t --org | -o --orgunit | -u --email | -e --keytype | -k (RSA or DSA)
Important: The REST command uses the -p flag to declare the base destination directory for the SSL certificate and key files. Without this command syntax, the SSL certificate and key files are generated as BIG-IP traffic SSL certificates and keys and are not accessible for use as the device certificate and key. Uploading a SSL certificate and key
To use a certificate and key that is not specifically generated on the BIG-IP device, upload the certificate and key to the /config/httpd/conf/ssl.crt and /config/httpd/conf/ssl.key directories respectively. The ability to upload SSL certificates and key files to the /config/httpd/conf directories using an iControl REST command is not possible. To workaround this limitation, the files can be uploaded using secure copy protocol (SCP). To upload the certificate and key files using SCP use the following procedure.
Important: Do not use the certificate or key file names server.crt or server.key as these are the default certificate and key names.
Note: There are restrictions in using the scp command to upload the files. For more information, refer to K73463547: Restrictions in transferring files to the BIG-IP system using the scp command.
Impact of procedure: Performing the following procedure should not have a negative impact on your system.
1. Using a SCP client on your local device, upload the SSL certificate file to the /config/httpd/conf/ssl.crt directory.
At the Linux command line, use the following command syntax:
scp
For example:
scp my_example_certificate.crt [email protected]:/config/httpd/conf/ssl.crt/my_example_certificate.crt
2. Using an SCP client on your local device, upload the SSL certificate key file to the /config/httpd/conf /ssl.key directory.
At the Linux command line, use the following command syntax:
scp
For example:
scp my_example_key.key [email protected]:/config/httpd/conf/ssl.key/my_example_key.key
Specifying the device SSL certificate and key
After your new SSL certificate and key is generated or you have uploaded the SSL certificate and key, you can use iControl REST to specify the BIG-IP device to use the SSL certificate and key for Configuration utility access.
Impact of procedure: The following procedure configures the BIG-IP device to use the specified SSL certificate and key for Configuration utility access. If the referenced certificate and key are mismatched, the command fails. Important: In BIG-IP 14.0.0 and later, when using the REST API to generate the SSL certificate and key files, the SSL certificate and key files both use the same base name and are named identically (without the . crt and .key suffixes) and are placed in the subdirectories ssl.key and ssl.crt of the specified base directory used in the REST command. For BIG-IP versions prior to 14.0.0, when using the REST API to generate the SSL certificate and key files, the SSL certificate and key file names are automatically appended with the .crt and .key file suffixes and are placed in the subdirectories ssl.key and ssl.crt of the specified base directory used in the REST command.
At the Linux command line, use the following command syntax:
For BIG-IP 14.0.0 and later, specify the iControl REST-generated SSL certificates and keys names without the suffixes. If the SSL certificate and key files were uploaded to the BIG-IP device in the /config/httpd/conf/ssl.key and ssl.crt directories, use the exact file name of the uploaded certificate and key when running the REST command.
For example:
For BIG-IP versions earlier than 14.0.0, specify the SSL certificate file using the .crt suffix and the key file with the .key suffix. If the SSL certificate and key files were uploaded to the BIG-IP device in the /config/httpd/conf/ssl.key and ssl.crt directories, use the exact file name of the SSL certificate and key when running the REST command.
At the Linux command line, use the following command syntax:
For example:
Restarting the httpd service
After you assign an SSL certificate and key for the device, you must restart the httpd service to implement the change.
Impact of procedure: The following procedure restarts the httpd service, causing the Configuration utility to become temporarily unavailable.
At the Linux command line, use the following command syntax:
ID 775845 K13292945: httpd failing to start after restarting the service using the iControl REST API Workaround on DevCentral: Creating a tmsh script with iControl REST and using it to restart HTTPD
Viewing the device SSL certificate configuration
You can use the iControl REST API to view the SSL certificate configuration of the device.
Impact of procedure: Performing the following procedure should not have a negative impact on your system.
At the Linux command line, type the following command:
Note: Viewing objects with a REST command can produce verbose JSON output. To format the JSON output to a more user-friendly format, use the jq command-line JSON-processor command. The jq command -MS flag sets the formatted JSON output to use monochrome when displaying the JSON output. The . (period) parameter is optional in jq 1.5 and later.
Supplemental Information
K13225405: Common iControl REST API command examples K00842042: BIG-IP AFM iControl REST API example commands K42442250: Obtaining the list of iControl REST asynchronous API transactions
Applies to:
Product: BIG-IP 14.X.X, 13.X.X, 12.X.X, 11.6.X, 11.5.9