Ekstern dokumentsignering med eSigner CSC API

Se alle guider

Denne veiledningen viser deg hvordan du registrerer en bestillingssertifikatsordre med SSL.com eSigner tjenesten og bruk Cloud Signature Consortium (CSC) API til digital signering av en dokumenthash og en PDF-fil. Du kan bruke denne guiden med begge cURL or Postbud. Vi anbefaler at Postman-brukere installerer desktop app for å jobbe gjennom eksemplene. Eksemplene i denne veiledningen gjelder både for SSL.coms produksjons- og testmiljøer for eSigner og eSealing. Forskjeller i kommandoer mellom produksjons- og testmodus er forklart i de følgende avsnittene.

For å følge disse instruksjonene trenger du:

  • En validert dokumentsigneringssertifikatordre. Vennligst les hvordan du gjør det for fullstendige instruksjoner om bestilling og validering.
  • A kunde-ID (også kjent som en Søknads-ID. Vennligst se hvordan du gjør det for instruksjoner om hvordan du genererer denne legitimasjonen).

Bestill ditt SSL.com-dokumentsigneringssertifikat

Du kan hoppe over denne delen hvis du allerede har et utstedt dokumentsigneringssertifikat. Hvis dette er tilfelle, vennligst fortsett til neste seksjon som diskuterer hvordan du registrerer sertifikatet ditt i eSigner.

Hvordan bestille et sertifikat i produksjonsmiljøet

Se denne veiledningsartikkelen for instruksjoner om hvordan du bestiller et produksjonsdokumentsigneringssertifikat: Bestillingsprosess for kode- og dokumentsigneringssertifikater

Hvordan bestille et testsertifikat på SSL.coms Sandbox

SSL.com tilbyr et dedikert Sandbox-miljø, som gjenspeiler vår live SSL.com-portal og SWS API, for et risikofritt eksperimenteringsrom. Denne "laboratorie"-innstillingen lar brukere utforske og teste SSL.com sine tjenester uten å bekymre seg for å forårsake forstyrrelser eller pådra seg faktiske kostnader. 

Artikkelen, Bruker SSL.com Sandbox for testing og integrering, vil hjelpe deg med å navigere i prosessen med å etablere en Sandbox-konto, starte en testbestilling og integrere Sandbox med SWS API.

Når du har opprettet testsertifikatet, vennligst kontakt SSL.com-støtteteamet for å få det validert. Du kan gjøre dette ved å klikke på nettchat-knappen i nedre høyre hjørne av SSL.com nettsiden eller sende en e-post til support@ssl.com.

Gå til toppen

Registrer deg i eSigner og sett opp tofaktorautentisering

Før du kan begynne å bruke CSC API, må du registrere deg for SSL.coms eSigner skysigneringstjeneste. Validerte bestillinger kan registreres i eSigner ved å følge instruksjonene nedenfor: 

  1. . Naviger til Mine ordre fanen i SSL.com-kontoen din og finn bestillingen din.
    Finn rekkefølgen
  2. Klikk på ordren detaljer kobling.
    detaljer
  3. Opprett en og bekreft en firesifret PIN-kode, og klikk deretter på opprette PIN knapp.
    Hvis du trenger å tilbakestille eSigner-PIN-koden, kan du lese hvordan du gjør det.
    Opprett PIN
  4. En QR-kode vises.
    Neste gang du laster inn siden på nytt, vil ikke QR-koden være synlig. Hvis du trenger å se eller tilbakestille eSigner QR-koden, kan du lese hvordan du gjør det.
    QR kode
  5. Skann koden til en 2-faktor autentiseringsapp på mobilenheten, for eksempel Google Authenticator or Authy. Appen vil gi deg engangspassord (OTP) som du kan bruke når du signerer. Hver OTP er gyldig i 30 sekunder.
    OTP i Authy
Tips: Du kan bruke eSigner til å dele organisasjonsvaliderte (OV) signeringssertifikater mellom lagkamerater. Vennligst les Team Sharing for eSigner Document and EV Code Signing Certificate for instruksjoner.
Gå til toppen

Valgfritt: Konverter signeringssertifikatet for OV-dokumenter til et forseglingssertifikat

OBS: Denne delen er kun for brukere som ønsker å forsegle. For å automatisere dokumentsignering og ikke bli spurt av One Time Passwords (OTP), konverterer brukere selv Organisasjonsvalidering (OV) dokumentsigneringssertifikatet til et eseleringssertifikat på SSL.com-kontoene sine. Vær oppmerksom på at et sertifikat for individuell validering (IV) dokumentsignering ikke kan konverteres for forsegling. Instruksjoner for forsegling av konvertering er detaljert nedenfor:

  1. Klikk Mine ordre på toppmenyen til SSL.com-kontoen din. 
  2. Finn sertifikatet ditt og klikk på nedlastings / detaljer kobling.
  3. Klikk på FJERN 2FA knapp.
Gå til toppen

Installer Postman and Import API Collections

Instruksjonene i denne delen er kun for Postman-brukere. Hvis du bruker cURL med CSC API, kan du gå videre til neste seksjon.

  1. Last ned og pakke ut CSC API Postman-samling og Document Signing API Postman-samling (Se https://www.postman.com/sslcom for online SSL.com API-samlinger).
    Postbudsamlinger
  2. Last ned og installer Postmann REST Client.
    Postman REST Client nedlasting
  3. Start Postman, og opprett deretter en ny Postman-konto eller logg deg på en eksisterende.
    Postmann Login
  4. Klikk på Import knapp.
    Importer-knapp
  5. Klikk på Last opp filer , naviger til de utpakkede API-samlingsfilene (csc-api-prod.postman_collection.json og document-signing-api-prod.postman_collection.json), og åpne dem.
    Last opp filer
  6. Klikk på Import knapp.
    Klikk på importknappen
  7. API-forespørslene du vil jobbe med er nå tilgjengelig i Kategorier på venstre side av Postmann-vinduet.
    API-forespørsler
Gå til toppen

Hent tilgangstoken

Neste trinn er å hente et tilgangstoken fra SSL.com. Du trenger din kunde-ID tilgjengelig, samt brukernavn og passord for SSL.com-kontoen din. Tilgangstokener er gyldige i en time etter at de er utstedt.

Bruk de klikkbare fanene nedenfor for å velge instruksjoner for Postman eller cURL:

PostboksinstruksjonerInstruksjoner for cURL
  1. Velg en API-forespørsel fra CSC API-samlingen.
    velg API-forespørsel
  2. Velg autorisasjon Fanen og velg OAuth 2.0 fra typen menyen.
    Fanen Autorisasjon
  3. Skriv inn følgende informasjon i skjemaet:
    • Topptekst: Bearer
    • Tokenavn: SSLCOM CSC (eller et annet lett å huske navn du foretrekker)
    • Tilskuddstype: Authorization Code
    • URL for tilbakeringing: https://upload.esigner.com
    • Autoriser ved hjelp av nettleser: ukontrollert
    • Godkjennings-URL:  https://login.ssl.com/oauth2/authorize for produksjonsmiljø; https://oauth-sandbox.ssl.com/oauth2/authorize for Sandbox-miljø.
    • Tilgangstoken-URL: https://login.ssl.com/oauth2/token for produksjonsmiljø; https://oauth-sandbox.ssl.com/oauth2/token for Sandbox-miljø. 
    • Klient-ID: [Din klient-ID]
    • Klienthemmelighet: [Din klienthemmelighet]
    • Omfang: service
    • Tilstand: [la stå tom]
    • Klientgodkjenning: Send as Basic Auth header

    Når du er ferdig, klikker du på Få nytt tilgangstoken knapp.
    Få nytt tilgangstoken

  4. Et påloggingsskjema vises. Skriv inn SSL.com brukernavnet og passordet ditt, og klikk deretter på Medlem Logg inn knapp.
    Kontoinnlogging
  5. Det nye tilgangstokenet ditt skal vises i Postman. Velg tilgangstokenteksten og kopier den til utklippstavlen, og lukk deretter Administrer tilgangstokener dialogboks. Lim inn tilgangstokenet ditt i et tekstredigeringsprogram der du enkelt kan få tilgang til det. Hvert tilgangstoken utløper etter en time.
    Du kan også lagre token for gjenbruk i Postman-forespørsler, men vi har funnet ut at det er mest pålitelig å kopiere og lime inn token direkte i hver forespørsel.
    tilgang Token
  1. Bruk følgende kommando for å be om et tilgangstoken. Erstatt verdiene som vises i ALL-CAPS med dine faktiske verdier:
    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-KLIENT-SECRET", "grant_type" : "passord", "brukernavn" : "DITT-BRUKERNAVN", "passord" : "DITT-PASSORD" }'
  2. Du bør motta et JSON-objekt som inneholder et tilgangstoken og et oppdateringstoken. Kopier tilgangstokenverdien for å lime inn i API-forespørslene dine. Du trenger ikke oppdateringstokenet for disse eksemplene.
    Hent tilgangstoken
Gå til toppen

Signer en Hash

Nå som du har tilgangstoken, kan du begynne å gjøre API-forespørsler og opprette signaturer. Denne delen vil lede deg gjennom de fem tilgjengelige forespørslene i Postman CSC-samlingen, noe som resulterer i opprettelsen av en digital signatur fra en dokumenthash.

SHA 256-algoritmen bør brukes til å beregne hashen til PDF-dokumentet. 

  1. Et PDF-bibliotek er nødvendig for å manipulere PDF-en for hash-inndata og senere bygge inn PKCS#7 i PDF-dokumentet. (eks. ApachePDFBox i Java). 
  2. Et kryptobibliotek for å lage PKCS#7 ut av rå signaturer mottatt fra eSigner API (eks. BouncyCastle i Java).

Få CSC-informasjon (valgfritt)

PostboksinstruksjonerInstruksjoner for cURL
  1. Du kan også bruke det CSC -informasjon forespørsel om å få informasjon om SSL.coms nettskytjeneste. Merk at, i motsetning til de andre i samlingen, krever denne forespørselen ikke tilgangstokenet ditt. Velg for å sende forespørselen CSC -informasjon fra CSC API samling, og klikk deretter på sent knapp.
    Send forespørsel om CSC -informasjon
  2. Informasjon om skysignaturtjenesten vil vises i et JSON-objekt i Postmans Respons feltet.
    CSC -informasjon
  1. Bruk følgende kommando for å få informasjon om SSL.coms CSC API-tjeneste. Hvis du er i sandkassemiljø, bruk https://cs-try.ssl.com/csc/v0/info i stedet. 
    curl --location --request POST "https://cs.ssl.com/csc/v0/info" \ --header "Content-Type: application / json" \ --data-raw "{}"
  2. Du vil motta et JSON-objekt med detaljer om tjenesten:
    Få CSC-informasjon

CSC legitimasjonsliste

De CSC legitimasjonsliste forespørsel vil hente en legitimasjon du vil bruke i senere API-forespørsler.

PostboksinstruksjonerInstruksjoner for cURL
  1. Plukke ut CSC legitimasjonsliste og klikk på autorisasjon fanen.
    Autorisasjonsfanen
  2. Velg Bærertoken fra typen menyen, lim inn tilgangstokenet i Pollett og klikk deretter på sent knapp.
    Send forespørsel om legitimasjonsliste
  3. Et JSON-objekt med en liste over legitimasjons-ID-er tilknyttet brukeren vises i Respons felt. Listen din vil sannsynligvis inneholde en verdi. Kopier og lim inn legitimasjons-ID-en din i et tekstredigeringsprogram for bruk i senere forespørsler.
    Legitimasjons-ID
  1. Skriv inn følgende kommando. (Erstatt MY-ACCESS-TOKEN med ditt faktiske tilgangstoken). Hvis du er i sandkassemiljø, bruk https://cs-try.ssl.com/csc/v0/credentials/list i stedet:
    curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/list" \ --header "Content-Type: application / json" \ --header "Authorization: Bearer MY- TILGANGSTOKEN "\ --data-raw" {} "

    Hvis du bruker et eseal-sertifikat (dokumentsigneringssertifikat med kun organisasjonsinformasjon; inkludert med din gratis esigner.com-konto), inkluder deretter "clientData": "DS_ESEAL" (merk: eseals krever ikke OTP-autentisering). Andre alternativer 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 "Autorisasjon: Bearer MY- ACCESS-TOKEN" \ --data-raw '{"clientData": "DS_ESEAL"}'
  2. Du bør motta et JSON-objekt med en liste over legitimasjons-ID-er tilknyttet brukeren. Listen din vil sannsynligvis inneholde en verdi. Kopier og lim inn legitimasjons-ID-en din i et tekstredigeringsprogram for bruk i senere forespørsler.
    Legitimasjons-ID

Informasjon om CSC-legitimasjon (valgfritt)

De Informasjon om CSC-legitimasjon forespørsel vil returnere sertifikater og annen informasjon tilknyttet en legitimasjons-ID, og ​​er ikke nødvendig for signering.

PostboksinstruksjonerInstruksjoner for cURL
  1. Velg for å bruke denne forespørselen Informasjon om CSC-legitimasjon fra samlingen og klikk på autorisasjon fanen.
    autorisasjonsfanen
  2. Velg Bærertoken fra typen menyen, og lim deretter inn tilgangstokenet i Pollett feltet.
    Lim inn token
  3. Velg Body kategorien, og lim deretter inn påloggings-ID-en din som verdien for credentialID.
    Lim inn legitimasjons-ID
  4. Klikk på sent knapp.
    sent
  5. Et JSON-objekt med signeringssertifikatkjeden og annen informasjon vises i Respons feltet.
    Legitimasjonsinformasjon
  1. Skriv inn følgende kommando. Hvis du er i sandkassemiljøet, bruk https://cs-try.ssl.com/csc/v0/credentials/info  Erstatt MY-ACCESS-TOKEN og MY-CREDENTIAL-ID med din faktiske informasjon:
    curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/info" \ --header "Content-Type: application/json" \ --header "Autorisasjon: Bearer MY- ACCESS-TOKEN" \ --data-raw '{ "credentialID": "MY-CREDENTIAL-ID", "certificates": "chain", "certInfo": true, "authInfo": true }'
  2. Du bør motta et JSON-objekt med signeringssertifikatkjeden og annen informasjon:
    Informasjon om CSC-legitimasjon

Legitimasjonsgodkjenning

De Legitimasjonsgodkjenning forespørsel vil hente autorisasjon for signering av en hash.

PostboksinstruksjonerInstruksjoner for cURL
  1. Begynn med å velge Legitimasjonsgodkjenning fra samlingen og klikke på autorisasjon fanen.
    Autorisasjonsfanen
  2. Velg Bærertoken fra typen menyen, og lim deretter inn tilgangstokenet i Pollett feltet.
    lim inn token
  3. Velg Body kategorien. Lim inn legitimasjons-ID-en din som credentialID verdi og en hash av dokumentet du vil signere som hash verdi. Hent og skriv inn en OTP fra autentiseringsappen din, og skriv den inn som verdien for OTP, klikk deretter på sent knapp. Merk: OTP er ikke nødvendig for å forsegle sertifikater.
    Kroppsfane
  4. Et JSON-objekt med signaturaktiveringsdataene dine (SAD) vises i Respons felt. Kopier og lim inn denne verdien i et tekstredigeringsprogram for bruk i hash-signeringsforespørselen.
    SAD
  1. Bruk følgende kommando. Erstatte MY-ACCESS-TOKEN, MY-CREDENTIAL-IDog MY-HASH med din faktiske informasjon. Få et engangspassord fra 2FA-applikasjonen din, og bruk er som verdien for MY-OTP. Merk: OTP er ikke nødvendig for å forsegle sertifikater.
    curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/authorize" \ --header "Content-Type: application/json" \ --header "Autorisasjon: Bearer MY- ACCESS-TOKEN" \ --data-raw '{ "credentialID": "MY-CREDENTIAL-ID", "numSignatures": 1, "hash": [ "MY-HASH" ], "OTP": "MY-OTP " }'
  2. Du bør motta et JSON-objekt med signaturaktiveringsdataene dine (SAD). Kopier og lim inn denne verdien i et tekstredigeringsprogram for bruk i hash-signeringsforespørselen.
    Legitimasjonsgodkjenning

Signer Hash

Nå er du klar til å signere dokumenthashen.

PostboksinstruksjonerInstruksjoner for cURL
  1. Plukke ut Signer Hash fra samlingen, og velg deretter autorisasjon fanen.
    Autorisasjonsfanen
  2. Velg Bærertoken fra typen menyen, og lim deretter inn tilgangstokenet i Pollett feltet.
    Lim inn token
  3. Velg Body kategorien. Lim inn legitimasjons-ID-en din som credentialID verdi, blir dine signaturaktiveringsdata som SAD verdi, og en hash av dokumentet du vil signere som hash verdi, og klikk deretter på sent knapp.
    Kroppsfane
  4. Et JSON-objekt med signaturen din vises i Respons feltet.
    Signatur
  1. Skriv inn følgende kommando. Erstatte MY-ACCESS-TOKEN,  MY-CREDENTIAL-ID, MY-SADog MY-HASH med din faktiske informasjon:
    curl --location --request POST "https://cs.ssl.com/csc/v0/signatures/signHash" \ --header "Content-Type: application/json" \ --header "Autorisasjon: Bearer MY- ACCESS-TOKEN" \ --data-raw '{ "credentialID": "MY-CREDENTIAL-ID", "SAD": "MY-SAD", "hash": [ "MY-HASH" ], "signAlgo": "1.2.840.113549.1.1.11" }'
  2. Du bør motta et JSON-objekt som inneholder signaturen din.
    Tegn hasj
Gå til toppen

Signer en PDF

I tillegg til å signere dokumenthash, kan du også laste opp og signere en PDF-fil.

Når du signerer en PDF, jobber du med to POST-forespørsler:

  • Last opp PDF-dokument
  • Signer PDF-dokument

Samling av API for dokumentsignering

Du kan bruke påloggingsinformasjonen du hentet ovenfor med CSC legitimasjonsliste be om. Du må sannsynligvis også hente en ny tilgangstoken.

Last opp PDF-dokument

PostboksinstruksjonerInstruksjoner for cURL
  1. Velg Last opp PDF-dokument forespørsel og klikk på autorisasjon fanen.
    Autorisasjonsfanen
  2. Velg Bærertoken fra typen menyen, og lim deretter inn tilgangstokenet i Pollett feltet.
    Lim inn token
  3. Velg Headers kategorien og lim inn legitimasjons-ID-en din i Verdi kolonne.
    Overskrift-fanen
  4. Velg Body kategorien og klikk på × ved siden av hello.pdf for å fjerne dette plassholderfilnavnet.
    fjern eksempel filnavn
  5. Klikk på Velg Fil , og naviger deretter til filen du vil laste opp.
    Velg Fil
  6. Klikk på sent knapp.
    sent
  7. Velg og kopier id verdi i svaret som skal brukes i neste forespørsel.
    ID
  1. Bruk følgende kommando. Erstatte MY-CREDENTIAL-ID, MY-ACCESS-TOKENog /PATH/TO/FILE.pdf med din faktiske informasjon:
    curl --location --request POST "https://ds.ssl.com/v1/pdf/upload" \ --header "Credential-Id: MY-CREDENTIAL-ID" \ --header "Authorization: Bearer MY- TILGANGSTOKEN "\ --hode" Innholdstype: applikasjon / pdf "\ --data-binær" @ / PATH / TO / FILE.pdf "
  2. Du vil motta et JSON-objekt med en verdi for id. Kopier denne verdien for å bruke i neste forespørsel.
    Last opp PDF

Merk: For synlige signaturer, se følgende HTTP-forespørselshoder (/v1/pdf/upload):

Forespørselshode

Beskrivelse

Legitimasjons-ID

Unik legitimasjons-ID tildelt nøkkelen – obligatorisk

Signering-grunn

Legg til signeringsgrunn for å legge til i signaturutseende og også i signaturordbok – Valgfritt, f.eks. jeg godkjenner dette dokumentet

Signeringssted

Legg til signeringssted i signaturordbok – Valgfritt, f.eks. Houston, Texas

Kontaktinfo

Legg til kontaktinformasjon i signaturordbok – Valgfritt, f.eks. Telefonnummer

Signatur-felt-posisjon

Signaturfeltposisjon der visuell signatur vises. Formatet er "x,y,bredde,høyde" - Valgfritt

Side nummer

Sidenummer hvor signaturen skal tegnes – Valgfritt

Håndsignatur

Base64-kodet PNG-bilde av håndsignatur – Valgfritt


Signer PDF-dokument

Nå kan du signere PDF-filen.

OTP -autorisasjon er ikke nødvendig når du signerer med et esealing -dokumentsigneringssertifikat. Ignorer alle OTP -parametrene i den følgende veiledningen hvis du bruker et esealing -dokument som signerer sertifikat.
PostboksinstruksjonerInstruksjoner for cURL
  1. Velg Last opp PDF-dokument forespørsel og klikk på autorisasjon fanen.
       autorisasjon
  2. Velg Bærertoken fra typen menyen, og lim deretter inn tilgangstokenet i Pollett feltet.
    Lim inn token
  3. Velg kategorien Body, lim inn i id verdien fra forrige trinn og en OTP fra autentiseringsappen din, og klikk deretter på sent knapp.
    Send forespørsel
  4. PDF-dataene vises nedenfor i Respons felt. Velge Lagre i en fil fra Lagre svar menyen, og gi filen et navn.
    Lagre PDF i fil
  5. Åpne filen i Acrobat for å bekrefte at filen er signert.
    Gyldig signatur
  1. Skriv inn følgende kommando. Erstatte MY-CREDENTIAL-ID, MY-FILE-IDog OUTPUT-FILENAME med din faktiske informasjon. Få et engangspassord (OTP) fra 2FA-appen din, og skriv den inn som MY-OTP. Merk: OTP er ikke nødvendig for å forsegle sertifikater:
    curl --location --request POST 'https://ds.ssl.com/v1/pdf/sign' \ --header 'Content-Transfer-Encoding: application / json' \ --header 'Content-Type: application / json '\ --header' Autorisasjon: Bearer MY-ACCESS-TOKEN '\ --data-raw' {"id": "MY-FILE-ID", "otp": "MY-OTP"} '\ - -utgang OUTPUT-FILENAME
  2. cURL vil laste ned den signerte filen og lagre den i filnavnet du spesifiserte:
    Signer PDF
  3. Åpne PDF-filen i Acrobat eller Acrobat Reader for å kontrollere at signaturen er gyldig.
    Gyldig signatur

Twitter
Facebook
Linkedin
Reddit
Epost

SSL.com Support Team

Forfatter - innholdsadministrator
Alle innlegg »

Hold deg informert og sikker

SSL.com er en global leder innen cybersikkerhet, PKI og digitale sertifikater. Registrer deg for å motta de siste bransjenyhetene, tipsene og produktkunngjøringene fra SSL.com.

Vi vil gjerne ha tilbakemeldinger

Ta vår spørreundersøkelse og fortell oss dine tanker om ditt nylige kjøp.

Ta undersøkelsen