5.20.3 api cert csr

The /api/cert/csr function helps you administer the certificate signing requests (CSR) and work with them in the device.

The function is part of the System API system and requires the user to have the System – Control privilege for authentication if required.

The POST, GET, PUT and DELETE methods can be used for this function.
The POST method helps create a new CSR.
The GET method retrieves information on the CSRs stored in the device.
The PUT method uploads the certificate corresponding to the given CSR to the device.
The DELETE method deletes the CSR from the device.

POST Method

Request parameters for POST:

ParameterDescription
commmonNameA mandatory parameter (string) containing a fully qualified domain name (FQDN) of the device (e.g. verso01.internal, verso01.example.com).
sanMdnsAn optional parameter (number, {0,1}) defining whether or not SAN with the mDNS name will be included in the CSR (<hostname>.local). The default value is 1 (added).
sanIpAn optional parameter (number, {0,1}) defining whether or not SAN with the current IPv4 address will be included in the CSR (<hostname>.local). The default value is 1 (added).
algorithm

An optional parameter (string) defining the cryptographic algorithm for key generation. Applicable values: P-256, P-384, RSA-2048, RSA-3072. P-256 is the default value. Note: RSA-3072 is unavailable on the TI-ARM legacy platform.

id

An optional parameter (string) defining the unique identifier of the certificate. If this parameter is unset, the certificate is only identified by fingerprint.

  • It must start with @ and contain 1–40 characters [a–z][A–Z][0–9], „_“ a „-“.
countryAn optional parameter (string) defining the country (ISO 3166 Alpha-2, 2 uppercase letters, CZ, e.g.).
stateAn optional parameter (string) defining the state/province/region. Length: 1–128 characters. The \ character is not allowed.
localityAn optional parameter (string) defining the city/location. Length: 1–128 characters. The \ character is not allowed.
organizationAn optional parameter (string) defining the organization. Length: 1–64 characters. The \ character is not allowed.
organizationalUnitAn optional parameter (string) defining the organizational unit. Length: 1–64 characters. The \ character is not allowed.
email

An optional parameter (string) containing the e-mail address (e.g. user@example.com). It has to have a valid format and length of 1–254 characters.

Output parameters:

In the case of success, a PEM file containing the CSR generated is returned.

In the case of error, a reply in the application/json format is returned including the error description.

Example 1: CSR generation based on input parameters

POST /api/cert/csr commonName=2nipverso-0000010016.internal&algorithm=P-256&id=%40test&country=CZ&state=Hlavn%C3%AD+m%C4%9Bsto&locality=Praha&organization=2N&organizationalUnit=2N+OS&email=2nos%40example.com // request

-----BEGIN CERTIFICATE REQUEST-----
MIIBtjCCAVwCAQAwgZwxJjAkBgNVBAMMHTJuaXB2ZXJzby0wMDAwMDEwMDE2Lmlu
dGVybmFsMQswCQYDVQQGEwJDWjEXMBUGA1UECAwOSGxhdm7DrSBtxJtzdG8xDjAM
BgNVBAcMBVByYWhhMQswCQYDVQQKDAIyTjEOMAwGA1UECwwFMk4gT1MxHzAdBgkq
hkiG9w0BCQEWEDJub3NAZXhhbXBsZS5jb20wWTATBgcqhkjOPQIBBggqhkjOPQMB
BwNCAASlQVzGnOuQVl/6jVP3fI1Udy0nBFU5ll1iuWj1k+e6aUIXUhob6Ak+YYY2
W71VQYUOQKksZ4vmAO/ACzo+jJMGoF0wWwYJKoZIhvcNAQkOMU4wTDBKBgNVHREE
QzBBgh0ybmlwdmVyc28tMDAwMDAxMDAxNi5pbnRlcm5hbIIaMm5pcHZlcnNvLTAw
MDAwMTAwMTYubG9jYWyHBKwRAAMwCgYIKoZIzj0EAwIDSAAwRQIgDSeN22+Hl2eU
6Chm7kHYXE34AXpN7Lt3oVjDnWc4aMoCIQCVFCllfhIKtaa9/f0Qn0E7aX05VvJM
7cUMFqPyvTICMA==
-----END CERTIFICATE REQUEST----- // successful reply

{
  "success" : false,
  "error" : {
    "code" : 12,
    "param" : "locality",
    "description" : "invalid parameter value"
  }
} // error

GET Method

Request parameters for GET:

ParameterDescription
id

An optional parameter (string) identifying the CSR. The id parameter can contain a user defined ID or fingerprint (hash) of the CSR for which information is to be retrieved. If id is unset, the reply includes a full list of all the CSR certificates in the device.

  • The user defined id starts with @ and must be followed by 1 to 40 characters of the following set: [a–z], [A–Z], [0–9], „_“ a „-“.
  • Fingerprint is a hexadecimal value representing hash CSR.


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

ParameterDescription
fingerprintCSR fingerprint.

subject

A structure (dictionary) containing information on the subject (Subject Distinguished Name). DN is split into RDN items (if set): Common Name (CN), Organization (O), Organizational Unit (OU), Location (L), State (S), Country (C).

id

A string representing the internal CSR ID. The value is user defined. The CSR does not need to have an ID – it can only be identified using its fingerprint. In that case, it is not included in the reply.


Example 1: Display of all CSRs in the device

GET /api/cert/csr // request

{
  "success" : true,
  "result" : {
    "certificates" : [
      {
        "fingerprint" : "1b59cd8563e37f19f1b579b16943204cfe057c00",
        "subject" : {
          "CN" : "2nipverso.internal",
          "O" : "2N",
          "OU" : "2N OS"
        }
      },
      {
        "fingerprint" : "7900d3488bdbdae0560d64cfc1d3961e87205d5a",
        "subject" : {
          "CN" : "myverso.internal",
          "O" : "2N",
          "OU" : "2N OS App",
          "L" : "Praha",
          "S" : "Praha",
          "C" : "CZ"
        },
        "id" : "@myid"
      }
    ]
  }
} // reply


Example 2: Obtaining one CSR identified with an internal ID

GET /api/cert/csr?id=@myid // request

{
  "success" : true,
  "result" : {
    "certificates" : [
      {
        "fingerprint" : "7900d3488bdbdae0560d64cfc1d3961e87205d5a",
        "subject" : {
          "CN" : "myverso.internal",
          "O" : "2N",
          "OU" : "2N OS App",
          "L" : "Praha",
          "S" : "Praha",
          "C" : "CZ"
        },
        "id" : "@myid"
      }
    ]
  }
} // reply

PUT Method

Request parameters for PUT:

ParameterDescription
id

A mandatory parameter (string) identifying the CSR. The id parameter can contain a user defined CSR ID or fingerprint (hash).

  • The user defined id starts with @ and must be followed by 1 to 40 characters of the following set: [a–z], [A–Z], [0–9], „_“ a „-“.
  • Fingerprint is a hexadecimal value representing hash CSR.
blob-cert A mandatory parameter containing a certificate in the PEM format. The certificate must match the private key of the given CSR.


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

ParameterDescription
certificates[]An array with a list of certificates.
certificates[].fingerprintCertificate fingerprint.
certificates[].replacedFingerprint of the replaced CSR. It is included only if id was set as fingerprint.


Example 1: Certificate upload to the device. The certificate matches the CSR private key.

PUT /api/cert/csr?id=9623fa25e414aa930ed22348a22d04a4c4fda26c // request

{
  "success" : true,
  "result" : {
    "certificates" : [
      {
        "fingerprint": "9623fa25e414aa930ed22348a22d04a4c4fda26b"
        "replaced": "9623fa25e414aa930ed22348a22d04a4c4fda26c"
      }
    ]
  }
} // reply 

{
  "success" : false,
  "error" : {
    "code" : 12,
    "param" : "blob-cert",
    "description" : "private key mismatch",
    "data" : "pk_mismatch"
  }
} // reply

DELETE Method

Request parameters for DELETE:

ParameterDescription
id

A mandatory parameter (string) identifying the CSR. The id parameter can contain a user defined CSR ID, internal ID or fingerprint (hash).

  • It starts with @ and must be followed by 1 to 40 characters of the following set: [a–z], [A–Z], [0–9], „_“ a „-“.
  • A hexadecimal value representing hash CSR.


Example 1: Deleting CSR according to its fingerprint (success/error examples)

DELETE /api/cert/csr?id=4deea7060d80babf1643b4e0f0104c82995075b7 // request

{
  "success" : true
} // reply

{
  "success" : false,
  "error" : {
    "code" : 12,
    "param" : "id",
    "description" : "certificate not found",
    "data": "cert_not_found"
  }
} // reply