Manage CA certificates
For X.509 certificate based device authentication, the certificate of a certificate authority (CA) which issued a device's certificate has to be uploaded to your tenant (refer to X.509 Certificate based device authentication). This page shows you how to upload CA certificates as well as further management operations with them.
You manage a tenant’s CA certificates by modifying (patching) the tenant with the given tenant-id using an HTTP PATCH request. The request schema follows RFC 6902 - JavaScript Object Notation (JSON) Patch. Only the property trusted-ca of a tenant can be modified with following further restrictions:
Modifying the tenant comprises the following operations:
Up to 5 CA certificates can be added. That is, the trusted-ca property of a tenant must contain an array of 1 to 5 elements which are indexed by 0 to 4.
Supported algorithms for the CA certificate’s public key are RSA and ECDSA. The private key’s length must be between 2048 and 4096 for RSA and between 256 and 384 for ECDSA.
add and replace operations must provide a value property. The value has to be an object with exactly one property named cert. This property contains a string which represents a Base64-encoded CA certificate in PEM format (including plain text headers and footers).
Several operations can be given in a sequence. However, we recommend to execute one operation. Even a single operation has to be wrapped by an array.
You address a specific certificate by appending its index to the path property, for example /trusted-ca/2. To address the next available index for adding an element, use /trusted-ca/-.
Each operation of the HTTP PATCH request has the following general structure (array of at least 1 operation element):
[ { "op": "add|remove|replace", "path": "string: /trusted-ca/[0-4,-]", "from": "string: /trusted-ca/[0-4]", "value": { "id": "string (optional): unique CA identifier, will be generated if omitted", "cert": "string: representing a Base64-encoded CA certificate in PEM format" } }, { "_comment": "another operation..." } ]The cert property of the operation’s value contains the CA’s certificate. It consists of the entire content of a PEM file represented as a Base64-encoded string. I.e. using a common unix console, you can create the value of the cert property by calling cat tenant-cert.pem | base64 -w 0 while tenant-cert.pem contains the CA’s certificate.
Operations
The following examples demonstrate how to use the HTTP PATCH request to manage your CA files.
Prerequisites
To follow along the examples below these prerequisites have to be met:
You are logged in to the Bosch IoT Hub - Management API. Refer to Login to Bosch IoT Hub - Management API.
In the Management API navigate to the tenant section and select the PATCH operation.
Press the Try it out button.
Enter your tenant-id in the tenant-id field.
Add certificate
The add operation adds one (or multiple) CA certificate(s) to the trusted-ca property of the target tenant document.
You can use the add operation as follows:
Add an array of 1 to 5 certificates at once to trusted-ca property.
Add a single certificate as an element with index i to trusted-ca/i (the target trusted-ca must already exist).
Examples
Add two certificates
In the Request body, enter the add operation referring to the trusted-ca property:
Enter the CA certificate Base64 encrypted certificate in PEM format as the first certificate and the CA certificate Another Base64 encrypted certificate in PEM format as the next (index 1).
[{"op":"add","path":"/trusted-ca","value": [{"id":"CA-1","cert":"Base64 encrypted certificate in PEM format"},{"id":"CA-2","cert":"Another base64 encrypted certificate in PEM format"}]}]Press the Execute button.
Verify that the request was successful (Status code 204 No Content).
Add a certificate
In the Request body, enter the add operation referring to the trusted-ca property:
Enter the CA certificate Third base64 encrypted certificate in PEM format. Omitting the id will generate a unique id for this certificate.
[{"op":"add","path":"/trusted-ca/-","value": [{"cert":"Third base64 encrypted certificate in PEM format"}]}]Press the Execute button.
Verify that the request was successful (Status code 204 No Content).
Remove certificate
The remove operation removes either the entire array of CA certificates trusted-ca or a single element of the array addressed by an index i (trusted-ca/i). The certificate must exist for the operation to be successful.
If removing an element from an array, any elements above the specified index are shifted one position to the left.
Examples
Remove two certificates
In this example the certificates at index 1 and index 0 are removed.
In the Request body, enter the remove operation referring to the trusted-ca property:
[{"op":"remove","path":"/trusted-ca/1"},{"op":"remove","path":"/trusted-ca/0"}]Press the Execute button.
Verify that the request was successful (Status code 204 No Content).
Remove all certificates
In this example all certificates are removed.
In the Request body, enter the remove operation referring to the trusted-ca property:
Remove the certificates indexed with 1 and 0.[{"op":"remove","path":"/trusted-ca"}]Press the Execute button.
Verify that the request was successful (Status code 204 No Content).
Replace certificate
The replace operation replaces (updates) either the entire array of CA certificates (trusted-ca) or one specific element of the existing array addressed by an index i (trusted-ca/i) with a new one.
The target location must exist for the operation to be successful.
This operation is functionally identical to a remove operation followed immediately by an add operation at the same position with the replacement certificate.
Examples
Replace one certificate
In this example the certificate at index 1 is replaced with a new one.
In the Request body, enter the replace operation referring to the trusted-ca property:
[{"op":"replace","path":"/trusted-ca/1","value": {"id":"replaced-CA","cert":"Replacing Base64 encrypted certificate in PEM format"}}]Press the Execute button.
Verify that the request was successful (Status code 204 No Content).
Replace the id of a certificate
In this example the id of certificate at index 1 will be replaced.
In the Request body, enter the replace operation referring to the trusted-ca property:
[{"op":"replace","path":"/trusted-ca/1/id","value":"new-id"}]Press the Execute button.
Verify that the request was successful (Status code 204 No Content).
Test certificate
The test operation verifies that certain conditions on the certificate are met. This comes in handy to check that an operation is executed on the correct certificate. For example before removing a certificate at a certain index, a test on the id can be performed, so the right certificate is deleted.
The target location must exist for the operation to be successful.
Example
Test a certificate has a certain id
In this example the certificate at index 1 is tested to have a certain id.
In the Request body, enter the test operation referring to the trusted-ca property:
[{"op":"test","path":"/trusted-ca/1/id","value":"CA-2"}]Press the Execute button.
Verify that the request was successful (Status code 204 No Content).