Skip navigation links

Oracle® Information Rights Management Server Java API Reference
11g Release 1 (11.1.1)

E12907-01


oracle.irm.engine.content.sealing
Class SealingOperationsInstance

java.lang.Object
  extended by oracle.irm.engine.content.sealing.SealingOperationsInstance


public final class SealingOperationsInstance
extends Object

Sealing, unsealing, resealing and peeking operations for content. Sealing is the process of taking unprotected content, encrypting it and adding in meta data called a classification. Unsealing is the term used when sealed content is decrypted. Resealing is the term used when altering the sealed content meta data or classification. Peeking is the term given to the process of extracting meta data from sealed content without decrypting the content.

The sealing operations are designed for use within a J2SE or J2EE application. This interface provides the most flexible set of operations for manipulating sealed and unsealed content. If remote sealing is required use the SealingServices as this interface is exposed as a web service.

The methods on the sealing operations interface are designed to be used from within an embedded application that needs to process sealed content locally, rather than sending the content to a sealing server.

This class provides static methods for a set of procedural style methods. The methods can be made to appear as global methods by using import static. e.g.

import static oracle.irm.engine.content.sealing.SealingOperationsInstance.*;

Method Summary
static ContentDescription peek(InputStream input)
          Peek sealed content.
static void reclassify(InputStream input, OutputStream output, Classification classification)
          Re-classify sealed content.
static void reseal(InputStream input, OutputStream output, Collection<CustomData> customData)
          Reseal content with new custom data.
static void seal(Source source, OutputStream output, SealingOptions options)
          Seal content.
static ContentDescription unseal(InputStream input, OutputStream output)
          Unseal a stream into an output stream.
static ContentDescription validatedPeek(InputStream input)
          Peek sealed content (with validation of the signature).
static void verify(InputStream input, SealingOperations.Section section)
          Verify content is sealed.

 

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

 

Method Detail

seal

public static void seal(Source source,
                        OutputStream output,
                        SealingOptions options)
                 throws IllegalEncryptedContentBlockSizeException,
                        PublicHeaderLengthException,
                        EmptyContentException,
                        ContentSizeMismatchException,
                        IOException,
                        AuthorizationDeniedException
Seal content. Sealing is the process of taking plaintext content, encrypting and signing the content with an associated Classification.

If the classification provided is the context classification system, this method will provide an automatic ItemCode value if applicable.

To perform a sealing operation the authenticated user must have the rights to seal content. Sealing is authorized if the authenticated user has a license that allows the oracle.irm.generic.Seal Feature for the Classification specified in the sealing options.

Sealing a file

The following code demonstrates how to seal a file using the seal method. The content to seal can be provided as any type of InputStream; this example uses a file input stream. Similarly the sealed content can be written out to any output stream; this example writes the sealed content as a file whose file name is derived from the unsealed file name. When a file is sealed a Classification must be specified. This example uses the synchronize call to obtain a list of classifications the authenticated user is allowed and uses the first classification returned from this call. Generally there is no need to call synchronize before a seal, this example only uses the synchronize call so it can obtain a classification.
 import static oracle.irm.engine.classifications.context.ContextConstants.CONTEXT_CLASSIFICATION_SYSTEM;
 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 static oracle.irm.engine.content.sealing.SealingOperationsInstance.seal;
 import static oracle.irm.engine.content.sealing.SealingOptionsFactory.createSealingOptions;
 import static oracle.irm.engine.content.source.FileSourceFactory.createFileSource;
 import static oracle.irm.engine.content.type.ContentTypeOperationsInstance.getSealedFileName;
 import static oracle.irm.engine.core.classification.ClassificationFactory.createClassification;
 import static oracle.irm.engine.core.general.LabelCollectionFactory.EMPTY_LABELS;
 
 import java.io.FileOutputStream;
 import java.net.Authenticator;
 import java.net.PasswordAuthentication;
 import java.net.URI;
 import java.util.Date;
 import java.util.UUID;
 
 import oracle.irm.engine.classifications.context.Context;
 import oracle.irm.engine.classifications.context.ContextCookie;
 import oracle.irm.engine.classifications.item.ItemCode;
 import oracle.irm.engine.content.sealing.SealingOptions;
 import oracle.irm.engine.content.source.FileSource;
 import oracle.irm.engine.core.classification.Classification;
 
 public class SealFile {
 
     public static void main(String[] args) throws Exception {
         
         // Provide an explicit item code for the document
         ItemCode itemCode = createItemCode("sample document");
         
         // Context UUID is fixed for sample code
         Context context = createContext(UUID.fromString("46f910d9-dd30-476e-b060-4d01f88f8b05"));
         
         // Context cookie specifying the context and the item code
         ContextCookie cookie = createContextCookie(
             context,
             itemCode);
         
         // The server address is the first command line argument
         // e.g. https://irm.example.com/irm_desktop
         URI serverURI = URI.create(args[0]);
         
         // Get the first classification from the list
         Classification classification = createClassification(
             "46f910d9-dd30-476e-b060-4d01f88f8b05",
             CONTEXT_CLASSIFICATION_SYSTEM,
             null, // automatically fill in key set
             serverURI,
             new Date(),
             EMPTY_LABELS, // automatically fill in labels
             cookie);
 
         // Create the sealing options
         SealingOptions sealingOptions = createSealingOptions(classification);
 
         // Create a file source from the file name
         String unsealedFilename = args[1];
         
         FileSource fileSource = createFileSource(unsealedFilename);
 
         // Get the sealed equivalent of the unsealed filename
         String sealedFilename = getSealedFileName(unsealedFilename);
 
         // Write the sealed stream out to a file
         FileOutputStream sealedOutputStream = new FileOutputStream(sealedFilename);
         
         // The username and password that will be used if the IRM
         // server is contacted for rights are the final command line
         // arguments
         final String username = args[2];
         final String password = args[3];
         
         // Configure an authenticator to provide the credentials
         // for the web service
         Authenticator.setDefault(new Authenticator() {
             @Override
             protected PasswordAuthentication getPasswordAuthentication() {
                 return new PasswordAuthentication(username, password.toCharArray());
             }
         });
 
         // Seal the file
         seal(fileSource, sealedOutputStream, sealingOptions);
 
         // Close the streams
         sealedOutputStream.close();
     }
 }
Parameters:
source - the unsealed source content. The sealing process will call source.close after a successful or unsuccessful call. This ensures any resources owned by the source are freed.
output - the sealed content output stream. It is the callers responsibility to close the output stream. The sealing process will flush the stream but not close it.
options - the sealing options.
Throws:
IllegalEncryptedContentBlockSizeException - illegal encrypted content block size specified in the sealing options.
PublicHeaderLengthException - the classification and custom data exceeds the maximum permitted size.
EmptyContentException - no unsealed content provided.
ContentSizeMismatchException - the source size did not match the amount of data in the source input stream.
IOException - an input/output/sealing error occurred sealing the content.
AuthorizationDeniedException - thrown if sealing content using the provided classification is not allowed.

unseal

public static ContentDescription unseal(InputStream input,
                                        OutputStream output)
                                 throws ContentParseException,
                                        IOException,
                                        AuthorizationDeniedException
Unseal a stream into an output stream. Unsealing is the process of taking sealed content, de-crypting it and returning the original unsealed content.

To perform an unsealing operation the authenticated user must have the rights to unseal content. Unsealing is allowed if the authenticated user has a license that allows the oracle.irm.generic.SaveUnsealed Feature for the content's Classification.

Unsealing a file

The following code demonstrates how to unseal a sealed file using the unseal method. The content to unseal can be provided as any type of InputStream; this example uses a file input stream. The sample code writes the resulting stream out to a file.
 import static oracle.irm.engine.content.sealing.SealingOperationsInstance.unseal;
 
 import java.io.FileInputStream;
 import java.io.FileOutputStream;
 import java.net.Authenticator;
 import java.net.PasswordAuthentication;
 
 public class UnsealFile {
 
     public static void main(String[] args) throws Exception {
 
         // The file to unseal is the first command line argument
         String sealedFilename = args[0];
 
         // The unsealed file name is the second command line argument
         String unsealedFilename = args[1];
 
         // Sealed file input stream
         FileInputStream inputStream = new FileInputStream(sealedFilename);
 
         // Unsealed file output stream        
         FileOutputStream outputStream = new FileOutputStream(unsealedFilename);
         
          // The username and password that will be used if the IRM
         // server is contacted for rights are the final command line
         // arguments
         final String username = args[2];
         final String password = args[3];
         
         // Configure an authenticator to provide the credentials
         // for the web service
         Authenticator.setDefault(new Authenticator() {
             @Override
             protected PasswordAuthentication getPasswordAuthentication() {
                 return new PasswordAuthentication(username, password.toCharArray());
             }
         });
 
         // Unseal the sealed file
         unseal(inputStream, outputStream);
 
         // Close the file streams
         inputStream.close();
         outputStream.close();
     }
 }
Parameters:
input - sealed content input stream. It is the callers responsibility to close the input stream.
output - unsealed content output stream. It is the callers responsibility to close this output stream. The unsealing process will flush the stream but not close it.
Returns:
the meta-data and classification details sealed into the content. This method will never return null.
Throws:
ContentParseException - indicates that there was an issue parsing the sealed content. The exception will contains a reason that identifies which section of the sealed content which caused the parsing to fail.
IOException - an input/output/sealing error occurred unsealing the content.
AuthorizationDeniedException - thrown if unsealing for the classification is not allowed.

reseal

public static void reseal(InputStream input,
                          OutputStream output,
                          Collection<CustomData> customData)
                   throws ContentParseException,
                          IOException,
                          AuthorizationDeniedException
Reseal content with new custom data. Resealing is the process of altering the data or meta-data in sealed content. This method allows the custom data portion of the meta data to be replaced.

To perform a resealing operation the authenticated user must have the rights to reseal the content. Resealing is allowed if the authenticated user has a valid license that has the oracle.irm.generic.Reseal Feature for the content's Classification.
Parameters:
input - the sealed content input stream. It is the callers responsibility to close the input stream.
output - the sealed content output stream. It is the callers responsibility to close the output stream. The resealing process will flush the stream but not close it.
customData - the new custom data. This parameter is optional, it is valid to pass null or an empty collection.
Throws:
ContentParseException - indicates that there was an issue parsing the sealed content. The exception will contains a reason that identifies which section of the sealed content which caused the parsing to fail.
IOException - an input/output/sealing error occurred resealing the content.
AuthorizationDeniedException - thrown if resealing for the classification is not allowed.

reclassify

public static void reclassify(InputStream input,
                              OutputStream output,
                              Classification classification)
                       throws ContentParseException,
                              IOException,
                              AuthorizationDeniedException
Re-classify sealed content. Re-classification is the process of altering the Classification of the sealed content without having to perform a two step unseal and seal. During re-classification the content is re-encrypted and re-signed.

If the classification labels or key set are not provided then the sealing process will attempt to fill in these details. If no labels are provided in the classification the labels are filled in automatically. Labels can only be filled in if provided classification Id matches the classification returned by the server. If no key set is provided then the key set is filled in from the license used to perform the sealing operation. If the license specifies multiple key sets then the first key set in the license is used.

To perform a resealing operation the authenticated user must have a license for both the source classification and the target classification. The source classification license must allow the oracle.irm.generic.CopyTo or oracle.irm.generic.SaveUnsealed Feature. The target classification license must allow the oracle.irm.generic.Seal feature. If the source license has a copy to feature the transformation is only permitted if target classification is allowed by the trusted Destinations of the source classification license. If the source license has a save unsealed feature then there are no restrictions on the target classification.

Reclassifying a file

The following code demonstrates how to reclassify a sealed file using the reclassify method. The content to reclassify can be provided as any type of InputStream; this example uses a file input stream. The sample code changes the labels of the classification and then writes the resulting reclassified stream out as a file.
 import static oracle.irm.engine.content.sealing.SealingOperationsInstance.peek;
 import static oracle.irm.engine.content.sealing.SealingOperationsInstance.reclassify;
 import static oracle.irm.engine.core.classification.ClassificationFactory.createClassification;
 import static oracle.irm.engine.core.general.LabelFactory.createLabel;
 
 import java.io.FileInputStream;
 import java.io.FileOutputStream;
 import java.net.Authenticator;
 import java.net.PasswordAuthentication;
 import java.util.Collections;
 import java.util.Locale;
 
 import oracle.irm.engine.content.sealing.ContentDescription;
 import oracle.irm.engine.core.classification.Classification;
 import oracle.irm.engine.core.general.Label;
 
 public class ReclassifyFile {
 
     public static void main(String[] args) throws Exception {
 
         // The file to reclassify is the first command line argument
         String filename = args[0];
 
         // The label to apply to the classification is the second
         // command line argument
         String labelName = args[1];
 
         // The output file name is the third command line argument
         String reclassifiedFilename = args[2];
         
         // The username and password that will be used if the IRM
         // server is contacted for rights are the final command line
         // arguments
         final String username = args[3];
         final String password = args[4];
         
         // Configure an authenticator to provide the credentials
         // for the web service
         Authenticator.setDefault(new Authenticator() {
             @Override
             protected PasswordAuthentication getPasswordAuthentication() {
                 return new PasswordAuthentication(username, password.toCharArray());
             }
         });
 
         // Peek the contents of the file to obtain the current classification
         FileInputStream originalFileStream = new FileInputStream(filename);
 
         ContentDescription contentDescription = peek(originalFileStream);
 
         // Close the file stream
         originalFileStream.close();
 
         // Extract the classification from the content description
         Classification classification = contentDescription.getClassification();
 
         // Replace the labels with the one specified
         Label label = createLabel(Locale.ENGLISH, labelName, null);
 
         classification = createClassification(classification.getId(),
                 classification.getSystem(), 
                 classification.getKeySet(),
                 classification.getUri(),
                 classification.getClassificationTime(), 
                 Collections.singleton(label), 
                 classification.getCookie());
 
         // Reclassify the sealed file with the new classification
         originalFileStream = new FileInputStream(filename);
 
         FileOutputStream reclassifiedFileStream = new FileOutputStream(
                 reclassifiedFilename);
 
         reclassify(originalFileStream, reclassifiedFileStream, classification);
 
         // Close the streams
         originalFileStream.close();
         reclassifiedFileStream.close();
     }
 }
Parameters:
input - the sealed content input stream. It is the callers responsibility to close the input stream.
output - the sealed content output stream. It is the callers responsibility to close the output stream. The resealing process will flush the stream but not close it.
classification - the new classification.
Throws:
ContentParseException - indicates that there was an issue parsing the sealed content. The exception will contains a reason that identifies which section of the sealed content which caused the parsing to fail.
IOException - an input/output/sealing error occurred reclassifying the content.
AuthorizationDeniedException - thrown if reclassification from the source to target classification is not allowed.

peek

public static ContentDescription peek(InputStream input)
                               throws ContentParseException,
                                      IOException
Peek sealed content. Peeking is the process of extracting the meta-data added to sealed content. This variant does not attempt to check the public header against its declared signature. If the meta-data has been altered post-sealing this method will not throw an exception.

This meta-data includes the Classification as well as information such as the CreationTime.

Peeking a sealed file

The following code demonstrates how to extract the meta-data from sealed content using the peek method. The sealed content can be provided as any type of InputStream; this example uses a file input stream. Once peeked the file meta data, which includes the Classification details, can be examined. The sample code prints out the human readable classification details (the labels) that were sealed into the content.
 import static oracle.irm.engine.content.sealing.SealingOperationsInstance.peek;
 
 import java.io.FileInputStream;
 import java.io.IOException;
 
 import oracle.irm.engine.content.sealing.ContentDescription;
 import oracle.irm.engine.core.classification.Classification;
 import oracle.irm.engine.core.general.Label;
 
 public class PeekFile {
 
     public static void main(String[] args) throws IOException {
 
         // The name of the file to peek is the first
         // command line argument
         FileInputStream stream = new FileInputStream(args[0]);
 
         // Perform the peek, providing a stream to the sealed file
         ContentDescription contentDescription = peek(stream);
 
         // Close the file stream
         stream.close();
 
         // Extract the classification details from the content
         Classification classification = contentDescription.getClassification();
 
         // Show all the labels sealed into content
         for (Label label : classification.getLabels()) {
             System.out.println(label.getLocale().getDisplayName() + " : " + label.getName());
         }
     }
 }
Parameters:
input - sealed content input stream. It is the callers responsibility to close the input stream.
Returns:
the meta-data and classification details sealed into the content. This method will never return null.
Throws:
ContentParseException - indicates that there was an issue parsing the sealed content. The exception will contains a reason that identifies which section of the sealed content which caused the parsing to fail.
IOException - an input/output/sealing error occurred peeking the content.

validatedPeek

public static ContentDescription validatedPeek(InputStream input)
                                        throws ContentParseException,
                                               IOException,
                                               AuthorizationDeniedException
Peek sealed content (with validation of the signature). Peeking is the process of extracting the meta-data added to sealed content. This variant attempts to check the public header against its declared signature. If the public header meta-data has been altered post sealing this method will throw an exception. Any sealed content can be peek, the authenticated account does not require a license for the content's classification.

A validated peek is allowed if the authenticated user has a license that has the open Feature for the content's Classification.
Parameters:
input - sealed content input stream. It is the callers responsibility to close the input stream.
Returns:
the meta-data and classification details sealed into the content. This method will never return null.
Throws:
ContentParseException - indicates that there was an issue parsing the sealed content. The exception will contains a reason that identifies which section of the sealed content which caused the parsing to fail.
IOException - an input/output/sealing error occurred peeking the content.
AuthorizationDeniedException - thrown if peeking the classification is not allowed.

verify

public static void verify(InputStream input,
                          SealingOperations.Section section)
                   throws ContentParseException,
                          IOException,
                          AuthorizationDeniedException
Verify content is sealed. Allows a stream of input data to be verified as sealed content. The strength of the verification process can be controlled by providing the section of the sealed content at which to stop. The preamble section is first, then the magic number, the public header, the signature and then the encrypted content. The PREAMBLE, MAGIC and PUBLIC_HEADER sections give a good indication that the data is sealed content. These sections, however, do not check any of the cryptography aspects of the sealed file. If further verification is required the SIGNATURE or CONTENT sections should be used. The signature section verifies that the public header has not been tampered using a digital signature. The content section verifies that the content can be decrypted. If the verification method completes without an exception then the content is verified as sealed content (up to the section provided).

To verify the signature or content the authenticated user must have a license that has the oracle.irm.generic.Open Feature for the content's Classification. This ensures the cryptography keys are available to the verification process.
Parameters:
input - the data input stream.
section - the section at which to stop.
Throws:
ContentParseException - indicates that there was an issue parsing/verifying the content. The exception will contains a reason that identifies which section of the sealed content which caused the verification to fail.
IOException - indicates that there was an issue reading the input stream.
AuthorizationDeniedException - thrown if peeking the verification is not allowed.

Skip navigation links

Oracle® Information Rights Management Server Java API Reference
11g Release 1 (11.1.1)

E12907-01


Copyright © 2010, Oracle. All rights reserved.