Den här guiden visar dig hur du registrerar en beställning av en dokumentsigneringscertifikat hos SSL.com eSigner tjänsten och använd Cloud Signature Consortium (CSC) API för att digitalt signera en dokumenthash och en PDF-fil. Du kan använda den här guiden med någon av dem ringla or Postman. Vi rekommenderar att Postman-användare installerar skrivbordsprogram för att arbeta igenom exemplen. Exemplen i denna guide är både tillämpliga på SSL.coms produktions- och testmiljöer för eSigner och eSealing. Skillnader i kommandon mellan produktions- och testlägen förklaras i följande avsnitt.
För att följa dessa instruktioner behöver du:
- En validerad certifikatorder för dokumentsignering. Vänligen läs det här för fullständiga instruktioner om beställning och validering.
- A kund-ID (även känd som en ansöknings-ID. Se till det här för instruktioner om hur du skapar denna referens).
Beställ ditt SSL.com-dokumentsigneringscertifikat
Hur man beställer ett certifikat i produktionsmiljön
Se den här guideartikeln för instruktioner om hur du beställer ett produktionsdokumentsigneringscertifikat: Beställningsprocess för kod- och dokumentsigneringscertifikat
Hur man beställer ett testcertifikat på SSL.coms sandlåda
SSL.com erbjuder en dedikerad Sandbox-miljö, som speglar vår live SSL.com-portal och SWS API, för ett riskfritt experimentutrymme. Denna "laboratorie"-inställning tillåter användare att utforska och testa SSL.coms tjänster utan att behöva oroa sig för att orsaka störningar eller ådra sig faktiska kostnader.
Artikeln, Använda SSL.com Sandbox för testning och integration, hjälper dig att navigera i processen att upprätta ett Sandbox-konto, initiera en testorder och integrera Sandbox med SWS API.
När du har skapat ditt testcertifikat, kontakta SSL.coms supportteam för att få det validerat. Du kan göra detta genom att klicka på chattknappen i det nedre högra hörnet av SSL.com hemsida eller skicka ett e-postmeddelande till support@ssl.com.
Registrera dig i eSigner och konfigurera tvåfaktorautentisering
Innan du kan börja använda CSC API måste du registrera dig för SSL.coms eSigner molnsigneringstjänst. Validerade beställningar kan registreras i eSigner enligt instruktionerna nedan:
- . Navigera till Beställningar fliken i ditt SSL.com-konto och hitta din beställning.
- Klicka på beställningens detaljer länken.
- Skapa en och bekräfta en fyrsiffrig PIN-kod och klicka sedan på skapa PIN knapp.
Läs om du behöver återställa din eSigner-PIN det här.
- En QR-kod visas.
Nästa gång du laddar om sidan visas inte QR-koden. Läs om du behöver visa eller återställa din eSigner QR-kod det här.
- Skanna koden till en 2-faktor autentiseringsapp på din mobila enhet, t.ex. Google Authenticator or Authy. Appen ger dig engångslösenord (OTP) för användning vid signering. Varje OTP är giltig i 30 sekunder.
Valfritt: Konvertera ditt OV-dokumentsigneringscertifikat till ett förseglingscertifikat
Notera: Det här avsnittet är endast för användare som vill göra försegling. För att automatisera dokumentsignering och inte bli tillfrågad av One Time Passwords (OTP), konverterar användare själv sitt certifikat för organisationsvalidering (OV) undertecknande av dokument till ett eseling-certifikat på sina SSL.com-konton. Observera att ett certifikat för individuell validering (IV) inte kan konverteras för försegling. Instruktioner för förslutningskonvertering beskrivs nedan:
- Klicka Beställningar på toppmenyn på ditt SSL.com-konto.
- Leta upp ditt certifikat och klicka på download / detaljer länken.
- Klicka på BORT 2FA knapp.
Installera Postman och Import API-samlingar
Instruktionerna i detta avsnitt är endast avsedda för Postman-användare. Om du använder cURL med CSC API kan du gå vidare till nästa avsnitt.
- Ladda ner och packa upp den CSC API Postman-samling och Document Signering API Postman collection (Se https://www.postman.com/sslcom för SSL.com API-samlingar online).
- Hämta och installera Postman REST-klient.
- Starta Postman och skapa sedan ett nytt Postman-konto eller logga in på ett befintligt.
- Klicka på Importera knapp.
- Klicka på Ladda upp filer , navigera till de unzippade API-samlingsfilerna (
csc-api-prod.postman_collection.jsonochdocument-signing-api-prod.postman_collection.json) och öppna dem.
- Klicka på Importera knapp.
- API-förfrågningarna du kommer att arbeta med finns nu tillgängliga i Kollektioner på vänster sida av brevbärarfönstret.
Hämta åtkomsttoken
Nästa steg är att hämta en åtkomsttoken från SSL.com. Du behöver din kund-ID tillgängligt, samt användarnamn och lösenord för ditt SSL.com-konto. Åtkomsttoken är giltigt i en timme efter det att de har utfärdats.
Använd de klickbara flikarna nedan för att välja instruktioner för Postman eller cURL:
- Välj en API-begäran från CSC API-samlingen.
- Välj Tillstånd Fliken och välj OAuth 2.0 från Typ meny.
- Ange följande information i formuläret:
- Rubrikprefix:
Bearer - Tokenamn:
SSLCOM CSC(eller något annat lätt att komma ihåg namn som du föredrar) - Bidragstyp:
Authorization Code - Återuppringnings-URL:
https://upload.esigner.com - Auktorisera med webbläsare: omarkerad
- Auth-URL:
https://login.ssl.com/oauth2/authorizeför produktionsmiljö;https://oauth-sandbox.ssl.com/oauth2/authorizeför Sandbox-miljö. - URL för åtkomsttoken:
https://login.ssl.com/oauth2/tokenför produktionsmiljö;https://oauth-sandbox.ssl.com/oauth2/tokenför Sandbox-miljö. - Klient ID: [Ditt klient-ID]
- Kundhemlighet: [Din klienthemlighet]
- Omfattning:
service - Ange: [lämna tom]
- Klientautentisering:
Send as Basic Auth header
När du är klar klickar du på Skaffa ny åtkomsttoken knapp.
- Rubrikprefix:
- Ett inloggningsformulär visas. Ange ditt SSL.com-användarnamn och lösenord och klicka sedan på Logga in knapp.
- Din nya åtkomsttoken ska visas i Postman. Välj åtkomsttokenstext och kopiera den till Urklipp och stäng sedan Hantera åtkomsttoken dialog ruta. Klistra in din åtkomsttoken i en textredigerare där du enkelt kan komma åt den. Varje åtkomsttoken upphör efter en timme.
Du kan också spara din token för återanvändning i Postman-förfrågningar, men vi har funnit att det är mest pålitligt att kopiera och klistra in token direkt i varje begäran.
- Använd följande kommando för att begära en åtkomsttoken. Ersätt värdena som visas i ALL-CAPS med dina faktiska värden:
curl --plats --request POST "https://login.ssl.com/oauth2/token" \ --header "Content-Type: application/json" \ --data-raw '{ "client_id" : "DITT -KLIENT-ID", "client_secret" : "DIN-KLIENT-HEMLIGT", "grant_type" : "lösenord", "användarnamn" : "DITT-ANVÄNDARNAMN", "lösenord" : "DITT-LÖSENORD" }' - Du bör få ett JSON-objekt som innehåller en åtkomsttoken och en uppdateringstoken. Kopiera åtkomsttokenvärdet för att klistra in i dina API-förfrågningar. Du behöver inte uppdateringstoken för dessa exempel.
Skriv en Hash
Nu när du har en åtkomsttoken kan du börja göra API-förfrågningar och skapa signaturer. Detta avsnitt leder dig genom de fem tillgängliga förfrågningarna i Postman CSC-samlingen, vilket resulterar i skapandet av en digital signatur från en dokumenthash.
- Ett PDF-bibliotek behövs för att manipulera PDF-filen för hash-inmatning och senare bädda in PKCS#7 i PDF-dokumentet. (ex. ApachePDFBox i Java).
- Ett kryptobibliotek för att skapa PKCS#7 av råa signaturer som tagits emot från eSigner API (ex. BouncyCastle i Java).
Få CSC-information (valfritt)
- Du kan använda CSC -information begär att få information om SSL.coms molntypservice. Observera att, till skillnad från de andra i samlingen, kräver denna begäran inte din åtkomsttoken. Välj för att skicka begäran CSC -information från CSC API samling och klicka sedan på Skicka knapp.
- Information om molnsignaturtjänsten visas i ett JSON-objekt i Postmans Svar fält.
- Använd följande kommando för att få information om SSL.com:s CSC API-tjänst. Om du befinner dig i sandlådemiljö, använd
https://cs-try.ssl.com/csc/v0/infoistället.
curl --location --request POST "https://cs.ssl.com/csc/v0/info" \ --header "Content-Type: application / json" \ --data-raw "{}" - Du får ett JSON-objekt med information om tjänsten:
CSC-referenslista
Smakämnen CSC-referenslista begäran hämtar en referens som du använder i senare API-förfrågningar.
- Välja CSC-referenslista och klicka på Tillstånd fliken.
- Välja Bärartoken från Typ menyn, klistra in din åtkomsttoken i Pollett och klicka sedan på Skicka knapp.
- Ett JSON-objekt med en lista över referens-ID: n som är associerade med användaren visas i Svar fält. Din lista kommer antagligen att innehålla ett värde. Kopiera och klistra in ditt referens-ID i en textredigerare för användning i senare förfrågningar.
- Ange följande kommando. (Ersätt MY-ACCESS-TOKEN med din faktiska åtkomsttoken). Om du är i sandlådemiljö, använd
https://cs-try.ssl.com/csc/v0/credentials/lististället:
curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/list" \ --header "Content-Type: application / json" \ --header "Authorization: Bearer MY- ACCESS-TOKEN "\ --data-raw" {} "Om du använder ett esigner-certifikat (dokumentsigneringscertifikat med endast organisationsinformation; ingår i ditt kostnadsfria esigner.com-konto), inkludera "clientData": "DS_ESEAL" (obs! eseals kräver inte OTP-autentisering). Andra alternativ för "clientData" är "EVCS" för EV Code Signing och "DS" (standard) för IV eller IV+OV Document Signing:
curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/list" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer MY- ACCESS-TOKEN" \ --data-raw '{"clientData": "DS_ESEAL"}' - Du bör få ett JSON-objekt med en lista över autentiserings-ID som är associerade med användaren. Din lista kommer antagligen att innehålla ett värde. Kopiera och klistra in ditt referens-ID i en textredigerare för användning i senare förfrågningar.
Information om CSC-referenser (valfritt)
Smakämnen Information om CSC-referenser begäran returnerar certifikat och annan information som är associerad med ett referens-ID och krävs inte för signering.
- För att använda denna begäran, välj Information om CSC-referenser från samlingen och klicka på Tillstånd fliken.
- Välja Bärartoken från Typ menyn och klistra sedan in din åtkomsttoken i Pollett fält.
- Välj Kaross fliken och klistra sedan in ditt referens-ID som värdet för
credentialID.
- Klicka på Skicka knapp.
- Ett JSON-objekt med din signaturcertifikatkedja och annan information visas i Svar fält.
- Ange följande kommando. Om du är i sandlådemiljön, använd
https://cs-try.ssl.com/csc/v0/credentials/infoersättaMY-ACCESS-TOKENochMY-CREDENTIAL-IDmed din faktiska information:
curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/info" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer MY- ACCESS-TOKEN" \ --data-raw '{ "credentialID": "MY-CREDENTIAL-ID", "certificates": "chain", "certInfo": true, "authInfo": true }' - Du bör få ett JSON-objekt med din signeringscertifikatkedja och annan information:
Autentiseringsuppgifter Auktoriserar
Smakämnen Autentiseringsuppgifter Auktoriserar begäran hämtar auktorisation för att underteckna en hash.
- Börja med att välja Autentiseringsuppgifter Auktoriserar från samlingen och klicka på Tillstånd fliken.
- Välja Bärartoken från Typ menyn och klistra sedan in din åtkomsttoken i Pollett fält.
- Välj Kaross flik. Klistra in ditt referens-ID som
credentialIDvärde och en hash av det dokument som du vill underteckna somhashvärde. Hämta och ange en OTP från din autentiseringsapp och ange den som värdet förOTP, klicka sedan på Skicka knapp. Obs: OTP krävs inte för att försegla certifikat.
- Ett JSON-objekt med dina signaturaktiveringsdata (SAD) visas i Svar fält. Kopiera och klistra in det här värdet i en textredigerare för användning i hashsigneringsförfrågan.
- Använd följande kommando. Byta ut
MY-ACCESS-TOKEN,MY-CREDENTIAL-IDochMY-HASHmed din faktiska information. Få ett engångslösenord från din 2FA-applikation och användningen är värdet förMY-OTP. Obs: OTP krävs inte för att försegla certifikat.
curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/authorize" \ --header "Content-Type: application/json" \ --header "Auktorisation: Bearer MY- ACCESS-TOKEN" \ --data-raw '{ "credentialID": "MY-CREDENTIAL-ID", "numSignatures": 1, "hash": [ "MY-HASH" ], "OTP": "MY-OTP " }' - Du bör få ett JSON-objekt med dina signaturaktiveringsdata (SAD). Kopiera och klistra in detta värde i en textredigerare för användning i hashsigneringsförfrågan.
Signera Hash
Nu är du redo att underteckna dokumenthashen.
- Välja Signera Hash från samlingen och välj sedan Tillstånd fliken.
- Välja Bärartoken från Typ menyn och klistra sedan in din åtkomsttoken i Pollett fält.
- Välj Kaross flik. Klistra in ditt referens-ID som
credentialIDvärde, dina signaturaktiveringsdata somSADvärde och en hash av dokumentet som du vill underteckna somhashoch klicka sedan på Skicka knapp.
- Ett JSON-objekt med din signatur kommer att visas i Svar fält.
- Ange följande kommando. Byta ut
MY-ACCESS-TOKEN,MY-CREDENTIAL-ID,MY-SADochMY-HASHmed din faktiska information:
curl --location --request POST "https://cs.ssl.com/csc/v0/signatures/signHash" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer MY- ACCESS-TOKEN" \ --data-raw '{ "credentialID": "MY-CREDENTIAL-ID", "SAD": "MY-SAD", "hash": [ "MY-HASH" ], "signAlgo": "1.2.840.113549.1.1.11" }' - Du bör få ett JSON-objekt som innehåller din signatur.
Skriv en PDF
Förutom att underteckna dokumenthashar kan du också ladda upp och signera en PDF-fil.
När du signerar en PDF kommer du att arbeta med två POST-förfrågningar:
- Ladda upp PDF-dokument
- Underteckna PDF-dokument
Du kan återanvända referensen du hämtat ovan med CSC-referenslista begäran. Du kommer antagligen också att behöva hämta en ny access token.
Ladda upp PDF-dokument
- Välj Ladda upp PDF-dokument begäran och klicka på Tillstånd fliken.
- Välja Bärartoken från Typ menyn och klistra sedan in din åtkomsttoken i Pollett fält.
- Välj Headers fliken och klistra in ditt referens-ID i Värde kolonn.
- Välj Kaross fliken och klicka på × bredvid
hello.pdfför att ta bort det här platshållarens filnamn.
- Klicka på Välj fil och sedan navigera till filen du vill ladda upp.
- Klicka på Skicka knapp.
- Välj och kopiera
idvärde i svaret som ska användas i nästa begäran.
- Använd följande kommando. Byta ut
MY-CREDENTIAL-ID,MY-ACCESS-TOKENoch/PATH/TO/FILE.pdfmed din faktiska information:
curl --location --request POST "https://ds.ssl.com/v1/pdf/upload" \ --header "Credential-Id: MY-CREDENTIAL-ID" \ --header "Authorization: Bearer MY- ACCESS-TOKEN "\ --header" Content-Type: application / pdf "\ --data-binary" @ / PATH / TO / FILE.pdf "
- Du får ett JSON-objekt med ett värde för
id. Kopiera detta värde för att använda i nästa begäran.
Obs: För synliga signaturer, se följande HTTP Request Headers (/v1/pdf/upload):
|
Credential-ID |
Unikt legitimations-ID tilldelat nyckeln – obligatoriskt |
|
Signering-anledning |
Lägg till signeringsorsak att lägga till i signaturutseende och även i signaturordbok – Valfritt t.ex. jag godkänner detta dokument |
|
Signeringsplats |
Lägg till signeringsplats i signaturordbok – Valfritt t.ex. Houston, Texas |
|
Kontaktinformation |
Lägg till kontaktinformation i signaturordbok – Valfritt t.ex. Telefonnummer |
|
Signatur-Fält-Position |
Signaturfältposition där visuell signatur visas. Formatet är "x,y,bredd,höjd" - Valfritt |
|
Sidonummer |
Sidnummer där signaturen ska ritas – Valfritt |
|
Hand-signatur |
Base64-kodad PNG-bild av handsignatur – Valfritt |
Underteckna PDF-dokument
Nu kan du underteckna PDF-filen.
- Välj Ladda upp PDF-dokument begäran och klicka på Tillstånd fliken.
- Välja Bärartoken från Typ menyn och klistra sedan in din åtkomsttoken i Pollett fält.
- Välj fliken Kropp, klistra in i
idvärde från föregående steg och en OTP från din autentiseringsapp och klicka sedan på Skicka knapp.
- PDF-uppgifterna visas nedan i Svar fält. Välja Spara i en fil från Spara svar menyn och ge sedan filen ett namn.
- Öppna filen i Acrobat för att bekräfta att filen har signerats.
- Ange följande kommando. Byta ut
MY-CREDENTIAL-ID,MY-FILE-IDochOUTPUT-FILENAMEmed din faktiska information. Få ett engångslösenord (OTP) från din 2FA-app och ange det somMY-OTP. Obs: OTP krävs inte för att försegla certifikat:
curl --location --request POST 'https://ds.ssl.com/v1/pdf/sign' \ --header 'Content-Transfer-Encoding: application / json' \ --header 'Content-Type: application / json '\ --header' Auktorisering: Bearer MY-ACCESS-TOKEN '\ --data-raw' {"id": "MY-FILE-ID", "otp": "MY-OTP"} '\ - -utgång OUTPUT-FILENAME - cURL hämtar den signerade filen och sparar den i det angivna filnamnet:
- Öppna PDF-filen i Acrobat eller Acrobat Reader för att kontrollera att signaturen är giltig.
