5.20.3 api cert csr

Funkce /api/cert/csr slouží ke správě požadavků na certifikát (CSR) a k práci s nimi v zařízení.

Funkce je součástí služby Systém API a v případě použití autentizace je nutné, aby uživatel měl přiřazené oprávnění Systém – řízení.

U této funkce lze použít metody POST, GET, PUT a DELETE.
Metoda POST slouží k vytvoření nového CSR.
Metoda GET slouží k získání informací o CSR uložených v zařízení.
Metoda PUT slouží k nahrání certifikátu odpovídajícího danému CSR do zařízení.
Metoda DELETE slouží k odstranění CSR ze zařízení.

Metoda POST

Parametry požadavku POST:

ParametrPopis
commmonNamePovinný parametr (string) obsahující plně kvalifikovaný název domény (FQDN) zařízení (např. verso01.internal, verso01.example.com).
sanMdnsVolitelný parametr (number, {0,1}), který určuje, zda bude do CSR zahrnut SAN s mDNS názvem (<hostname>.local). Výchozí hodnota je 1 (přidáno).
sanIpVolitelný parametr (number, {0,1}), který určuje, zda bude do CSR zahrnut SAN s aktuální IPv4 adresou. Výchozí hodnota je 1 (přidáno).
algorithm

Volitelný parametr (string) určující kryptografický algoritmus pro generování klíčů. Povolené hodnoty: P-256, P-384, RSA-2048, RSA-3072. Výchozí je P-256. Poznámka: RSA-3072 není dostupné na platformě TI-ARM legacy.

id

Volitelný parametr (string) určující unikátní identifikátor certifikátu. Pokud není zadán, certifikát je identifikován pouze otiskem (fingerprintem).

  • Musí začínat znakem @ a obsahovat 1–40 znaků [a–z][A–Z][0–9], „_“ a „-“.
countryVolitelný parametr (string) určující zemi (ISO 3166 Alpha-2, 2 velká písmena, např. CZ).
stateVolitelný parametr (string) určující stát/provincii/region. Délka 1–128 znaků. Znak \ není povolen.
localityVolitelný parametr (string) určující město/lokalitu. Délka 1–128 znaků. Znak \ není povolen.
organizationVolitelný parametr (string) určující název organizace. Délka 1–64 znaků. Znak \ není povolen.
organizationalUnitVolitelný parametr (string) určující oddělení v organizaci. Délka 1–64 znaků. Znak \ není povolen.
email

Volitelný parametr (string) obsahující e-mailovou adresu (např. user@example.com). Musí mít platný formát a délku 1–254 znaků.

Výstupní parametry:

Při úspěchu je vrácen PEM soubor obsahující vygenerované CSR.

V případě chyby je vrácena odpověď ve formátu application/json obsahující popis chyby.

Příklad 1: Vygenerování CSR na základě vstupních parametrů.

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 // požadavek

-----BEGIN CERTIFICATE REQUEST-----
MIIBtjCCAVwCAQAwgZwxJjAkBgNVBAMMHTJuaXB2ZXJzby0wMDAwMDEwMDE2Lmlu
dGVybmFsMQswCQYDVQQGEwJDWjEXMBUGA1UECAwOSGxhdm7DrSBtxJtzdG8xDjAM
BgNVBAcMBVByYWhhMQswCQYDVQQKDAIyTjEOMAwGA1UECwwFMk4gT1MxHzAdBgkq
hkiG9w0BCQEWEDJub3NAZXhhbXBsZS5jb20wWTATBgcqhkjOPQIBBggqhkjOPQMB
BwNCAASlQVzGnOuQVl/6jVP3fI1Udy0nBFU5ll1iuWj1k+e6aUIXUhob6Ak+YYY2
W71VQYUOQKksZ4vmAO/ACzo+jJMGoF0wWwYJKoZIhvcNAQkOMU4wTDBKBgNVHREE
QzBBgh0ybmlwdmVyc28tMDAwMDAxMDAxNi5pbnRlcm5hbIIaMm5pcHZlcnNvLTAw
MDAwMTAwMTYubG9jYWyHBKwRAAMwCgYIKoZIzj0EAwIDSAAwRQIgDSeN22+Hl2eU
6Chm7kHYXE34AXpN7Lt3oVjDnWc4aMoCIQCVFCllfhIKtaa9/f0Qn0E7aX05VvJM
7cUMFqPyvTICMA==
-----END CERTIFICATE REQUEST----- // úspěšná odpověď

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

Metoda GET

Parametry požadavku GET:

ParametrPopis
id

Volitelná hodnota (string) identifikující CSR. Parametr id může obsahovat uživatelsky definované ID nebo otisk (hash) CSR, pro které mají být získány informace. Pokud id není zadáno, odpověď obsahuje kompletní seznam všech CSR certifikátů v zařízení.

  • Uživatelsky definované id začíná znakem „@“ a musí být následováno 1 až 40 znaky z množiny: [a–z], [A–Z], [0–9], „_“ a „-“.
  • Otisk (fingerprint) je hexadecimální hodnota představující hash CSR.


Odpověď je ve formátu application/json a může obsahovat následující parametry:

ParametrPopis
fingerprintOtisk CSR.

subject

Struktura (dictionary) obsahující informace o subjektu (Subject Distinguished Name). DN je rozdělen na jednotlivé RDN položky (pokud jsou nastaveny): Common Name (CN), Organization (O), Organizational Unit (OU), Location (L), State (S), Country (C).

id

Řetězec představující interní ID CSR. Hodnota je definována uživatelem. CSR nemusí mít ID – může být identifikováno pouze svým otiskem. V takovém případě se v odpovědi neuvádí.


Příklad 1: Zobrazení všech CSR v zařízení

GET /api/cert/csr // požadavek

{
  "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"
      }
    ]
  }
} // odpověď


Příklad 2. Získání jednoho CSR identifikovaného interním ID

GET /api/cert/csr?id=@myid // požadavek

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

Metoda PUT

Parametry požadavku PUT:

ParametrPopis
id

Povinný parametr (string) identifikující CSR. Parametr id může obsahovat uživatelsky definované ID nebo otisk (hash) CSR.

  • Uživatelsky definované id musí začínat znakem „@“ a obsahovat 1–40 znaků z množiny: [a–z], [A–Z], [0–9], „_“ a „-“.
  • Otisk (fingerprint) je hexadecimální hodnota představující hash CSR.
blob-cert Povinný parametr obsahující certifikát ve formátu PEM. Certifikát musí odpovídat privátnímu klíči daného CSR.


Odpověď je ve formátu application/json a může obsahovat následující parametry:

ParametrPopis
certificates[]Pole obsahující seznam certifikátů.
certificates[].fingerprintOtisk certifikátu.
certificates[].replacedOtisk nahrazeného CSR. Uvede se pouze v případě, že id bylo zadáno jako fingerprint.


Příklad 1: Nahrání certifikátu do zařízení. Certifikát odpovídá privátnímu klíči daného CSR.

PUT /api/cert/csr?id=9623fa25e414aa930ed22348a22d04a4c4fda26c // požadavek

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

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

Metoda DELETE

Parametry požadavku DELETE:

ParametrPopis
id

Povinný parametr (string) identifikující CSR. Parametr id může obsahovat uživatelsky definované ID, interní ID nebo otisk (hash).

  • Musí začínat znakem „@“ a obsahovat 1–40 znaků z množiny: [a–z], [A–Z], [0–9], „_“ a „-“.
  • Hexadecimální hodnota představující hash CSR.


Příklad 1. Odstranění CSR podle jeho otisku (příklady úspěchu a chyby)

DELETE /api/cert/csr?id=4deea7060d80babf1643b4e0f0104c82995075b7 // požadavek

{
  "success" : true
} // odpověď

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