Import certificate and key to BIG-IQ

Overview

The workflow described in this topic assumes you have data files for the key and certificate you wish to import to the BIG-IQ. First you can use BIG-IQ’s File Uploads API to copy these files to the BIG-IQ. Second you can use the SSL Object Management API to create unmanaged SSL objects on the BIG-IQ and retrieve the keyReference and certReference links to these. An unmanaged object cannot be deployed by the BIG-IQ to a BIG-IP. With keyReference and certReference you can use the SSL Object Management API to make the unmanaged objects managed as described in the Manage SSL Objects from BIG-IQ section.

POST to upload the key file

The following example uses BIG-IQ’s File Uploads API to upload a key data file, mykey.key, to the destination file located at /var/config/rest/downloads on the BIG-IQ. This is the location required to use the SSL Object Management API to create the unmanaged SSL object.

POST https://<BIG-IQ>/mgmt/shared/file-transfer/uploads/mykey.key

The JSON in the body of the POST request can look similar to the following example.

{
    "payload": {
            "content": "-----BEGIN PRIVATE KEY-----\r\nMIIEvQIBADANBgkqhkiG9w...characters_ommited...36a/FLHa6p1oo=\r\n-----END PRIVATE KEY-----"
    },
    "headers": {
            "Content-Length": "1679",
            "Content-Type": "application/octet-stream",
            "Content-Range": "0-1678/1679"
    }
}

Response

The response to the POST can look similar to the following.

HTTP/1.1 200 OK

{
    "payload": {
            "content": "-----BEGIN PRIVATE KEY-----\r\nMIIEvQIBADANBgkqhkiG9w...characters_ommited...36a/FLHa6p1oo=\r\n-----END PRIVATE KEY-----"
    },
    "headers": {
            "Content-Length": "1679",
            "Content-Type": "application/octet-stream",
            "Content-Range": "0-1678/1679"
    },
    "totalByteCount": "1234",
    "localFilePath": "/var/config/rest/downloads/mykey.key"
}

On success, the file is saved to /var/config/rest/downloads/mykey.key.

POST for the unmanaged key object

Use BIG-IQ’s SSL Object Management API to create a key object and retrieve the key’s keyReference on the BIG-IQ. In the following example, a copy of the key file, mykey.key, has previously been copied to /var/config/rest/downloads/mykey.key on the BIQ-IQ using the BIG-IQ’s File Uploads API. Send a POST request to the certificate-management collection with the key’s naming properties provided in the body and the value of command set to “ADD_KEY”.

POST https://<BIG-IQ>/mgmt/cm/adc-core/tasks/certificate-management

The JSON in the body of the POST request can look similar to the following example.

{
    "payload": {
            "content": {
                    "filePath": "/var/config/rest/downloads/mykey.key",
                    "itemName": "mykey.key",
                    "itemPartition": "Common",
                    "command": "ADD_KEY"
            }
    },
    "headers": {
            "Content-Length": "1679",
            "Content-Type": "application/octet-stream",
            "Content-Range": "0-1678/1679"
    }
}

Response

The response to the POST can look similar to the following example.

HTTP/1.1 200 OK

{
    "command": "ADD_KEY",
    "itemName": "mykey.key",
    "itemPartition": "Common",
    "filePath": "/var/config/rest/downloads/mykey.key",
    "id": "6ddf7eb1-7d5d-4781-b30f-e07c900034da",
    "status": "STARTED",
    "userReference": {
            "link": "https://localhost/mgmt/shared/authz/users/admin"
    },
    "identityReferences": [{
            "link": "https://localhost/mgmt/shared/authz/users/admin"
    }],
    "ownerMachineId": "cc6a840f-b524-45f7-b0ae-affaf6584d7c",
    "selfLink": "https://localhost/mgmt/cm/adc-core/tasks/certificate-management/6ddf7eb1-7d5d-4781-b30f-e07c900034da"
}

Note that the JSON in the body of the response includes the task’s id and an initial status of STARTED. After initiating the task you can poll for the task’s completion by sending GET requests to the task’s endpoint to check the updated value of status until the task completes. Polling for this example task would look as follows.

GET https://<BIG-IQ>/mgmt/cm/adc-core/tasks/certificate-management/6ddf7eb1-7d5d-4781-b30f-e07c900034da

When the value of status in a GET response is “FINISHED”, the response will include a keyReference similar to the following. The keyReference provides a pointer to a new key.

{
    "keyReference": {
            "id": "ed0168ee-696f-3036-8266-7b81c4840246",
            "name": "mykey.key",
            "kind": "cm:adc-core:working-config:sys:file:ssl-key:adcsslkeystate",
            "partition": "Common",
            "link": "https://localhost/mgmt/cm/adc-core/working-config/sys/file/ssl-key/ed0168ee-696f-3036-8266-7b81c4840246"
    },
    "command": "ADD_KEY",
    "filePath": "/var/config/rest/downloads/mykey.key",
    "id": "6ddf7eb1-7d5d-4781-b30f-e07c900034da",
    "identityReferences": [{
            "link": "https://localhost/mgmt/shared/authz/users/admin"
    }],
    "itemName": "mykey.key",
    "itemPartition": "Common",
    "selfLink": "https://localhost/mgmt/cm/adc-core/tasks/certificate-management/6ddf7eb1-7d5d-4781-b30f-e07c900034da",
    "ownerMachineId": "cc6a840f-b524-45f7-b0ae-affaf6584d7c",
    "status": "FINISHED",
    "userReference": {
            "link": "https://localhost/mgmt/shared/authz/users/admin"
    },
    "username": "admin"
}

With keyReference you can use the SSL Object Management API to make the unmanaged key object managed as described in the Manage SSL Objects from BIG-IQ section.

POST to upload the certificate file

The following example uses BIG-IQ’s File Uploads API to upload a certificate file, mycert.crt, to the destination file located at /var/config/rest/downloads on the BIG-IQ. This is the location required to use SSL Object Management API to create the unmanaged SSL object.

POST https://<BIG-IQ>/mgmt/shared/file-transfer/uploads/mycert.crt

Response

On success, the file is saved to the location /var/config/rest/downloads/mycert.crt.

HTTP/1.1 200 OK

On success, the file is saved to /var/config/rest/downloads/mycert.crt.

POST for the unmanaged certificate object

Use BIG-IQ’s SSL Object Management API to create a certificate object and retrieve the certificate’s certReference on the BIG-IQ. In the following example, a copy of the certificate file, mycert.crt, has previously been copied to /var/config/rest/downloads on the BIQ-IQ using the BIG-IQ’s File Uploads API. Send a POST request to the certificate-management collection with the key’s naming properties provided in the body and the value of command set to “ADD_CERT”.

POST https://<BIG-IQ>/mgmt/cm/adc-core/tasks/certificate-management

The JSON in the body of the POST request can look similar to the following example.

{
    "payload": {
            "content": {
                    "filePath": "/var/config/rest/downloads/mycert.crt",
                    "itemName": "mycert.crt",
                    "itemPartition": "Common",
                    "command": "ADD_CERT"
            }
    },
    "headers": {
            "Content-Length": "1679",
            "Content-Type": "application/octet-stream",
            "Content-Range": "0-1678/1679"
    }
}

Response

The response to the POST can look similar to the following example.

HTTP/1.1 200 OK

{
    "command": "ADD_CERT",
    "itemName": "mycert.crt",
    "itemPartition": "Common",
    "filePath": "/var/config/rest/downloads/58ef3796-06ee-4d7c-aa3c-2db195015c0b",
    "id": "58ef3796-06ee-4d7c-aa3c-2db195015c0b",
    "status": "STARTED",
    "userReference": {
            "link": "https://localhost/mgmt/shared/authz/users/admin"
    },
    "identityReferences": [{
            "link": "https://localhost/mgmt/shared/authz/users/admin"
    }],
    "ownerMachineId": "cc6a840f-b524-45f7-b0ae-affaf6584d7c",
    "selfLink": "https://localhost/mgmt/cm/adc-core/tasks/certificate-management/58ef3796-06ee-4d7c-aa3c-2db195015c0b"
}

Note that the JSON in the body of the response includes the task’s id and an initial status of STARTED. After initiating the task you can poll for the task’s completion by sending GET requests to the task’s endpoint to check the updated value of status until the task completes. Polling for this example task would look as follows.

GET https://<BIG-IQ>/mgmt/cm/adc-core/tasks/certificate-management/58ef3796-06ee-4d7c-aa3c-2db195015c0b

When the value of status in a GET response is “FINISHED”, the response will include a certReference similar to the following. The certReference provides a pointer to a new certificate on the BIG-IQ.

{
    "certReference": {
            "id": "9c6dfe1c-7d89-3447-bf35-e58c88904a7c",
            "name": "mycert.crt",
            "kind": "cm:adc-core:working-config:sys:file:ssl-cert:adcsslcertstate",
            "partition": "Common",
            "link": "https://localhost/mgmt/cm/adc-core/working-config/sys/file/ssl-cert/9c6dfe1c-7d89-3447-bf35-e58c88904a7c"
    },
    "command": "ADD_CERT",
    "filePath": "/var/config/rest/downloads/mycert.crt",
    "id": "58ef3796-06ee-4d7c-aa3c-2db195015c0b",
    "identityReferences": [{
            "link": "https://localhost/mgmt/shared/authz/users/admin"
    }],
    "itemName": "mycert.crt",
    "itemPartition": "Common",
    "selfLink": "https://localhost/mgmt/cm/adc-core/tasks/certificate-management/58ef3796-06ee-4d7c-aa3c-2db195015c0b",
    "status": "FINISHED",
    "ownerMachineId": "cc6a840f-b524-45f7-b0ae-affaf6584d7c",
    "userReference": {
            "link": "https://localhost/mgmt/shared/authz/users/admin"
    },
    "username": "admin"
}

With certReference you can use the SSL Object Management API to make the unmanaged certificate object managed as described in the Manage SSL Objects from BIG-IQ section.