|
Oracle® Information Rights Management Server Java API Reference 11g Release 1 (11.1.1) E12907-01 |
|||||||||
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. 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(); } }
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 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(); } }
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
.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 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(); } }
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 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()); } } }
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
.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-01 |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |