In deze handleiding wordt uitgelegd hoe u een bestelling voor een certificaat voor ondertekening van documenten registreert bij SSL.com eSigner service en gebruik de Cloud Signature Consortium (CSC) API om een document-hash en een pdf-bestand digitaal te ondertekenen. U kunt deze gids met beide gebruiken Krul or Postbode We raden Postman-gebruikers aan om het desktop-app voor het doornemen van de voorbeelden. De voorbeelden in deze handleiding zijn beide van toepassing op de productie- en testomgevingen van SSL.com voor eSigner en eSealing. Verschillen in commando's tussen productie- en testmodi worden in de volgende secties uitgelegd.
Om deze instructies te volgen heeft u nodig:
- Een gevalideerde bestelling voor het ondertekenen van documenten. Gelieve te lezen deze how-to voor volledige instructies over bestellen en valideren.
- A klant-ID (ook bekend als een Applicatie ID. Raadpleeg deze how-to voor instructies over het genereren van deze referentie).
Bestel uw SSL.com Document Signing Certificaat
Hoe u een certificaat bestelt in de productieomgeving
Raadpleeg dit gidsartikel voor instructies over het bestellen van een ondertekeningscertificaat voor productiedocumenten: Bestelproces voor certificaten voor code- en documentondertekening
Een testcertificaat bestellen op de Sandbox van SSL.com
SSL.com biedt een speciale Sandbox-omgeving, die onze live SSL.com-portal en SWS API weerspiegelt, voor een risicovrije experimenteerruimte. Met deze “laboratorium”-instelling kunnen gebruikers de diensten van SSL.com verkennen en testen zonder dat ze zich zorgen hoeven te maken over verstoringen of daadwerkelijke kosten.
Het artikel, De SSL.com Sandbox gebruiken voor testen en integratie, helpt u bij het navigeren door het proces van het aanmaken van een Sandbox-account, het initiëren van een testbestelling en het integreren van de Sandbox met de SWS API.
Nadat u uw testcertificaat heeft aangemaakt, neemt u contact op met het ondersteuningsteam van SSL.com om het te laten valideren. U kunt dit doen door op de online chatknop rechtsonder in het scherm te klikken SSL.com website of door een e-mail te sturen naar support@ssl.com.
Schrijf u in voor eSigner en stel twee-factorenauthenticatie in
Voordat u de CSC API kunt gaan gebruiken, moet u zich aanmelden voor de eSigner-cloudondertekeningsservice van SSL.com. Gevalideerde bestellingen kunnen worden geregistreerd in eSigner door de onderstaande instructies te volgen:
- . Navigeer naar de Bestellingen tab in uw SSL.com-account in en zoek uw bestelling.
- Klik op de bestelling gegevens link.
- Maak een en bevestig een 4-cijferige pincode en klik op het PIN maken knop.
Als u uw eSigner-pincode opnieuw moet instellen, lees dan a.u.b. deze how-to.
- Er verschijnt een QR-code.
De volgende keer dat u de pagina opnieuw laadt, is de QR-code niet zichtbaar. Als u uw eSigner QR-code moet bekijken of resetten, lees dan a.u.b. deze how-to.
- Scan de code in een 2-factor authenticatie-app op uw mobiele apparaat, zoals Google Authenticator or Authy De app geeft u eenmalige wachtwoorden (OTP's) die u kunt gebruiken bij het ondertekenen. Elke OTP is 30 seconden geldig.
Optioneel: Converteer uw OV-documentondertekeningscertificaat naar een zegelcertificaat
Opmerking: Deze sectie is alleen bedoeld voor gebruikers die willen sealen. Om het ondertekenen van documenten te automatiseren en niet te worden gevraagd door eenmalige wachtwoorden (OTP), converteren gebruikers zelf hun Organization Validation (OV) documentondertekeningscertificaat naar een verzegelingscertificaat op hun SSL.com-accounts. Houd er rekening mee dat een documentondertekeningscertificaat voor individuele validatie (IV) niet kan worden geconverteerd voor verzegeling. Instructies voor de conversie van afdichtingen worden hieronder beschreven:
- Klik Bestellingen in het bovenste menu van uw SSL.com-account.
- Zoek uw certificaat en klik op de download / details link.
- Klik op de VERWIJDER 2FA knop.
Installeer Postman en importeer API-verzamelingen
De instructies in deze sectie zijn alleen voor Postman-gebruikers. Als u cURL gebruikt met de CSC API, kunt u naar de volgende sectie gaan.
- Download en pak het uit CSC API Postman-collectie en Document Signing API Postman-collectie (Zie https://www.postman.com/sslcom voor online SSL.com API-verzamelingen).
- Download en installeer de Postman REST-client.
- Start Postman en maak vervolgens een nieuw Postman-account aan of log in op een bestaand account.
- Klik op de import knop.
- Klik op de Upload bestanden knop, navigeer naar de uitgepakte API-verzamelingsbestanden (
csc-api-prod.postman_collection.jsonendocument-signing-api-prod.postman_collection.json), en open ze.
- Klik op de import knop.
- De API-verzoeken waarmee u gaat werken, zijn nu beschikbaar in het Collecties tab aan de linkerkant van het Postman-venster.
Toegangstoken ophalen
De volgende stap is om een toegangstoken op te halen bij SSL.com. Je hebt je klant-ID beschikbaar, evenals de gebruikersnaam en het wachtwoord voor uw SSL.com-account. Toegangstokens zijn één uur geldig nadat ze zijn uitgegeven.
Gebruik de klikbare tabbladen hieronder om instructies voor Postman of cURL te kiezen:
- Selecteer een API-verzoek uit de CSC API-collectie.
- Selecteer het autorisatie Tab en selecteer OAuth 2.0 van het Type menu.
- Voer de volgende informatie in het formulier in:
- Koptekstvoorvoegsel:
Bearer - Token Naam:
SSLCOM CSC(of een andere gemakkelijk te onthouden naam die u verkiest) - Soort subsidie:
Authorization Code - Terugbel-URL:
https://upload.esigner.com - Autoriseren via browser: ongehinderd
- Verificatie-URL:
https://login.ssl.com/oauth2/authorizevoor Productieomgeving;https://oauth-sandbox.ssl.com/oauth2/authorizevoor Sandbox-omgeving. - Toegangstoken-URL:
https://login.ssl.com/oauth2/tokenvoor Productieomgeving;https://oauth-sandbox.ssl.com/oauth2/tokenvoor Sandbox-omgeving. - Klant identificatie: [Uw klant-ID]
- Cliëntgeheim: [Uw klantgeheim]
- Domein:
service - Staat: [Leeg laten]
- Clientverificatie:
Send as Basic Auth header
Als u klaar bent, klikt u op het Krijg een nieuw toegangstoken knop.
- Koptekstvoorvoegsel:
- Er verschijnt een inlogformulier. Voer uw SSL.com gebruikersnaam en wachtwoord in en klik op het Leden knop.
- Uw nieuwe toegangstoken zou in Postman moeten verschijnen. Selecteer de toegangstoken-tekst en kopieer deze naar het klembord en sluit het Beheer toegangstokens dialoog venster. Plak uw toegangstoken in een teksteditor waar u deze gemakkelijk kunt openen. Elk toegangstoken vervalt na een uur.
U kunt uw token ook opslaan voor hergebruik in Postman-verzoeken, maar we hebben geconstateerd dat het het meest betrouwbaar is om het token rechtstreeks in elk verzoek te kopiëren en te plakken.
- Gebruik de volgende opdracht om een toegangstoken aan te vragen. Vervang de waarden die in HOOFDLETTERS worden weergegeven door uw werkelijke waarden:
curl --location --request POST "https://login.ssl.com/oauth2/token" \ --header "Content-Type: application/json" \ --data-raw '{ "client_id" : "UW -CLIENT-ID", "client_secret" : "UW-KLANT-GEHEIM", "grant_type" : "password", "username" : "YOUR-USERNAME", "password" : "UW-WACHTWOORD" }' - U zou een JSON-object moeten ontvangen met een toegangstoken en een vernieuwingstoken. Kopieer de waarde van het toegangstoken om in uw API-verzoeken te plakken. U hebt het vernieuwingstoken niet nodig voor deze voorbeelden.
Teken een hash
Nu u een toegangstoken heeft, kunt u beginnen met het doen van API-verzoeken en het maken van handtekeningen. Dit gedeelte leidt u door de vijf beschikbare verzoeken in de Postman CSC-collectie, wat resulteert in het maken van een digitale handtekening op basis van een documenthash.
- Er is een PDF-bibliotheek nodig om de PDF te manipuleren voor hash-invoer en later de PKCS#7 in het PDF-document in te sluiten. (bijvoorbeeld ApachePDFBox in Java).
- Een cryptobibliotheek voor het maken van PKCS#7 op basis van onbewerkte handtekeningen ontvangen van de eSigner API (bijv. BouncyCastle in Java).
CSC-info opvragen (optioneel)
- U kunt gebruik maken van de CSC-info verzoek om informatie over de cloudhandtekeningservice van SSL.com. Merk op dat dit verzoek, in tegenstelling tot de andere in de collectie, uw toegangstoken niet vereist. Selecteer om het verzoek te verzenden CSC-info van het CSC-API verzameling en klik vervolgens op het Verzenden knop.
- Informatie over de cloud-handtekeningservice wordt weergegeven in een JSON-object in Postman's antwoord veld.
- Gebruik de volgende opdracht om informatie te krijgen over de CSC API-service van SSL.com. Als u zich in een sandbox-omgeving bevindt, gebruikt u
https://cs-try.ssl.com/csc/v0/infogebruiken.
curl --location --request POST "https://cs.ssl.com/csc/v0/info" \ --header "Content-Type: application / json" \ --data-raw "{}" - U ontvangt een JSON-object met details over de service:
CSC-referentieslijst
De CSC-referentieslijst request haalt een referentie op die u in latere API-verzoeken zult gebruiken.
- kies CSC-referentieslijst En klik op de knop autorisatie Tab.
- Kies Token aan toonder van het Type menu, plak je toegangstoken in het Token veld en klik vervolgens op Verzenden knop.
- Een JSON-object met een lijst met referentie-ID's die aan de gebruiker zijn gekoppeld, wordt weergegeven in het antwoord veld. Uw lijst bevat waarschijnlijk één waarde. Kopieer en plak uw identificatie-ID in een teksteditor voor gebruik in latere verzoeken.
- Voer de volgende opdracht in. (Vervang MY-ACCESS-TOKEN door uw huidige toegangstoken). Als u zich in een sandbox-omgeving bevindt, gebruikt u
https://cs-try.ssl.com/csc/v0/credentials/listin plaats daarvan:
curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/list" \ --header "Content-Type: application / json" \ --header "Autorisatie: Bearer MY- ACCESS-TOKEN "\ --data-raw" {} "Als u een eseal-certificaat gebruikt (certificaat voor documentondertekening met alleen organisatie-informatie; inbegrepen bij uw gratis esigner.com-account), voeg dan "clientData" toe: "DS_ESEAL" (opmerking: voor eseals is geen OTP-authenticatie vereist). Andere opties voor “clientData” zijn “EVCS” voor EV Code Signing en “DS” (standaard) voor IV of IV+OV Document Signing:
curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/list" \ --header "Content-Type: application/json" \ --header "Autorisatie: Drager MIJN- TOEGANG TOKEN" \ --data-raw '{"clientData": "DS_ESEAL"}' - U zou een JSON-object moeten ontvangen met een lijst met referentie-ID's die aan de gebruiker zijn gekoppeld. Uw lijst bevat waarschijnlijk één waarde. Kopieer en plak uw identificatie-ID in een teksteditor voor gebruik in latere verzoeken.
CSC-inloggegevens (optioneel)
De CSC-inloggegevens request retourneert certificaten en andere informatie die aan een identificatie-ID is gekoppeld en is niet vereist voor ondertekening.
- Selecteer om dit verzoek te gebruiken CSC-inloggegevens uit de verzameling en klik op het autorisatie Tab.
- Kies Token aan toonder van het Type menu en plak vervolgens uw toegangstoken in het Token veld.
- Selecteer het Lichaam tabblad en plak vervolgens uw referentie-ID als de waarde voor
credentialID.
- Klik op de Verzenden knop.
- Een JSON-object met uw handtekeningcertificaatketen en andere informatie verschijnt in het antwoord veld.
- Voer de volgende opdracht in. Als u zich in de sandbox-omgeving bevindt, gebruikt u
https://cs-try.ssl.com/csc/v0/credentials/infovervangenMY-ACCESS-TOKENenMY-CREDENTIAL-IDmet uw actuele informatie:
curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/info" \ --header "Content-Type: application/json" \ --header "Autorisatie: Drager MIJN- ACCESS-TOKEN" \ --data-raw '{ "credentialID": "MY-CREDENTIAL-ID", "certificates": "chain", "certInfo": true, "authInfo": true }' - U zou een JSON-object moeten ontvangen met uw handtekeningcertificaatketen en andere informatie:
Inloggegevens autoriseren
De Inloggegevens autoriseren request haalt autorisatie op voor het ondertekenen van een hash.
- Begin met selecteren Inloggegevens autoriseren uit de verzameling en klik op de autorisatie Tab.
- Kies Token aan toonder van het Type menu en plak vervolgens uw toegangstoken in het Token veld.
- Selecteer het Lichaam tabblad. Plak uw referentie-ID als het
credentialIDwaarde en een hash van het document dat u wilt ondertekenen als dehashwaarde. Haal een OTP op van uw authenticatie-app en voer deze in als de waarde voorOTP, klik dan op de knop Verzenden knop. Opmerking: OTP is niet vereist voor het verzegelen van certificaten.
- Een JSON-object met uw Signature Activation Data (SAD) verschijnt in het antwoord veld. Kopieer en plak deze waarde in een teksteditor voor gebruik in het verzoek om hash-ondertekening.
- Gebruik de volgende opdracht. Vervangen
MY-ACCESS-TOKEN,MY-CREDENTIAL-IDenMY-HASHmet uw actuele informatie. Ontvang een eenmalig wachtwoord van uw 2FA-applicatie en gebruik dit als de waarde voorMY-OTP. Opmerking: OTP is niet vereist voor het verzegelen van certificaten.
curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/authorize" \ --header "Content-Type: application/json" \ --header "Autorisatie: Drager MIJN- ACCESS-TOKEN" \ --data-raw '{ "credentialID": "MY-CREDENTIAL-ID", "numSignatures": 1, "hash": [ "MY-HASH" ], "OTP": "MY-OTP " }' - U zou een JSON-object moeten ontvangen met uw Signature Activation Data (SAD). Kopieer en plak deze waarde in een teksteditor voor gebruik in het verzoek om hash-ondertekening.
Teken Hash
Nu bent u klaar om de document-hash te ondertekenen.
- kies Teken Hash uit de verzameling en selecteer vervolgens het autorisatie Tab.
- Kies Token aan toonder van het Type menu en plak vervolgens uw toegangstoken in het Token veld.
- Selecteer het Lichaam tabblad. Plak uw referentie-ID als het
credentialIDwaarde, uw handtekeningactiveringsgegevens als deSADwaarde en een hash van het document dat u wilt ondertekenen als dehashwaarde en klik vervolgens op het Verzenden knop.
- Een JSON-object met uw handtekening verschijnt in het antwoord veld.
- Voer de volgende opdracht in. Vervangen
MY-ACCESS-TOKEN,MY-CREDENTIAL-ID,MY-SADenMY-HASHmet uw actuele informatie:
curl --location --request POST "https://cs.ssl.com/csc/v0/signatures/signHash" \ --header "Content-Type: application/json" \ --header "Autorisatie: Drager MIJN- ACCESS-TOKEN" \ --data-raw '{ "credentialID": "MY-CREDENTIAL-ID", "SAD": "MY-SAD", "hash": [ "MY-HASH" ], "signAlgo": "1.2.840.113549.1.1.11" }' - U zou een JSON-object moeten ontvangen met uw handtekening.
Teken een pdf
Naast het ondertekenen van document-hashes, kunt u ook een pdf-bestand uploaden en ondertekenen.
Bij het ondertekenen van een pdf werkt u met twee POST-verzoeken:
- Upload PDF-document
- Teken PDF-document
U kunt de inloggegevens die u hierboven heeft opgehaald opnieuw gebruiken met de CSC-referentieslijst verzoek. U zult waarschijnlijk ook een nieuw toegangstoken.
Upload PDF-document
- Selecteer het Upload PDF-document verzoek en klik op het autorisatie Tab.
- Kies Token aan toonder van het Type menu en plak vervolgens uw toegangstoken in het Token veld.
- Selecteer het Headers tabblad en plak uw referentie-ID in het Waarde kolom.
- Selecteer het Lichaam Tab en klik op de knop × naast
hello.pdfom deze tijdelijke bestandsnaam te verwijderen.
- Klik op de Selecteer bestand knop en navigeer vervolgens naar het bestand dat u wilt uploaden.
- Klik op de Verzenden knop.
- Selecteer en kopieer het
idwaarde in het antwoord dat in het volgende verzoek moet worden gebruikt.
- Gebruik de volgende opdracht. Vervangen
MY-CREDENTIAL-ID,MY-ACCESS-TOKENen/PATH/TO/FILE.pdfmet uw actuele informatie:
curl --location --request POST "https://ds.ssl.com/v1/pdf/upload" \ --header "Credential-Id: MY-CREDENTIAL-ID" \ --header "Autorisatie: Bearer MY- ACCESS-TOKEN "\ --header" Content-Type: application / pdf "\ --data-binary" @ / PATH / TO / FILE.pdf "
- U ontvangt een JSON-object met een waarde voor
id Kopieer deze waarde om te gebruiken in de volgende aanvraag.
Opmerking: Raadpleeg voor zichtbare handtekeningen de volgende HTTP-verzoekheaders (/v1/pdf/upload):
|
Referentie-ID |
Unieke referentie-ID toegewezen aan de sleutel – Verplicht |
|
Ondertekeningsreden: |
Voeg ondertekeningsreden toe om toe te voegen in handtekeningweergave en ook in handtekeningwoordenboek - Optioneel, bijv. Ik keur dit document goed |
|
Ondertekenlocatie |
Voeg ondertekeningslocatie toe aan handtekeningwoordenboek – Optioneel, bijv. Houston, Texas |
|
Contact informatie |
Voeg contactgegevens toe aan het handtekeningwoordenboek - Optioneel, bijv. Telefoonnummer |
|
Handtekening-veld-positie |
Handtekeningveldpositie waar visuele handtekening wordt weergegeven. Het formaat is "x,y,breedte,hoogte" - Optioneel |
|
Paginanummer |
Paginanummer waar handtekening te trekken – Optioneel |
|
Hand-handtekening |
Base64-gecodeerde PNG-afbeelding van handhandtekening - Optioneel |
Teken PDF-document
Nu kunt u de pdf ondertekenen.
- Selecteer het Upload PDF-document verzoek en klik op het autorisatie Tab.
- Kies Token aan toonder van het Type menu en plak vervolgens uw toegangstoken in het Token veld.
- Selecteer het tabblad Body, plak in het
idwaarde uit de vorige stap en een OTP van uw authenticatie-app, en klik vervolgens op het Verzenden knop.
- De PDF-gegevens verschijnen hieronder in het antwoord veld. Kiezen Opslaan in een bestand van het Sla reactie op menu en geef het bestand een naam.
- Open het bestand in Acrobat om te bevestigen dat het bestand is ondertekend.
- Voer de volgende opdracht in. Vervangen
MY-CREDENTIAL-ID,MY-FILE-IDenOUTPUT-FILENAMEmet uw actuele informatie. Haal een eenmalig wachtwoord (OTP) van uw 2FA-app en voer het in alsMY-OTP. Opmerking: OTP is niet vereist voor het verzegelen van certificaten:
curl --location --request POST 'https://ds.ssl.com/v1/pdf/sign' \ --header 'Content-Transfer-Encoding: application / json' \ --header 'Content-Type: applicatie / json '\ --header' Autorisatie: Bearer MY-ACCESS-TOKEN '\ --data-raw' {"id": "MY-FILE-ID", "otp": "MY-OTP"} '\ - -output OUTPUT-FILENAME - cURL downloadt het ondertekende bestand en slaat het op onder de bestandsnaam die je hebt opgegeven:
- Open de pdf in Acrobat of Acrobat Reader om te controleren of de handtekening geldig is.
