Verschlüsselung und Passwörter bearbeiten mit der wsclient Bibliothek

Hier wollen wir Ihnen die Security Operation der Toolbox Webservices von webPDF vorstellen und deren Nutzung mit der wsclient Bibliothek aufzeigen.

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:

webPDF und Java: mit der „wsclient“ Bibliothek ganz einfach

REST- oder SOAP-Session erzeugen

Um den Webservice aufrufen zu können, sollten Sie zunächst eine REST- oder SOAP-Session erzeugt haben und somit über Aufruf der WebserviceFactory entweder ein ToolboxWebService Objekt (für eine SOAP Session) erzeugen können:

ToolboxWebService toolboxWebService =
    WebServiceFactory.createInstance(
        session, WebServiceType.TOOLBOX
    );

..oder ein ToolboxRestWebService Objekt (für eine REST Session) erzeugen können:

ToolboxRestWebService toolboxWebService =
    WebServiceFactory.createInstance(
        session, WebServiceType.TOOLBOX
    );

..und diesem WebService Objekt über Aufruf der Methode setDocument() entweder ein RestDocument oder ein SoapDocument Objekt übergeben haben. Beachten Sier hier auch unsere Blog-Beiträge zu REST und SOAP.

Webservice Parameter

Gerade um ändernden Zugriff auf ein Dokument zu erhalten, ist es oft nötig dem Webserviceaufruf das aktuelle open und/oder permission Passwort des Dokuments mit zu geben. Dies können Sie direkt am erzeugten ToolboxWebService Objekt tun:

toolboxWebService.getPassword().setOpen("password");
toolboxWebService.getPassword().setPermission("password");

Falls das Dokument nicht über einen entsprechenden Passwortschutz verfügt, so können Sie diesen Punkt überspringen.

Der Toolbox Webservice

Der Toolbox Webservice ist ein Endpunkt ihres webPDF Servers, der eine Reihe von Operationen zusammenfasst, mit denen Sie Ihr PDF Dokument direkt manipulieren können. Eine dieser Operationen ist die Security Operation, die wir hier besprechen möchten.

Die Security Operation ermöglicht es Ihnen, die Sicherheits- und Zugriffseinstellungen, sowie die Verschlüsselung eines PDF Dokuments zu ändern.

Sie fügen Ihrem WebService Objekt wie folgt eine Security Operation hinzu:

SecurityType security = new SecurityType();
toolboxWebService.getOperation().add(security);

Die Parametirisierung der Operation erfolgt am hier erzeugten Objekt Security.

Der Modus “encrypt”

Der erste Modus der Security Operation erlaubt Ihnen, einem PDF Dokument Sicherheitseinstellungen hinzuzufügen, oder diese entsprechend zu verändern. Um diesen Modus zu nutzen, erzeugen Sie zunächst wie folgt ein EncryptType Objekt und fügen es der Operation hinzu:

EncryptType encrypt = new EncryptType();
security.setEncrypt(encrypt);

Am Objekt Encrypt lassen sich folgende Parameter setzen:

canAssemble (Standardwert: false)

Wird dieser boolesche Wert auf true gesetzt, so ist es dem Betrachter des Dokuments gestattet, es umzugestalten. Also zum Beispiel Seiten zu löschen, einzufügen oder zu drehen.

Wird er auf false gesetzt, so ist ihm dies nicht gestattet.

encrypt.setCanAssemble(true);

canExtractContent (Standardwert: false)

Wird dieser boolesche Wert auf true gesetzt, so ist es dem Betrachter des Dokuments gestattet, Inhalte zu entnehmen und zu kopieren.

Wird er auf false gesetzt, so ist ihm dies nicht gestattet.

encrypt.setCanExtractContent(true);

canExtractContentForAccessibility (Standardwert: false)

Wird dieser boolesche Wert auf true gesetzt, so ist es dem Betrachter des Dokuments gestattet, Inhalte zum Zweck der Barrierefreiheit zu entnehmen und zu kopieren.

Wird er auf false gesetzt, so ist ihm dies nicht gestattet.

encrypt.setCanExtractForAccessibility(true);

canFillInForm (Standardwert: false)

Wird dieser boolesche Wert auf true gesetzt, so ist es dem Betrachter des Dokuments gestattet, Formulare auszufüllen und das Dokument zu signieren.

Wird er auf false gesetzt, so ist ihm dies nicht gestattet.

encrypt.setCanFillInForm(true);

canModify (Standardwert: false)

Wird dieser boolesche Wert auf true gesetzt, so ist es dem Betrachter des Dokuments gestattet, Inhalte der Dokumentenseiten zu verändern und anzupassen.

Wird er auf false gesetzt, so ist ihm dies nicht gestattet.

encrypt.setCanModify(true);

canModifyAnnotations (Standardwert: false)

Wird dieser boolesche Wert auf true gesetzt, so ist es dem Betrachter des Dokuments gestattet Anmerkungen und Annotationen des Dokuments zu bearbeiten und zu ändern.

Wird er auf false gesetzt, so ist ihm dies nicht gestattet.

encrypt.setCanModifyAnnotations(true);

canPrint (Standardwert: false)

Wird dieser boolesche Wert auf true gesetzt, so ist es dem Betrachter des Dokuments gestattet, das Dokument auszudrucken.

Wird er auf false gesetzt, so ist ihm dies nicht gestattet.

encrypt.setCanPrint(true);

canPrintHighRes (Standardwert: false)

Wird dieser boolesche Wert auf true gesetzt, so ist es dem Betrachter des Dokuments gestattet, das Dokument hochauflösend auszudrucken.

Wird er auf false gesetzt, so ist ihm dies nicht gestattet.

encrypt.setCanPrintHighRes(true);

Das Objekt „password“ (encrypt Modus)

Das Objekt Password kann für den encrypt Modus gesetzt werden, um ein Passwort und eine Verschlüsselung für das Dokument zu setzen.

EncryptType.Password password = new EncryptType.Password();
encrypt.setPassword(password);

encryptionKey (Standardwert: „RC4_128“)

Über diesen Wert wird das Verschlüsselungsverfahren gewählt, mit dem das Dokument verschlüsselt werden soll. Folgende Werte können hier gesetzt werden:

• RC4_40 = 40 bit RC4
• RC4_128 = 128 bit RC4
• AES_128 = 128 bit AES
• AES_256 = 256 bit AES

password.setEncryptionKey(PdfEncryptionKeyType.AES_128);

Bitte beachten Sie, dass die Option „256 bit AES“ nur funktioniert, wenn die „Java Cryptography Extension (JCE)“ mit „Unlimited Strength“ in der JVM aktiviert ist. Sie bekommen die geänderten „Policy Files“ (mit Anleitung für die Installation) auf der Oracle Website:

Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files 7 Download:

http://www.oracle.com/technetwork/java/javase/downloads/jce-7-download-432124.html

open (Standardwert: „“)

Setzt das Passwort, das abgefragt wird, wenn das PDF-Dokument zum Lesen geöffnet wird.

password.setOpen("password");

permission (Standardwert: „“)

Setzt das Passwort, das abgefragt wird, wenn die Datei zur Bearbeitung geöffnet wird (z. B. beim Entfernen von Seiten). Das Passwort wird für die Aktivierung der einzelnen Zugriffsberechtigungen benötigt und darf nicht leer sein, wenn die Zugriffsberechtigungen gesetzt werden sollen.

password.setPermission("password");

Während das open Passwort tatsächlich notwendig ist, um das Dokument überhaupt öffnen und entschlüsseln zu können, ist die Durchsetzung des Permission Passworts absolut abhängig vom Anzeigeprogramm oder Editor, welcher verwendet wird. Die Schutzfunktion durch das Permission Passwort ist damit nur eingeschränkt zuverlässig.

Der Modus “decrypt”

Der zweite Modus der Security Operation erlaubt Ihnen, jegliche Form von Verschlüsselung aus dem Dokument zu entfernen und es somit zu entschlüsseln. Dieser Modus benötigt keine weiteren Parameter.

security.setDecrypt(new DecryptType());

Beispiel für den Webserviceaufruf

Hier möchten wir ein noch ausführlicheres Beispiel für unseren gesamten Webserviceaufruf (für die Ansprache der SOAP Schnittstelle) zeigen:

try (
    // Aufbau einer Session mit dem webPDF Server(hier SOAP):
    SoapSession session = SessionFactory.createInstance(
        WebServiceProtocol.SOAP,
        new URL("https://localhost:8080/webPDF/")
    );
    // Bereit stellen des Dokuments, das verarbeitet werden soll
    // und der Datei, in die das Ergebnis geschrieben werden soll:
    SoapDocument soapDocument = new SoapDocument(
        new File("Pfad des Quelldokuments").toURI(),
        new File("Pfad des Zieldokuments")
    )
) {
    // Wahl des Webservices über eine Factory:
    ToolboxWebService toolboxWebService =
        WebServiceFactory.createInstance(
            session, WebServiceType.TOOLBOX
        );
    toolboxWebService.setDocument(soapDocument);
    toolboxWebService.getPassword().setOpen("password");
    toolboxWebService.getPassword().setPermission("password");

    // Objektorientierte Parametrisierung des Aufrufs:
    SecurityType security = new SecurityType();
    toolboxWebService.getOperation().add(security);

    EncryptType encrypt = new EncryptType();
    security.setEncrypt(encrypt);
    encrypt.setCanAssemble(true);
    encrypt.setCanExtractContent(true);
    encrypt.setCanExtractForAccessibility(true);
    encrypt.setCanFillInForm(true);

    EncryptType.Password password = new EncryptType.Password();
    encrypt.setPassword(password);
    password.setEncryptionKey(PdfEncryptionKeyType.AES_128);
    password.setOpen("password");
    password.setPermission("password");
    // Ausführung.
    toolboxWebService.process();

} catch (ResultException | MalformedURLException ex) {
    // Zur Auswertung möglicher aufgetretener Fehler, stellt ihnen die
    // wsclient Bibliothek entsprechende Methoden zur Verfügung:
}

WebPDF Dokumentation

Bitte beachten Sie auch unser Nutzerhandbuch, in dem eine entsprechende Dokumentation zu finden ist. Zusätzlich finden Sie dort eine Dokumentation der Errorcodes und möglicherweise auftretenden Fehler. (Beachten Sie bitte auch: Alle Parameter sind mit Standardwerten vorbelegt. Ist ein solcher Standardwert angegeben und weicht er nicht von Ihrem gewünschten Wert ab, so ist es nicht zwingend nötig, diesen Parameter zu setzen.)

Weitere Coding-Beispiele für Webservices, welche Sie mit der ws-client Bibliothek nutzen können finden Sie hier.