====== 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 [[cs:tcs-robot-request.html|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/%%'' 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 [[https://tcs.cesnet.cz | 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 [[https://pki.cesnet.cz/cs/ch-tcs-ev-ssl-ca-4-crt-crl.html | 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 j**mé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/%%'' == 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 [[https://github.com/jirutka/cesnet-tcs-cli|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 [[jakub.jirutka@fit.cvut.cz|na něj]].