cs:tcs-api-documentation.html

Strojový přístup ke službě TCS

Od 1. 7. 2018 je možné požádat o serverový certifikát TCS prostřednictvím API rozhraní. O jiné, než serverové certifikáty přes toto rozhraní žádat nelze.

Dokumentace API

Volání API je realizováno HTTP požadavkem s autorizací klientským certifikátem. Akceptovány jsou pouze certifikáty vydané v rámci služby TCS a to certifikáty robotové. Z výše uvedeného vyplývá, že uživatelé z organizací, které nejsou zapojeny ve federaci identit eduId.cz, a nemohou tudíž vydávat osobní certifikáty, bohužel nemohou TCS API využívat. Popis vydání robotového certifikátu naleznete zde.

Obecný popis volání funkcí API

Základní adresa pro volání aktuální verze API je

https://tcs.cesnet.cz/api/v2/certificate/<jméno_funkce>

Podle typu funkce je nutné odeslat požadavek jako GET, POST, PUT, nebo DELETE. Momentálně nejsou všechny z těchto typů požadavků rozhraním využity, funkce ale budou v budoucnu rozšiřovány a mohou být využity i dosud nevyužité typy volání rozhraní.

Jak vstupní, tak i vrácená data jsou ve formátu JSON. Pro volání, při kterém jsou předávána data, je tedy potřeba nastavit typ obsahu na application/json.

Příklad takového volání prostřednictvím aplikace curl:

curl \
  --cacert /etc/ssl/certs/geant_ev_rsa_ca_4.pem \
  --cacert /etc/ssl/certs/usertrust_rsa_certification_authority.pem \
  --cacert /etc/ssl/certs/Comodo_AAA_Services_root.pem \
  --cert muj_certifikat.crt \
  --key muj_klic.key \
  -d '{"prom1":"hod1", "prom2":"hod2"}' \
  -H "Content-Type: application/json" \
  -X POST \
  https://tcs.cesnet.cz/api/v2/certificate/funkce

Příklad vrácených dat:

{"status":"ok","id":1527791390}

Jak je z příkladu patrné, server tcs.cesnet.cz se prokazuje EV TCS certifikátem. Zatímco kořenový certifikát Comodo_AAA_Services_root.pem bývá standardní součástí většiny distribucí a v Linuxu se nachází právě ve výše uvedené cestě, mezilehlé certifikáty geant_ev_rsa_ca_4.pem a usertrust_rsa_certification_authority.pem je zapotřebí stáhnout např. z této stránky.

Funkce

Níže naleznete popis volání implementovaných funkcí rozhraní. Funkce mohou být v budoucnu doplňovány, u existujících funkcí bude zachována kompatibilita tak, aby nebyla narušena funkcionalita dříve implementovaných klientských systémů.

Podání žádosti o serverový certifikát

URL

https://tcs.cesnet.cz/api/v2/certificate/request

Metoda volání

POST

Argumenty žádosti
Klíč Uvedení Popis Povolené hodnoty / Příklad Implicitní hodnota
certificateRequest povinné žádost o certifikát
v BASE64 kódovaném formátu
PKCS10 (formát PEM)
—–BEGIN CERTIFICATE REQUEST—–

—–END CERTIFICATE REQUEST—–
-
certificateType volitelné profil (typ) certifikátu ov nebo es nebo ev
(běžné ověření;
gridový certifikát;
rozšířené ověření)
ov
certificateValidity volitelné doba platnosti certifikátu [roky] 1 nebo 2 1
subjectLanguage volitelné jazyková verze jména organizace
v předmětu certifikátu
cs nebo en nebo ac
(česká; anglická; ASCII)
cs
notificationMail volitelné e-mailová adresa pro upozornění
a informace o certifikátu
horymir.neumetelsky@cesnet.cz -
requesterPhone povinné telefon pro ověření žadatele
v mezinárodním formátu E.123
+420123456789 -

Poznámky:

  • DNS jména jsou brána z CSR žádosti; první uvedené jméno bude zároveň v poli CN= předmětu certifikátu
  • žolíkový certifikát musí mít v žádosti uvedeno pouze jedno DNS jméno - začínající hvězdičkou; Digicert automaticky doplní i jméno bez hvězdičky, tj. pro *.ezproxy.cesnet.cz bude doplněno ezproxy.cesnet.cz
  • pro eScience (gridový) certifikát je ignorován parametr certificateValidity - platnost je vždy nastavena na 13 měsíců
  • pro eScience (gridový) certifikát je ignorován parametr subjectLanguage - jazyk předmětu může být pouze anglický
  • pro EV certifikát je ignorován parametr subjectLanguage - jazyk předmětu může být pouze český
  • jako notificationMail může být uvedena i hromadná adresa, nebo více adres správců serveru
  • jako requesterPhone musí být uveden funkční telefon žadatele - telefon slouží pouze pro interní ověření žadatele správcem organizace a není zasílán certifikační autoritě
  • další informace, jako je jméno a příjmení žadatele, organizace a jeho e-mailová adresa jsou brány z informací uložených při vydání certifikátu, kterým se žadatel autorizoval k TCS API
  • vydat certifikát pro jinou organizaci, než je domovská organizace žadatele, nelze; pro vydání certifikátu pro jinou než domovskou organizaci je nutné použít formulářové WWW rozhraní
Výsledek volání
Klíč Výskyt Popis Možné hodnoty / Příklad
status vždy Výsledek volání funkce ok nebo error
id v případě úspěšného odeslání přidělené číslo žádosti 1527791390
message v případě chyby popis chybového stavu CSR could not be parsed.
Příklad volání

Požadavek:

POST /api/v2/certificate/request HTTP/1.1
Host: tcs.cesnet.cz
Content-Type: application/json

{
    "certificateRequest": "----BEGIN CERTIFICATE REQUEST-----...-----END CERTIFICATE REQUEST-----",
    "certificateType": "ev",
    "certificateValidity": 2,
    "notificationMail": [
        "admin1@myuniversity.cz",
        "admin2@myuniversity.cz",
        "server_admins@myuniversity.cz"
    ],
    "requesterPhone": "+420123456789"
}

Odpověď:

Status Code: 201
Content-Type: application/json

{
    "status": "ok",
    "id": 1527791390
}

Zjištění stavu žádosti o serverový certifikát

URL

https://tcs.cesnet.cz/api/v2/certificate/status/<id>

Metoda volání

GET nebo POST (je-li uveden volitelný argument)

Argumenty žádosti
Klíč Uvedení Popis Povolené hodnoty / Příklad Implicitní hodnota
id povinné, vždy v URL číslo ověřované žádosti 1527791390 -
stopNotifications volitelné žádost o zastavení aktuálních expiračních notifikací pro certifikáty se stejným CN v předmětu JSON boolean (true nebo false bez uvozovek) false

Výsledek volání

Klíč Výskyt Popis Možné hodnoty / Příklad
status vždy Výsledek volání funkce issued nebo added nebo accepted
nebo refused nebo revoked nebo error
(vydaný; čekající na schválení;
schválený - čekající na vydání;
zamítnutý; odvolaný; chyba
certificate v případě vydaného certifikátu vydaný certifikát ve formátu PEM —–BEGIN CERTIFICATE—–

—–END CERTIFICATE—–
message v případě chyby popis chybového stavu Invalid certificate id supplied.
Příklad volání

Požadavek:

GET /api/v2/certificate/status/1527791390 HTTP/1.1
Host: tcs.cesnet.cz

Odpověď:

Status Code: 400
Content-Type: application/json

{
    "status": "refused",
    "message": "Certificate request refused by administrator."
}

TCS API klient

Pokud si mechanizmus strojové žádosti o TCS certifikát nechcete implementovat sami, existuje již hotový klient, kterého lze (včetně dokumentace) stáhnout na GitHubu. Klient není z dílny pracovníků CESNET CA, autorem je kolega Jakub Jirůtka z ČVUT FIT. Veškeré náměty prosím směrujte na něj.

Poslední úprava:: 2024/02/14 12:12