This section contains the following topics:
Peeking is the process of extracting metadata from sealed content. This metadata includes the classification details and any custom metadata supplied during the sealing process. Peeking is typically used to extract information from the sealed content without decrypting the file. Peeking is used by Oracle IRM Desktop when sealed file properties are displayed.
The sealing server supports both peeking and validated peek (where the digital signature of the sealed content is validated). In both cases the sealed content is uploaded to the sealing server, the content is examined, and the sealed content metadata is returned to the caller.
For JAX-WS generated web service proxies, the sealed content is provided as a DataHandler parameter. Using a data handler allows the web service stack to stream the binary content to the server without having to load the complete file into memory.
javax.activation.DataHandler input = new javax.activation.DataHandler(new FileDataSource("example.stml"));
The data source does not have to be a file.
peekA call to the peek method results in the metadata being returned as a ContentDescription object. This object contains the classification details, custom metadata and a few other attributes, such as the time the sealed file was created.
SealingServices sealingServices = new SealingServicesService().getSealingServices(new javax.xml.ws.soap.MTOMFeature()); ContentDescription results = sealingServices.peek(input);
It is important to enable the MTOM web service feature. This ensures the sealed content is uploaded to the server in the most optimal form. It also avoids java.lang.OutOfMemoryException exceptions if the uploaded file is large.
To call the peek operation the authenticated user does not need any rights to access the sealed content.
validatedPeekA call to the validatedPeek method results in the metadata being returned as a ContentDescription object in the same way as peek. If the digital signature has been tampered with, or the file is corrupt, a ContentParseFault exception is thrown. This exception will detail the reason for the sealed content parsing failure. A successful invocation of this operation signifies that the metadata signature has been verified.
SealingServices sealingServices = new SealingServicesService().getSealingServices(new javax.xml.ws.soap.MTOMFeature()); ContentDescription results = sealingServices.validatedPeek(input);
To call the validated peek operation, the authenticated user must have the rights to open the sealed content.
The classification is the most important part of the sealed content metadata. The classification contains the opaque XML document called the classification cookie. The classification cookie is the data used by Oracle IRM Desktop and the Oracle IRM J2EE application when associating rights with content. The classification cookie XML structure is defined by the classification system of the sealed content. The context classification system has an XML structure that includes a UUID to identify the context and a value called the item code which can be used to identify an individual document. The following is a sample context cookie that might appear in sealed content:
<?xml version="1.0" ?>
<classifications:ContextCookie xmlns:classifications="http://xmlns.oracle.com/irm/classifications">
<context>
<uuid>588403f9-9cff-4cce-88e4-e030cc57282a</uuid>
</context>
<itemCode>
<value>sample.sdoc</value>
<time>2007-05-10T12:00:00.000+00:00</time>
</itemCode>
</classifications:ContextCookie>
Rights for the context classification system are expressed using this information, for example:
John can access all documents with a context UUID of f3cd57c1-f495-48aa-b008-f23afa4d6b07
or:
Mary can access documents with a context UUID of f3cd57c1-f495-48aa-b008-f23afa4d6b07 and an item code value of plan001.sdoc or plan002.sdoc
The classification metadata also contains the human-readable labels for the classification. There may be multiple labels if the labels have been translated into multiple languages. These labels are used to display a friendly name and description to a user, rather than showing raw computer oriented data from the classification cookie.
The classification contains a set of human-readable strings called labels. The classification labels can be used to inform the user which classification the sealed content was sealed against.
Classification classification = results.getClassification();
Label[] labels = classification.getLabels();
if (labels != null) {
for (Label label : labels) {
System.out.println(label.getLocale().getDisplayName() + " : " + label.getName());
}
}
The classification cookie is defined in the classification XML schema as an <any> element. The cookie XML can be accessed from the classification object and is typically returned as a org.w3c.dom.Element. The following code snippet shows a context UUID being extracted from a context classification cookie using the DOM.
Classification classification = results.getClassification();
org.w3c.dom.Element element = (org.w3c.dom.Element)results.getAny();
org.w3c.dom.NodeList nodes = element.getElementsByTagName("context");
org.w3c.dom.Node node = nodes.item(0);
String uuid = node.getTextContent();
If the file is large there is no need to send the complete file to the sealing server. Peeking only requires the portion of the file that contains the metadata. This portion of the file is dynamic in size, but limited to 1MB in size. A pessimistic view would be to send the first 1MB of the file contents (or the complete contents if this is less than 1MB). In reality the sealed content preamble and metadata are usually a lot smaller, so 16K to 32K is usually sufficient. If the metadata section of the sealed content sent to the sealing server is truncated, the peek or validatedPeek call will throw a ContentParseFault.
Peeking is the process of extracting metadata from sealed content. This metadata includes the classification details and any custom metadata supplied during the sealing process. Peeking is typically used to extract information from the sealed content without decrypting the file. Peeking is used by Oracle IRM Desktop when sealed file properties are displayed.
The IRM Java libraries allow peeking to be performed locally. This can be used where performance is an issue and the overhead of sending content to the sealing server is undesirable. The functionality is identical to that provided by remote peeking.
peekLocal peeking is performed using the SealingOperations interface rather than the sealing services web service. Sealed content is provided as an InputStream rather than a DataHandler.
import static oracle.irm.engine.content.sealing.SealingOperationsInstance.peek;
InputStream fileInputStream = new FileInputStream("example.stml");
ContentDescription results = peek(fileInputStream);
The result can be examined in the same manner as for remote peeking.