The implementation of security for watermark and redaction annotations allows each layer to have a permission level assigned to it. This permission level is not inherent in the layer and is only defined when the layer is retrieved by the content handler.

In order to assign a permission level to an annotation layer, the content handler must be implemented or extended and the getAnnotationProperties method used.

The annotation security model

The security model is such that when reading annotation layers, various levels of permissions for viewing and working with annotation layers may be specified.

The model currently accounts for nine levels on a per layer basis.

Note: Redaction annotations are only considered redactions when they are burned in and saved as an image format file such as TIFF format.

Permission levels

Each successive level includes the functionality of previous levels. This allow each annotation layer to carry a set of permissions. These permissions allows the layer to be passed in with several different levels of permissions such as read only or edit.

If you are storing the annotations as layers (XML files) with a redaction permission level, then you will be able to present them to the users in the viewer as burned in, but they will not actually be burned into the source document.

Permission Level Actions Permitted
PERM_HIDDEN Hidden The layer is passed to the client but not displayed.
PERM_PRINT_WATERMARK Print Watermark The user does not see the layer, but it will be burned in for printing.
PERM_VIEW_WATERMARK View Watermark The user may view the layer but may not hide the layer.
PERM_VIEW View The user may view or hide the layer.
PERM_PRINT Print The user may print the layer.
PERM_CREATE Create The user may add an object to the layer.
PERM_EDIT Edit The user may also edit an object on the layer, and edit layer properties.
PERM_DELETE Delete The user may also delete an object on the layer, and delete the layer.

Level definitions

Permission Definition
Hidden If a layer is indicated as having the Hidden permission, the information about the layer will be passed, so that changes done by Page Manipulation will be applied when the annotations are saved. The layer is not displayed to the user even if manipulations are applied.
Print Watermark If a layer is indicated as having the Print Watermark permission, it shall be passed as a normal layer, but will not be shown to the user. When the document is printed, any layer with Print Watermark permission will be applied to the image before printing.
View Watermark If a layer is indicated as having the View Watermark permission, it shall be passed as a normal layer. However, the user will not be allowed to show or hide the layer, or manipulate the layer in any way. This layer will never be printed.
View If a layer is indicated as having the View permission, it shall be passed as a normal layer. The user will be able to hide or show the layer. The user will not be able to add an object, edit an object, delete an object, print the layer, rename the layer, or delete the layer.
Print If a layer is indicated as having the Print permission, it shall be passed as a normal layer. The user will be able to hide or show the layer, print the layer. The user will not be able to add an object, edit an object, delete an object, or rename or delete the layer.
Create If a layer is indicated as having the Create permission, it shall be passed as a normal layer. The user will be able to hide or show the layer, print the layer, or add an object to the layer. The user will not be able to edit an object, delete an object, edit the layer properties, or delete the layer.
Edit If a layer is indicated as having the Edit permission, it shall be passed as a normal layer. The user will be able to hide or show the layer, add an object, edit an object, or edit the layer properties. The user will not be able to delete objects or delete the layer.
Delete If a layer is indicated as having the Delete permission, it shall be passed as a normal layer. The user will have full rights to perform any operation on the layer.

Securely retrieving annotation layers

When loading a document, annotation layers will need to be retrieved and have the correct permission level set. The process of loading an annotation layer is as follows:

For each annotationKey returned by getAnnotationNames the following method will be called:

public Hashtable getAnnotationProperties (clientInstanceId, documentKey, annotationKey)

This method returns a hash table with the following expected key/value pairs for that annotation layer.

Key/value pairs

  • The permissionLevel will determine how the layer is handled. If no value is set, an exception will occur.
  • The redactionFlag determines if the layer has Mark Layer As Redaction selected in the client. If no value is set, an exception will occur.
  • If the permissionLevel is set to PERM_REDACTION, the value of redactionFlag is moot since the client does not receive that layer as an annotation layer.
  • If getAnnotationProperties returns null, an exception will occur. This prevents cases where a layer should have strict permissions but for some reason no permission level gets set.

Saving redaction layers

If a layer has Mark Layer As Redaction selected, when choosing Save Annotations, VirtualViewer HTML5 for Java will pass both the permissionLevel and the redactionFlag to the saveAnnotationContent method in a hash table:

public void saveAnnotationContent(ContentHandlerInput input) saveAnnotationContent(ContentHandlerInput input)
(String clientInstanceId, String documentId, String annotationKey, byte [] data, Hashtable annProperties)

Printing layers

When printing a document, the user may choose to print with or without annotations. Only visible layers with a Print permission level or higher in the Image Panel will print.

A layer which has been given a permissionLevel of PERM_REDACTION shall always print as part of the image, (since it has been burned into the image), even if the user chose to print without annotations.