Táto príručka vám ukáže, ako zaregistrovať objednávku certifikátu na podpis dokumentu pomocou protokolu SSL.com eSigner službu a pomocou rozhrania Cloud Signature Consortium (CSC) digitálne podpísať hash dokumentu a súbor PDF. Túto príručku môžete použiť s ktorýmkoľvek z týchto nástrojov cURL or poštár. Používateľom servera Postman odporúčame nainštalovať app desktop pre prácu s príkladmi. Príklady v tejto príručke sú použiteľné pre produkčné a testovacie prostredia eSigner a eSealing SSL.com. Rozdiely v príkazoch medzi produkčným a testovacím režimom sú vysvetlené v nasledujúcich častiach.
Ak chcete postupovať podľa týchto pokynov, budete potrebovať:
- Overená objednávka certifikátu na podpis dokumentu. Prosím čítajte toto ako na to úplné pokyny na objednanie a validáciu.
- A ID klienta (tiež známy ako ID aplikácie. Prečítajte si prosím toto ako na to pokyny na generovanie tohto poverenia).
Objednajte si certifikát na podpisovanie dokumentov SSL.com
Ako si objednať certifikát vo výrobnom prostredí
Pokyny na objednanie certifikátu na podpis produkčného dokumentu nájdete v tomto článku sprievodcu: Proces objednávania certifikátov na podpisovanie kódu a dokumentov
Ako si objednať testovací certifikát na SSL.com's Sandbox
SSL.com ponúka vyhradené prostredie Sandbox, ktoré odzrkadľuje náš živý portál SSL.com a SWS API, pre priestor na experimentovanie bez rizika. Toto „laboratórne“ nastavenie umožňuje používateľom skúmať a testovať služby SSL.com bez obáv z toho, že spôsobí prerušenie alebo vzniknú skutočné náklady.
Článok, Používanie karantény SSL.com na testovanie a integráciu, vám pomôže orientovať sa v procese založenia účtu Sandbox, spustenia testovacej objednávky a integrácie Sandboxu s SWS API.
Po vytvorení testovacieho certifikátu kontaktujte tím podpory SSL.com, aby ho overil. Môžete to urobiť kliknutím na tlačidlo online chatu v pravom dolnom rohu SSL.com webovej stránke alebo odoslaním e-mailu support@ssl.com.
Zaregistrujte sa do eSigneru a nastavte dvojfaktorové overenie
Skôr ako začnete používať CSC API, budete sa musieť zaregistrovať v službe cloudového podpisovania eSigner SSL.com. Overené objednávky je možné zaregistrovať do eSigner podľa pokynov nižšie:
- . Prejdite na ikonu Objednávky vo svojom účte SSL.com a vyhľadajte svoju objednávku.
- Kliknite na objednávku Podrobnosti odkaz.
- Vytvorte a potvrďte 4-ciferný PIN, potom kliknite na vytvoriť PIN tlačidlo.
Ak potrebujete resetovať kód PIN eSigneru, prečítajte si tento text toto ako na to.
- Zobrazí sa QR kód.
Pri ďalšom načítaní stránky nebude QR kód viditeľný. Ak potrebujete zobraziť alebo resetovať QR kód eSigneru, prečítajte si ho toto ako na to.
- Naskenujte kód do dvojfaktorovej autentifikačnej aplikácie na vašom mobilnom zariadení, ako je napr Google Authenticator or aUTH. Aplikácia vám poskytne jednorazové heslá (OTP), ktoré môžete použiť pri podpisovaní. Každé jednorazové heslo je platné 30 sekúnd.
Voliteľné: Preveďte svoj certifikát na podpisovanie dokumentov OV na certifikát esealing
Poznámka: Táto sekcia je len pre používateľov, ktorí chcú vykonávať tesnenie. Aby sa zautomatizovalo podpisovanie dokumentov a nemuseli byť požiadaní o jednorazové heslá (OTP), používatelia si sami konvertujú svoj certifikát na podpisovanie dokumentov organizácie Validation (OV) na certifikát esealing na svojich účtoch SSL.com. Berte na vedomie, že certifikát na podpis dokumentu individuálnej validácie (IV) nie je možné skonvertovať na zapečatenie. Pokyny na zapečatenie konverzie sú podrobne uvedené nižšie:
- kliknite Objednávky v hornej ponuke vášho účtu SSL.com.
- Nájdite svoj certifikát a kliknite na stiahnutie / podrobnosti odkaz.
- Kliknite na tlačidlo ODSTRÁŇTE 2FA tlačidlo.
Nainštalujte si Postman a importujte zbierky API
Pokyny v tejto časti sú určené iba pre používateľov služby Postman. Ak používate cURL s CSC API, môžete prejsť na ďalšiu časť.
- Stiahnite a rozbaľte CSC API zbierka poštárov a Zbierka Postman API pre podpisovanie dokumentov (vidieť https://www.postman.com/sslcom pre online kolekcie SSL.com API).
- Stiahnite a nainštalujte Poštový klient REST.
- Spustite Postman, potom vytvorte nový účet Postman alebo sa prihláste do existujúceho.
- Kliknite na tlačidlo import tlačidlo.
- Kliknite na tlačidlo Nahrať súbory tlačidlo, prejdite na rozbalené súbory kolekcie API (
csc-api-prod.postman_collection.jsonadocument-signing-api-prod.postman_collection.json) a otvorte ich.
- Kliknite na tlačidlo import tlačidlo.
- Požiadavky API, s ktorými budete pracovať, sú teraz k dispozícii v zbierky na ľavej strane okna Poštár.
Načítať prístupový token
Ďalším krokom je získanie prístupového tokenu zo stránky SSL.com. Budete potrebovať svoje ID klienta dostupné ako aj používateľské meno a heslo pre váš účet SSL.com. Prístupové tokeny sú platné jednu hodinu po ich vydaní.
Pomocou záložiek, na ktoré je možné kliknúť, vyberte pokyny pre Poštára alebo KURRA:
- Vyberte žiadosť o API zo zbierky CSC API.
- Vybrať povolenie A vyberte položku OAuth 2.0 z Typ Ponuka.
- Do formulára zadajte nasledujúce informácie:
- Predpona hlavičky:
Bearer - Názov tokenu:
SSLCOM CSC(alebo akékoľvek iné ľahko zapamätateľné meno, ktoré uprednostňujete) - Typ grantu:
Authorization Code - URL spätného volania:
https://upload.esigner.com - Autorizovať pomocou prehliadača: nekontrolovaný
- Autentická URL:
https://login.ssl.com/oauth2/authorizepre výrobné prostredie;https://oauth-sandbox.ssl.com/oauth2/authorizepre prostredie Sandbox. - URL prístupového tokenu:
https://login.ssl.com/oauth2/tokenpre výrobné prostredie;https://oauth-sandbox.ssl.com/oauth2/tokenpre prostredie Sandbox. - ID klienta: [Vaše ID klienta]
- Tajomstvo klienta: [Tajomstvo vášho klienta]
- Rozsah:
service - Stav: [nechaj prázdne]
- Autentifikácia klienta:
Send as Basic Auth header
Po dokončení kliknite na ikonu Získajte nový prístupový token tlačidlo.
- Predpona hlavičky:
- Zobrazí sa prihlasovací formulár. Zadajte svoje používateľské meno a heslo pre SSL.com a potom kliknite na ikonu Členské Prihlásiť tlačidlo.
- Váš nový prístupový token by sa mal zobraziť v službe Postman. Vyberte text prístupového tokenu, skopírujte ho do schránky a zatvorte Spravujte prístupové tokeny dialógové okno. Vložte svoj prístupový token do textového editora, kde k nemu máte ľahký prístup. Platnosť každého prístupového tokenu uplynie po jednej hodine.
Svoj token môžete tiež uložiť na opätovné použitie v požiadavkách Postmana, ale zistili sme, že je najspoľahlivejšie skopírovať a vložiť token priamo do každej žiadosti.
- Pomocou nasledujúceho príkazu požiadajte o prístupový token. Nahraďte hodnoty zobrazené v ALL-CAPS vašimi skutočnými hodnotami:
curl --location --request POST "https://login.ssl.com/oauth2/token" \ --header "Typ obsahu: application/json" \ --data-raw '{ "client_id" : "VAŠE -CLIENT-ID", "client_secret" : "VAŠE-KLIENTSKÉ-TAJNÉ", "grant_type" : "password", "username" : "VAŠE-POUŽÍVATEĽSKÉ MENO", "password" : "VAŠE-HESLO" }' - Mali by ste dostať objekt JSON obsahujúci prístupový token a obnovovací token. Skopírujte hodnotu prístupového tokenu a vložte ju do svojich požiadaviek API. Pre tieto príklady nebudete potrebovať obnovovací token.
Podpíšte hash
Teraz, keď máte prístupový token, môžete začať zadávať požiadavky API a vytvárať podpisy. Táto časť vás prevedie piatimi dostupnými požiadavkami v zbierke Postman CSC, ktorých výsledkom je vytvorenie digitálneho podpisu z hodnoty hash dokumentu.
- Knižnica PDF je potrebná na manipuláciu s PDF pre vstup hash a neskoršie vloženie PKCS#7 do dokumentu PDF. (napr. ApachePDFBox v jazyku Java).
- Knižnica Crypto na vytváranie PKCS#7 z nespracovaných podpisov prijatých z eSigner API (napr. BouncyCastle v jazyku Java).
Získať informácie o CSC (voliteľné)
- Môžete použiť Informácie o CSC žiadosť o získanie informácií o cloudovej podpisovej službe SSL.com. Upozorňujeme, že na rozdiel od ostatných v kolekcii táto požiadavka nevyžaduje váš prístupový token. Ak chcete žiadosť odoslať, vyberte Informácie o CSC z CSC API zbierku a potom kliknite na ikonu odoslať tlačidlo.
- Informácie o cloudovej podpisovej službe sa objavia v objekte JSON v službe Postman's Odpoveď Pole.
- Na získanie informácií o službe CSC API služby SSL.com použite nasledujúci príkaz. Ak ste v prostredí sandbox, použite
https://cs-try.ssl.com/csc/v0/infomiesto.
curl --location --request POST "https://cs.ssl.com/csc/v0/info" \ --header "Content-Type: application / json" \ --data-raw "{}" - Dostanete objekt JSON s podrobnosťami o službe:
Zoznam poverení CSC
Zoznam poverení CSC požiadavka získa poverenie, ktoré použijete v neskorších požiadavkách API.
- vybrať Zoznam poverení CSC a kliknite na tlačidlo povolenie tab.
- Vybrať Token na doručiteľa z Typ ponuky, vložte prístupový token do priečinka Známka pole a potom kliknite na odoslať tlačidlo.
- Objekt JSON so zoznamom ID poverení priradených k používateľovi sa zobrazí v priečinku Odpoveď lúka. Váš zoznam bude pravdepodobne obsahovať jednu hodnotu. Skopírujte a prilepte svoje ID poverenia do textového editora na použitie v neskorších požiadavkách.
- Zadajte nasledujúci príkaz. (Nahraďte MY-ACCESS-TOKEN svojím skutočným prístupovým tokenom). Ak sa nachádzate v prostredí karantény, použite
https://cs-try.ssl.com/csc/v0/credentials/listmiesto:
curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/list" \ --header "Content-Type: application / json" \ --header "Autorizácia: Bearer MY- ACCESS-TOKEN "\ --data-raw" {} "Ak používate certifikát eseal (certifikát na podpisovanie dokumentov iba s informáciami o organizácii; je súčasťou vášho bezplatného účtu esigner.com), potom uveďte „clientData“: „DS_ESEAL“ (poznámka: eseals nevyžadujú overenie OTP). Ďalšie možnosti pre „clientData“ sú „EVCS“ pre podpisovanie kódu EV a „DS“ (predvolené) pre IV alebo IV+OV podpisovanie dokumentov:
curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/list" \ --header "Typ obsahu: application/json" \ --header "Autorizácia: Nositeľ MY- ACCESS-TOKEN" \ --data-raw '{"clientData": "DS_ESEAL"}' - Mali by ste dostať objekt JSON so zoznamom ID poverení priradených k používateľovi. Váš zoznam bude pravdepodobne obsahovať jednu hodnotu. Skopírujte a prilepte svoje ID poverenia do textového editora na použitie v neskorších požiadavkách.
Informácie o povereniach CSC (voliteľné)
Informácie o povereniach CSC Žiadosť vráti certifikáty a ďalšie informácie spojené s ID poverenia a na podpis sa nevyžaduje.
- Ak chcete použiť túto požiadavku, zvoľte Informácie o povereniach CSC zo zbierky a kliknite na ikonu povolenie tab.
- Vybrať Token na doručiteľa z Typ do ponuky a potom vložte prístupový token do priečinka Známka Pole.
- Vybrať Telo kartu, potom prilepte svoje ID poverenia ako hodnotu pre
credentialID.
- Kliknite na tlačidlo odoslať tlačidlo.
- Objekt JSON s reťazcom podpisového certifikátu a ďalšími informáciami sa objaví v Odpoveď Pole.
- Zadajte nasledujúci príkaz. Ak sa nachádzate v prostredí karantény, použite
https://cs-try.ssl.com/csc/v0/credentials/infovymeniťMY-ACCESS-TOKENaMY-CREDENTIAL-IDs vašimi skutočnými informáciami:
curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/info" \ --header "Typ obsahu: application/json" \ --header "Autorizácia: Nositeľ MY- ACCESS-TOKEN" \ --data-raw '{ "ID poverenia": "MOJE-ID POVERENIA", "certifikáty": "chain", "certInfo": true, "authInfo": true }' - Mali by ste dostať objekt JSON s reťazcom podpisového certifikátu a ďalšími informáciami:
Autorizácia poverení
Autorizácia poverení žiadosť získa oprávnenie na podpísanie hash.
- Začnite výberom Autorizácia poverení zo zbierky a kliknutím na ikonu povolenie tab.
- Vybrať Token na doručiteľa z Typ do ponuky a potom vložte prístupový token do priečinka Známka Pole.
- Vybrať Telo tab. Vložte svoje identifikačné údaje ako
credentialIDhodnotu a hash dokumentu, ktorý chcete podpísať akohashhodnotu. Načítajte a zadajte OTP z vašej autentifikačnej aplikácie a zadajte ho ako hodnotu preOTP, Potom kliknite na tlačidlo odoslať tlačidlo. Poznámka: OTP sa nevyžaduje na zapečatenie certifikátov.
- Objekt JSON s vašimi podpisovými aktivačnými údajmi (SAD) sa objaví v Odpoveď lúka. Skopírujte a prilepte túto hodnotu do textového editora na použitie v žiadosti o podpis hash.
- Použite nasledujúci príkaz. Vymeniť
MY-ACCESS-TOKEN,MY-CREDENTIAL-IDaMY-HASHs vašimi skutočnými informáciami. Získajte jednorazové heslo zo svojej aplikácie 2FA a jeho hodnotou je hodnota preMY-OTP. Poznámka: OTP sa nevyžaduje na zapečatenie certifikátov.
curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/authorize" \ --header "Typ obsahu: application/json" \ --header "Autorizácia: Nositeľ MY- ACCESS-TOKEN" \ --data-raw '{ "identifikátor poverenia": "MOJE-ID POVERENIA", "numSignatures": 1, "hash": [ "MY-HASH" ], "OTP": "MY-OTP "}" - Mali by ste dostať objekt JSON s vašimi podpisovými aktivačnými údajmi (SAD). Skopírujte a prilepte túto hodnotu do textového editora na použitie v žiadosti o podpis hash.
Podpísať hash
Teraz ste pripravení podpísať hash dokumentu.
- vybrať Podpísať hash zo zbierky a potom vyberte povolenie tab.
- Vybrať Token na doručiteľa z Typ do ponuky a potom vložte prístupový token do priečinka Známka Pole.
- Vybrať Telo tab. Vložte svoje identifikačné údaje ako
credentialIDhodnota, vaše údaje o aktivácii podpisu akoSADhodnotu a hašovanie dokumentu, ktorý chcete podpísať akohashhodnotu, potom kliknite na odoslať tlačidlo.
- Objekt JSON s vašim podpisom sa objaví v Odpoveď Pole.
- Zadajte nasledujúci príkaz. Vymeniť
MY-ACCESS-TOKEN,MY-CREDENTIAL-ID,MY-SADaMY-HASHs vašimi skutočnými informáciami:
curl --location --request POST "https://cs.ssl.com/csc/v0/signatures/signHash" \ --header "Content-Type: application/json" \ --header "Autorizácia: Nositeľ MY- ACCESS-TOKEN" \ --data-raw '{ "ID poverenia": "MOJE-ID POVERENIA", "SAD": "MY-SAD", "hash": [ "MY-HASH" ], "signAlgo": "1.2.840.113549.1.1.11" }' - Mali by ste dostať objekt JSON obsahujúci váš podpis.
Podpíšte PDF
Okrem podpisovania hašovania dokumentov môžete tiež nahrať a podpísať súbor PDF.
Pri podpisovaní súboru PDF budete pracovať s dvoma požiadavkami POST:
- Nahrajte dokument PDF
- Podpísať dokument PDF
Poverenie, ktoré ste získali vyššie, môžete znova použiť pomocou Zoznam poverení CSC žiadosť. Pravdepodobne budete tiež musieť získať nový prístupový token.
Nahrajte dokument PDF
- Vybrať Nahrajte dokument PDF požiadajte a kliknite na ikonu povolenie tab.
- Vybrať Token na doručiteľa z Typ do ponuky a potom vložte prístupový token do priečinka Známka Pole.
- Vybrať Záhlavie na kartu a vložte svoje ID poverenia do priečinka Hodnota stĺpec.
- Vybrať Telo a kliknite na tlačidlo × pri
hello.pdfna odstránenie tohto zástupného názvu súboru.
- Kliknite na tlačidlo Vyberte položku Súbor a potom prejdite na súbor, ktorý chcete nahrať.
- Kliknite na tlačidlo odoslať tlačidlo.
- Vyberte a skopírujte súbor
idhodnota v odpovedi, ktorá sa má použiť v nasledujúcej žiadosti.
- Použite nasledujúci príkaz. Vymeniť
MY-CREDENTIAL-ID,MY-ACCESS-TOKENa/PATH/TO/FILE.pdfs vašimi skutočnými informáciami:
curl --location --request POST "https://ds.ssl.com/v1/pdf/upload" \ --header "Credential-Id: MY-CREDENTIAL-ID" \ --header "Autorizácia: Bearer MY- ACCESS-TOKEN "\ --header" Content-Type: application / pdf "\ --data-binary" @ / PATH / TO / FILE.pdf "
- Dostanete objekt JSON s hodnotou pre
id. Skopírujte túto hodnotu, aby ste ju mohli použiť v nasledujúcej žiadosti.
Poznámka: Viditeľné podpisy nájdete v nasledujúcich hlavičkách požiadaviek HTTP (/v1/pdf/upload):
|
Identifikačné číslo poverenia |
Jedinečné ID poverenia priradené ku kľúču – Povinné |
|
Dôvod podpisu |
Pridať dôvod podpisu na pridanie do vzhľadu podpisu a tiež do podpisového slovníka – Voliteľné, napr. Súhlasím s týmto dokumentom |
|
Miesto podpisu |
Pridajte miesto podpisu do podpisového slovníka – voliteľné, napr. Houston, Texas |
|
Kontaktné informácie |
Pridajte kontaktné informácie do podpisového slovníka – voliteľné, napr. telefónne číslo |
|
Podpis-Pole-Pozícia |
Pozícia poľa podpisu, kde sa zobrazuje vizuálny podpis. Formát je "x,y,šírka,výška" - Voliteľné |
|
Číslo strany |
Číslo strany, kam nakresliť podpis – Voliteľné |
|
Ručný podpis |
Obrázok podpisu ruky PNG zakódovaný v Base64 – voliteľné |
Podpísať dokument PDF
Teraz môžete PDF podpísať.
- Vybrať Nahrajte dokument PDF požiadajte a kliknite na ikonu povolenie tab.
- Vybrať Token na doručiteľa z Typ do ponuky a potom vložte prístupový token do priečinka Známka Pole.
- Vyberte kartu Text a vložte do
idhodnotu z predchádzajúceho kroku a OTP z vašej autentifikačnej aplikácie, potom kliknite na odoslať tlačidlo.
- Údaje PDF sa zobrazia nižšie v Odpoveď lúka. Vyberte si Uložiť do súboru z Uložiť odpoveď ponuky, potom pomenujte súbor.
- Otvorte súbor v aplikácii Acrobat a skontrolujte, či je súbor podpísaný.
- Zadajte nasledujúci príkaz. Vymeniť
MY-CREDENTIAL-ID,MY-FILE-IDaOUTPUT-FILENAMEs vašimi skutočnými informáciami. Získajte jednorazové heslo (OTP) z aplikácie 2FA a zadajte ho akoMY-OTP. Poznámka: Jednorazové heslo sa nevyžaduje na zapečatenie certifikátov:
curl --location --request POST 'https://ds.ssl.com/v1/pdf/sign' \ --header 'Content-Transfer-Encoding: application / json' \ --header 'Content-Type: application / json '\ --header' Autorizácia: Nositeľ MY-ACCESS-TOKEN '\ --data-raw' {"id": "MY-FILE-ID", "otp": "MY-OTP"} '\ - -výstup OUTPUT-FILENAME - cURL stiahne podpísaný súbor a uloží ho do súboru, ktorý ste zadali:
- Otvorte PDF v aplikácii Acrobat alebo Acrobat Reader a skontrolujte platnosť podpisu.
