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
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.
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:
- . Naviger til Mine ordre fanen i SSL.com-kontoen din og finn bestillingen din.
- Klikk på ordren detaljer kobling.
- 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. - 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. - 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.
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:
- Klikk Mine ordre på toppmenyen til SSL.com-kontoen din.
- Finn sertifikatet ditt og klikk på nedlastings / detaljer kobling.
- Klikk på FJERN 2FA knapp.
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.
- 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).
- Last ned og installer Postmann REST Client.
- Start Postman, og opprett deretter en ny Postman-konto eller logg deg på en eksisterende.
- Klikk på Import knapp.
- Klikk på Last opp filer , naviger til de utpakkede API-samlingsfilene (
csc-api-prod.postman_collection.json
ogdocument-signing-api-prod.postman_collection.json
), og åpne dem.
- Klikk på Import knapp.
- API-forespørslene du vil jobbe med er nå tilgjengelig i Kategorier på venstre side av Postmann-vinduet.
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:
- Velg en API-forespørsel fra CSC API-samlingen.
- Velg autorisasjon Fanen og velg OAuth 2.0 fra typen menyen.
- 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.
- Topptekst:
- Et påloggingsskjema vises. Skriv inn SSL.com brukernavnet og passordet ditt, og klikk deretter på Medlem Logg inn knapp.
- 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.
- 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" }'
- 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.
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.
- 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).
- Et kryptobibliotek for å lage PKCS#7 ut av rå signaturer mottatt fra eSigner API (eks. BouncyCastle i Java).
Få CSC-informasjon (valgfritt)
- 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.
- Informasjon om skysignaturtjenesten vil vises i et JSON-objekt i Postmans Respons feltet.
- 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 "{}"
- Du vil motta et JSON-objekt med detaljer om tjenesten:
CSC legitimasjonsliste
De CSC legitimasjonsliste forespørsel vil hente en legitimasjon du vil bruke i senere API-forespørsler.
- Plukke ut CSC legitimasjonsliste og klikk på autorisasjon fanen.
- Velg Bærertoken fra typen menyen, lim inn tilgangstokenet i Pollett og klikk deretter på sent knapp.
- 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.
- 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"}'
- 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.
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.
- Velg for å bruke denne forespørselen Informasjon om CSC-legitimasjon fra samlingen og klikk på autorisasjon fanen.
- Velg Bærertoken fra typen menyen, og lim deretter inn tilgangstokenet i Pollett feltet.
- Velg Body kategorien, og lim deretter inn påloggings-ID-en din som verdien for
credentialID
.
- Klikk på sent knapp.
- Et JSON-objekt med signeringssertifikatkjeden og annen informasjon vises i Respons feltet.
- Skriv inn følgende kommando. Hvis du er i sandkassemiljøet, bruk
https://cs-try.ssl.com/csc/v0/credentials/info
ErstattMY-ACCESS-TOKEN
ogMY-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 }'
- Du bør motta et JSON-objekt med signeringssertifikatkjeden og annen informasjon:
Legitimasjonsgodkjenning
De Legitimasjonsgodkjenning forespørsel vil hente autorisasjon for signering av en hash.
- Begynn med å velge Legitimasjonsgodkjenning fra samlingen og klikke på autorisasjon fanen.
- Velg Bærertoken fra typen menyen, og lim deretter inn tilgangstokenet i Pollett feltet.
- Velg Body kategorien. Lim inn legitimasjons-ID-en din som
credentialID
verdi og en hash av dokumentet du vil signere somhash
verdi. Hent og skriv inn en OTP fra autentiseringsappen din, og skriv den inn som verdien forOTP
, klikk deretter på sent knapp. Merk: OTP er ikke nødvendig for å forsegle sertifikater.
- 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.
- Bruk følgende kommando. Erstatte
MY-ACCESS-TOKEN
,MY-CREDENTIAL-ID
ogMY-HASH
med din faktiske informasjon. Få et engangspassord fra 2FA-applikasjonen din, og bruk er som verdien forMY-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 " }'
- 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.
Signer Hash
Nå er du klar til å signere dokumenthashen.
- Plukke ut Signer Hash fra samlingen, og velg deretter autorisasjon fanen.
- Velg Bærertoken fra typen menyen, og lim deretter inn tilgangstokenet i Pollett feltet.
- Velg Body kategorien. Lim inn legitimasjons-ID-en din som
credentialID
verdi, blir dine signaturaktiveringsdata somSAD
verdi, og en hash av dokumentet du vil signere somhash
verdi, og klikk deretter på sent knapp.
- Et JSON-objekt med signaturen din vises i Respons feltet.
- Skriv inn følgende kommando. Erstatte
MY-ACCESS-TOKEN
,MY-CREDENTIAL-ID
,MY-SAD
ogMY-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" }'
- Du bør motta et JSON-objekt som inneholder signaturen din.
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
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
- Velg Last opp PDF-dokument forespørsel og klikk på autorisasjon fanen.
- Velg Bærertoken fra typen menyen, og lim deretter inn tilgangstokenet i Pollett feltet.
- Velg Headers kategorien og lim inn legitimasjons-ID-en din i Verdi kolonne.
- Velg Body kategorien og klikk på × ved siden av
hello.pdf
for å fjerne dette plassholderfilnavnet.
- Klikk på Velg Fil , og naviger deretter til filen du vil laste opp.
- Klikk på sent knapp.
- Velg og kopier
id
verdi i svaret som skal brukes i neste forespørsel.
- Bruk følgende kommando. Erstatte
MY-CREDENTIAL-ID
,MY-ACCESS-TOKEN
og/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 "
- Du vil motta et JSON-objekt med en verdi for
id
. Kopier denne verdien for å bruke i neste forespørsel.
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.
- Velg Last opp PDF-dokument forespørsel og klikk på autorisasjon fanen.
- Velg Bærertoken fra typen menyen, og lim deretter inn tilgangstokenet i Pollett feltet.
- Velg kategorien Body, lim inn i
id
verdien fra forrige trinn og en OTP fra autentiseringsappen din, og klikk deretter på sent knapp.
- PDF-dataene vises nedenfor i Respons felt. Velge Lagre i en fil fra Lagre svar menyen, og gi filen et navn.
- Åpne filen i Acrobat for å bekrefte at filen er signert.
- Skriv inn følgende kommando. Erstatte
MY-CREDENTIAL-ID
,MY-FILE-ID
ogOUTPUT-FILENAME
med din faktiske informasjon. Få et engangspassord (OTP) fra 2FA-appen din, og skriv den inn somMY-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
- cURL vil laste ned den signerte filen og lagre den i filnavnet du spesifiserte:
- Åpne PDF-filen i Acrobat eller Acrobat Reader for å kontrollere at signaturen er gyldig.