webPDF Webservices Signature
Minimum technical requirements
- Java version: 7
- webPDF version: 7
- wsclient version: 1
Signatur auf PDF-Dokumenten anbringen
Wenn Sie die Operation des webPDF Webservices Signature nutzen möchten, dann haben Sie die Möglichkeit, diese mittels der webPDF wsclient Bibliothek zu verwenden.
Wichtiger Hinweis:
Das nun folgende Coding-Beispiel beruht auf der Nutzung der webPDF wsclient Bibliothek. Um das Beispiel zu verstehen und anzuwenden, sollte zunächst folgender Blogbeitrag beachtet werden:
Vorbereitungen für Webservice Signature
Zunächst sollten Sie bereits eine REST- oder SOAP-Session erzeugt haben und über den Aufruf der WebserviceFactory entweder ein SignatureWebService Objekt (für eine SOAP Session)
SignatureWebService signatureWebService = WebServiceFactory.createInstance(session, WebServiceType.SIGNATURE);
..oder ein SignatureRestWebService Objekt (für eine REST Session) erzeugen können:
SignatureRestWebService signatureWebService = WebServiceFactory.createInstance(session, WebServiceType.SIGNATURE);
Außerdem sollten Sie diesem WebService Objekt über Aufruf der Methode setDocument() entweder ein RestDocument oder ein SoapDocument Objekt übergeben haben.
Was ist der Signature Webservice?
Der Signature Webservice ist ein Endpunkt des webPDF Servers, der das Hinzufügen von Signaturen zu PDF-Dokumenten ermöglicht.
Die Signature Operation vom Typ SignatureType können Sie neu initialisieren und im Webservice setzen oder die automatisch generierte Instanz des Webservices nutzen.
SignatureType signatureType = signatureWebService.getOperation();
Für die ConverterType Instanz lassen sich folgende Parameter setzen:
Das Objekt „add“
In diesem Objekt werden alle Einstellungen das Hinzufügen einer Signatur gesetzt.
SignatureType.Add add = new SignatureType.Add(); signatureType.setAdd(add);
appendSignature (Standardwert: true)
Mit dem Parameter wird angegeben, ob eine vorhandene Unterschrift ersetzt werden soll.
add.setAppendSignature(true);
certificationLevel (Standardwert: „noChanges“)
Mit dem Parameter wird angegeben, die Signaturstufe angegeben. Die möglichen Werte befinden sich im Enum CertificationLevelType und sind:
- CertificationLevelType.NONE
Unterschreiben, aber nicht zertifizieren, des Dokuments – d. h. weitere Unterschriften bzw. Änderungen sind möglich. - CertificationLevelType.NO_CHANGES
Dokument zertifizieren, und keine weiteren Änderungen mehr zulassen. - CertificationLevelType.FORM_FILLING_AND_SIGNATURES
Dokument zertifizieren, aber das Ausfüllen von Feldern erlauben. - CertificationLevelType.FORM_FILLING_AND_SIGNATURES_AND_ANNOTATIONS
Dokument zertifizieren, aber das Ausfüllen von Feldern und das Anbringen von Anmerkungen erlauben.
add.setCertificationLevel(CertificationLevelType.FORM_FILLING_AND_SIGNATURES);
contact (Standardwert: „“)
Mit dem Parameter wird der Name des Unterzeichners angegeben.
add.setContact("John Doe");
fieldName (Standardwert: „Signature1“)
Mit dem Parameter der Name des Feldes, in dem die Signatur enthalten sein wird, angegeben.
add.setFieldName("SignatureField");
keyName (Standardwert: „“)
Definiert den Namen des Schlüssel (Alias), der bei der Unterzeichnung des Dokuments verwendet werden soll. Diese Einstellung überschreibt die Konfigurationseinstellung des Servers. Weitere Informationen finden Sie in der webPDF Doku im Kapitel „Keystore„.
add.setKeyName("keyAlias");
keyPassword (Standardwert: „“)
Definiert das Passwort, das für den Zugriff auf den privaten Schlüssel von „keyName“ benötigt wird. Diese Einstellung überschreibt die Konfigurationseinstellung des Servers. Weitere Informationen finden Sie in der webPDF Doku im Kapitel „Keystore„.
add.setKeyPassword("keyPassword");
reason (Standardwert: „“)
Mit diesem Parameter kann der Grund für das Hinzufügen der Signatur angegeben werden.
add.setReason("demonstration for wsclient blog article");
location (Standardwert: „“)
Mit diesem Parameter kann der Ort für das Hinzufügen der Signatur angegeben werden.
add.setLocation("Main Street 0, Anytown, USA");
Das Objekt „appearence“
In diesem Objekt können Eigenschaften zum visuellen Erscheinungsbild der Signatur festgelegt werden.
SignatureType.Add.Appearance appearance = new SignatureType.Add.Appearance(); add.setAppearance(appearance);
page (Standardwert: 1)
Mit diesem Parameter wird festgelegt auf welcher Seite die Signatur angezeigt wird.
appearance.setPage(1);
identifier (Standardwert: „“)
Text, der im rechten Textfeld der Signatur angezeigt werden soll. Wird kein Wert angegeben, dann stehen dort der Name des Unterschreibers und die Namensbestandteile des Zertifikats.
appearance.setIdentifier("right field of signature text");
name (Standardwert: „“)
Setzt den Text, der im linken Bereich der Signatur angezeigt werden soll. Wird kein Wert angegeben, dann steht dort der Name des Unterschreibers.
appearance.setName("left area of signature");
Das Objekt „identifierElements“
In diesem Objekt werden die Bestandteile der visuellen Signatur festgelegt.
SignatureIdentifierType identifier = new SignatureIdentifierType(); appearance.setIdentifierElements(identifier);
Mit den hier aufgeführten Optionen für das Objekt kann die Anzeige jeweils aktiviert oder deaktiviert werden. Der Standartwert ist jeweils true.
identifier.setShowCommonName(true); identifier.setShowCountry(true); identifier.setShowDate(true); identifier.setShowLocal(true); identifier.setShowMail(true); identifier.setShowName(true); identifier.setShowOrganisationUnit(true); identifier.setShowSignedBy(true); identifier.setShowState(true);
Das Objekt „image“
In diesem Objekt wird eine Grafik für die visuelle Signatur festgelegt, welche im Hintergrund der Signatur gezeichnet wird.
SignatureImageType image = new SignatureImageType(); appearance.setImage(image);
position (Standardwert: „center“)
Legt die Position der Grafik innerhalb des Signature-Feldes fest. Dies wird jeweils mit einem Eintrag des Enums SignatureImagePositionType getätigt.
- SignatureImagePositionType.CENTER – zentrier
- SignatureImagePositionType.LEFT – links
- SignatureImagePositionType.RIGHT – rechts
image.setPosition(SignatureImagePositionType.CENTER);
opacity(Standardwert: 50)
Legt die Deckkraft für die Grafik prozentual fest.
image.setOpacity(60);
Das Objekt „data“
Mit diesem Objekt wird die eigentliche Grafik für das image-Objekt als Base64 übergeben.
SignatureFileDataType imageData = new SignatureFileDataType();
image.setData(imageData);
imageData.setValue(Base64.encodeBase64(FileUtils.readFileToByteArray(new File("image.png"))));
Das Objekt „position“
Mit diesem Objekt wird die Position der visuellen Signatur festgelegt.
SignaturePositionType position = new SignaturePositionType(); appearance.setPosition(position);
x(Standardwert: 10 (Millimeter vom linken Rand))
X-Position des Signaturfeldes.
position.setX(10F);
y(Standardwert: 10 (Millimeter vom unteren Rand))
Y-Position des Signaturfeldes.
position.setY(10F);
width(Standardwert: 80 (Millimeter))
Breite des Signaturfeldes.
position.setWidth(80F);
height(Standardwert: 40 (Millimeter))
Höhe des Signaturfeldes.
position.setHeight(60F);
coordinates (Standardwert: „user“)
Legt das Koordinatensystem und somit den Ursprung für die Angaben mit einem Eintrag des Enums CoordinatesType fest.
- CoordinatesType.USER – User-Koordinatensystem (Ausgangspunkt links oben)
- CoordinatesType.PDF – PDF-Koordinatensystem (Ausgangspunkt links unten)
position.setCoordinates(CoordinatesType.USER);
metrics (Standardwert: „mm“)
Legt die Maßeineit für die Angaben mit einem Eintrag des Enums MetricsType fest.
- MetricsType.MM – Millimeter
- MetricsType.PX – Pixel
position.setMetrics(MetricsType.MM);
Beispiel
Schließlich noch ein Beispiel für einen Webserviceaufruf (für die Ansprache der SOAP Schnittstelle):
try (
// Aufbau einer Session mit dem webPDF Server(hier SOAP):
SoapSession session = SessionFactory.createInstance(
WebServiceProtocol.SOAP,
new URL("https://localhost:8080/webPDF/"));
) {
SignatureWebService signatureWebService = WebServiceFactory.createInstance(session, WebServiceType.SIGNATURE);
SignatureType signatureType = signatureWebService.getOperation();
SignatureType.Add add = new SignatureType.Add();
signatureType.setAdd(add);
add.setReason("webPDF wsclient sample");
add.setLocation("Main Street, Anytown, USA");
add.setContact("Any Company");
add.setCertificationLevel(CertificationLevelType.NO_CHANGES);
add.setKeyName("Generic self-signed certificate");
SignatureType.Add.Appearance appearance = new SignatureType.Add.Appearance();
add.setAppearance(appearance);
SignaturePositionType position = new SignaturePositionType();
position.setX(5.0f);
position.setY(5.0f);
position.setWidth(80.0f);
position.setHeight(15.0f);
appearance.setPosition(position);
SignatureImageType image = new SignatureImageType();
SignatureFileDataType imageData = new SignatureFileDataType();
imageData.setValue(Files.readAllBytes(Paths.get("logo.png")));
image.setData(imageData);
image.setOpacity(40);
appearance.setImage(image);
appearance.setIdentifier("John Doe");
try (
// Bereit stellen des Dokuments, das verarbeitet werden soll
// und der Datei, in die das Ergebnis geschrieben werden soll:
SoapDocument document = new SoapDocument(new File("source.pdf").toURI(), new File("result.pdf"))) {
//Ausführung und schließen der Dokumente
signatureWebService.setDocument(document);
signatureWebService.process().close();
}
}
Mehr Infos:
- Mehr zur Nutzung von REST und SOAP im Blog.
- Hinweis: Die Parameter sind mit bestimmten Standardwerten vorbelegt. Ist ein Standardwert angegeben, welcher nicht von Ihrem gewünschten Wert abweicht, so ist es nicht nötig diesen Parameter zu setzen. Die Parameter finden Sie auch in unserem Nutzerhandbuch dokumentiert: Signature Parameterstruktur
- Beachten Sie auch unsere Blog-Reihe zum Thema Digitale Signatur Teil 1 (Grundlagen und Rechtliches zur Digitalen Signatur), Teil 2 (wie funktioniert die Verschlüsselungstechnik) und Teil 3 (Anleitung: Wie bringt man die Signatur im webPDF-Portal an: Dokumente mit Digitalen Signaturen sichern):
Weitere Coding-Beispiele für Webservices, welche Sie mit der ws-client Bibliothek nutzen können finden Sie hier.