Example: Getting and installing a signed leaf certificate using REST APIs

This example includes the step to create a trust anchor (TA) profile. If the TA profile had previously been configured, that step of the example would be skipped. The TA profile is used to validate the signed certificate when you import the certificate as part of the PUT request.

For more information about certificates and certificate management, see the Security Guide.

Procedure

Create a trust anchor (TA) profile:
1. From the certificate authority (CA), get a copy of the certificate against which you will validate leaf certificates.
  The certificate you validate leaf certificates against can be a root certificate or an intermediate certificate.
  
  The steps to get the certificate depend on the CA and the operating system you use.
2. Create a JSON object with a certificate key and a name key.
  For example:
```
{
  "name": "<profile-name>",
  "certificate": "<root-ca-cert>"
}
```
  - For the value of the name key, replace <profile-name> with the name of the TA profile you want to create.
  - For the value of the certificate key, replace <root-ca-cert> by pasting the copied certificate.
    
    After pasting, edit the text to ensure proper loading as a JSON object by doing the following:
    - Ensure the certificate headers and footers are treated as separate lines by adding \n characters after the header and before the footer.
      
      The following example shows the \n characters in bold. Ellipses (…) represent data not shown in the example.
      
      { "name": "myta", "certificate": "-----BEGIN CERTIFICATE-----\nMIIF2DCCA8CgAwIBAgIlCnL MA0GCSqGSIb3DQEBCwUAMHkxCzAJBgNVBAYTAkdCMRAwDgYDVQQIDAdFbmdsYW5kMRIwEAYDVQDAl ... PKj0FmJ1+Qzw9Bcm6HiPTyxOVozMeRQzSQhTZVlh3OvBw/cUwTIqFJCe/afNQCqa9XnvTpJvP/Q3z ... S4L9sxrk/i3hKB88\n-----END CERTIFICATE-----" }
    - Ensure that any private key headers and footers are treated as separate lines by adding \n characters before and after them as needed.
      
      For example:
      
      \n-----BEGIN PRIVATE KEY-----\n MIIFDjBABgkqhkiG9wBBQ0wMzAbBgqkw0QwwDQIpJMN7sVGwCAggA ... iKnXnUMpVPfLc74ty2S41DtH0X9gf6aa1jStg+7cND9XfGtjaV2CA \n-----END PRIVATE KEY-----\n
      \n-----BEGIN ENCRYPTED PRIVATE KEY-----\n IJ6L/UhEtH523nUkdV6gvAgoYaD83PswToAGv5VS8OMFTPttrn5/K ... OgSecqZsG6arbx0ESaYBir1c/6rPspcjbx283iD1MWOpeoS2aEmOX= \n-----END ENCRYPTED PRIVATE KEY-----\n
3. Use the POST method to create the TA profile with the copied certificate. Include the JSON object in the request body:
  Example method and URI:
```
POST "https://192.0.2.5/rest/v1/system/pki_ta_profiles"
```
  Example curl commands (Ellipses (…) represent data not shown in the example.):
```
$ curl -k --noproxy 192.0.2.5 -POST \
-b /tmp/primary_auth_cookie \ 
--data '{
  "name": "myta",
  "certificate": "-----BEGIN CERTIFICATE-----\nMIIF2DCCA8CgAwIBAgIJANkWgud1lCnL
MA0GCSqGSIb3DQEBCwUAMHkxCzAJBgNVBAYTAkdCMRAwDgYDVQQIDAdFbmdsYW5kMRIwEAYDVQQKDAl
...
PKj0FmJ1+Qzw9Bcm6HiPTyxOVozMeRQzSQhTZVlh3OvBw/cUwTIqFJCe/afNQCqa9XnvTpJvP/Q3ze6
S4L9sxrk/i3hKB88\n-----END CERTIFICATE-----"
}' 
"https://192.0.2.5/rest/v1/system/pki_ta_profiles"
```
  On successful completion, the switch returns response code 201 Created.

Create a certificate with a pending certificate signing request (CSR).

For information about the required and optional items in the request body, see the JSON model for the certificates resource in the AOS-CX REST API Reference.

Example method and URI:

POST "https://192.0.2.5/rest/v1/certificates"

Example request body:

{
  "certificate_name": "my-cert-name",
  "subject": {
    "common_name": "CX-8400"
    "country": "US",
    "locality":"el camino",
    "state": "CA",
    "org": "HPE",
    "org_unit": "Aruba",
    },
  "key_type": "RSA",
  "key_size": 2048,
  "cert_type": "regular"
}

Example curl command:

$ curl -k --noproxy 192.0.2.5 -POST \
-b /tmp/primary_auth_cookie \ 
--data '{
  "certificate_name": "my-cert-name",
  "subject": {
    "common_name": "CX-8400"
    "country": "US",
    "locality":"el camino",
    "state": "CA",
    "org": "HPE",
    "org_unit": "Aruba",
    },
  "key_type": "RSA",
  "key_size": 2048,
  "cert_type": "regular"
}' 
"https://192.0.2.5/rest/v1/certificates"

On successful completion, the switch returns response code 201 Created.

Get the certificate you created in the previous step.
Example method and URI:
```
GET "https://192.0.2.5/rest/v1/certificates/my-cert-name"
```
Example curl command:
```
$ curl -k --noproxy 192.0.2.5 -GET \
-b /tmp/primary_auth_cookie \ 
"https://192.0.2.5/rest/v1/certificates/my-cert-name"
```
On successful completion, the switch returns response code 200 OK and a response body containing the CSR in PEM format.
Send the CSR to the CA for signing.
The steps to send the CSR depend on the CA and the operating system you use.

The CA returns the signed certificate in PEM format.

Import the signed certificate by using a PUT request to update the my-cert-name certificate with the signed certificate you received from the CA.

The imported certificate data must include all the intermediate CA certificates in the certificate chain leading to the certificate that was imported into the specified TA profile.

If you copy and paste the certificate into a JSON object, you must ensure that the certificate and private key headers and footers are processed as separate lines by editing the text to add \n characters as needed.

As part of the PUT request, the switch attempts to validate the certificate against the pool of all TA profiles installed on the switch. The certificate is accepted if it is validated with one of the TA profiles.

Example method and URI:

PUT "https://192.0.2.5/rest/v1/certificates/my-cert-name"

Example request bodies (Ellipses (…) represent data not shown in the example.):

{
  "certificate": "-----BEGIN CERTIFICATE-----\n
MIIFRDCCAyygAwIBAgQP8nS2Vp15u0xXMdkDJzANBgkqhkiG9w0Bv
...
1NGNm3NG03GqPScs/TF9bVyFA5BOS5lmmkfRYK8D/kMTfRreSdxis
YQ1u1NqShps=
\n-----END CERTIFICATE-----\n
\n-----BEGIN ENCRYPTED PRIVATE KEY-----\n
MIIFDjBABgkqhkiG9wBBQ0wMzAbBgqkw0QwwDQIpJMN7sVGwCAggA
...
iKnXnUMpVPfLc74ty2S41DtH0X9gf6aa1jStg+7cND9XfGtjaV2+/
cb4=
\n-----END ENCRYPTED PRIVATE KEY-----"
}

Example curl commands (Ellipses (…) represent data not shown in the example.):

$ curl -k --noproxy 192.0.2.5 -PUT \
-b /tmp/primary_auth_cookie \ 
--data '{
  "certificate": "-----BEGIN CERTIFICATE-----\n
MIIFRDCCAyygAwIBAgQP8nS2Vp15u0xXMdkDJzANBgkqhkiG9w0Bv
...
1NGNm3NG03GqPScs/TF9bVyFA5BOS5lmmkfRYK8D/kMTfRreSdxis
YQ1u1NqShps=
\n-----END CERTIFICATE-----\n
\n-----BEGIN ENCRYPTED PRIVATE KEY-----\n
MIIFDjBABgkqhkiG9wBBQ0wMzAbBgqkw0QwwDQIpJMN7sVGwCAggA
...
iKnXnUMpVPfLc74ty2S41DtH0X9gf6aa1jStg+7cND9XfGtjaV2+/
cb4=
\n-----END ENCRYPTED PRIVATE KEY-----"
}' 
"https://192.0.2.5/rest/v1/certificates/my-cert-name"

On successful completion, the switch returns response code 200 OK.

The certificate is installed and ready to be associated with switch features.