xml

www.ssls.cz

Co je to SAPI SAPI je zkratka pro SSLS API provozované společností Alpiro na adrese www.ssls.cz. 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: https://www.ssls.cz/api/ssls// je jednoznačný identifikátor partnera, je vždy stejný a zaručuje, že dotaz odesílá ten či onen partner 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.: https://www.ssls.cz/api/ssls///xml

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

Popis

initial.responseTime Čas ve který byla žádost zpracována, je uveden v tzv. UNIX čase (počet vteřin od 01.01.1970 00:00 UTC) SSLS.CZ www.ssls.cz

1

© 2013 Alpiro s.r.o. – Všechna práva vyhrazena.

www.ssls.cz initial.responseID

Jednoznačný identifikátor odpovědi, můžete uložit pro řešení případných dotazů.

auth.userID

Vaše interní ID pro SAPI

auth.userName

Příslušný účet na www.ssls.cz

auth.creditBalance

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.

errors.isError

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.

errors.errorMessage Je-‐li isError false, pak je hodnota prázdná. Pokud hodnota isError je true, je zde uveden popis nastalé chyby.

Typy dotazů /csr

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.

/authlist

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.

/neworder

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 www.ssls.cz dostatečný kredit.

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

/download

Stáhne vystavený SSL certifikát (implicitně formát ZIP zakódovaný pomocí standardu BASE64_ENCODE).

SSLS.CZ www.ssls.cz

2


www.ssls.cz

/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: https://www.ssls.cz/api/ssls//csr XML: https://www.ssls.cz/api/ssls//csr/xml

Parametry dotazu: Parametr

Metoda

Povinné

Popis

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

Popis

csrData.cn

Common Name, tj. doména, pro kterou je CSR žádost vygenerována.

csrData.orgCountry

Kód státu/země žadatele podle RFC 3066, např. CZ (Česká republika), SK (Slovensko), US (Spojené Státy Americké), DE (Německo) atd.

csrData.orgState

Kraj nebo okres, může být uveden název státu/země žadatele. Nesmí obsahovat českou diakritiku.

csrData.orgCity

Město sídla nebo trvalého pobytu či místa podnikání žadatele. Nesmí obsahovat českou diakritiku.

csrData.orgName

Firma žadatele (název společnosti nebo celé jméno fyzické osoby). Nesmí obsahovat českou diakritiku.

csrData.orgUnit

Organizační složka. Nesmí obsahovat českou diakritiku.

csrStatus.validCn

Uvedené Common Name v csrData.cn je validní (true) nebo chybné (false)

csrStatus.badExts

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.

csrStatus.wildcard

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 (www.example.com).

Příklad odpovědi (JSON): { "initial":{ "responseTime":"1369237022",

SSLS.CZ www.ssls.cz

3


www.ssls.cz "responseID":"9b887691d0cde6bc72e663a3362656e4069f17d2#3413" }, "auth":{ "userID":"1234", "userName":"[email protected]", "creditBalance":"2458100" }, "csrData":{ "cn":"www.example.com", "orgCountry":"CZ", "orgState":"Praha", "orgCity":"Praha", "orgName":"Alpiro s.r.o.", "orgUnit":"IT Security", "orgMail":"[email protected]" }, "csrStatus":{ "validCn":"true", "badExts":"false", "wildcard":"false" }, "errors":{ "isError":"false", "errorMessage":"" } }

Příklad odpovědi (XML): <SAPI> 1369237446 1a7dc24da938010f2fadc8c6f3dda683bd5af166#3453 <userID>1234 <userName>[email protected] 2458100 www.example.com CZ Praha Praha Alpiro s.r.o. IT Security [email protected] true false <wildcard>false <errors> false <errorMessage/>

SSLS.CZ www.ssls.cz

4


www.ssls.cz

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


JSON: https://www.ssls.cz/api/ssls//authlist XML: https://www.ssls.cz/api/ssls//authlist/xml


Metoda

Povinné

Popis

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

Popis

authlist.emailX

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":"1369237022", "responseID":"9b887691d0cde6bc72e663a3362656e4069f17d2#3413" }, "auth":{ "userID":"1234", "userName":"[email protected]", "creditBalance":"2458100" }, "authlist":{ "mail0":"[email protected]", "mail1":"[email protected]", "mail2":"[email protected]", "mail3":"[email protected]", "mail4":"[email protected]", "mail5":"[email protected]",

SSLS.CZ www.ssls.cz

5


www.ssls.cz "mail6":"[email protected]", "mail7":"[email protected]", "mail8":"[email protected]", "mail9":"[email protected]", "mail10":"[email protected]" }, "errors":{ "isError":"false", "errorMessage":"" } }

Příklad odpovědi (XML): <SAPI> 1369237446 1a7dc24da938010f2fadc8c6f3dda683bd5af166#3453 <userID>1234 <userName>[email protected] 2458100 <mail0>[email protected] <mail1>[email protected] <mail2>[email protected] <mail3>[email protected] <mail4>[email protected] <mail5>[email protected] <mail6>[email protected] <mail7>[email protected] <mail8>[email protected] <mail9>[email protected] <mail10>[email protected] <errors> false <errorMessage/>

SSLS.CZ www.ssls.cz

6


www.ssls.cz

/neworder 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 www.ssls.cz dostatečný kredit.


JSON: https://www.ssls.cz/api/ssls//neworder XML: https://www.ssls.cz/api/ssls//neworder/xml


Metoda

Povinné

Popis

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

SSLS.CZ www.ssls.cz

7


www.ssls.cz /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ř. +420123456789 nebo jen 420123456789

Odpověď Parametr

Popis

order.orderID

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.

order.vendorID

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.

order.product

Název SSL certifikátu

order.serverType

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

order.price

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":"1369237022", "responseID":"9b887691d0cde6bc72e663a3362656e4069f17d2#3413" }, "auth":{ "userID":"1234", "userName":"[email protected]", "creditBalance":"2458100" },

SSLS.CZ www.ssls.cz

8


www.ssls.cz "order":{ "orderID":"P1019U1369289552R9492", "vendorID":"13034011", "product":"Comodo PositiveSSL Certificate", "serverType":"apachessl", "price":259 }, "errors":{ "isError":"false", "errorMessage":"" } }

Příklad odpovědi (XML): <SAPI> 1369237446 1a7dc24da938010f2fadc8c6f3dda683bd5af166#3453 <userID>1234 <userName>[email protected] 2458100 P1019U1369289552R9492 13034011 <product>Comodo PositiveSSL Certificate <serverType>apachessl <price>259 <errors> false <errorMessage/>

SSLS.CZ www.ssls.cz

9


www.ssls.cz

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


JSON: https://www.ssls.cz/api/ssls//orderstatus XML: https://www.ssls.cz/api/ssls//orderstatus/xml


Metoda

Povinné

Popis

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

Popis

order.cn

Common Name, pro které je či bude SSL certifikát vystaven, např. www.example.com nebo *.example.com (wildcard SSL certifikát)

order.vendorID

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.

order.product

Název SSL certifikátu

order.status

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

E-‐mailová adresa, na kterou certifikační autorita pošle nebo již zaslala autorizační e-‐ mail.

order.serverType

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

Příklad odpovědi (JSON): { "initial":{

SSLS.CZ www.ssls.cz

10


www.ssls.cz "responseTime":"1369237022", "responseID":"9b887691d0cde6bc72e663a3362656e4069f17d2#3413" }, "auth":{ "userID":"1234", "userName":"[email protected]", "creditBalance":"2458100" }, "order":{ "cn":"www.example.com", "vendorID":"13034011", "product":"Comodo PositiveSSL Certificate", "status":"Active", "vendorMessage":"Completed (ACTIVE)", "authMail":"[email protected]", "serverType":"apachessl" }, "errors":{ "isError":"false", "errorMessage":"" } }

Příklad odpovědi (XML): <SAPI> 1369237446 1a7dc24da938010f2fadc8c6f3dda683bd5af166#3453 <userID>1234 <userName>[email protected] 2458100 www.example.com 13034011 <product>Comodo PositiveSSL Certificate <status>Active Completed (ACTIVE) [email protected] <serverType>apachessl <errors> false <errorMessage/>

SSLS.CZ www.ssls.cz

11


www.ssls.cz

/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).


JSON: https://www.ssls.cz/api/ssls//download XML: https://www.ssls.cz/api/ssls//download/xml


Metoda

Povinné

Popis

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

Popis

certificate.nvb

Datum, od kterého je SSL certifikát platný (Not Valid Before). Datum je v tzv. UNIX čase (počet vteřin od 01.01.1970 00:00 UTC)

certificate.nva

Datum, do kterého je SSL certifikát platný (Not Valid After). Datum je v tzv. UNIX čase (počet vteřin od 01.01.1970 00:00 UTC)

certificate.status

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ý

certificate.zip

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":"1369237022", "responseID":"9b887691d0cde6bc72e663a3362656e4069f17d2#3413" }, "auth":{ "userID":"1234", "userName":"[email protected]", "creditBalance":"2458100" }, "certificate":{

SSLS.CZ www.ssls.cz

12


www.ssls.cz "nvb":"1358942400", "nva":"1390564799", "status":"Active", "zip":"UEsDBAoAAAAAABNWviiLYnnr8QUAAPEFAAAaAAAAQWRkVHJ1c3RFeHRlcm5…" }, "errors":{ "isError":"false", "errorMessage":"" } }

Příklad odpovědi (XML): <SAPI> 1369237446 1a7dc24da938010f2fadc8c6f3dda683bd5af166#3453 <userID>1234 <userName>[email protected] 2458100 1358942400 1390564799 <status>Active <serverType>UEsDBAoAAAAAABNWviiLYnnr8QUAAPEFAAAaAAAAQWRkV… <errors> false <errorMessage/>

SSLS.CZ www.ssls.cz

13


www.ssls.cz

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

Popis

apachessl

Apache + ModSSL

apacheopenssl

Apache + OpenSSL

apacheapachessl

Apache + ApacheSSL

apacheraven

Apache + Raven

apachessleay

Apache + SSLeay

iis

Microsoft IIS

Iis4

Microsoft IIS 4

Iis5

Microsoft IIS 5

cpanel

cPanel

plesk

Plesk!

tomcat

Jakart TomCat server

redhat

RedHat Linux

oracle

Oracle

javawebserver

Sun Java Web Server

cisco3000

Cisco 3000 Series VPN C.

ensim

Ensim

Other

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

Popis

positive

Comodo PositiveSSL

positivewc

Comodo PositiveSSL Wildcard

essential

Comodo EssentialSSL

essentialwc

Comodo EssentialSSL Wildcard

instant

Comodo InstantSSL

SSLS.CZ www.ssls.cz

14


www.ssls.cz instantpro

Comodo InstantSSL Pro

comprem

Comodo PremiumSSL

elite

Comodo Elite SSL

comodoev

Comodo EV SSL

comodosgc

Comodo SGC SSL

comodoevsgc

Comodo EV SGC SSL

sgcsuper

Comodo SGC SuperCerts

comintra

Comodo Intranet SSL

rapid

RapidSSL

rapidwc

RapidSSL Wildcard

quickprem

GeoTrust QuickSSL Premium

truebid

GeoTrust True BusinessID

truebidev

GeoTrust True BusinessID EV

truevidwc

GeoTrust True BusinessID Wildcard

secsite

Symantec (VeriSign) Secure Site

secsitepro

Symantec (VeriSign) Secure Site Pro

secsiteev

Symantec (VeriSign) Secure Site EV

secsiteevpro

Symantec (VeriSign) Secure Site EV Pro

secsitewc

Symantec (VeriSign) Secure Site Wildcard

ssl123

Thawte SSL 123

websrv

Thawte Web Server

websrvev

Thawte Web Server EV

websrvwc

Thawte Wildcard SSL

twdv

Trustwave Domain SSL

twprem

Trustwave Premium SSL

twpremev

Trustwave Premium EV SSL

twpremwc

Trustwave Premium Wildcard SSL

twenterprise

Trustwave Enterprise SSL

SSLS.CZ www.ssls.cz

15


xml

Recommend Documents