|
Oracle® Information Rights Management Server Java API Reference 11g Release 1 (11.1.1) E12907-03 |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface SealingOperations
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.
The methods on SealingOperations can be invoked using SealingOperationsInstance
.
setAutomaticItemCode
Nested Class Summary | |
---|---|
static class |
SealingOperations.Section Logical sections of sealed content. |
Method Summary | |
---|---|
ContentDescription |
peek(InputStream input) Peek sealed content. |
void |
reclassify(InputStream input, OutputStream output, Classification classification) Re-classify sealed content. |
void |
reseal(InputStream input, OutputStream output, Collection<CustomData> customData) Reseal content with new custom data. |
void |
seal(Source source, OutputStream output, SealingOptions options) Seal content. |
ContentDescription |
unseal(InputStream input, OutputStream output) Unseal a stream into an output stream. |
ContentDescription |
validatedPeek(InputStream input) Peek sealed content (with validation of the signature). |
void |
verify(InputStream input, SealingOperations.Section section) Verify content is sealed. |
Method Detail |
---|
void seal(Source source, OutputStream output, SealingOptions options) throws IllegalEncryptedContentBlockSizeException, PublicHeaderLengthException, EmptyContentException, ContentSizeMismatchException, IOException, AuthorizationDeniedException
Classification
.ItemCode
value if applicable.Feature
for the Classification
specified in the sealing options.
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. In this sample the file is sealed using the context classification system, specifying a context with a known UUID value and a fixed item code value.
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 { // The user name and password are provided on the command line. In a production // system these details should be provided in a more secure manner, such // as prompting from the console, or reading from a secure source. final String username = args[0]; final String password = args[1]; // Configure an authenticator to provide the credentials for any network access Authenticator.setDefault(new Authenticator() { @Override protected PasswordAuthentication getPasswordAuthentication() { return new PasswordAuthentication(username, password.toCharArray()); } }); // 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 e.g. https://irm.example.com/irm_desktop URI serverURI = URI.create(args[2]); // Create the classification details used in the sealing options 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[3]; 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); // Seal the file seal(fileSource, sealedOutputStream, sealingOptions); // Close the streams sealedOutputStream.close(); } }
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.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.ContentDescription unseal(InputStream input, OutputStream output) throws ContentParseException, IOException, AuthorizationDeniedException
Feature
for the content's Classification
.
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 user name and password are provided on the command line. In a production // system these details should be provided in a more secure manner, such // as prompting from the console, or reading from a secure source. final String username = args[0]; final String password = args[1]; // Configure an authenticator to provide the credentials for any network access Authenticator.setDefault(new Authenticator() { @Override protected PasswordAuthentication getPasswordAuthentication() { return new PasswordAuthentication(username, password.toCharArray()); } }); // The file to unseal String sealedFilename = args[2]; // The unsealed file name String unsealedFilename = args[3]; // Sealed file input stream FileInputStream inputStream = new FileInputStream(sealedFilename); // Unsealed file output stream FileOutputStream outputStream = new FileOutputStream(unsealedFilename); // Unseal the sealed file unseal(inputStream, outputStream); // Close the file streams inputStream.close(); outputStream.close(); } }
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.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.void reseal(InputStream input, OutputStream output, Collection<CustomData> customData) throws ContentParseException, IOException, AuthorizationDeniedException
Feature
for the content's Classification
.
reseal
method. This sample adds XML based custom data to the sealed file.
import static oracle.irm.engine.content.sealing.CustomDataCollectionFactory.createCustomData; import static oracle.irm.engine.content.sealing.CustomDataFactory.createCustomData; import static oracle.irm.engine.content.sealing.SealingOperationsInstance.reseal; import java.io.FileInputStream; import java.io.FileOutputStream; import java.net.Authenticator; import java.net.PasswordAuthentication; import java.util.Collection; import java.util.UUID; import javax.xml.parsers.DocumentBuilder; import javax.xml.parsers.DocumentBuilderFactory; import oracle.irm.engine.content.sealing.CustomData; import org.w3c.dom.Document; import org.w3c.dom.Element; public class ResealFile { public static void main(String[] args) throws Exception { // The user name and password are provided on the command line. In a production // system these details should be provided in a more secure manner, such // as prompting from the console, or reading from a secure source. final String username = args[0]; final String password = args[1]; // Configure an authenticator to provide the credentials for any network access Authenticator.setDefault(new Authenticator() { @Override protected PasswordAuthentication getPasswordAuthentication() { return new PasswordAuthentication(username, password.toCharArray()); } }); // The file to reseal String filename = args[2]; // The output file name String resealedFilename = args[3]; // Custom data is provided as XML DocumentBuilderFactory documentBuilderFactory = DocumentBuilderFactory.newInstance(); DocumentBuilder documentBuilder = documentBuilderFactory.newDocumentBuilder(); Document document = documentBuilder.newDocument(); Element element = document.createElement("SampleCustomData"); element.setTextContent("Some example custom data provided as an XML text element"); // UUID identifies the custom data, in this example just use a random UUID value UUID uuid = UUID.randomUUID(); // Create the custom data, UUID + value CustomData data = createCustomData(uuid, element); Collection<CustomData> customData = createCustomData(data); // Reclassify the sealed file with the new classification FileInputStream sealedFileStream = new FileInputStream(filename); FileOutputStream resealedFileStream = new FileOutputStream(resealedFilename); reseal(sealedFileStream, resealedFileStream, customData); // Close the streams sealedFileStream.close(); resealedFileStream.close(); } }
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.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.void reclassify(InputStream input, OutputStream output, Classification classification) throws ContentParseException, IOException, AuthorizationDeniedException
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.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.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.
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 user name and password are provided on the command line. In a production // system these details should be provided in a more secure manner, such // as prompting from the console, or reading from a secure source. final String username = args[0]; final String password = args[1]; // Configure an authenticator to provide the credentials for any network access Authenticator.setDefault(new Authenticator() { @Override protected PasswordAuthentication getPasswordAuthentication() { return new PasswordAuthentication(username, password.toCharArray()); } }); // The file to reclassify String filename = args[2]; // The output file name String reclassifiedFilename = args[3]; // The label to apply to the classification String labelName = args[4]; // 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(); } }
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.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.ContentDescription peek(InputStream input) throws ContentParseException, IOException
Classification
as well as information such as the CreationTime
.
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 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()); } } }
input
- sealed content input stream. It is the callers responsibility to close the input stream.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.ContentDescription validatedPeek(InputStream input) throws ContentParseException, IOException, AuthorizationDeniedException
Feature
for the content's Classification
.
validatedPeek
method. 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.validatedPeek; import java.io.FileInputStream; import java.io.IOException; import java.net.Authenticator; import java.net.PasswordAuthentication; import oracle.irm.engine.content.sealing.ContentDescription; import oracle.irm.engine.core.classification.Classification; import oracle.irm.engine.core.general.Label; public class ValidatedPeekFile { public static void main(String[] args) throws IOException { // The user name and password are provided on the command line. In a production // system these details should be provided in a more secure manner, such // as prompting from the console, or reading from a secure source. final String username = args[0]; final String password = args[1]; // Configure an authenticator to provide the credentials for any network access Authenticator.setDefault(new Authenticator() { @Override protected PasswordAuthentication getPasswordAuthentication() { return new PasswordAuthentication(username, password.toCharArray()); } }); // The name of the file to peek FileInputStream stream = new FileInputStream(args[2]); // Perform the peek, providing a stream to the sealed file ContentDescription contentDescription = validatedPeek(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()); } } }
input
- sealed content input stream. It is the callers responsibility to close the input stream.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.void verify(InputStream input, SealingOperations.Section section) throws ContentParseException, IOException, AuthorizationDeniedException
Feature
for the content's Classification
. This ensures the cryptography keys are available to the verification process.input
- the data input stream.section
- the section at which to stop.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.
|
Oracle® Information Rights Management Server Java API Reference 11g Release 1 (11.1.1) E12907-03 |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |