Rozdíly
Zde můžete vidět rozdíly mezi vybranou verzí a aktuální verzí dané stránky.
| Obě strany předchozí revize Předchozí verze Následující verze | Předchozí verze | ||
| cs:tcs-api-documentation.html [2018/07/24 11:34] – [Strojový přístup ke službě TCS] dans@cesnet.cz | cs:tcs-api-documentation.html [2025/05/22 09:33] (aktuální) – odstraněno Ing. Daniel Studený | ||
|---|---|---|---|
| Řádek 1: | Řádek 1: | ||
| - | ====== 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 **osobní** a **robotové**. | ||
| - | Z výše uvedeného vyplývá, že uživatelé z organizací, | ||
| - | |||
| - | ==== Obecný popis volání funkcí API ==== | ||
| - | |||
| - | Základní adresa pro volání aktuální verze API je | ||
| - | |||
| - | '' | ||
| - | |||
| - | 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/ | ||
| - | |||
| - | Příklad takového volání prostřednictvím aplikace **curl**: | ||
| - | |||
| - | < | ||
| - | curl \ | ||
| - | --cacert / | ||
| - | --cacert / | ||
| - | --cert muj_certifikat.crt \ | ||
| - | --key muj_klic.key \ | ||
| - | -d ' | ||
| - | -H " | ||
| - | -X POST \ | ||
| - | https:// | ||
| - | </ | ||
| - | |||
| - | Příklad vrácených dat: | ||
| - | |||
| - | < | ||
| - | {" | ||
| - | </ | ||
| - | |||
| - | Jak je z příkladu patrné, server [[https:// | ||
| - | 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 [[https:// | ||
| - | |||
| - | ==== Funkce ==== | ||
| - | |||
| - | Níže naleznete popis volání implementovaných funkcí rozhraní. Funkce mohou být v budoucnu doplňovány, | ||
| - | dříve implementovaných klientských systémů. | ||
| - | |||
| - | === Podání žádosti o serverový certifikát === | ||
| - | |||
| - | == URL == | ||
| - | '' | ||
| - | |||
| - | == Metoda volání == | ||
| - | '' | ||
| - | |||
| - | == Argumenty žádosti == | ||
| - | |||
| - | ^Klíč | ||
| - | | **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; | ||
| - | | **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 | - | | ||
| - | |||
| - | <wrap em> | ||
| - | * **DNS jména** jsou brána z **CSR žádosti**; | ||
| - | * **žolíkový certifikát** musí mít v žádosti uvedeno pouze jedno DNS jméno - začínající hvězdičkou; | ||
| - | * 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, | ||
| - | * vydat certifikát pro **jinou organizaci**, | ||
| - | |||
| - | == Výsledek volání == | ||
| - | |||
| - | ^Klíč ^Výskyt ^Popis | ||
| - | | **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 / | ||
| - | Host: tcs.cesnet.cz | ||
| - | Content-Type: | ||
| - | |||
| - | { | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | admin1@myuniversity.cz, | ||
| - | admin2@myuniversity.cz, | ||
| - | server_admins@myuniversity.cz | ||
| - | ], | ||
| - | " | ||
| - | } | ||
| - | </ | ||
| - | |||
| - | Odpověď: | ||
| - | < | ||
| - | Status Code: 201 | ||
| - | Content-Type: | ||
| - | |||
| - | { | ||
| - | " | ||
| - | " | ||
| - | } | ||
| - | </ | ||
| - | |||
| - | === Zjištění stavu žádosti o serverový certifikát === | ||
| - | |||
| - | == URL == | ||
| - | '' | ||
| - | |||
| - | == Metoda volání == | ||
| - | '' | ||
| - | |||
| - | == Argumenty žádosti == | ||
| - | |||
| - | ^Klíč | ||
| - | | **id** | povinné | číslo ověřované žádosti | 1527791390 | - | | ||
| - | |||
| - | === Výsledek volání === | ||
| - | |||
| - | ^Klíč ^Výskyt ^Popis | ||
| - | | **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í; | ||
| - | | **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 / | ||
| - | Host: tcs.cesnet.cz | ||
| - | </ | ||
| - | |||
| - | Odpověď: | ||
| - | < | ||
| - | Status Code: 400 | ||
| - | Content-Type: | ||
| - | |||
| - | { | ||
| - | " | ||
| - | " | ||
| - | } | ||
| - | </ | ||
| - | |||