This section contains the following topics:
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});
Sealing is the process of encrypting plaintext content and adding signed metadata to that content. This metadata includes the classification details and any custom metadata supplied during the sealing process. Sealing can also be performed by using Oracle IRM Desktop. A call to the seal requires the unsealed data in the form of a source, the MIME type of the unsealed or sealed content (either is acceptable), 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.
import static oracle.irm.engine.content.sealing.SealingOperationsInstance.seal;
import static oracle.irm.engine.content.sealing.FileSource.createFileSource;
import oracle.irm.engine.content.sealing.Source;
import oracle.irm.engine.content.sealing.SealingOptions;
...
// Create the unsealed content source
Source source = createFileSource("unsealed.html");
// Sealed file written out to a file
OutputStream output = new FileOutputStream("sealed.stml");
// Sealing options...more on this later
SealingOptions options = ...
// Seal the content
seal(source, output, options);
To call the seal operation, the authenticated user needs rights that allow the seal feature for the specified classification.
The source parameter provides the sealing operation with a stream to the unsealed data, the MIME type of the content, and the size of the unsealed content (if available). The MIME type is important because Oracle IRM Desktop uses the MIME type to determine how to render the content. The IRM Java API provides a number of sources: the main ones are listed here.
The file source provides can be used to seal a file. Internally, the file source provides a FileInputStream stream to the sealing code. The MIME type is inferred from the file extension.
import static oracle.irm.engine.content.sealing.FileSource.createFileSource;
import oracle.irm.engine.content.sealing.Source;
...
Source source = createFileSource("unsealed.html");
The URL source provides content downloaded from a HTTP or FTP server. Internally, the URL source opens a connection using a java.net.URLConnection and provides a stream to downloaded content. The MIME type is inferred from the content-type header, or if that header is not present, a file extension on the URL path.
import static oracle.irm.engine.content.sealing.URLSource.createURLSource;
import oracle.irm.engine.content.sealing.Source;
...
java.net.URL url = new java.net.URL("http://irm.example.com/sample.html");
Source source = createURLSource(url);
The stream source allows the programmer to supply both the input stream and MIME type. This option gives the programmer control over the type of input stream and MIME type used during sealing.
import static oracle.irm.engine.content.sealing.StreamSource.createStreamSource; import oracle.irm.engine.content.sealing.Source; ... java.io.InputStream myStream = new MyInputStreamStream(); Source source = createStreamSource(myStream, "text/html");
The MIME type can be either the unsealed or sealed content MIME type. 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.
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. An example context cookie that might appear in sealed content:
<?xml version="1.0" ?>
All rights reserved. -->
<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.
import static oracle.irm.engine.content.sealing.SealingOptionsFactory.createSealingOptions;
import static oracle.irm.engine.core.classification.ClassificationFactory.createClassification;
import oracle.irm.engine.content.sealing.SealingOptions;
import oracle.irm.engine.core.classification.Classification;
...
// Create the classification...parameter details are described below
Classification classification = createClassification(
id,
system,
keySet,
uri,
classificationTime,
labels,
cookie);
// Create sealing options
SealingOptions options = new createSealingOptions(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 IRM Java API looks up the master classification definition by classification ID and uses the labels and key set defined on the master classification.
Note:
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. 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.
A classification system is identified with a UUID value.
import static oracle.irm.engine.core.classification.ClassificationSystemFactory.createClassificationSystem;
import oracle.irm.engine.core.classification.ClassificationSystem;
...
java.util.UUID uuid = java.util.UUID.fromString("37c8da32-5420-4146-816c-27f63de27250");
ClassificationSystem system = createClassificationSystem(uuid);
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.
Note:
The IRM Java API provides the constantoracle.irm.engine.classifications.context.ContextConstants.CONTEXT_CLASSIFICATION_SYSTEM which can be used as the system parameter when creating a context}.When content is sealed, the cryptography keys used to encrypt and sign the content are specified using a key set. If there is a selection of key sets available to a classification, a key set can be explicitly set in the classification. This would, for example, allow the caller of the seal method to select a stronger encryption algorithm based on the type of content being sealed. The key set specified must be one the classification allows.
import static oracle.irm.engine.content.key.KeySetFactory.createKeySet;
import oracle.irm.engine.content.key.KeySet;
...
java.util.UUID uuid = java.util.UUID.fromString("52546b5c-a273-46c0-b990-e3538700182e");
KeySet keySet = createKeySet(uuid);
However, the most common way to specify which key set to use during the seal process is to let the system automatically select a key set. This is done by using a null key set value. The IRM Java API will then select the most recently generated key set that this classification allows.
KeySet keySet = null;
Note:
When sealing content to the context classification system, the most common approach is to specify null in the key set property and let the IRM Java API select the most up to date key set available for the context.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.
java.net.URI uri = java.net.URI.create("https://irm.example.com/irm_desktop");
Value:
It is important that this value be the same as the URI value configured on the IRM server as the value sealed into content. The IRM Java API and IRM server use the server URI value as an internal way of indexing and referencing information. If this value is incorrect (for example, because it is using an IP address) the IRM Java API will not authorize the operation.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.
java.util.Date classificationTime = new java.util.Date();
If the classification time is not specified, it defaults to the current time by the IRM Java API.
java.util.Date classificationTime = null;
Note:
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 provided on the classification provided to the seal operation, the IRM Java API 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. Oracle IRM Desktop picks the most appropriate label based on the installed Oracle IRM Desktop language.
Context Classification System:
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.
import oracle.irm.engine.core.general.Label; ... java.util.Collection<Label> labels = null;
Labels can also be provided during the sealing process: these override any master classification definition.
import static oracle.irm.engine.core.general.LabelFactory.createLabel;
import static oracle.irm.engine.core.general.LabelCollectionFactory.createLabels;
import oracle.irm.engine.core.general.Label;
...
// Create the label with an English locale, a name and description
Label label1 = createLabel("en", "Top Secret", "Top Secret - this is a top secret document");
Label label2 = createLabel("fr", "Top Secret", "Top secret - c'est un document extrêmement secret");
// Create the labels
java.util.Collection<Label> labels = createLabels(label1, label2);
The classification cookie is defined by the classification XML schema as an any element; a XML element of any type. The structure of this XML document is defined by the classification system being used. When sealing to the context classification system the IRM Java API provides a set of objects that can be used instead of providing raw XML documents.
import static oracle.irm.engine.classifications.context.ContextCookieFactory.createContextCookie;
import static oracle.irm.engine.classifications.context.ContextFactory.createContext;
import static oracle.irm.engine.classifications.item.ItemCodeFactory.createItemCode;
import oracle.irm.engine.classifications.context.Context;
import oracle.irm.engine.classifications.context.ContextCookie;
import oracle.irm.engine.classifications.item.ItemCode;
...
// Create an item code, this identifies the sealed content within the context
ItemCode itemCode = createItemCode("sample.shtml");
// Create a context, this is identified with a UUID value
java.util.UUID uuid = java.util.UUID.fromString("a4905cd7-7405-469e-b72c-78d11e959b3a");
Context context = createContext(uuid);
// Create the cookie data sealed into content
ContextCookie cookie = createContextCookie(context, itemCode);
When using other classification systems, the cookie XML is typically provided as a org.w3c.dom.Element. The following code snippet shows the same context details as the sample above, but using a raw XML. The cookie is created using the DOM to create the required XML document. It does not matter how the XML document 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>" +
" </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 can be provided when creating 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.
import static oracle.irm.engine.content.sealing.CustomDataFactory.createCustomData;
import static oracle.irm.engine.content.sealing.CustomDataCollectionFactory.createCustomData;
import oracle.irm.engine.content.sealing.CustomData;
...
org.w3c.dom.Element element = ...
UUID uuid = UUID.fromString("7f79d1e8-fc07-464c-8477-834951e07060");
// Create the custom data from the UUID and the XML element
CustomData data = createCustomData(uuid, element);
// Create the set of custom data used when creating the sealing options
java.util.Collection<CustomData> customData = createCustomData(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.
import static oracle.irm.engine.content.sealing.CustomDataFactory.createCustomData;
import static oracle.irm.engine.content.sealing.CustomDataCollectionFactory.createCustomData;
import oracle.irm.engine.content.sealing.CustomData;
...
// UUID for poster page image
java.util.UUID posterPageUUID = java.util.UUID.fromString("6f2c8fba-a2cb-4493-8861-45e5cbda1bac");
// Custom data is base 64 encoded data for image
org.w3c.dom.Element imageElement = document.createElement("item");
imageElement.setTextContent("R0lGODlhhQASAPcAAP.....XfNIQAAAOw==");
CustomData posterPage = createCustomData(posterPageUUID, imageElement);
// UUID for poster page file type - either 'gif' or 'jpeg'
java.util.UUID postPageTypeUUID = java.util.UUID.fromString("38663feb-5df9-4c14-bd75-b557b6dfea18");
// Custom data is XML document
Element typeElement = document.createElement("item");
type.setTextContent("gif");
CustomData posterPageType = createCustomData(postPageTypeUUID , typeElement);
// Create the set of custom data
java.util.Collection<CustomData> customData = createCustomData(posterPage, posterPageType);