- PDF Stažení zdarma

Transkript

1 Co je to SAPI SAPI je zkratka pro SSLS API provozované společností Alpiro na adrese. Toto API (Application Programming Interface) je komunikační rozhraní pro interakci se systémem pro správu SSL certifikátů. Mezi hlavní funkce SAPI patří mj.: Aktivace / prodloužení SSL certifikátů a s tím spojené operace Zjištění stavu SSL certifikátů Stažení SSL certifikátů Mezi přednosti SAPI patří: ü Srozumitelnost odpovědi jsou volitelně ve formátu JSON nebo XML ü Univerzalita nezáleží na platformě ani na programovacím jazyku, které používáte ü Stabilita SAPI je stabilní, komunikace je plynulá a zpracování dotazů rychlé Komunikace se SAPI Komunikace funguje na principu dotaz è odpověď, tzn.: odešlete dotaz, SAPI ho zpracuje a vrátí odpověď. Dotazy Dotazy jsou přijímány metodou GET a/nebo POST. Pro každý typ dotazu je vyhrazena vlastní URL adresa, která je v následujícím tvaru: <token> je jednoznačný identifikátor partnera, je vždy stejný a zaručuje, že dotaz odesílá ten či onen partner <typ_dotazu> definuje, jaký typ dotazu má SAPI zpracovat (např. aktivovat nový SSL certifikát), více níže Všechny dotazy musí být bezpodmínečně provedeny přes zabezpečený HTTPS protocol. Dotazy přes nezabezpečený HTTP protocol nebudou zpracovány (bude vrácena odpověď s iserror = true). Odpovědi Odpovědi jsou odesílány zpět implicitně ve formátu JSON, neboť je efektivnější a šetří přenesená data. Preferujete- li raději odpověď ve formátu XML, stačí za URL adresu v dotazu přidat /xml, tj.: Každá odpověď obsahuje vždy alespoň 3 části initial, auth a errors. Podle typu dotazu pak další části specifické pro daný dotaz. Jejich vysvětlení najdete v následující tabulce: Parametr initial.responsetime Čas ve který byla žádost zpracována, je uveden v tzv. UNIX čase (počet vteřin od :00 UTC) 1

2 initial.responseid auth.userid auth.username auth.creditbalance errors.iserror errors.errormessage Jednoznačný identifikátor odpovědi, můžete uložit pro řešení případných dotazů. Vaše interní ID pro SAPI Příslušný účet na Stav kreditu v Kč před zpracováním dotazu. Pokud např. aktivujete nový SSL certifikát, bude výše kreditu snížena o jeho příslušnou cenu. Pokud při zpracování dotazu došlo k chybě, je hodnota true. Je- li vše v pořádku a dotaz byl zpracován bez chyby, je hodnota false. Je- li iserror false, pak je hodnota prázdná. Pokud hodnota iserror je true, je zde uveden popis nastalé chyby. Typy dotazů /csr /authlist /neworder /orderstatus /download Ověří validitu a integritu CSR žádosti a správnost obsažených údajů, zda se jedná o CSR žádost pro standardní nebo wildcard certifikát a také zda CSR žádost neobsahuje některá rozšíření, která certifikační autorita nepovoluje. Vrátí seznam e- mailových adres, které je možné použít pro autorizaci. Autorizace je nutná pro ověření kontroly nad doménou, pro niž se žádá o vystavení SSL certifikátu. Každá certifikační autorita povoluje různé tvary e- mailových adres, a tudíž je vhodné nejprve zjistit, na kterou e- mailovou adresu může certifikační autorita zaslat autorizační e- mail. Vytvoří žádost o nový SSL certifikát nebo žádost o prodloužení existujícího SSL certifikátu. Pro úspěšné zpracování tohoto dotazu je nutné mít na svém SSLS účtu na dostatečný kredit. Vrátí informace o aktuálním stavu objednávky SSL certifikátu, např. zda- li byl již vystaven či zda stále čeká na ověření certifikační autoritou. Stáhne vystavený SSL certifikát (implicitně formát ZIP zakódovaný pomocí standardu BASE64_ENCODE). 2

3 /csr Vrátí informace o CSR žádosti jednak informace v CSR uvedené a také prověří, zda je CSR žádost v pořádku a použitelná pro aktivaci/prodloužení SSL certifikátu v dotazu na /neworder. SAPI take prověří, zda se jedná o CSR žádost o standardní SSL certifikát pro jednu doménu nebo o CSR žádost pro wildcard SSL certifikát. Dotaz URL adresa dotazu: JSON: XML: Parametry dotazu: Parametr Metoda Povinné csr POST Ano Obsah CSR žádosti productcode POST Ano Kód identifikující SSL certifikát (viz. tabulka productcode na konci dokumentu), pro který má být ověřena správnost CSR žádosti Odpověď Parametr csrdata.cn csrdata.orgcountry csrdata.orgstate csrdata.orgcity csrdata.orgname csrdata.orgunit csrstatus.validcn csrstatus.badexts csrstatus.wildcard Common Name, tj. doména, pro kterou je CSR žádost vygenerována. Kód státu/země žadatele podle RFC 3066, např. CZ (Česká republika), SK (Slovensko), US (Spojené Státy Americké), DE (Německo) atd. Kraj nebo okres, může být uveden název státu/země žadatele. Nesmí obsahovat českou diakritiku. Město sídla nebo trvalého pobytu či místa podnikání žadatele. Nesmí obsahovat českou diakritiku. Firma žadatele (název společnosti nebo celé jméno fyzické osoby). Nesmí obsahovat českou diakritiku. Organizační složka. Nesmí obsahovat českou diakritiku. Uvedené Common Name v csrdata.cn je validní (true) nebo chybné (false) Obsahuje- li CSR žádost nepovolená rozšíření, pak je hodnota true (CSR žádost nelze použít). Je- li vše v pořádku, pak je hodnota false. Hodnota je true, jedná- li se o CSR žádost vystavenou pro vystavení wildcard SSL certifikátu (*.example.com). Je- li hodnota false, je CSR žádost určena pro vystavení standardního SSL certifikátu pro jedno doménové jméno ( Příklad odpovědi (JSON): { "initial":{ "responsetime":" ", 3

4 "responseid":"9b887691d0cde6bc72e663a e4069f17d2#3413" "auth":{ "userid":"1234", "creditbalance":" " "csrdata":{ "cn":" "orgcountry":"cz", "orgstate":"praha", "orgcity":"praha", "orgname":"alpiro s.r.o.", "orgunit":"it Security", "csrstatus":{ "validcn":"true", "badexts":"false", "wildcard":"false" "errors":{ "iserror":"false", "errormessage":"" Příklad odpovědi (XML): <SAPI> <initial> <responsetime> </responsetime> <responseid>1a7dc24da938010f2fadc8c6f3dda683bd5af166#3453</responseid> </initial> <auth> <userid>1234</userid> <creditbalance> </creditbalance> </auth> <csrdata> <cn> <orgcountry>cz</orgcountry> <orgstate>praha</orgstate> <orgcity>praha</orgcity> <orgname>alpiro s.r.o.</orgname> <orgunit>it Security</orgUnit> </csrdata> <csrstatus> <validcn>true</validcn> <badexts>false</badexts> <wildcard>false</wildcard> </csrstatus> <errors> <iserror>false</iserror> <errormessage/> </errors> </SAPI> 4

5 /authlist Authlist vrátí seznam e- mailových adres, které certifikační autorita pro daný produkt akceptuje pro zaslání autorizačního e- mailu. Jednu z těchto e- mailových adres je nutné uvést při aktivaci/prodloužení SSL certifikátů v dotazu na /neworder. Tento dotaz nelze použít pro produkty certifikační autority Trustwave! Certifikační autorita Trustwave ověřuje pouze e- mailovou adresu u kontaktu vlastníka domény ve veřejném WHOIS. Dotaz URL adresa dotazu: JSON: XML: Parametry dotazu: Parametr Metoda Povinné csr POST Ano Obsah CSR žádosti productcode POST Ano Kód identifikující SSL certifikát (viz. tabulka productcode), pro který má být vrácen seznam e- mailových adres cn POST Ano Common Name Odpověď Parametr authlist. x Seznam e- mailových adres, ze kterého může být vybrána jedna pro zaslání autorizačního e- mailu certifikační autoritou. Znakem X se rozumí pořadové číslo začínající od 0 do n. Na prvním místě je zpravidla e- mailová adresa uvedená u kontaktu vlastníka domény ve veřejném WHOIS. Příklad odpovědi (JSON): { "initial":{ "responsetime":" ", "responseid":"9b887691d0cde6bc72e663a e4069f17d2#3413" "auth":{ "userid":"1234", "username":"info@ssls.cz", "creditbalance":" " "authlist":{ "mail0":"owner@whoisexample.org", "mail1":"admin@ "mail2":"administrator@ "mail3":"hostmaster@ "mail4":"postmaster@ "mail5":"webmaster@ 5

6 "errors":{ "iserror":"false", "errormessage":"" Příklad odpovědi (XML): <SAPI> <initial> <responsetime> </responsetime> <responseid>1a7dc24da938010f2fadc8c6f3dda683bd5af166#3453</responseid> </initial> <auth> <userid>1234</userid> <creditbalance> </creditbalance> </auth> <authlist> </authlist> <errors> <iserror>false</iserror> <errormessage/> </errors> </SAPI> 6

7 /neworder 7 Neworder provede novou objednávku SSL certifikátu buď nového nebo prodlouží stávající SSL certifikát. V obou případech je však postup stejný jako při aktivaci nového SSL certifikátu. UPOZORNĚNÍ: Pro úspěšné provedení dotazu /neworder je nutné mít na svém účtu na dostatečný kredit. Dotaz URL adresa dotazu: JSON: XML: Parametry dotazu: Parametr Metoda Povinné productcode POST Ano Kód identifikující SSL certifikát (viz. tabulka productcode na konci dokumentu), který chcete aktivovat nebo prodloužit. validity POST Ne Délka platnosti SSL certifikátu v letech (1 = 1 rok, 5 = 5 let). Maximální platnost každého SSL certifikátu se liší některé SSL certifikáty mohou být vystaveny na max. 4, 3 nebo jen 2 roky (např. EV certifikáty). Pokud není nastaveno, výchozí hodnotou je 1 tedy 1 rok. cn POST Ano Common Name. Hodnota musí být stejná jako Common Name v CSR žádosti (lze zjistit pomocí dotazu na /csr). authmail POST Ano E- mailová adresa, na kterou certifikační autorita pošle autorizační e- mail. Seznam možných e- mailových adres získáte dotazem na /authlist csr POST Ano CSR žádost, včetně prvního a posledního řádku s --- pomlčkami servertype POST Ne Typ serveru, na který bude vystavený SSL certifikát nainstalován. Výchozí hodnota je apachessl (pro Apache ModSSL). Kompletní seznam najdete v tabulce servertype (na konci dokumentu). isrenewal POST Ne Pro prodloužení stávajícího SSL certifikátu nastavte hodnotu true. Výchozí hodnota je false (bude vystaven nový SSL certifikát). orgname POST Ano Firma žadatele (název společnosti nebo celé jméno fyzické osoby). Musí být stejné jako csrdata.orgname z dotazu na /csr. Nesmí obsahovat českou diakritiku. orgunit POST Ano Organizační složka. Musí být stejná jako csrdata.orgunit z dotazu na /csr. Nesmí obsahovat českou diakritiku. orgcity POST Ano Město sídla nebo trvalého pobytu či místa podnikání žadatele. Hodnota musí být stejná jako csrdata.orgunit z dotazu na

8 /csr. Nesmí obsahovat českou diakritiku. orgstate POST Ano Kraj nebo okres, může být uveden název státu/země žadatele. Hodnota musí být stejná jako csrdata.orgcity z dotazu na /csr. Nesmí obsahovat českou diakritiku. orgcountry POST Ano Kód státu/země žadatele podle RFC 3066, např. CZ (Česká republika), SK (Slovensko), US (Spojené Státy Americké), DE (Německo) atd. Hodnota musí být stejná jako csrdata.orgcountry z dotazu na /csr orgstreet POST Ano Ulice a č.p./č.o. adresy sídla, trvalého pobytu nebo místa podnikání žadatele o SSL certifikát. Nesmí obsahovat českou diakritiku. orgzip POST Ano PSČ adresy sídla, trvalého pobytu nebo místa podnikání žadatele o SSL certifikát. orgphone POST Ano Hlavní telefonní číslo žadatele o SSL certifikát v mezinárodním formátu, např nebo jen Odpověď Parametr order.orderid order.vendorid order.product order.servertype order.price Jednoznačný identifikátor objednávky SSL certifikátu. Tento identifikátor je nutný pro pozdější stažení SSL certifikátu dotazem na /download a pro zjištění stavu SSL certifikátu dotazem na /orderstatus. ID, resp. interní číslo objednávky certifikační autority. Toto číslo je potřeba uvést při komunikaci s technickou podporou certifikační autority. Název SSL certifikátu Typ serveru, na který bude vystavený SSL certifikát nainstalován. Pokud nebylo v dotazu nastaveno, výchozí hodnotou je apachessl (pro Apache ModSSL). Kompletní seznam najdete v tabulce servertype (na konci dokumentu). Celková cena objednávky za aktivaci nebo prodloužení SSL certifikátu na období uvedené ve validity v dotazu. O tuto částku byl snížen kredit. Připomínáme, že hodnota auth.creditbalance v odpovědi uvádí stav kreditu před zpracováním objednávky. Příklad odpovědi (JSON): { "initial":{ "responsetime":" ", "responseid":"9b887691d0cde6bc72e663a e4069f17d2#3413" "auth":{ "userid":"1234", "username":"info@ssls.cz", "creditbalance":" " 8

9 "order":{ "orderid":"p1019u r9492", "vendorid":" ", "product":"comodo PositiveSSL Certificate", "servertype":"apachessl", "price":259 "errors":{ "iserror":"false", "errormessage":"" Příklad odpovědi (XML): <SAPI> <initial> <responsetime> </responsetime> <responseid>1a7dc24da938010f2fadc8c6f3dda683bd5af166#3453</responseid> </initial> <auth> <userid>1234</userid> <creditbalance> </creditbalance> </auth> <order> <orderid>p1019u r9492</orderid> <vendorid> </vendorid> <product>comodo PositiveSSL Certificate</product> <servertype>apachessl</servertype> <price>259</price> </order> <errors> <iserror>false</iserror> <errormessage/> </errors> </SAPI> 9

10 /orderstatus Vrátí informace o aktuálním stavu objednávky SSL certifikátu, např. zda- li byl již vystaven či zda stále čeká na ověření certifikační autoritou, pro kterou doménu a typ serveru má být či již je SSL certifikát vystaven, na kterou e- mailovou adresu certifikační autorita odeslala autorizační e- mail apod. Dotaz URL adresa dotazu: JSON: XML: Parametry dotazu: Parametr Metoda Povinné orderid POST Ano Jednoznačný identifikátor objednávky SSL certifikátu. Tato hodnota byla získána dotazem na /neworder v odpovědi order.orderid Odpověď Parametr order.cn order.vendorid order.product order.status Common Name, pro které je či bude SSL certifikát vystaven, např. nebo *.example.com (wildcard SSL certifikát) ID, resp. interní číslo objednávky certifikační autority. Toto číslo je potřeba uvést při komunikaci s technickou podporou certifikační autority. Název SSL certifikátu Stav objednávky SSL certifikátu. Možné hodnoty jsou: Pending SSL certifikát čeká na schválení, ještě nebyl vystaven Active SSL certifikát je aktivní a můžete stáhnout dotazem na /download Cancelled SSL certifikát byl revokován (zrušen) a je neplatný Expired Platnost SSL certifikátu vypršela a je neplatný order.vendormessage Aktuální stav SSL certifikátu v závislosti na konkrétním stavu a konkrétním produktu SSL certifikátu order.authmail order.servertype Příklad odpovědi (JSON): { "initial":{ E- mailová adresa, na kterou certifikační autorita pošle nebo již zaslala autorizační e- mail. Typ serveru, na který bude vystavený SSL certifikát nainstalován. Pokud nebylo v dotazu na /neworder nastaveno, výchozí hodnotou je apachessl (pro Apache ModSSL). Kompletní seznam najdete v tabulce servertype (na konci dokumentu). 10

11 "responsetime":" ", "responseid":"9b887691d0cde6bc72e663a e4069f17d2#3413" "auth":{ "userid":"1234", "creditbalance":" " "order":{ "cn":" "vendorid":" ", "product":"comodo PositiveSSL Certificate", "status":"active", "vendormessage":"completed (ACTIVE)", "servertype":"apachessl" "errors":{ "iserror":"false", "errormessage":"" Příklad odpovědi (XML): <SAPI> <initial> <responsetime> </responsetime> <responseid>1a7dc24da938010f2fadc8c6f3dda683bd5af166#3453</responseid> </initial> <auth> <userid>1234</userid> <creditbalance> </creditbalance> </auth> <order> <cn> <vendorid> </vendorid> <product>comodo PositiveSSL Certificate</product> <status>active</status> <vendormessage>completed (ACTIVE)</vendorMessage> <servertype>apachessl</servertype> </order> <errors> <iserror>false</iserror> <errormessage/> </errors> </SAPI> 11

12 /download Odpoví vrácením vystaveného SSL certifikátu (implicitně formát ZIP zakódovaný pomocí standardu BASE64_ENCODE). Obsahuje také informace o stavu SSL certifikátu (např. zda je aktivní nebo zrušený) a informace o platnosti SSL certifikátu (platný od a platný do). Dotaz URL adresa dotazu: JSON: XML: Parametry dotazu: Parametr Metoda Povinné orderid POST Ano Jednoznačný identifikátor objednávky SSL certifikátu. Tato hodnota byla získána dotazem na /neworder v odpovědi order.orderid Odpověď Parametr certificate.nvb certificate.nva certificate.status certificate.zip Datum, od kterého je SSL certifikát platný (Not Valid Before). Datum je v tzv. UNIX čase (počet vteřin od :00 UTC) Datum, do kterého je SSL certifikát platný (Not Valid After). Datum je v tzv. UNIX čase (počet vteřin od :00 UTC) Stav objednávky SSL certifikátu. Možné hodnoty jsou: Pending SSL certifikát čeká na schválení, ještě nebyl vystaven Active SSL certifikát je aktivní a můžete stáhnout dotazem na /download Cancelled SSL certifikát byl revokován (zrušen) a je neplatný Expired Platnost SSL certifikátu vypršela a je neplatný Tělo ZIP archívu, který obsahuje SSL certifikát (a intermediate certifikát). Je zakódované standardem BASE64_ENCODE. Příklad odpovědi (JSON): { "initial":{ "responsetime":" ", "responseid":"9b887691d0cde6bc72e663a e4069f17d2#3413" "auth":{ "userid":"1234", "username":"info@ssls.cz", "creditbalance":" " "certificate":{ 12

13 "nvb":" ", "nva":" ", "status":"active", "zip":"uesdbaoaaaaaabnwviilynnr8quaapefaaaaaaaaqwrkvhj1c3rfehrlcm5 " "errors":{ "iserror":"false", "errormessage":"" Příklad odpovědi (XML): <SAPI> <initial> <responsetime> </responsetime> <responseid>1a7dc24da938010f2fadc8c6f3dda683bd5af166#3453</responseid> </initial> <auth> <userid>1234</userid> <creditbalance> </creditbalance> </auth> <certificate> <nvb> </nvb> <nva> </nva> <status>active</status> <servertype>uesdbaoaaaaaabnwviilynnr8quaapefaaaaaaaaqwrkv </servertype> </certificate> <errors> <iserror>false</iserror> <errormessage/> </errors> </SAPI> 13

14 Přílohy servertype Hodnota servertype určuje, na který typ serveru bude SSL certifikát nainstalován. Tabulka obsahuje seznam všech možných hodnot pro nastavení hodnoty servertype, které můžete použít v dotazu na /neworder. servertype apachessl apacheopenssl apacheapachessl apacheraven apachessleay iis Iis4 Iis5 cpanel plesk tomcat redhat oracle javawebserver cisco3000 ensim Other Apache + ModSSL Apache + OpenSSL Apache + ApacheSSL Apache + Raven Apache + SSLeay Microsoft IIS Microsoft IIS 4 Microsoft IIS 5 cpanel Plesk! Jakart TomCat server RedHat Linux Oracle Sun Java Web Server Cisco 3000 Series VPN C. Ensim Jiný, neuvedený typ serveru productcode Hodnota servertype určuje konrétní SSL certifikát. Tabulka obsahuje seznam všech aktuálně dostupných SSL certifikátů, které můžete použít v dotazu na /neworder. servertype positive positivewc essential essentialwc instant Comodo PositiveSSL Comodo PositiveSSL Wildcard Comodo EssentialSSL Comodo EssentialSSL Wildcard Comodo InstantSSL 14

15 instantpro comprem elite comodoev comodosgc comodoevsgc sgcsuper comintra rapid rapidwc quickprem truebid truebidev truevidwc secsite secsitepro secsiteev secsiteevpro secsitewc ssl123 websrv websrvev websrvwc twdv twprem twpremev twpremwc twenterprise Comodo InstantSSL Pro Comodo PremiumSSL Comodo Elite SSL Comodo EV SSL Comodo SGC SSL Comodo EV SGC SSL Comodo SGC SuperCerts Comodo Intranet SSL RapidSSL RapidSSL Wildcard GeoTrust QuickSSL Premium GeoTrust True BusinessID GeoTrust True BusinessID EV GeoTrust True BusinessID Wildcard Symantec (VeriSign) Secure Site Symantec (VeriSign) Secure Site Pro Symantec (VeriSign) Secure Site EV Symantec (VeriSign) Secure Site EV Pro Symantec (VeriSign) Secure Site Wildcard Thawte SSL 123 Thawte Web Server Thawte Web Server EV Thawte Wildcard SSL Trustwave Domain SSL Trustwave Premium SSL Trustwave Premium EV SSL Trustwave Premium Wildcard SSL Trustwave Enterprise SSL 15