|
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 SealingServicesEndpoint
Web Service end point interface for Sealing Services. 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 methods on the sealing services are designed to used remotely, where the content is sent to a server, processes and the results returned to the client.
The sealing services support the MTOM (Message Transmission Optimization Mechanism) feature. This allows the services to transfer the binary sealed and unsealed content in the most optimal form available. When sending content to using the sealing services it is recommended to enable MTOM in the client web service stack.
The WSDL for this end point interface can be downloaded from the server using the following URL:
http://irm.example.com/irm_sealing/sealing_services?wsdl
Requests for this web service should be sent to the following URL:
https://irm.example.com/irm_sealing/sealing_services
Method Summary | |
---|---|
ContentDescription |
peek(DataHandler input) Peek sealed content. |
DataHandler |
reclassify(DataHandler input, Classification classification) Re-classify sealed content. |
DataHandler |
reseal(DataHandler input, CustomData[] customData) Reseal content with new custom data. |
DataHandler |
seal(DataHandler stream, String mimeType, SealingOptions options) Seal content. |
DataHandler |
unseal(DataHandler input) Unseal a stream into an output stream. |
ContentDescription |
validatedPeek(DataHandler input) Peek sealed content (with validation of the signature). |
Method Detail |
---|
DataHandler seal(DataHandler stream, String mimeType, SealingOptions options) throws UnsupportedContentTypeFault, IllegalEncryptedContentBlockSizeFault, PublicHeaderLengthFault, AuthorizationDeniedFault
Classification
.ItemCode
if one is not specified in the classification details.Feature
for the Classification
specified in the sealing options.
import static oracle.irm.engine.classifications.context.ContextConstants.CONTEXT_CLASSIFICATION_SYSTEM_UUID; import static oracle.irm.engine.content.type.ContentTypeOperationsInstance.getContentTypeFromPath; import static oracle.irm.engine.content.type.ContentTypeOperationsInstance.getSealedFileName; import static oracle.irm.j2ee.jws.content.sealing.SealingServices.getSealingServicesEndpoint; import java.io.File; import java.net.URI; import java.util.Date; import java.util.Map; import java.util.UUID; import javax.activation.DataHandler; import javax.activation.FileDataSource; import javax.xml.ws.BindingProvider; import oracle.irm.engine.content.type.ContentType; import oracle.irm.engine.types.classifications.context.ContextCookie; import oracle.irm.engine.types.classifications.context.ContextRef; import oracle.irm.engine.types.classifications.item.ItemCode; import oracle.irm.engine.types.content.sealing.SealingOptions; import oracle.irm.engine.types.core.classification.Classification; import oracle.irm.engine.types.core.classification.ClassificationSystemRef; import oracle.irm.j2ee.jws.content.sealing.SealingServicesEndpoint; import com.sun.xml.ws.developer.JAXWSProperties; import com.sun.xml.ws.developer.StreamingDataHandler; public class SealFile { public static void main(String[] args) throws Exception { String hostPort = args[0]; String username = args[1]; String password = args[2]; // The server URI. e.g. https://irm.example.com/irm_desktop URI serverURI = URI.create(args[3]); // The filename to seal String filename = args[4]; // Context UUID is fixed for sample code ContextRef context = new ContextRef(UUID.fromString("46f910d9-dd30-476e-b060-4d01f88f8b05")); // Provide an explicit item code value and time ItemCode itemCode = new ItemCode(); itemCode.setValue(new File(filename).getName()); itemCode.setTime(new Date()); // Create a context cookie for the classification - this specifies which context to use as // well as the item code for the content. ContextCookie cookie = new ContextCookie(); cookie.setContext(context); cookie.setItemCode(itemCode); // Create the classification details used in the sealing options Classification classification = new Classification(); // For the context classification system the classification Id is the context UUID value. classification.setId("46f910d9-dd30-476e-b060-4d01f88f8b05"); // Context classification system classification.setSystem(new ClassificationSystemRef(CONTEXT_CLASSIFICATION_SYSTEM_UUID)); // As the key set is not known get the sealing process to automatically fill this in classification.setKeySet(null); // URL sealed into content that tells the desktop where to go to get licenses classification.setUri(serverURI); // Classification time set explicitly to the current time classification.setClassificationTime(new Date()); // As the labels are not known get the sealing process to automatically fill these in classification.setLabels(null); // Set the context and item code details classification.setCookie(cookie); // The classification is the only mandatory property for sealing options SealingOptions sealingOptions = new SealingOptions(); sealingOptions.setClassification(classification); // Get the MIME type of the file to seal, this is inferred from the unsealed file name ContentType contentType = getContentTypeFromPath(filename); String mimeType = contentType.getMimeTypes()[0]; // Get the sealing services web service proxy SealingServicesEndpoint sealingServices = getSealingServicesEndpoint(hostPort); // Set the user name and password Map<String, Object> requestContext = ((BindingProvider)sealingServices).getRequestContext(); requestContext.put(BindingProvider.USERNAME_PROPERTY, username); requestContext.put(BindingProvider.PASSWORD_PROPERTY, password); // Without this setting the client may get an java.lang.OutOfMemoryException // when large files are buffered into memory by the HTTP stack. // // For more information see: // https://jax-ws.dev.java.net/guide/HTTP_client_streaming_support.html // https://jax-ws.dev.java.net/guide/Large_Attachments.html requestContext.put(JAXWSProperties.HTTP_CLIENT_STREAMING_CHUNK_SIZE, 4096); // Send the file contents to the server for sealing DataHandler input = new DataHandler(new FileDataSource(filename)); StreamingDataHandler results = (StreamingDataHandler)sealingServices.seal(input, mimeType, sealingOptions); // Get the sealed equivalent of the unsealed filename String sealedFilename = getSealedFileName(filename); // Copy the downloaded file to the relevant location results.moveTo(new File(sealedFilename)); } }
stream
- the data stream.mimeType
- the unsealed or sealed MIME type of the data provided in the stream. The stream is assumed to contain unsealed data. It is advisable to use the sealed MIME type; this ensures the sealed content content type is unambiguous. e.g. the {text/plain} content type can be sealed as sealed text or sealed email. If the {text/plain} MIME type is specified the content will be sealed as sealed text.options
- the sealing options.UnsupportedContentTypeFault
- unsupported MIME type. The MIME type is not a supported sealable content type.IllegalEncryptedContentBlockSizeFault
- illegal encrypted content block size specified in the sealing options.PublicHeaderLengthFault
- the classification and custom data exceeds the maximum permitted size.AuthorizationDeniedFault
- thrown if sealing content using the provided classification is not allowed.DataHandler unseal(DataHandler input) throws ContentParseFault, AuthorizationDeniedFault
Feature
for the content's Classification
.
unseal
method. The sample writes the resulting unsealed stream out to a file.
import static oracle.irm.j2ee.jws.content.sealing.SealingServices.getSealingServicesEndpoint; import java.io.File; import java.util.Map; import javax.activation.DataHandler; import javax.activation.FileDataSource; import javax.xml.ws.BindingProvider; import oracle.irm.j2ee.jws.content.sealing.SealingServicesEndpoint; import com.sun.xml.ws.developer.JAXWSProperties; import com.sun.xml.ws.developer.StreamingDataHandler; public class UnsealFile { public static void main(String[] args) throws Exception { String hostPort = args[0]; String username = args[1]; String password = args[2]; // The file to unseal String sealedFilename = args[3]; // The unsealed file name String unsealedFilename = args[4]; // Get the sealing services web service proxy SealingServicesEndpoint sealingServices = getSealingServicesEndpoint(hostPort); // Set the user name and password Map<String, Object> requestContext = ((BindingProvider)sealingServices).getRequestContext(); requestContext.put(BindingProvider.USERNAME_PROPERTY, username); requestContext.put(BindingProvider.PASSWORD_PROPERTY, password); // Without this setting the client may get an java.lang.OutOfMemoryException // when large files are buffered into memory by the HTTP stack. // // For more information see: // https://jax-ws.dev.java.net/guide/HTTP_client_streaming_support.html // https://jax-ws.dev.java.net/guide/Large_Attachments.html requestContext.put(JAXWSProperties.HTTP_CLIENT_STREAMING_CHUNK_SIZE, 4096); // Send the file contents to the server for unsealing DataHandler input = new DataHandler(new FileDataSource(sealedFilename)); StreamingDataHandler results = (StreamingDataHandler)sealingServices.unseal(input); // Copy the downloaded file to the relevant location results.moveTo(new File(unsealedFilename)); } }
input
- sealed data.ContentParseFault
- 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.AuthorizationDeniedFault
- thrown if unsealing for the classification is not allowed.DataHandler reseal(DataHandler input, CustomData[] customData) throws ContentParseFault, AuthorizationDeniedFault
Feature
for the content's Classification
.
reseal
method. This sample adds XML based custom data to the sealed file.
import static oracle.irm.j2ee.jws.content.sealing.SealingServices.getSealingServicesEndpoint; import java.io.File; import java.util.Map; import java.util.UUID; import javax.activation.DataHandler; import javax.activation.FileDataSource; import javax.xml.parsers.DocumentBuilder; import javax.xml.parsers.DocumentBuilderFactory; import javax.xml.ws.BindingProvider; import oracle.irm.engine.types.content.sealing.CustomData; import oracle.irm.j2ee.jws.content.sealing.SealingServicesEndpoint; import org.w3c.dom.Document; import org.w3c.dom.Element; import com.sun.xml.ws.developer.JAXWSProperties; import com.sun.xml.ws.developer.StreamingDataHandler; public class ResealFile { public static void main(String[] args) throws Exception { String hostPort = args[0]; String username = args[1]; String password = args[2]; // Get the file to reseal String filename = args[3]; // Get the sealing services web service proxy SealingServicesEndpoint sealingServices = getSealingServicesEndpoint(hostPort); // Set the user name and password Map<String, Object> requestContext = ((BindingProvider)sealingServices).getRequestContext(); requestContext.put(BindingProvider.USERNAME_PROPERTY, username); requestContext.put(BindingProvider.PASSWORD_PROPERTY, password); // Without this setting the client may get an java.lang.OutOfMemoryException // when large files are buffered into memory by the HTTP stack. // // For more information see: // https://jax-ws.dev.java.net/guide/HTTP_client_streaming_support.html // https://jax-ws.dev.java.net/guide/Large_Attachments.html requestContext.put(JAXWSProperties.HTTP_CLIENT_STREAMING_CHUNK_SIZE, 4096); // 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"); CustomData data = new CustomData(); // UUID identifies the custom data, in this example just use a random UUID value data.setUuid(UUID.randomUUID()); // Custom data is XML document data.setData(element); // Send the sealed file contents to the server for resealing DataHandler input = new DataHandler(new FileDataSource(filename)); StreamingDataHandler results = (StreamingDataHandler)sealingServices.reseal(input, new CustomData[] {data}); // Copy the downloaded file to the relevant location results.moveTo(new File(filename)); } }
input
- sealed data.customData
- the new custom data. This parameter is optional, it is valid to pass null or an empty collection.ContentParseFault
- 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.AuthorizationDeniedFault
- thrown if resealing for the classification is not allowed.DataHandler reclassify(DataHandler input, Classification classification) throws ContentParseFault, AuthorizationDeniedFault
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 sample changes the labels of the classification and then writes the resulting stream out as a file.
import static oracle.irm.j2ee.jws.content.sealing.SealingServices.getSealingServicesEndpoint; import java.io.File; import java.util.Locale; import java.util.Map; import javax.activation.DataHandler; import javax.activation.FileDataSource; import javax.xml.ws.BindingProvider; import oracle.irm.engine.types.content.sealing.ContentDescription; import oracle.irm.engine.types.core.classification.Classification; import oracle.irm.engine.types.core.general.Label; import oracle.irm.j2ee.jws.content.sealing.SealingServicesEndpoint; import com.sun.xml.ws.developer.JAXWSProperties; import com.sun.xml.ws.developer.StreamingDataHandler; public class ReclassifyFile { public static void main(String[] args) throws Exception { String hostPort = args[0]; String username = args[1]; String password = args[2]; // Get the file to reclassify String filename = args[3]; // Get the label to apply to the classification String labelName = args[4]; // Get the sealing services web service proxy SealingServicesEndpoint sealingServices = getSealingServicesEndpoint(hostPort); // Set the user name and password Map<String, Object> requestContext = ((BindingProvider)sealingServices).getRequestContext(); requestContext.put(BindingProvider.USERNAME_PROPERTY, username); requestContext.put(BindingProvider.PASSWORD_PROPERTY, password); // Without this setting the client may get an java.lang.OutOfMemoryException // when large files are buffered into memory by the HTTP stack. // // For more information see: // https://jax-ws.dev.java.net/guide/HTTP_client_streaming_support.html // https://jax-ws.dev.java.net/guide/Large_Attachments.html requestContext.put(JAXWSProperties.HTTP_CLIENT_STREAMING_CHUNK_SIZE, 4096); // Peek the contents of the file to obtain the classification details DataHandler input = new DataHandler(new FileDataSource(filename)); ContentDescription contentDescription = sealingServices.peek(input); // Extract the classification from the content description Classification classification = contentDescription.getClassification(); // Replace the labels with one Label label = new Label( Locale.ENGLISH, labelName, null); classification.setLabels(new Label[] { label }); // Reclassify the sealed file with the new classification StreamingDataHandler results = (StreamingDataHandler)sealingServices.reclassify(input, classification); // Copy the downloaded file to the relevant location results.moveTo(new File(filename)); } }
input
- sealed data.classification
- new classification.ContentParseFault
- 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.AuthorizationDeniedFault
- thrown if reclassification from the source to target classification is not allowed.ContentDescription peek(DataHandler input) throws ContentParseFault
Classification
as well as information such as the CreationTime
.peek
method. This method sends the sealed content to the sealing server, the server extracts the meta data and returns this information to the caller. 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.j2ee.jws.content.sealing.SealingServices.getSealingServicesEndpoint; import java.util.Map; import javax.activation.DataHandler; import javax.activation.FileDataSource; import javax.xml.ws.BindingProvider; import oracle.irm.engine.types.content.sealing.ContentDescription; import oracle.irm.engine.types.core.classification.Classification; import oracle.irm.engine.types.core.general.Label; import oracle.irm.j2ee.jws.content.sealing.SealingServicesEndpoint; import com.sun.xml.ws.developer.JAXWSProperties; public class PeekFile { public static void main(String[] args) throws Exception { String hostPort = args[0]; String username = args[1]; String password = args[2]; // The name of the file to peek String filename = args[3]; // Get the sealing services web service proxy SealingServicesEndpoint sealingServices = getSealingServicesEndpoint(hostPort); // Set the user name and password Map<String, Object> requestContext = ((BindingProvider)sealingServices).getRequestContext(); requestContext.put(BindingProvider.USERNAME_PROPERTY, username); requestContext.put(BindingProvider.PASSWORD_PROPERTY, password); // Without this setting the client may get an java.lang.OutOfMemoryException // when large files are buffered into memory by the HTTP stack. // // For more information see: // https://jax-ws.dev.java.net/guide/HTTP_client_streaming_support.html // https://jax-ws.dev.java.net/guide/Large_Attachments.html requestContext.put(JAXWSProperties.HTTP_CLIENT_STREAMING_CHUNK_SIZE, 4096); // Perform the peek, providing a stream to the sealed file DataHandler input = new DataHandler(new FileDataSource(filename)); ContentDescription results = sealingServices.peek(input); // Extract the classification details from the content Classification classification = results.getClassification(); // Show all the labels sealed into content (assumes labels are available) for (Label label : classification.getLabels()) { System.out.println(label.getLocale().getDisplayName() + " : " + label.getName()); } } }
input
- sealed data.ContentParseFault
- 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.ContentDescription validatedPeek(DataHandler input) throws ContentParseFault, AuthorizationDeniedFault
Feature
for the content's Classification
.validatedPeek
method. This method sends the sealed content to the sealing server, the server extracts the meta data and returns this information to the caller. 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.j2ee.jws.content.sealing.SealingServices.getSealingServicesEndpoint; import java.util.Map; import javax.activation.DataHandler; import javax.activation.FileDataSource; import javax.xml.ws.BindingProvider; import com.sun.xml.ws.developer.JAXWSProperties; import oracle.irm.engine.types.content.sealing.ContentDescription; import oracle.irm.engine.types.core.classification.Classification; import oracle.irm.engine.types.core.general.Label; import oracle.irm.j2ee.jws.content.sealing.SealingServicesEndpoint; public class ValidatedPeekFile { public static void main(String[] args) throws Exception { String hostPort = args[0]; String username = args[1]; String password = args[2]; // The name of the file to peek String filename = args[3]; // Get the sealing services web service proxy SealingServicesEndpoint sealingServices = getSealingServicesEndpoint(hostPort); // Set the user name and password Map<String, Object> requestContext = ((BindingProvider)sealingServices).getRequestContext(); requestContext.put(BindingProvider.USERNAME_PROPERTY, username); requestContext.put(BindingProvider.PASSWORD_PROPERTY, password); // Without this setting the client may get an java.lang.OutOfMemoryException // when large files are buffered into memory by the HTTP stack. // // For more information see: // https://jax-ws.dev.java.net/guide/HTTP_client_streaming_support.html // https://jax-ws.dev.java.net/guide/Large_Attachments.html requestContext.put(JAXWSProperties.HTTP_CLIENT_STREAMING_CHUNK_SIZE, 4096); // Send the file contents to the server for peeking DataHandler input = new DataHandler(new FileDataSource(filename)); ContentDescription results = sealingServices.validatedPeek(input); // Extract the classification details from the content Classification classification = results.getClassification(); // Show all the labels sealed into content (assumes labels are available) for (Label label : classification.getLabels()) { System.out.println(label.getLocale().getDisplayName() + " : " + label.getName()); } } }
input
- sealed data.ContentParseFault
- 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.AuthorizationDeniedFault
- thrown if peeking the classification 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 |