This section contains the following topics:
When sealing content, it is useful to be able to look up the file extension that Oracle IRM Desktop uses. The content operations described later in this section provide useful operations for obtaining file extension information, such as looking up sealed file extensions.
Sealed content uses file extensions that differ from the ones used for unsealed files. For example, a PDF file has the file extension .pdf, whereas a sealed PDF file has the file extension .spdf. The sealed file extension allows Oracle IRM Desktop to identify what file format the sealed content is, and display appropriate sealed file icons. The table below shows some example file extensions and the corresponding sealed file extension.
Sealed content includes a MIME type in the sealed content metadata. This MIME type is used by Oracle IRM Desktop to identify the format of the unsealed content. The MIME type is an alternative way of detecting the file format when the content is not stored in a file (for example, a stream of data downloaded from a HTTP server). Unsealed MIME types vary and there are many examples where a single file format has more than one MIME type. For this reason the sealed content contains a sealed MIME type rather than the unsealed content MIME type. For example, a PDF file has the MIME type application/pdf, whereas a sealed PDF file will have a MIME type of application/vnd.sealedmedia.softseal.pdf added to the metadata.
Opening up sealed content in an editor will show that a sealed MIME type is added to the metadata. For example, the public header of a sealed PDF file:
<?xml version="1.0" ?>
<content:PublicHeader xmlns:content="http://xmlns.oracle.com/irm/content" xmlns:classifications="http://xmlns.oracle.com/irm/classifications">
<contentDescription>
...
<sealedMime>application/vnd.sealedmedia.softseal.pdf</sealedMime>
...
</contentDescription>
</content:PublicHeader>
The sealing server provides a web service that can be used to query file and MIME type information. Sealed content file format information is immutable, so consider retrieving this information once and using a local copy when processing sealed files. This will avoid potentially expensive remote calls to a sealing server.
When sealing a file a common scenario is to create the corresponding sealed file next to the original. The getSealedFileName operation takes a path and file name or just a file name and provides the equivalent sealed file name.
ContentTypeOperations contentTypeOperations = new ContentTypeOperationsService().getContentTypeOperations();
String results = contentTypeOperations.getSealedFileName("/usr/home/john/sample.html");
In the example above the results of calling the method would be "/usr/home/john/sample.stml".
A content type object contains all the file type information for content that can be sealed. The content type specifies the file extension(s), its sealed file extension, and the associated MIME types. Content type objects can be obtained using the file extension or the MIME type of the sealed or unsealed content.
ContentTypeOperations contentTypeOperations = new ContentTypeOperationsService().getContentTypeOperations();
ContentType results = contentTypeOperations.getContentTypeFromExtension("pdf");
The content type operations can be used locally within Java applications. To use these methods requires irm-common.jar and irm-engine.jar to be present in the classpath of the calling application.
The content type operations are locally available on the content type operations instance.
import static oracle.irm.engine.content.type.ContentTypeOperationsInstance.getSealedFileName;
String results = getSealedFileName("/usr/home/john/sample.html");
The sealing server supports sealing. Content is uploaded to the sealing server, encrypted and signed, and the sealed content returned to the caller.
For JAX-WS generated web service proxies the content is provided as a javax.activation.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.html"));
The data source does not have to be a file.
sealA call to the seal method requires the unsealed data (in the form of a DataHandler), the MIME type of the unsealed or sealed content (either is fine) and the sealing options. The sealing options contain 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()); DataHandler results = sealingServices.seal(input, "txt/html", options);
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 seal operation, the authenticated user needs rights that allow the seal feature for the specified classification.
The seal method requires the MIME type of the unsealed or sealed content to be specified, for example:
For HTML content either the txt/html or application/vnd.sealed.txt MIME types can be used.
For text content either the txt/plain or application/vnd.sealedmedia.softseal.html MIME types can be used.
For more information about how to obtain sealed content MIME types and what MIME types are supported, see "File Extensions".
The sealing options contain the classification, custom metadata and settings that affect how the content is encrypted. 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, for example, 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 an example 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 is mandatory and must be specified in the sealing options. The other sealing option properties are optional.
SealingOptions options = new SealingOptions(); options.setClassification(classification);
The classification ID is a simple string value that is used to uniquely identify the classification. The contents and format of the classification ID differ depending on what classification system is used. The classification ID is used to match classification details with master classification details stored on the server. During the seal operation, if the classification labels and key set are not specified the sealing server looks up the master classification definition by classification ID and uses the labels and key set defined on the master classification.
classification.setId("a4905cd7-7405-469e-b72c-78d11e959b3a");
The classification ID value for the context classification system should be set as the context UUID value. If this value is not set correctly, labels and key set details cannot be automatically set.
A classification must specify what classification system is being used to seal the content. A classification system is identified with a UUID value.
ClassificationSystemRef system = new ClassificationSystemRef();
system.setUuid("37c8da32-5420-4146-816c-27f63de27250");
classification.setSystem(system);
The classification system defines what value should be used as the classification ID, as well as what XML data should be set in the classification cookie. When sealed content is opened in Oracle IRM Desktop this information is sent to the Oracle IRM J2EE application. The Oracle IRM J2EE application then uses the classification system and classification cookie data to determine how rights are obtained for the authenticated user.
The UUID value for the context classification system is 37c8da32-5420-4146-816c-27f63de27250. This value is immutable and will never change.
When content is sealed, the cryptography keys used to encrypt and sign the content are specified using a key set. This value should be set to null, and is provided for future feature enhancements.
classification.setKeySet(null);
When sealed content is opened or created, the rights to open or seal the content must be obtained from an IRM server. A classification has a URI property which must be set to the URI of an IRM server that will provide the licenses and cryptography keys needed to open or seal content for the classification.
classification.setUri("https://irm.example.com/irm_desktop");
It is important that this value is the same as the the "Server URL" property configured on the General Settings page of the Oracle IRM Server Control Console (the Oracle IRM pages of the Oracle Enterprise Manager Fusion Middleware Control Console).
Rights to access sealed content can include time constraints. One such constraint can be based on the classification time, for example:
allow John to access any sealed content up to one month after the classification time
or:
allow Mary to access any content classified in 2008
The classification time can be set during the sealing process:
classification.setClassificationTime(new java.util.Date());
If the classification time is not specified, it defaults to the current time by the sealing server.
classification.setClassificationTime(null);
In the 10g Oracle IRM release the classification time was called the publication time.
A classification can contain a set of human-readable strings called labels. The classification labels are used by Oracle IRM Desktop to show the user classification details, for example informing the user that a document is sealed to the Top Secret classification. If no labels are specified for the classification provided to the seal operation, the sealing server will attempt to fill in the labels from the master classification definition. To allow for multi-language support, labels have a locale property. If the classification can be translated into multiple languages, multiple labels can be provided, each one specifying the appropriate locale (for example, en for English or zh-CN for traditional Chinese - see Locale Codes). Oracle IRM Desktop picks the most appropriate label based on the installed Oracle IRM Desktop language.
For the context classification system, the context labels defined on the Oracle IRM Server Management Console are the ones that are sealed into content.
Empty labels are specified by setting an empty set of labels using null.
classification.setLabels(null);
Labels can also be provided during the sealing process: these override any master classification definition.
Label label = new Label();
label.setLocale("en");
label.setName("Top Secret");
label.setDescription("Top Secret - this is a top secret document");
classification.setLabels(new Label[] {label});
The classification cookie is defined by the classification XML schema as an <any> element, that is, an XML element of any form. The structure of this XML document is defined by the classification system being used. Depending on the web service proxy generator used, the cookie XML is typically provided as a org.w3c.dom.Element or Object. The following code snippet shows a classification cookie for the context classification system. The cookie XML document is created using standard Java document object model (DOM) APIs. It does not matter how the XML document object is created: loaded from a file, created from a string, loaded in from a stream, etc. This example shows the cookie XML being created from a string.
String xml =
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>" +
"<classifications:ContextCookie xmlns:classifications=\"http://xmlns.oracle.com/irm/classifications\">" +
" <context>" +
" <uuid>a4905cd7-7405-469e-b72c-78d11e959b3a</uuid>" +
" </context>" +
" <itemCode>" +
" <value>sample.shtml</value>" +
" <time>2007-05-10T12:00:00.000+00:00</time>" +
" </itemCode>" +
"</classifications:ContextCookie>";
java.io.ByteArrayInputStream stream = new java.io.ByteArrayInputStream(xml.getBytes("utf-8"));
javax.xml.parsers.DocumentBuilderFactory documentBuilderFactory = javax.xml.parsers.DocumentBuilderFactory.newInstance();
// As the context classification cookie uses namespaces, ensure these are maintained on parsing the XML
documentBuilderFactory.setNamespaceAware(true);
javax.xml.parsers.DocumentBuilder documentBuilder = documentBuilderFactory.newDocumentBuilder();
org.w3c.dom.Document document = documentBuilder.parse(stream);
Custom metadata can be specified during the sealing process. Custom metadata is an optional property on the SealingOptions. Custom metadata is added as an XML element together with a UUID value that can be used to identify the custom data when peeking the sealed content.
Element element = document.createElement("SampleCustomData");
element.setTextContent("Some example custom data provided as an XML element containing this text");
CustomData data = new CustomData();
// UUID identifies the custom data, this example uses a fixed example UUID value
data.setUuid("7f79d1e8-fc07-464c-8477-834951e07060");
// Custom data is XML document
data.setData(element);
// Set on the options before sealing
options.setCustomData(new CustomData[] {data});
A poster page is the image shown before a sealed movie is started. Oracle IRM Desktop loads the optional poster page from the custom metadata section of the public header. A poster page must be a JPEG or GIF image. The image is provided in the custom data as base 64 encoded data together with the file type.
// UUID for poster page image
CustomData image = new CustomData();
image.setUuid("6f2c8fba-a2cb-4493-8861-45e5cbda1bac");
// Custom data is base 64 encoded data for image
Element imageElement = document.createElement("item");
imageElement.setTextContent("R0lGODlhhQASAPcAAP.....XfNIQAAAOw==");
image.setData(imageElement);
// UUID for poster page file type - either 'gif' or 'jpeg'
CustomData fileType = new CustomData();
fileType.setUuid("38663feb-5df9-4c14-bd75-b557b6dfea18");
// Custom data is XML document
Element imageElement = document.createElement("item");
imageElement.setTextContent("gif");
image.setData(imageElement);
// Set on the options before sealing
options.setCustomData(new CustomData[] {image, fileType});
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 (but not validated 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.
Local peeking requires irm-common.jar and irm-engine.jar to be present in the classpath of the calling application.
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.
Resealing is the process of altering the custom metadata or editing the encrypted content. Oracle IRM Desktop allows certain formats, such as Microsoft Office, to be edited in sealed form. The process of saving edits is called resealing.
The sealing server supports resealing to update the custom metadata but does not support updating the encrypted content of the sealed file. Content is uploaded to the sealing server, the custom metadata is updated, and the sealed content is returned to the caller.
For JAX-WS generated web service proxies, the 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.
resealA call to reseal requires the sealed data (in the form of a DataHandler) and the custom data for the update. The following demonstrates how to reseal a sealed file using the reseal method adding XML-based custom data to the sealed file.
The XML based custom data is provided as an XML element.
Element element = document.createElement("SampleCustomData");
element.setTextContent("Some example custom data provided as an XML element containing this text");
CustomData data = new CustomData();
// UUID identifies the custom data, this example uses a fixed example UUID value
data.setUuid("7f79d1e8-fc07-464c-8477-834951e07060");
// Custom data is XML document
data.setData(element);
Then the reseal operation is called to reseal the content and re-sign the metadata.
SealingServices sealingServices = new SealingServicesService().getSealingServices(new javax.xml.ws.soap.MTOMFeature());
DataHandler results = sealingServices.reseal(input, new CustomData[] {data});
To call the reseal operation, the authenticated user needs rights that allow the reseal feature to be performed for the classification of the sealed content.
The DataHandler class can be used to write out the resealed content to an output stream of the programmer's choice. This example shows the resealed content being written out to a file.
java.io.FileOutputStream outputStream = new java.io.FileOutputStream("example.stml");
results.writeTo(outputStream);
outputStream.close();
Reclassifying sealed content is the process of altering the classification of the sealed content. Reclassification usually means re-signing and re-encrypting the content, because most classifications have a dedicated set of cryptography keys. Reclassifying is typically used when content changes sensitivity, for example when a top secret document becomes a company confidential document.
The sealing server supports reclassifying. Content is uploaded to the sealing server, the classification is updated, and the updated sealed content is returned to the caller.
For JAX-WS generated web service proxies, the 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.
reclassifyA call to reclassify requires the sealed data (in the form of a DataHandler) and the new classification details. Refer to the sealing example for details about how to specify a classification in code.
SealingServices sealingServices = new SealingServicesService().getSealingServices(new javax.xml.ws.soap.MTOMFeature()); DataHandler results = sealingServices.reclassify(input,classification);
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 reclassify operation, the authenticated user needs either:
Rights that allow the copy to feature for the source classification with a trusted destination that allows the target classification, and rights that allow the seal feature for the target classification.
In the context classification system, this means the user has to have a role that has export constraints set as trusted with the target context being a trusted context of the source context, or that the role has export constraints set as none.
Rights that allow the unseal feature for the specified classification and the seal feature for the target classification.
In the context classification system, this means the user has to have a role that has export constraints set as none.
When using the Oracle IRM Server Management Console, the copy to and unseal features are enabled and controlled using the export constraints defined on a role.
The DataHandler class can be used to write out the resealed content to an output stream of the programmer's choice. This example shows the resealed content being written out to a file.
java.io.FileOutputStream outputStream = new java.io.FileOutputStream("example.stml");
results.writeTo(outputStream);
outputStream.close();
Unsealing is the process of converting sealed content back into the original, plaintext content. Unsealing is typically used to convert sealed content that is no longer sensitive back into normal content. Unsealing is an operation that is supported by both Oracle IRM Desktop and the sealing server.
The sealing server supports unsealing. The sealed content is uploaded to the sealing server, the content is decrypted, and the unsealed content 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.
unsealA call to the unseal method results in the unsealed data being returned as a javax.activation.DataHandler. This object can be used to stream the unsealed data into a file or buffer.
SealingServices sealingServices = new SealingServicesService().getSealingServices(new javax.xml.ws.soap.MTOMFeature()); javax.activation.DataHandler results = sealingServices.unseal(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 unseal operation, the authenticated user needs rights that allow the unseal feature to be performed for the classification of the sealed content.
When using the Oracle IRM Server Management Console, the unseal feature is enabled when a role has export constraints of none.
The DataHandler class can be used to write out the unsealed content to an output stream of the programmer's choice. This example shows the unsealed content being written out to a file.
java.io.FileOutputStream outputStream = new java.io.FileOutputStream("example.html");
results.writeTo(outputStream);
outputStream.close();