In diesem Handbuch erfahren Sie, wie Sie eine Bestellung für ein Dokumentensignaturzertifikat bei SSL.com registrieren eSignierer Service und verwenden Sie die CSC-API (Cloud Signature Consortium), um einen Dokument-Hash und eine PDF-Datei digital zu signieren. Sie können diese Anleitung mit beiden verwenden cURL or Postman. Wir empfehlen Postman-Benutzern, das zu installieren Desktop-App für das Durcharbeiten der Beispiele. Die Beispiele in diesem Handbuch gelten sowohl für die Produktions- als auch für die Test-eSigner- und eSealing-Umgebungen von SSL.com. Unterschiede in den Befehlen zwischen Produktions- und Testmodus werden in den folgenden Abschnitten erläutert.
Um diese Anweisungen zu befolgen, benötigen Sie:
- Eine validierte Bestellung eines Dokumentensignaturzertifikats. Bitte lesen Sie diese Anleitung Für vollständige Anweisungen zur Bestellung und Validierung.
- A Kunden-ID (auch bekannt als Anwendungs-ID. Bitte beziehen Sie sich auf diese Anleitung Anweisungen zum Generieren dieses Berechtigungsnachweises).
Bestellen Sie Ihr SSL.com-Dokumentsignaturzertifikat
So bestellen Sie ein Zertifikat in der Produktionsumgebung
Anweisungen zum Bestellen eines Signaturzertifikats für Produktionsdokumente finden Sie in diesem Leitartikel: Bestellvorgang für Code- und Dokumentensignaturzertifikate
So bestellen Sie ein Testzertifikat in der Sandbox von SSL.com
SSL.com bietet eine dedizierte Sandbox-Umgebung, die unser Live-SSL.com-Portal und die SWS-API widerspiegelt, für einen risikofreien Experimentierraum. Diese „Labor“-Einstellung ermöglicht es Benutzern, die Dienste von SSL.com zu erkunden und zu testen, ohne befürchten zu müssen, dass es zu Störungen kommt oder tatsächliche Kosten anfallen.
Der Artikel, Verwenden der SSL.com-Sandbox zum Testen und Integrieren, hilft Ihnen dabei, den Prozess der Einrichtung eines Sandbox-Kontos, der Initiierung einer Testbestellung und der Integration der Sandbox in die SWS-API zu steuern.
Nachdem Sie Ihr Testzertifikat erstellt haben, wenden Sie sich bitte an das Support-Team von SSL.com, um es validieren zu lassen. Sie können dies tun, indem Sie unten rechts auf die Schaltfläche „Online-Chat“ klicken SSL.com Website oder senden Sie eine E-Mail an support@ssl.com.
Melden Sie sich bei eSigner an und richten Sie die Zwei-Faktor-Authentifizierung ein
Bevor Sie die CSC-API verwenden können, müssen Sie sich beim eSigner-Cloud-Signaturdienst von SSL.com anmelden. Validierte Bestellungen können in eSigner registriert werden, indem Sie die folgenden Anweisungen befolgen:
- . Navigieren Sie zu Bestellungen Tab in Ihrem SSL.com-Konto und suchen Sie Ihre Bestellung.
- Klicken Sie auf die Bestellung Details Link.
- Erstellen Sie eine und bestätigen Sie eine 4-stellige PIN. Klicken Sie dann auf PIN erstellen .
Wenn Sie Ihre eSigner-PIN zurücksetzen müssen, lesen Sie bitte diese Anleitung.
- Ein QR-Code wird angezeigt.
Wenn Sie die Seite das nächste Mal neu laden, wird der QR-Code nicht angezeigt. Wenn Sie Ihren eSigner-QR-Code anzeigen oder zurücksetzen müssen, lesen Sie bitte diese Anleitung.
- Scannen Sie den Code in eine 2-Faktor-Authentifizierungs-App auf Ihrem Mobilgerät, z Google Authenticator or Authy. Die App stellt Ihnen Einmalkennwörter (OTPs) zur Verfügung, die Sie beim Signieren verwenden können. Jedes OTP ist 30 Sekunden lang gültig.
Optional: Konvertieren Sie Ihr OV-Dokumentsignaturzertifikat in ein E-Siegelzertifikat
Hinweis: Dieser Abschnitt ist nur für Benutzer gedacht, die eine E-Versiegelung durchführen möchten. Um das Signieren von Dokumenten zu automatisieren und nicht durch Einmalkennwörter (One Time Passwords, OTP) dazu aufgefordert zu werden, konvertieren Benutzer ihr Organization Validation (OV)-Dokumentsignaturzertifikat selbst in ein E-Versiegelungszertifikat auf ihren SSL.com-Konten. Beachten Sie, dass ein Dokumentsignaturzertifikat mit individueller Validierung (IV) nicht für die Versiegelung konvertiert werden kann. Nachfolgend finden Sie detaillierte Anweisungen zur Esealing-Konvertierung:
- Klicken Sie Bestellungen im oberen Menü Ihres SSL.com-Kontos.
- Suchen Sie Ihr Zertifikat und klicken Sie auf Download / Details Link.
- Klicken Sie auf die 2FA ENTFERNEN .
Installieren Sie Postman und importieren Sie API-Sammlungen
Die Anweisungen in diesem Abschnitt gelten nur für Postman-Benutzer. Wenn Sie cURL mit der CSC-API verwenden, können Sie mit dem nächsten Abschnitt fortfahren.
- Downloaden und entpacken Sie die CSC API Postman-Sammlung und Document Signing API Postman-Sammlung (sehen https://www.postman.com/sslcom für Online-SSL.com-API-Sammlungen).
- Laden Sie die Postbote REST Client.
- Starten Sie Postman und erstellen Sie ein neues Postman-Konto oder melden Sie sich bei einem vorhandenen an.
- Klicken Sie auf die Import .
- Klicken Sie auf die Daten hochladen Klicken Sie auf die Schaltfläche, um zu den entpackten API-Sammlungsdateien zu navigieren (
csc-api-prod.postman_collection.jsonunddocument-signing-api-prod.postman_collection.json) und öffne sie.
- Klicken Sie auf die Import .
- Die API-Anforderungen, mit denen Sie arbeiten, sind jetzt in der verfügbar Kollektionen Registerkarte auf der linken Seite des Postbotenfensters.
Zugriffstoken abrufen
Der nächste Schritt besteht darin, ein Zugriffstoken von SSL.com abzurufen. Du wirst deine brauchen Kunden-ID verfügbar, sowie den Benutzernamen und das Passwort für Ihr SSL.com-Konto. Zugriffstoken sind eine Stunde nach ihrer Ausstellung gültig.
Verwenden Sie die anklickbaren Registerkarten unten, um Anweisungen für Postman oder cURL auszuwählen:
- Wählen Sie eine API-Anforderung aus der CSC-API-Sammlung aus.
- Wähle aus Genehmigung Registerkarte, und wählen Sie OAuth 2.0 von dem Typ Menü.
- Geben Sie die folgenden Informationen in das Formular ein:
- Header-Präfix:
Bearer - Token Name:
SSLCOM CSC(oder einen anderen leicht zu merkenden Namen, den Sie bevorzugen) - Zuschusstyp:
Authorization Code - Rückruf-URL:
https://upload.esigner.com - Mit Browser autorisieren: ungeprüft
- Authentifizierungs-URL:
https://login.ssl.com/oauth2/authorizefür Produktionsumgebung;https://oauth-sandbox.ssl.com/oauth2/authorizefür Sandbox-Umgebung. - Zugriffstoken-URL:
https://login.ssl.com/oauth2/tokenfür Produktionsumgebung;https://oauth-sandbox.ssl.com/oauth2/tokenfür Sandbox-Umgebung. - Kunden ID: [Ihre Kunden-ID]
- Kundengeheimnis: [Ihr Client-Geheimnis]
- Umfang:
service - Bundesland/ Kanton: [freilassen]
- Client-Authentifizierung:
Send as Basic Auth header
Wenn Sie fertig sind, klicken Sie auf Holen Sie sich ein neues Zugangstoken .
- Header-Präfix:
- Ein Anmeldeformular wird angezeigt. Geben Sie Ihren SSL.com-Benutzernamen und Ihr Passwort ein und klicken Sie auf Mitgliederzugang .
- Ihr neues Zugriffstoken sollte in Postman angezeigt werden. Wählen Sie den Zugriffstoken-Text aus, kopieren Sie ihn in die Zwischenablage und schließen Sie die Zugriffstoken verwalten Dialogbox. Fügen Sie Ihr Zugriffstoken in einen Texteditor ein, auf den Sie problemlos zugreifen können. Jeder Zugriffstoken läuft nach einer Stunde ab.
Sie können Ihr Token auch zur Wiederverwendung in Postman-Anfragen speichern. Wir haben jedoch festgestellt, dass es am zuverlässigsten ist, das Token direkt in jede Anfrage zu kopieren und einzufügen.
- Verwenden Sie den folgenden Befehl, um ein Zugriffstoken anzufordern. Ersetzen Sie die in ALL-CAPS angezeigten Werte durch Ihre tatsächlichen Werte:
curl --location --request POST "https://login.ssl.com/oauth2/token" \ --header "Content-Type: application/json" \ --data-raw '{ "client_id" : "IHR -CLIENT-ID", "client_secret" : "IHR-CLIENT-SECRET", "grant_type" : "password", "username" : "IHR-BENUTZERNAME", "password" : "IHR-PASSWORT" }' - Sie sollten ein JSON-Objekt erhalten, das ein Zugriffstoken und ein Aktualisierungstoken enthält. Kopieren Sie den Zugriffstokenwert, um ihn in Ihre API-Anforderungen einzufügen. Für diese Beispiele benötigen Sie das Aktualisierungstoken nicht.
Unterschreibe einen Hash
Nachdem Sie über ein Zugriffstoken verfügen, können Sie API-Anforderungen und Signaturen erstellen. Dieser Abschnitt führt Sie durch die fünf verfügbaren Anforderungen in der Postman CSC-Sammlung, die zur Erstellung einer digitalen Signatur aus einem Dokument-Hash führen.
- Eine PDF-Bibliothek ist erforderlich, um das PDF für die Hash-Eingabe zu bearbeiten und später das PKCS#7 in das PDF-Dokument einzubetten. (z. B. ApachePDFBox in Java).
- Eine Krypto-Bibliothek zum Erstellen von PKCS#7 aus Rohsignaturen, die von der eSigner-API (z. B. BouncyCastle in Java) empfangen wurden.
CSC-Informationen abrufen (optional)
- Sie können die Verwendung CSC-Info Fordern Sie Informationen zum Cloud-Signaturdienst von SSL.com an. Beachten Sie, dass für diese Anforderung im Gegensatz zu den anderen in der Sammlung kein Zugriffstoken erforderlich ist. Um die Anfrage zu senden, wählen Sie CSC-Info von dem CSC-API Sammlung, dann klicken Sie auf die Absenden .
- Informationen zum Cloud-Signaturdienst werden in einem JSON-Objekt in Postman's angezeigt Antwort Feld.
- Verwenden Sie den folgenden Befehl, um Informationen über den CSC-API-Dienst von SSL.com zu erhalten. Wenn Sie sich in einer Sandbox-Umgebung befinden, verwenden Sie
https://cs-try.ssl.com/csc/v0/infostattdessen.
curl --location --request POST "https://cs.ssl.com/csc/v0/info" \ --header "Inhaltstyp: application / json" \ --data-raw "{}" - Sie erhalten ein JSON-Objekt mit Details zum Service:
Liste der CSC-Anmeldeinformationen
Das Liste der CSC-Anmeldeinformationen Die Anforderung ruft einen Berechtigungsnachweis ab, den Sie in späteren API-Anforderungen verwenden werden.
- Select Liste der CSC-Anmeldeinformationen Und klicken Sie auf die Genehmigung Tab.
- Wählen Inhaber-Token von dem Typ Menü, fügen Sie Ihren Zugriffstoken in das Token Klicken Sie auf das Feld Absenden .
- Ein JSON-Objekt mit einer Liste der dem Benutzer zugeordneten Anmeldeinformations-IDs wird in angezeigt Antwort Feld. Ihre Liste wird wahrscheinlich einen Wert enthalten. Kopieren Sie Ihre Anmeldeinformations-ID und fügen Sie sie in einen Texteditor ein, um sie in späteren Anforderungen zu verwenden.
- Geben Sie den folgenden Befehl ein. (Ersetzen Sie MY-ACCESS-TOKEN durch Ihr tatsächliches Zugriffstoken.) Wenn Sie sich in einer Sandbox-Umgebung befinden, verwenden Sie
https://cs-try.ssl.com/csc/v0/credentials/liststattdessen:
curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/list" \ --header "Inhaltstyp: application / json" \ --header "Autorisierung: Inhaber MY- ACCESS-TOKEN "\ --data-raw" {} "Wenn Sie ein eseal-Zertifikat verwenden (Dokumentensignaturzertifikat mit nur Organisationsinformationen; in Ihrem kostenlosen esigner.com-Konto enthalten), dann fügen Sie „clientData“ ein: „DS_ESEAL“ (Hinweis: eseals erfordern keine OTP-Authentifizierung). Andere Optionen für „clientData“ sind „EVCS“ für EV Code Signing und „DS“ (Standard) für IV oder 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"}' - Sie sollten ein JSON-Objekt mit einer Liste der dem Benutzer zugeordneten Anmeldeinformations-IDs erhalten. Ihre Liste wird wahrscheinlich einen Wert enthalten. Kopieren Sie Ihre Anmeldeinformations-ID und fügen Sie sie in einen Texteditor ein, um sie in späteren Anforderungen zu verwenden.
Informationen zu CSC-Anmeldeinformationen (optional)
Das Informationen zu CSC-Anmeldeinformationen Die Anforderung gibt Zertifikate und andere Informationen zurück, die mit einer Anmeldeinformations-ID verknüpft sind, und ist für die Signatur nicht erforderlich.
- Um diese Anforderung zu verwenden, wählen Sie Informationen zu CSC-Anmeldeinformationen aus der Sammlung und klicken Sie auf Genehmigung Tab.
- Wählen Inhaber-Token von dem Typ Menü, dann fügen Sie Ihr Zugriffstoken in das Token Feld.
- Wähle aus Korpus Fügen Sie dann Ihre Anmeldeinformations-ID als Wert für ein
credentialID.
- Klicken Sie auf die Absenden .
- Ein JSON-Objekt mit Ihrer Signaturzertifikatskette und anderen Informationen wird in der angezeigt Antwort Feld.
- Geben Sie den folgenden Befehl ein. Wenn Sie sich in der Sandbox-Umgebung befinden, verwenden Sie
https://cs-try.ssl.com/csc/v0/credentials/infoErsetzenMY-ACCESS-TOKENundMY-CREDENTIAL-IDmit Ihren tatsächlichen Informationen:
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 }' - Sie sollten ein JSON-Objekt mit Ihrer Signaturzertifikatskette und anderen Informationen erhalten:
Anmeldeinformationen autorisieren
Das Anmeldeinformationen autorisieren Die Anforderung ruft die Berechtigung zum Signieren eines Hash ab.
- Beginnen Sie mit der Auswahl Anmeldeinformationen autorisieren aus der Sammlung und klicken Sie auf Genehmigung Tab.
- Wählen Inhaber-Token von dem Typ Menü, dann fügen Sie Ihr Zugriffstoken in das Token Feld.
- Wähle aus Korpus Tab. Fügen Sie Ihre Anmeldeinformations-ID als ein
credentialIDWert und ein Hash des Dokuments, das Sie als signieren möchtenhashWert. Rufen Sie ein OTP aus Ihrer Authentifizierungs-App ab, geben Sie es ein und geben Sie es als Wert für einOTP, Dann klicken Sie auf die Absenden Taste. Hinweis: OTP ist zum Versiegeln von Zertifikaten nicht erforderlich.
- Ein JSON-Objekt mit Ihren Signaturaktivierungsdaten (SAD) wird im angezeigt Antwort Feld. Kopieren Sie diesen Wert und fügen Sie ihn in einen Texteditor ein, um ihn in der Hash-Signaturanforderung zu verwenden.
- Verwenden Sie den folgenden Befehl. Ersetzen
MY-ACCESS-TOKEN,MY-CREDENTIAL-IDundMY-HASHmit Ihren tatsächlichen Informationen. Holen Sie sich ein Einmalkennwort von Ihrer 2FA-Anwendung und verwenden Sie es als Wert fürMY-OTP. Hinweis: OTP ist zum Versiegeln von Zertifikaten nicht erforderlich.
curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/authorize" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer MY- ACCESS-TOKEN" \ --data-raw '{ "credentialID": "MY-CREDENTIAL-ID", "numSignatures": 1, "hash": [ "MY-HASH" ], "OTP": "MY-OTP "}' - Sie sollten ein JSON-Objekt mit Ihren Signaturaktivierungsdaten (SAD) erhalten. Kopieren Sie diesen Wert und fügen Sie ihn in einen Texteditor ein, um ihn in der Hash-Signaturanforderung zu verwenden.
Zeichen Hash
Jetzt können Sie den Dokument-Hash signieren.
- Select Zeichen Hash Wählen Sie dann aus der Sammlung die aus Genehmigung Tab.
- Wählen Inhaber-Token von dem Typ Menü, dann fügen Sie Ihr Zugriffstoken in das Token Feld.
- Wähle aus Korpus Tab. Fügen Sie Ihre Anmeldeinformations-ID als ein
credentialIDWert, Ihre Signaturaktivierungsdaten alsSADWert und ein Hash des Dokuments, das Sie als signieren möchtenhashWert, dann klicken Sie auf die Absenden .
- Ein JSON-Objekt mit Ihrer Signatur wird in der angezeigt Antwort Feld.
- Geben Sie den folgenden Befehl ein. Ersetzen
MY-ACCESS-TOKEN,MY-CREDENTIAL-ID,MY-SADundMY-HASHmit Ihren tatsächlichen Informationen:
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" }' - Sie sollten ein JSON-Objekt erhalten, das Ihre Signatur enthält.
Unterschreiben Sie ein PDF
Neben dem Signieren von Dokument-Hashes können Sie auch eine PDF-Datei hochladen und signieren.
Wenn Sie ein PDF signieren, arbeiten Sie mit zwei POST-Anfragen:
- PDF-Dokument hochladen
- PDF-Dokument unterschreiben
Sie können den oben abgerufenen Berechtigungsnachweis mit dem wiederverwenden Liste der CSC-Anmeldeinformationen Anfrage. Sie müssen wahrscheinlich auch eine neue abrufen Zugangstoken.
PDF-Dokument hochladen
- Wähle aus PDF-Dokument hochladen anfordern und klicken Sie auf die Genehmigung Tab.
- Wählen Inhaber-Token von dem Typ Menü, dann fügen Sie Ihr Zugriffstoken in das Token Feld.
- Wähle aus Headers Klicken Sie auf die Registerkarte und fügen Sie Ihre Anmeldeinformations-ID in das Feld ein Wert Spalte.
- Wähle aus Korpus Registerkarte und klicken Sie auf die × neben
hello.pdfum diesen Platzhalter-Dateinamen zu entfernen.
- Klicken Sie auf die Datei Auswählen Klicken Sie auf die Schaltfläche und navigieren Sie zu der Datei, die Sie hochladen möchten.
- Klicken Sie auf die Absenden .
- Wählen und kopieren Sie die
idWert in der Antwort, der in der nächsten Anforderung verwendet werden soll.
- Verwenden Sie den folgenden Befehl. Ersetzen
MY-CREDENTIAL-ID,MY-ACCESS-TOKENund/PATH/TO/FILE.pdfmit Ihren tatsächlichen Informationen:
curl --location --request POST "https://ds.ssl.com/v1/pdf/upload" \ --header "Berechtigungsnachweis-ID: MY-CREDENTIAL-ID" \ --header "Autorisierung: Inhaber MY- ACCESS-TOKEN "\ --header" Inhaltstyp: application / pdf "\ --data-binary" @ / PATH / TO / FILE.pdf "
- Sie erhalten ein JSON-Objekt mit dem Wert für
id. Kopieren Sie diesen Wert, um ihn in der nächsten Anforderung zu verwenden.
Hinweis: Informationen zu sichtbaren Signaturen finden Sie in den folgenden HTTP-Anforderungsheadern (/v1/pdf/upload):
|
Credential-ID |
Dem Schlüssel zugewiesene eindeutige Anmelde-ID – Obligatorisch |
|
Unterzeichnungsgrund |
Fügen Sie einen Unterzeichnungsgrund hinzu, um das Erscheinungsbild der Unterschrift und auch das Unterschriftenwörterbuch hinzuzufügen – Optional, z. B. Ich stimme diesem Dokument zu |
|
Unterzeichnungsort |
Signierort im Signaturwörterbuch hinzufügen – Optional, z. B. Houston, Texas |
|
Kontaktinformation |
Kontaktinformationen im Signaturwörterbuch hinzufügen – Optional, z. B. Telefonnummer |
|
Signatur-Feld-Position |
Signaturfeldposition, an der die visuelle Signatur angezeigt wird. Das Format ist „x,y,Breite,Höhe“ - Optional |
|
Seitennummer |
Seitenzahl, wo die Unterschrift gezeichnet werden soll – Optional |
|
Handsignatur |
Base64-codiertes PNG-Bild der Handunterschrift – Optional |
PDF-Dokument unterschreiben
Jetzt können Sie das PDF signieren.
- Wähle aus PDF-Dokument hochladen anfordern und klicken Sie auf die Genehmigung Tab.
- Wählen Inhaber-Token von dem Typ Menü, dann fügen Sie Ihr Zugriffstoken in das Token Feld.
- Wählen Sie die Registerkarte Body und fügen Sie sie ein
idWert aus dem vorherigen Schritt und ein OTP aus Ihrer Authentifizierungs-App, klicken Sie dann auf Absenden .
- Die PDF-Daten werden unten in der angezeigt Antwort Feld. Wählen In einer Datei speichern von dem Antwort speichern Menü, dann geben Sie der Datei einen Namen.
- Öffnen Sie die Datei in Acrobat, um zu bestätigen, dass die Datei signiert wurde.
- Geben Sie den folgenden Befehl ein. Ersetzen
MY-CREDENTIAL-ID,MY-FILE-IDundOUTPUT-FILENAMEmit Ihren tatsächlichen Informationen. Holen Sie sich ein Einmalkennwort (OTP) von Ihrer 2FA-App und geben Sie es als einMY-OTP. Hinweis: OTP ist zum Versiegeln von Zertifikaten nicht erforderlich:
curl --location --request POST 'https://ds.ssl.com/v1/pdf/sign' \ --header 'Inhaltsübertragungscodierung: application / json' \ --header 'Inhaltstyp: Anwendung / json '\ --header' Autorisierung: Inhaber MY-ACCESS-TOKEN '\ --data-raw' {"id": "MY-FILE-ID", "otp": "MY-OTP"} '\ - -Ausgabe OUTPUT-FILENAME - cURL lädt die signierte Datei herunter und speichert sie unter dem von Ihnen angegebenen Dateinamen:
- Öffnen Sie die PDF-Datei in Acrobat oder Acrobat Reader, um zu überprüfen, ob die Signatur gültig ist.
