Fjern dokumentsignering med eSigner CSC API

Denne guide viser dig, hvordan du tilmelder en ordreseddel til signaturcertifikat hos SSL.com eSigner servicere og bruge Cloud Signature Consortium (CSC) API til digital signering af en dokumenthash og en PDF-fil. Du kan bruge denne guide med begge cURL or Postman. Vi anbefaler, at Postman-brugere installerer desktop app for at gennemgå eksemplerne. Eksemplerne i denne vejledning gælder både for SSL.coms produktions- og testmiljøer for eSigner og eSealing. Forskelle i kommandoer mellem produktions- og testtilstande er forklaret i de følgende afsnit.

For at følge disse instruktioner har du brug for:

  • En valideret dokumentunderskrivelsescertifikatordre. Læs venligst denne vej for fulde instruktioner om bestilling og validering.
  • A kunde-id (også kendt som en Ansøgnings-id. Vær sød at henvise til denne vej for instruktioner om generering af denne legitimationsoplysninger).

Bestil dit SSL.com-dokumentsigneringscertifikat

Du kan springe dette afsnit over, hvis du allerede har et udstedt dokumentsigneringscertifikat. Hvis dette er tilfældet, skal du fortsætte til næste afsnit, som diskuterer, hvordan du tilmelder dit certifikat i eSigner.

Sådan bestiller du et certifikat i produktionsmiljøet

Se venligst denne guide-artikel for instruktioner om, hvordan du bestiller et produktionsdokument-signeringscertifikat: Bestillingsproces for kode- og dokumentsigneringscertifikater

Sådan bestiller du et testcertifikat på SSL.com's Sandbox

SSL.com tilbyder et dedikeret Sandbox-miljø, der afspejler vores live SSL.com-portal og SWS API, for et risikofrit eksperimenteringsrum. Denne "laboratorie"-indstilling giver brugerne mulighed for at udforske og teste SSL.coms tjenester uden at bekymre sig om at forårsage forstyrrelser eller pådrage sig faktiske omkostninger. 

Artiklen, Brug af SSL.com Sandbox til test og integration, vil hjælpe dig med at navigere i processen med at oprette en Sandbox-konto, starte en testordre og integrere Sandbox med SWS API.

Når du har oprettet dit testcertifikat, bedes du kontakte SSL.com supportteamet for at få det valideret. Du kan gøre dette ved at klikke på online chat-knappen i nederste højre hjørne af SSL.com hjemmeside eller sende en e-mail til support@ssl.com.

Tilmeld dig eSigner og opsæt tofaktorautentificering

Før du kan begynde at bruge CSC API, skal du tilmelde dig SSL.com's eSigner cloud-signeringstjeneste. Validerede ordrer kan tilmeldes eSigner ved at følge instruktionerne nedenfor: 

  1. . Naviger til Mine Ordrer fanen i din SSL.com-konto og find din ordre.
    Find rækkefølge
  2. Klik på ordren detaljer .
    detaljer
  3. Opret en, og bekræft en firecifret PIN-kode, og klik derefter på Opret PIN .
    Hvis du har brug for at nulstille din eSigner-pinkode, skal du læse denne vej.
    Opret PIN-kode
  4. En QR-kode vises.
    Næste gang du genindlæser siden, vil QR-koden ikke være synlig. Hvis du har brug for at se eller nulstille din eSigner QR-kode, skal du læse denne vej.
    QR kode
  5. Scan koden til en 2-faktor-godkendelsesapp på din mobile enhed, f.eks Google Autentificering or Authy. Appen giver dig engangs-adgangskoder (OTP'er) til brug ved signering. Hver OTP er gyldig i 30 sekunder.
    OTP i Authy
Tip: Du kan bruge eSigner til at dele organisationsvaliderede (OV) signeringscertifikater mellem holdkammerater. Læs venligst Teamdeling til eSigner-dokument og EV-kodesigneringscertifikater for at få vejledning.

Valgfrit: Konverter dit OV-dokumentsigneringscertifikat til et plomberingscertifikat

Bemærk: Denne sektion er kun for brugere, der ønsker at udføre forsegling. For at automatisere dokumentsignering og ikke blive bedt om af One Time Passwords (OTP), konverterer brugere selv deres Organization Validation (OV) dokumentsigneringscertifikat til et eseling-certifikat på deres SSL.com-konti. Vær opmærksom på, at et certifikat for individuel validering (IV) ikke kan konverteres til forsegling. Instruktioner til forsegling af konvertering er detaljeret nedenfor:

  1. Klik Mine Ordrer i topmenuen på din SSL.com-konto. 
  2. Find dit certifikat, og klik på download / detaljer .
  3. Klik på knappen FJERN 2FA .

Installer Postman og Import API-samlinger

Instruktionerne i dette afsnit er kun til Postman-brugere. Hvis du bruger cURL med CSC API, kan du gå videre til næste afsnit.

  1. Download og pakk ud CSC API Postman-samling og Document Signing API Postman-samling (Se https://www.postman.com/sslcom for online SSL.com API-samlinger).
    Postbudsamlinger
  2. Download og installer Postbudets REST-klient.
    Postmand REST Client download
  3. Start Postman, og opret derefter en ny Postman-konto, eller log ind på en eksisterende.
    Postbogs login
  4. Klik på knappen Importere .
    Import-knap
  5. Klik på knappen Upload filer knap, naviger til de udpakkede API-indsamlingsfiler (csc-api-prod.postman_collection.json og document-signing-api-prod.postman_collection.json), og åbn dem.
    Upload filer
  6. Klik på knappen Importere .
    Klik på importknappen
  7. De API-anmodninger, du vil arbejde med, er nu tilgængelige i Kollektioner fanen i venstre side af postbudvinduet.
    API-anmodninger

Hent adgangstoken

Det næste trin er at hente et adgangstoken fra SSL.com. Du skal bruge din kunde-id tilgængelig samt brugernavn og adgangskode til din SSL.com-konto. Adgangstokener er gyldige i en time, efter at de er udstedt.

Brug de klikbare faner nedenfor for at vælge instruktioner til Postbrevet eller cURL:

Postmand InstruktionerCURL-instruktioner
  1. Vælg en API-anmodning fra CSC API-samlingen.
    vælg API-anmodning
  2. Vælg Tilladelse Fanebladet og vælg OAuth 2.0 fra Type menu.
    Fanen Autorisation
  3. Indtast følgende oplysninger i formularen:
    • Header-præfiks: Bearer
    • Token Navn: SSLCOM CSC (eller ethvert andet let at huske navn, som du foretrækker)
    • Tilskudstype: Authorization Code
    • URL til tilbagekaldelse: https://upload.esigner.com
    • Godkend ved hjælp af browser: ukontrolleret
    • Godkend URL:  https://login.ssl.com/oauth2/authorize til produktionsmiljø; https://oauth-sandbox.ssl.com/oauth2/authorize til sandkassemiljø.
    • Adgangstoken-URL: https://login.ssl.com/oauth2/token til produktionsmiljø; https://oauth-sandbox.ssl.com/oauth2/token til sandkassemiljø. 
    • Klient-id: [Dit klient-id]
    • Klienthemmelighed: [Din klienthemmelighed]
    • Anvendelsesområde: service
    • Tilstand: [Efterlad blank]
    • Klientgodkendelse: Send as Basic Auth header

    Når du er færdig, skal du klikke på Få nyt adgangstoken .
    Få nyt adgangstoken

  4. En loginformular vises. Indtast dit SSL.com-brugernavn og din adgangskode, og klik derefter på Medlem Login .
    Konto login
  5. Dit nye adgangstoken skal vises i Postman. Vælg adgangstokenteksten, og kopier den til udklipsholderen, og luk derefter Administrer adgangstokens dialog boks. Indsæt dit adgangstoken i en teksteditor, hvor du nemt kan få adgang til det. Hvert adgangstoken udløber efter en time.
    Du kan også gemme dit token til genbrug i Postman-anmodninger, men vi har fundet ud af, at det er mest pålideligt at kopiere og indsætte tokenet direkte i hver anmodning.
    Adgang Token
  1. Brug følgende kommando til at anmode om et adgangstoken. Erstat værdierne vist i ALL-CAPS med dine faktiske værdier:
    curl --location --request POST "https://login.ssl.com/oauth2/token" \ --header "Content-Type: application/json" \ --data-raw '{ "client_id" : "DIN -KLIENT-ID", "client_secret" : "DIN-KUNDE-HEMMELIG", "grant_type" : "adgangskode", "brugernavn" : "DIT-BRUGERNAVN", "adgangskode" : "DIT-ADGANGSKODE" }'
  2. Du skal modtage et JSON-objekt, der indeholder et adgangstoken og et opdateringstoken. Kopier adgangstokenværdien for at indsætte i dine API-anmodninger. Du behøver ikke opdateringstokenet til disse eksempler.
    Hent adgangstoken

Skriv en Hash

Nu hvor du har et adgangstoken, kan du begynde at stille API-anmodninger og oprette signaturer. Dette afsnit fører dig gennem de fem tilgængelige anmodninger i Postman CSC-samlingen, hvilket resulterer i oprettelsen af ​​en digital signatur fra en dokumenthash.

SHA 256-algoritmen skal bruges til at beregne hashen i PDF-dokumentet. 

  1. Et PDF-bibliotek er nødvendigt for at manipulere PDF'en til hash-input og senere indlejre PKCS#7 i PDF-dokumentet. (eks. ApachePDFBox i Java). 
  2. Et kryptobibliotek til at skabe PKCS#7 ud af rå signaturer modtaget fra eSigner API (f.eks. BouncyCastle i Java).

Få CSC Info (valgfri)

Postmand InstruktionerCURL-instruktioner
  1. Du kan bruge CSC info anmodning om at få oplysninger om SSL.coms cloud signatur-tjeneste. Bemærk, at i modsætning til de andre i samlingen kræver denne anmodning ikke dit adgangstoken. Vælg for at sende anmodningen CSC info fra CSC API samling, og klik derefter på Send .
    Send anmodning om CSC -oplysninger
  2. Oplysninger om cloud-signaturtjenesten vises i et JSON-objekt i Postman's Respons felt.
    CSC info
  1. Brug følgende kommando til at få information om SSL.com's CSC API-tjeneste. Hvis du er i sandkassemiljø, brug https://cs-try.ssl.com/csc/v0/info i stedet. 
    curl --location --quest POST "https://cs.ssl.com/csc/v0/info" \ --header "Content-Type: application / json" \ --data-raw "{}"
  2. Du modtager et JSON-objekt med detaljer om tjenesten:
    Få CSC-oplysninger

CSC legitimationsoplysninger

 CSC legitimationsoplysninger anmodning henter en legitimationsoplysninger, du vil bruge i senere API-anmodninger.

Postmand InstruktionerCURL-instruktioner
  1. Type CSC legitimationsoplysninger og klik på Tilladelse fane.
    Fanen Autorisation
  2. Vælg Bærertoken fra Type menuen, indsæt dit adgangstoken i Polet , og klik derefter på Send .
    Send anmodning om legitimationsoplysninger
  3. Et JSON-objekt med en liste over legitimations-id'er, der er knyttet til brugeren, vises i Respons Mark. Din liste indeholder sandsynligvis én værdi. Kopier og indsæt dit legitimations-id i en teksteditor til brug i senere anmodninger.
    Legitimations-id'er
  1. Indtast følgende kommando. (Erstat MY-ACCESS-TOKEN med dit faktiske adgangstoken). Hvis du er i sandkassemiljø, så brug https://cs-try.ssl.com/csc/v0/credentials/list i stedet:
    krøll - placering - anmodning POST "https://cs.ssl.com/csc/v0/credentials/list" \ --header "Content-Type: application / json" \ --header "Autorisation: Bearer MY- ADGANGSTOKEN "\ --data-raw" {} "

    Hvis du bruger et eseal-certifikat (dokumentsigneringscertifikat med kun organisationsoplysninger; inkluderet med din gratis esigner.com-konto), skal du inkludere "clientData": "DS_ESEAL" (bemærk: eseals kræver ikke OTP-godkendelse). Andre muligheder for "clientData" er "EVCS" for EV Code Signing og "DS" (standard) for IV eller IV+OV Document Signing:

    curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/list" \ --header "Content-Type: application/json" \ --header "Autorisation: Bearer MY- ACCESS-TOKEN" \ --data-raw '{"clientData": "DS_ESEAL"}'
  2. Du skal modtage et JSON-objekt med en liste over legitimations-id'er, der er knyttet til brugeren. Din liste indeholder sandsynligvis én værdi. Kopier og indsæt dit legitimations-id i en teksteditor til brug i senere anmodninger.
    Legitimations-id'er

Info om CSC-legitimationsoplysninger (valgfri)

Info om CSC-legitimationsoplysninger anmodning returnerer certifikater og andre oplysninger tilknyttet et legitimations-id og er ikke påkrævet for signering.

Postmand InstruktionerCURL-instruktioner
  1. Vælg for at bruge denne anmodning Info om CSC-legitimationsoplysninger fra samlingen, og klik på Tilladelse fane.
    fanen autorisation
  2. Vælg Bærertoken fra Type menuen, og indsæt derefter dit adgangstoken i Polet felt.
    Indsæt token
  3. Vælg Fylde fanen, og indsæt derefter dit legitimations-id som værdien for credentialID.
    Indsæt legitimations-id
  4. Klik på knappen Send .
    Send
  5. Et JSON-objekt med din signaturcertifikatkæde og andre oplysninger vises i Respons felt.
    Oplysninger om legitimationsoplysninger
  1. Indtast følgende kommando. Hvis du er i sandkassemiljøet, brug https://cs-try.ssl.com/csc/v0/credentials/info  udskifte MY-ACCESS-TOKEN og MY-CREDENTIAL-ID med dine faktiske oplysninger:
    curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/info" \ --header "Content-Type: application/json" \ --header "Autorisation: Bearer MY- ACCESS-TOKEN" \ --data-raw '{ "credentialID": "MY-CREDENTIAL-ID", "certificates": "chain", "certInfo": true, "authInfo": true }'
  2. Du skal modtage et JSON-objekt med din signaturcertifikatkæde og andre oplysninger:
    Info om CSC-legitimationsoplysninger

Legitimationsoplysninger Godkend

Legitimationsoplysninger Godkend anmodning henter tilladelse til at underskrive en hash.

Postmand InstruktionerCURL-instruktioner
  1. Begynd med at vælge Legitimationsoplysninger Godkend fra samlingen og klikke på Tilladelse fane.
    Fanen Autorisation
  2. Vælg Bærertoken fra Type menuen, og indsæt derefter dit adgangstoken i Polet felt.
    indsæt token
  3. Vælg Fylde fanen. Indsæt dit legitimations-id som credentialID værdi og en hash af det dokument, du vil underskrive som hash værdi. Hent og indtast en OTP fra din godkendelsesapp, og indtast den som værdien for OTP, og klik derefter på Send knap. Bemærk: OTP er ikke påkrævet for at forsegle certifikater.
    Fanen Krop
  4. Et JSON-objekt med dine signaturaktiveringsdata (SAD) vises i Respons Mark. Kopier og indsæt denne værdi i en teksteditor til brug i anmodningen om hashsignering.
    SAD
  1. Brug følgende kommando. Erstatte MY-ACCESS-TOKEN, MY-CREDENTIAL-IDog MY-HASH med dine faktiske oplysninger. Få en engangskodeord fra din 2FA-applikation, og brugen er som værdien for MY-OTP. Bemærk: OTP er ikke påkrævet for at forsegle certifikater.
    curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/authorize" \ --header "Content-Type: application/json" \ --header "Autorisation: Bearer MY- ACCESS-TOKEN" \ --data-raw '{ "credentialID": "MY-CREDENTIAL-ID", "numSignatures": 1, "hash": [ "MY-HASH" ], "OTP": "MIN-OTP " }'
  2. Du skal modtage et JSON-objekt med dine signaturaktiveringsdata (SAD). Kopier og indsæt denne værdi i et teksteditor til brug i anmodningen om hashsignering.
    Legitimationsoplysninger Godkend

Underskriv Hash

Nu er du klar til at underskrive dokumentets hash.

Postmand InstruktionerCURL-instruktioner
  1. Type Underskriv Hash fra samlingen, og vælg derefter Tilladelse fane.
    Fanen Autorisation
  2. Vælg Bærertoken fra Type menuen, og indsæt derefter dit adgangstoken i Polet felt.
    Indsæt token
  3. Vælg Fylde fanen. Indsæt dit legitimations-id som credentialID værdi, dine signaturaktiveringsdata som SAD værdi og en hash af det dokument, du vil underskrive som hash værdi, og klik derefter på Send .
    Fanen Krop
  4. Et JSON-objekt med din signatur vises i Respons felt.
    underskrift
  1. Indtast følgende kommando. Erstatte MY-ACCESS-TOKENMY-CREDENTIAL-ID, MY-SADog MY-HASH med dine faktiske oplysninger:
    curl --location --request POST "https://cs.ssl.com/csc/v0/signatures/signHash" \ --header "Content-Type: application/json" \ --header "Autorisation: Bearer MY- ACCESS-TOKEN" \ --data-raw '{ "credentialID": "MY-CREDENTIAL-ID", "SAD": "MIN-SAD", "hash": [ "MY-HASH" ], "signAlgo": "1.2.840.113549.1.1.11" }'
  2. Du skal modtage et JSON-objekt, der indeholder din signatur.
    Tegn hash

Skriv en PDF

Ud over at underskrive dokumenthasker kan du også uploade og underskrive en PDF-fil.

Når du underskriver en PDF, arbejder du med to POST-anmodninger:

  • Upload PDF-dokument
  • Underskriv PDF-dokument

Dokumentsignering API -samling

Du kan genbruge den legitimationsoplysninger, du har hentet ovenfor med CSC legitimationsoplysninger anmodning. Du bliver sandsynligvis også nødt til at hente en ny adgangstoken.

Upload PDF-dokument

Postmand InstruktionerCURL-instruktioner
  1. Vælg Upload PDF-dokument anmodning og klik på Tilladelse fane.
    Fanen Autorisation
  2. Vælg Bærertoken fra Type menuen, og indsæt derefter dit adgangstoken i Polet felt.
    Indsæt token
  3. Vælg Headers fanen og indsæt dit legitimations-id i Værdi kolonne.
    Fanen Overskrifter
  4. Vælg Fylde fanebladet og klik på knappen × siden hello.pdf for at fjerne dette pladsholderfilnavn.
    fjern eksempel filnavn
  5. Klik på knappen Vælg fil knappen, og naviger derefter til den fil, du vil uploade.
    Vælg fil
  6. Klik på knappen Send .
    Send
  7. Vælg og kopier id værdi i svaret, der skal bruges i den næste anmodning.
    ID
  1. Brug følgende kommando. Erstatte MY-CREDENTIAL-ID, MY-ACCESS-TOKENog /PATH/TO/FILE.pdf med dine faktiske oplysninger:
    curl --location --quest POST "https://ds.ssl.com/v1/pdf/upload" \ --header "Credential-Id: MY-CREDENTIAL-ID" \ --header "Autorisation: Bearer MY- ACCESS-TOKEN "\ --header" Content-Type: application / pdf "\ --data-binary" @ / PATH / TO / FILE.pdf "
  2. Du modtager et JSON-objekt med en værdi for id. Kopier denne værdi til brug i den næste anmodning.
    Upload PDF

Bemærk: For synlige signaturer henvises til følgende HTTP-anmodningsoverskrifter (/v1/pdf/upload):

Anmodningshoved

Beskrivelse

Legitimations-id

Unikt legitimations-id tildelt nøglen – obligatorisk

Underskrivelse-grund

Tilføj underskriftsgrund for at tilføje i signaturudseende og også i signaturordbog – Valgfrit, f.eks. godkender jeg dette dokument

Signering-Placering

Tilføj signeringssted i signaturordbogen – Valgfrit, f.eks. Houston, Texas

Kontaktoplysninger

Tilføj kontaktoplysninger i signaturordbog – Valgfrit, f.eks. Telefonnummer

Signatur-felt-position

Signaturfeltposition, hvor visuel signatur vises. Formatet er "x,y,bredde,højde" - Valgfri

Sidenummer

Sidenummer, hvor signaturen skal tegnes – Valgfrit

Hånd-signatur

Base64-kodet PNG-billede af håndsignatur – valgfrit


Underskriv PDF-dokument

Nu kan du underskrive PDF'en.

OTP -autorisation er ikke påkrævet, når der signeres ved hjælp af et esealing -dokumentsigneringscertifikat. Ignorer alle OTP -parametre i den følgende vejledning, hvis du bruger et esealing -dokument, der signerer certifikat.
Postmand InstruktionerCURL-instruktioner
  1. Vælg Upload PDF-dokument anmodning og klik på Tilladelse fane.
       Tilladelse
  2. Vælg Bærertoken fra Type menuen, og indsæt derefter dit adgangstoken i Polet felt.
    Indsæt token
  3. Vælg fanen Krop, indsæt i id værdi fra det forrige trin og en OTP fra din godkendelsesapp, og klik derefter på Send .
    Send anmodning
  4. PDF-dataene vises nedenfor i Respons Mark. Vælge Gem i en fil fra Gem svar menuen, og giv derefter filen et navn.
    Gem PDF i fil
  5. Åbn filen i Acrobat for at bekræfte, at filen er underskrevet.
    Gyldig underskrift
  1. Indtast følgende kommando. Erstatte MY-CREDENTIAL-ID, MY-FILE-IDog OUTPUT-FILENAME med dine faktiske oplysninger. Få en engangskodeord (OTP) fra din 2FA-app, og indtast den som MY-OTP. Bemærk: OTP er ikke påkrævet for at forsegle certifikater:
    curl --location --quest POST 'https://ds.ssl.com/v1/pdf/sign' \ --header 'Content-Transfer-Encoding: application / json' \ --header 'Content-Type: application / json '\ --header' Autorisation: Bearer MY-ACCESS-TOKEN '\ --data-raw' {"id": "MY-FILE-ID", "otp": "MY-OTP"} '\ - -output OUTPUT-FILENAME
  2. cURL downloader den underskrevne fil og gemmer den i det filnavn, du har angivet:
    Signer PDF
  3. Åbn PDF-filen i Acrobat eller Acrobat Reader for at kontrollere, at signaturen er gyldig.
    Gyldig signatur

Twitter
Facebook
LinkedIn
Reddit
E-mail

Hold dig informeret og sikker

SSL.com er en global leder inden for cybersikkerhed, PKI og digitale certifikater. Tilmeld dig for at modtage de seneste industrinyheder, tips og produktmeddelelser fra SSL.com.

Vi vil meget gerne have din feedback

Tag vores undersøgelse og fortæl os dine tanker om dit seneste køb.