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.

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 osobní a 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.

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

https://tcs-dev.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/TERENA_SSL_CA_3.pem \
  --cacert /etc/ssl/certs/DigiCert_High_Assurance_EV_Root_CA.pem \
  --cert muj_certifikat.crt \
  --key muj_klic.key \
  -d '{"prom1":"hod1", "prom2":"hod2"}' \
  -H "Content-Type: application/json" \
  -X POST \
  https://tcs-dev.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 DigiCert_High_Assurance_EV_Root_CA.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át TERENA_SSL_High_Assurance_CA_3.pem je zapotřebí stáhnout např. z tohoto odkazu.

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ů.

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

POST

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í

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
}

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

GET

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."
}