5.20.1 api cert ca

The /api/cert/ca function helps you administer the CA certificates.

The function is part of the System API service and the user must be assigned the System Control privilege for authentication if required.

The GET, PUT or DELETE method can be used for this function. The GET method returns information about one or more CA certificates on the device. The PUT method uploads the given CA certificates to the device. The DELETE method deletes a single CA certificate from the device.

GET method

Request parameters for GET:

Parameter	Description
id	An optional string value identifying a CA certificate. The id value is user defined id, internal id or certificate fingerprint (hash). If id is not completed, the reply includes a long list of all user certificates in the device.

The reply is in the application/json format and can include the following parameters:

Parameter	Description
fingerprint	A fingerprint (hash) of the certificate.
subjet,issuer	A dictionary which splits information for the Subject or the Issuer: Common Name (CN), Organization (O), Organization Unit (OU), Location (L), State (S), Country (C).
id	A string value of the previously specified certificate identification.
startDate	A date identifying when this certificate started to be valid.
endDate	A date identifying when this certificate will cease to be valid.
protected	A boolean value indicating whether the certificate is protected and therefore cannot be deleted from the device. Internal certificates with id starting with "#" are protected and cannot be deleted.
systemUseOnly	A boolean value indicating whether the certificate should be selectable by the user as a certificate for any service. If it is `true`, the certificate is not shown in the selection list.

Example 1: List of all the certificates in the device

GET /api/cert/ca							//request
{											//response
  "success" : true,
  "result" : {
    "certificates" : [
      {
        "fingerprint" : "4deea7060d80babf1643b4e0f0104c82995075b7",
        "subject" : {
          "CN" : "Thawte RSA CA 2018",
          "O" : "DigiCert Inc",
          "OU" : "www.digicert.com",
          "C" : "US"
        },
        "issuer" : {
          "CN" : "DigiCert Global Root CA",
          "O" : "DigiCert Inc",
          "OU" : "www.digicert.com",
          "C" : "US"
        },
        "startDate" : "2017-11-06T12:23:52Z",
        "endDate" : "2027-11-06T12:23:52Z",
        "allowRemove" : true
      },
      {
        "fingerprint" : "a8985d3a65e5e5c4b2d7d66d40c6dd2fb19c5436",
        "subject" : {
          "CN" : "DigiCert Global Root CA",
          "O" : "DigiCert Inc",
          "OU" : "www.digicert.com",
          "C" : "US"
        },
        "issuer" : {
          "CN" : "DigiCert Global Root CA",
          "O" : "DigiCert Inc",
          "OU" : "www.digicert.com",
          "C" : "US"
        },
        "startDate" : "2006-11-10T00:00:00Z",
        "endDate" : "2031-11-10T00:00:00Z",
        "protected" : false,
        "id" : "#my2n-utility",
        "systemUseOnly" : true
      }
    ]
  }
}

Example 2: Get one certificate identified by id

GET /api/cert/ca?id=#my2n-utility			//request
{											//response
  "success" : true,
  "result" : {
    "certificates" : [
      {
        "fingerprint" : "a8985d3a65e5e5c5b2d7d66d40c6dd2fb19c5436",
        ...
        "id" : "#my2n-utility",
        ...
      }
    ]
  }
}

PUT method

If one and the same certificate is already on the device, it is overwritten. It is possible to upload multiple certificates in one PEM formatted file. It can contain any blocks, only certificates are processed. If any of the included certificates fails to load, none are saved and the error code is returned.

Request parameters for PUT:

Parameter

Description

blob-cert

A mandatory blob-cert contains the certificate in the DER or PEM format.

id

An optional string of a unique user defined identification of a certificate. The user defined id starts with the '@' character. It must consist of 1-40 characters of the following set: [a-z][A-Z][0-9], _ and -.

If a new certificate with the same id is uploaded, the original certificate is overwritten.

The id must not be specified when uploading multiple certificates in one file.

The reply is in the application/json format and includes:

Parameter	Description
fingerprint	A fingerprint (hash) of a certificate.
replaced	A fingerprint of a replaced certificate.

Example

PUT /api/cert/ca							//request
{											// response
  "success" : true,
  "result" : {
    "certificates" : [
      {
        "fingerprint": "9623fa25e414aa930ed22348a22d04a4c4fda26b"
      },
      {
        "fingerprint": "9623fa25e414aa930ed22348a22d04a4c4fda26b"
        "replaced": "9623fa25e414aa930ed22348a22d04a4c4fda26c"
      }
    ]
  }
}
----	
{											//response
  "success" : false,
  "error" : {
    "code" : 12,
    "param" : "blob-cert",
    "description" : "invalid certificate",
    "data" : "invalid_cert"
  }
}

DELETE method

Request parameters for DELETE:

Parameter	Description
id	A mandatory string value identifying a CA certificate. The id value is user defined id, internal id or certificate fingerprint (hash). Internal certificates with id starting with "#" are protected and cannot be deleted.

The reply is in the application/json format.

Example:

DELETE /api/cert/ca?fingerprint=a163b11215a30f08603fd85c314327e275772b00				//request
{
  "success" : true																		//response
}
-----
{																						//response
  "success" : false,
  "error" : {
    "code" : 12,
    "param" : "id",
    "description" : "certificate not found",
    "data": "cert_not_found"
  }
}