Encryption and password editing with the wsclient library

Here we want to show you the Security operation of the ToolboxWebServices of webPDF and their use with the wsclient library.

Important note:

The following coding example is based on the use of the webPDF wsclient library. In order to understand and apply the example, the following blog post should be considered first:

webPDF and Java: very easy with the “wsclient” library

Creating a REST or SOAP Session

To be able to call the Webservice, you should first have created a REST or SOAP session and therefore be able to create either a ToolboxWebService object (for a SOAP session) by calling the WebServiceFactory:

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

..or a ToolboxRestWebService object (for a REST session):

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

..and passed either a RestDocument or a SoapDocument object to this WebService object by calling the method setDocument(). Please also note our blog posts about REST and SOAP.

Webservice Parameters

To get changing access to a document, it is often necessary to give the current open and/or permission password of the document to the webservice call. You can do this directly at the created ToolboxWebService object:

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

If the document does not have an appropriate password protection, you can skip this point.

The Toolbox Webservice

The Toolbox Webservice is an endpoint of your webPDF server that summarizes a number of operations with which you can directly manipulate your PDF document. One of these operations is the Security Operation, which we would like to discuss here.

The Security operation allows you to change the security and access settings, as well as the encryption of a PDF document.

You add a security operation to your WebService object as follows:

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

The parameterization of the operation takes place on the Security object created here.

The encrypt mode

The first mode of the security operation allows you to add or change security settings to a PDF document. To use this mode, first create an EncryptType object as follows and add it to the operation:

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

The following parameters can be set on the Encrypt object:

canAssemble (default value: false)

If this boolean value is set to true, the viewer of the document is allowed to modify it. For example, to delete, insert or rotate pages.

If it is set to false, it is not allowed to do so.

encrypt.setCanAssemble(true);

canExtractContent (default value: false)

If this boolean value is set to true, the viewer of the document is allowed to extract and copy content.

If he is set to false, he is not allowed to do so.

encrypt.setCanExtractContent(true);

canExtractContentForAccessibility (default value: false)

If this boolean value is set to true, the viewer of the document is permitted to extract and copy content for the purpose of accessibility.

If the viewer is set to false, this is not permitted.

encrypt.setCanExtractForAccessibility(true);

canFillInForm (default value: false)

If this boolean value is set to true, the viewer of the document is allowed to fill out forms and sign the document.

If set to false, the viewer is not allowed to do so.

encrypt.setCanFillInForm(true);

canModify (default value: false)

If this boolean value is set to true, the viewer of the document is allowed to modify and adapt the contents of the document pages.

If he is set to false, he is not allowed to do so.

encrypt.setCanModify(true);

canModifyAnnotations (default value: false)

If this boolean value is set to true, the viewer of the document is allowed to edit and change annotations and annotations of the document.

If set to false, the viewer is not allowed to do so.

encrypt.setCanModifyAnnotations(true);

canPrint (default value: false)

If this boolean value is set to true, the viewer of the document is allowed to print the document.

If it is set to false, it is not allowed to do so.

encrypt.setCanPrint(true);

canPrintHighRes (default value: false)

If this boolean value is set to true, the viewer of the document is allowed to print the document in high resolution.

If it is set to false, it is not permitted to do so.

encrypt.setCanPrintHighRes(true);

The object Password (encrypt mode)

The Password object can be set for encrypt mode to set a password and encryption for the document.

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

encryptionKey (default value: “RC4_128”)

This value is used to select the encryption method with which the document is to be encrypted. The following values can be set here:

• 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);

Please note that the option “256 bit AES” only works if the “Java Cryptography Extension (JCE)” with “Unlimited Strength” is activated in the JVM. You can get the changed “Policy Files” (with installation instructions) on the 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 (default value: „“)

Sets the password that is requested when the PDF document is opened for reading.

password.setOpen("password");

permission (default value: „“)

Sets the password that is requested when the file is opened for editing (e.g. when removing pages). The password is required for activating the individual access rights and must not be empty if the access rights are to be set.

password.setPermission("password");

While the open password is actually necessary to open and decrypt the document at all, the enforcement of the permission password is absolutely dependent on the display program or editor used. The protection provided by the permission password is therefore only partially reliable.

The “decrypt” mode

The second mode of the Security operation allows you to remove any form of encryption from the document and thus decrypt it. This mode does not require any additional parameters.

security.setDecrypt(new DecryptType());

Webservice call example

Here we would like to show an even more detailed example of our entire webservice call (for addressing the SOAP interface):

try (
    // Setup of a session with the webPDF server (here SOAP):
    SoapSession session = SessionFactory.createInstance(
        WebServiceProtocol.SOAP,
        new URL("https://localhost:8080/webPDF/")
    );
    // Make available the document to be processed
    // and the file in which the result is to be written:
    SoapDocument soapDocument = new SoapDocument(
        new File("Path of the source document").toURI(),
        new File("Path of the target document")
    )
) {
    // Selection of the webservice via a factory::
    ToolboxWebService toolboxWebService =
        WebServiceFactory.createInstance(
            session, WebServiceType.TOOLBOX
        );
    toolboxWebService.setDocument(soapDocument);
    toolboxWebService.getPassword().setOpen("password");
    toolboxWebService.getPassword().setPermission("password");

    // Object oriented parameterization of the call:
    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");
    // Execution.
    toolboxWebService.process();

} catch (ResultException | MalformedURLException ex) {
    // To evaluate possible errors that may have occurred, the
    // wsclient library appropriate methods are available:
}

WebPDF Documentation

Please also refer to our user manual, which contains the corresponding documentation. In addition, you will find a documentation of the error codes and any errors that may occur. (Please also note: All parameters are preset with default values. If such a default value is specified and does not deviate from your desired value, it is not mandatory to set this parameter.)

More coding examples for webservices that you can use with the ws-client library can be found here.