Encryption and password editing with the wsclient library

Minimum technical requirements​

• Java version: 7
• webPDF version: 7
• wsclient version: 1

In this article, we present the Security operation of the Toolbox web services from webPDF and show how to use it with the wsclient library.

Important note: The following coding example is based on the webPDF wsclient library.

Creating a REST or SOAP Session​

To call the web service, you should first create a REST or SOAP session. Via WebServiceFactory, you can then create either a ToolboxWebService object for SOAP or a ToolboxRestWebService object for REST.

SOAP:

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

REST:

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

Via setDocument(), you pass either a RestDocument or a SoapDocument to the web service object.

Further reading:

• REST: Using the REST interface via webPDF wsclient
• SOAP: Using the SOAP interface via webPDF wsclient

Webservice parameters​

For write access to a document, it is often necessary to provide the current open and/or permission password to the web service call. You can do this directly on 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 bundles operations for directly modifying PDF documents. One of these operations is Security.

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 lets you add or change security settings for a PDF document. To use this mode, first create an EncryptType object 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 it is set to false, this is not permitted.

encrypt.setCanExtractContent(true);

canExtractContentForAccessibility (default value: false)​

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

If it 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 it is set to false, this is not permitted.

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 is used in encrypt mode to define password protection 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 AES_256 only works if the Java Cryptography Extension (JCE) with "Unlimited Strength" is enabled in the JVM.

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​

Below is a more detailed example of the full web service call for the SOAP interface:

try (
    SoapSession session = SessionFactory.createInstance(
        WebServiceProtocol.SOAP,
        new URL("https://localhost:8080/webPDF/")
    );
    SoapDocument soapDocument = new SoapDocument(
        new File("Path of the source document").toURI(),
        new File("Path of the target document")
    )
) {
    ToolboxWebService toolboxWebService =
        WebServiceFactory.createInstance(session, WebServiceType.TOOLBOX);

    toolboxWebService.setDocument(soapDocument);

    SecurityType security = new SecurityType();
    EncryptType encrypt = new EncryptType();
    EncryptType.Password password = new EncryptType.Password();

    password.setEncryptionKey(PdfEncryptionKeyType.AES_128);
    password.setOpen("password");
    password.setPermission("password");

    encrypt.setPassword(password);
    encrypt.setCanPrint(true);
    encrypt.setCanModify(false);

    security.setEncrypt(encrypt);
    toolboxWebService.getOperation().add(security);
} catch (ResultException | MalformedURLException ex) {
    // error handling
}

WebPDF Documentation​

Please also refer to the user manual with the documentation for the Security parameter structure as well as the documentation for error codes and possible errors.

Note: All parameters are preset with default values. If a default value already matches the intended behavior, the parameter does not need to be set explicitly.

More coding examples for web services that you can use with the wsclient library can be found here.