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:<password> -H "Content-Type: application/json" -X POST https://<big-ip address> PUT = curl -sk -u admin:<password> -H "Content-Type: application/json" -X PUT https://<big-ip address> GET = curl -sk -u admin:<password> -H "Content-Type: application/json" -X GET https://<big-ip address> 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: <POST>/mgmt/tm/util/gencert -d '{"command":"run","utilCmdArgs":" -n \"<name>\" -p \"/config/httpd /conf/\" -e \"<admin email>\" -h \"<hostname>\" -c \"<country>\" -s \"<state>\" -t \"<city>\" --org \" <organization>\" -u \"<organizational unit>\" -k RSA <key size>" }' For example: <POST>/mgmt/tm/util/gencert -d '{"command":"run","utilCmdArgs":" -n \"bigip1.example.com\" -p \" /config/httpd/conf/\" -e \"[email protected]\" -h \"bigip1.example.com\" -c \"US\" -s \"IL\" -t \" Chicago\" --org \"Example BIG-IP\" -u \"Internet Services\" -k RSA 2048" }' 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) <keysize> --fips | -f create the key inside the FIPS-140 device --yesterday | -y] Back date the certificate by 1 day --nocfg | -X The certificate will not be part of the configuration 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 <certificate file name>.crt <username>@<big-ip ip address>:/config/httpd/conf/ssl.crt/<certificate file name>.crt 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 <certificate key file name>.key <username>@<big-ip ip address>:/config/httpd/conf/ssl.key /<certificate key file name>.key 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: <PUT>/mgmt/tm/sys/httpd -d '{"sslCertfile":"/config/httpd/conf/ssl.crt/<file name>","sslCertkeyfile":" /config/httpd/conf/ssl.key/<file name>"}' 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: <PUT>/mgmt/tm/sys/httpd -d '{"sslCertfile":"/config/httpd/conf/ssl.crt/example","sslCertkeyfile":"/config /httpd/conf/ssl.key/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: <PUT>/mgmt/tm/sys/httpd -d '{"sslCertfile":"/config/httpd/conf/ssl.crt/<file name>.crt","sslCertkeyfile":" /config/httpd/conf/ssl.key/<file name>.key"}' For example: <PUT>/mgmt/tm/sys/httpd -d '{"sslCertfile":"/config/httpd/conf/ssl.crt/example.crt","sslCertkeyfile":" /config/httpd/conf/ssl.key/example.key"}' 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: <POST> /mgmt/tm/sys/service -d '{"name":"httpd","command":"restart"}' Note: An issue confirmed in BIGIP 12.1.0-16.0.1 exists when restarting httpd from a simple iControl POST. For more information, refer to the following information: 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: <GET> /mgmt/tm/sys/httpd | jq -M. 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.