javax.xml.crypto.enc

Class XMLEncryptionFactory

java.lang.Object

javax.xml.crypto.enc.XMLEncryptionFactory

public abstract class XMLEncryptionFactory
extends java.lang.Object

A factory for creating EncryptedType objects (such as EncryptedData, EncryptedKey) from scratch or for unmarshalling an EncryptedType object from a corresponding XML representation.

XMLEncryptionFactory Type

Each instance of XMLEncryptionFactory supports a specific XML mechanism type. To create an XMLEncryptionFactory, call one of the static getInstance methods, passing in the XML mechanism type desired, for example:

XMLEncryptionFactory factory = XMLEncryptionFactory.getInstance("DOM");

The objects that this factory produces will be based on DOM and abide by the DOM interoperability requirements as defined in the DOM Mechanism Requirements section of the API overview.

Note that a caller must use the same XMLEncryptionFactory instance to create the XMLStructures of a particular EncryptedType that is to be generated. The behavior is undefined if XMLStructures from different providers or different mechanism types are used together.

Creating EncryptedDatas from scratch

Once the XMLEncryptionFactory has been created, objects can be instantiated by calling the appropriate method.

Unmarshalling EncryptedData from XML

Alternatively, an EncryptedData may be created from an existing XML representation by invoking the unmarshalEncryptedType method and passing it a mechanism-specific XMLDecryptContext instance containing the XML content:

 DOMDecryptContext context = new DOMDecryptContext(key, encElement);
 EncryptedData data = (EncryptedData) factory.unmarshalEncryptedType(context);
 

Each XMLEncryptionFactory must support the required XMLDecryptContext types for that factory type, but may support others. A DOM XMLEncryptionFactory must support DOMDecryptContext objects.

Encrypting and Marshalling EncryptedData to XML

Each EncryptedData created by the factory can also be marshalled back to an XML representation, by invoking the encrypt method of the EncryptedData object and passing it a mechanism-specific XMLEncryptContext object that will hold the marshalled representation; for example:

    DOMEncryptContext context = new DOMEncryptContext(key, document);
    data.encrypt(context);
 

Concurrent Access

The static methods of this class are guaranteed to be thread-safe. Multiple threads may concurrently invoke the static methods defined in this class with no ill effects.

However, this is not true for the non-static methods defined by this class. Unless otherwise documented by a specific provider, threads that need to access a single XMLEncryptionFactory instance concurrently should synchronize amongst themselves and provide the necessary locking. Multiple threads each manipulating a different XMLEncryptionFactory instance need not synchronize.

Field Summary

Fields

Modifier and Type	Field and Description
private static java.lang.Class	cl
private static java.lang.reflect.Method	getImplMethod
private static java.lang.Class[]	getImplParams
private java.lang.String	mechanismType
private java.security.Provider	provider

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	XMLEncryptionFactory() Default constructor, for invocation by subclasses.

Method Summary

Modifier and Type	Method and Description
private static XMLEncryptionFactory	findInstance(java.lang.String mechanismType, java.security.Provider provider)
static XMLEncryptionFactory	getInstance() Returns an XMLEncryptionFactory that supports the default XML processing mechanism and representation type ("DOM").
static XMLEncryptionFactory	getInstance(java.lang.String mechanismType) Returns an XMLEncryptionFactory that supports the specified XML processing mechanism and representation type (ex: "DOM").
static XMLEncryptionFactory	getInstance(java.lang.String mechanismType, java.security.Provider provider) Returns an XMLEncryptionFactory that supports the requested XML processing mechanism and representation type (ex: "DOM"), as supplied by the specified provider.
static XMLEncryptionFactory	getInstance(java.lang.String mechanismType, java.lang.String provider) Returns an XMLEncryptionFactory that supports the requested XML processing mechanism and representation type (ex: "DOM"), as supplied by the specified provider.
java.lang.String	getMechanismType() Returns the type of the XML processing mechanism and representation supported by this XMLEncryptionFactory (ex: "DOM").
java.security.Provider	getProvider() Returns the provider of this XMLEncryptionFactory.
abstract boolean	isFeatureSupported(java.lang.String feature) Indicates whether a specified feature is supported.
abstract AgreementMethod	newAgreementMethod(java.lang.String algorithm, byte[] kaNonce, KeyInfo originatorKeyInfo, KeyInfo recipientKeyInfo, AgreementMethodParameterSpec params) Creates an AgreementMethod.
abstract CanonicalizationMethod	newCanonicalizationMethod(java.lang.String algorithm, C14NMethodParameterSpec params) Creates a CanonicalizationMethod for the specified algorithm URI and parameters.
abstract CipherReference	newCipherReference(java.lang.String uri, java.util.List transforms) Creates a CipherReference from the specified parameters.
abstract DataReference	newDataReference(java.lang.String uri, java.util.List content) Creates a DataReference from the specified URI.
abstract DHKeyValue	newDHKeyValue(java.security.PublicKey key) Creates a DHKeyValue from the specified key
abstract EncryptedData	newEncryptedData(ToBeEncrypted toBeEncrypted, EncryptionMethod encMethod, KeyInfo keyInfo, EncryptionProperties properties, java.lang.String id) Creates an EncryptedData which contains a CipherValue.
abstract EncryptedData	newEncryptedData(ToBeEncrypted toBeEncrypted, EncryptionMethod encMethod, KeyInfo keyInfo, EncryptionProperties properties, java.lang.String id, CipherReference cipherRef) Creates an EncryptedData which contains a CiphereReference.
abstract EncryptedKey	newEncryptedKey(ToBeEncryptedKey key, EncryptionMethod encMethod, KeyInfo keyInfo, EncryptionProperties properties, java.util.List references, java.lang.String id, java.lang.String carriedKeyName, java.lang.String recipient) Creates an EncryptedKey which contains a CipherValue.
abstract EncryptedKey	newEncryptedKey(ToBeEncryptedKey key, EncryptionMethod encMethod, KeyInfo keyInfo, EncryptionProperties properties, java.util.List references, java.lang.String id, java.lang.String carriedKeyName, java.lang.String recipient, CipherReference cipherRef) Creates an EncryptedKey.
abstract EncryptionMethod	newEncryptionMethod(java.lang.String algorithm, java.lang.Integer keySize, EncryptionMethodParameterSpec params) Creates a EncryptionMethod for the specified algorithm URI, key size, and parameters.
abstract EncryptionProperties	newEncryptionProperties(java.util.List properties, java.lang.String id) Creates a EncryptionProperties containing the specified list of EncryptionPropertys and optional id.
abstract EncryptionProperty	newEncryptionProperty(java.util.List content, java.lang.String target, java.lang.String id, java.util.Map attributes) Creates an EncryptionProperty containing the specified list of XMLStructures, target URI and optional id.
abstract KeyReference	newKeyReference(java.lang.String uri, java.util.List content) Creates a KeyReference from the specified URI.
abstract KeyInfo	newOriginatorKeyInfo(java.util.List content, java.lang.String id) Creates an originator KeyInfo containing the specified list of key information.
abstract KeyInfo	newRecipientKeyInfo(java.util.List content, java.lang.String id) Creates a recipient KeyInfo containing the specified list of key information.
abstract EncryptedType	unmarshalEncryptedType(XMLDecryptContext context) Unmarshals a new EncryptedType instance from a mechanism-specific XMLDecryptContext instance.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

mechanismType

private java.lang.String mechanismType

provider

private java.security.Provider provider

cl

private static java.lang.Class cl

getImplParams

private static final java.lang.Class[] getImplParams

getImplMethod

private static java.lang.reflect.Method getImplMethod

Constructor Detail

XMLEncryptionFactory

protected XMLEncryptionFactory()

Default constructor, for invocation by subclasses.

Method Detail

getInstance

public static XMLEncryptionFactory getInstance(java.lang.String mechanismType)
                                        throws NoSuchMechanismException

Returns an XMLEncryptionFactory that supports the specified XML processing mechanism and representation type (ex: "DOM").

This method uses the standard JCA provider lookup mechanism to locate and instantiate an XMLEncryptionFactory implementation of the desired mechanism type.

Parameters:

mechanismType - the type of the XML processing mechanism and representation

Returns:

a new XMLEncryptionFactory

Throws:

java.lang.NullPointerException - if mechanismType is null

NoSuchMechanismException - if an implementation of the requested mechanismType cannot be found

findInstance

private static XMLEncryptionFactory findInstance(java.lang.String mechanismType,
                                                 java.security.Provider provider)

getInstance

public static XMLEncryptionFactory getInstance(java.lang.String mechanismType,
                                               java.security.Provider provider)
                                        throws NoSuchMechanismException

Returns an XMLEncryptionFactory that supports the requested XML processing mechanism and representation type (ex: "DOM"), as supplied by the specified provider.

Parameters:

mechanismType - the type of the XML processing mechanism and representation. See the Service Providers section of the API overview for a list of standard mechanism types.

provider - the provider

Returns:

a new XMLEncryptionFactory

Throws:

java.lang.NullPointerException - if provider or mechanismType is null

NoSuchMechanismException - if an implementation of the requested mechanismType is not available from the specified provider

getInstance

public static XMLEncryptionFactory getInstance(java.lang.String mechanismType,
                                               java.lang.String provider)
                                        throws java.security.NoSuchProviderException,
                                               NoSuchMechanismException

Returns an XMLEncryptionFactory that supports the requested XML processing mechanism and representation type (ex: "DOM"), as supplied by the specified provider.

Parameters:

mechanismType - the type of the XML processing mechanism and representation. See the Service Providers section of the API overview for a list of standard mechanism types.

provider - the name of the provider

Returns:

a new XMLEncryptionFactory

Throws:

java.security.NoSuchProviderException - if provider has not been configured

java.lang.NullPointerException - if provider or mechanismType is null

NoSuchMechanismException - if an implementation of the requested mechanismType is not available from the specified provider

getInstance

public static XMLEncryptionFactory getInstance()
                                        throws NoSuchMechanismException

Returns an XMLEncryptionFactory that supports the default XML processing mechanism and representation type ("DOM").

This method uses the standard JCA provider lookup mechanism to locate and instantiate an XMLEncryptionFactory implementation of the default mechanism type.

Returns:

a new XMLEncryptionFactory

Throws:

NoSuchMechanismException - if an implementation for the default mechanism type cannot be found

getMechanismType

public final java.lang.String getMechanismType()

Returns the type of the XML processing mechanism and representation supported by this XMLEncryptionFactory (ex: "DOM").

Returns:

the XML processing mechanism type supported by this XMLEncryptionFactory

getProvider

public final java.security.Provider getProvider()

Returns the provider of this XMLEncryptionFactory.

Returns:

the provider of this XMLEncryptionFactory

newEncryptedData

public abstract EncryptedData newEncryptedData(ToBeEncrypted toBeEncrypted,
                                               EncryptionMethod encMethod,
                                               KeyInfo keyInfo,
                                               EncryptionProperties properties,
                                               java.lang.String id)

Creates an EncryptedData which contains a CipherValue.

Parameters:

toBeEncrypted - the data to be encrypted in this EncryptedData

encMethod - the encryption method (may be null)

keyInfo - the key info (may be null)

properties - the encryption properties (may be null)

id - the ID (may be null)

Returns:

an EncryptedData

Throws:

java.lang.IllegalArgumentException - if ToBeEncryptedKey is passed in as toBeEncrypted

java.lang.NullPointerException - if toBeEncrypted is null.

newEncryptedData

public abstract EncryptedData newEncryptedData(ToBeEncrypted toBeEncrypted,
                                               EncryptionMethod encMethod,
                                               KeyInfo keyInfo,
                                               EncryptionProperties properties,
                                               java.lang.String id,
                                               CipherReference cipherRef)

Creates an EncryptedData which contains a CiphereReference.

Parameters:

toBeEncrypted - the data to be encrypted in this EncryptedData

encMethod - the encryption method (may be null)

keyInfo - the key info (may be null)

properties - the encryption properties (may be null)

id - the ID (may be null)

cipherRef - the CiphereReference this EncryptedData will contain

Returns:

an EncryptedData

Throws:

java.lang.IllegalArgumentException - if ToBeEncryptedKey is passed in as toBeEncrypted

java.lang.NullPointerException - if toBeEncrypted or cipherRef is null

newDataReference

public abstract DataReference newDataReference(java.lang.String uri,
                                               java.util.List content)

Creates a DataReference from the specified URI.

Parameters:

uri - the uri that refers to an EncryptedData element

content - a list of XMLStructures (may be null or empty). The list is defensively copied to protect against subsequent modification.

Returns:

a DataReference

Throws:

java.lang.IllegalArgumentException - if uri is not RFC2396 compliant

java.lang.ClassCastException - if content contains any entries that are not of type XMLStructure

java.lang.NullPointerException - if uri is null

newKeyReference

public abstract KeyReference newKeyReference(java.lang.String uri,
                                             java.util.List content)

Creates a KeyReference from the specified URI.

Parameters:

uri - the uri that refers to an EncryptedKey element

content - a list of XMLStructures (may be null or empty). The list is defensively copied to protect against subsequent modification.

Returns:

a KeyReference

Throws:

java.lang.IllegalArgumentException - if uri is not RFC2396 compliant

java.lang.ClassCastException - if content contains any entries that are not of type XMLStructure

java.lang.NullPointerException - if uri is null

newEncryptionProperty

public abstract EncryptionProperty newEncryptionProperty(java.util.List content,
                                                         java.lang.String target,
                                                         java.lang.String id,
                                                         java.util.Map attributes)

Creates an EncryptionProperty containing the specified list of XMLStructures, target URI and optional id.

Parameters:

content - a list of one or more XMLStructures. The list is defensively copied to protect against subsequent modification.

target - the target URI of the EncryptedType that this property applies to (may be null)

id - the id (may be null)

attributes - a map of attributes from the XML namespace (may be empty or null). The map is defensively copied to protect against subsequent modification.

Returns:

an EncryptionProperty

Throws:

java.lang.NullPointerException - if content is null

java.lang.IllegalArgumentException - if content is empty or one or more of the attributes are not from the XML namespace

java.lang.ClassCastException - if content contains any entries that are not of type XMLStructure

newEncryptionProperties

public abstract EncryptionProperties newEncryptionProperties(java.util.List properties,
                                                             java.lang.String id)

Creates a EncryptionProperties containing the specified list of EncryptionPropertys and optional id.

Parameters:

properties - a list of one or more EncryptionPropertys. The list is defensively copied to protect against subsequent modification.

id - the id (may be null)

Returns:

a EncryptionProperties

Throws:

java.lang.NullPointerException - if properties is null

java.lang.IllegalArgumentException - if properties is empty

java.lang.ClassCastException - if properties contains any entries that are not of type EncryptionProperty

newEncryptionMethod

public abstract EncryptionMethod newEncryptionMethod(java.lang.String algorithm,
                                                     java.lang.Integer keySize,
                                                     EncryptionMethodParameterSpec params)
                                              throws java.security.NoSuchAlgorithmException,
                                                     java.security.InvalidAlgorithmParameterException

Creates a EncryptionMethod for the specified algorithm URI, key size, and parameters.

Parameters:

algorithm - the URI identifying the encryption algorithm. Supported algorithms are defined in EncryptionMethod interface.

keySize - the size of the key to be used (or null if not applicable)

ivSpec - the initialization vector (or null if not applicable)

params - algorithm-specific encryption parameters (may be null)

Returns:

the EncryptionMethod

Throws:

java.security.InvalidAlgorithmParameterException - if the specified parameters are inappropriate for the requested algorithm

java.security.NoSuchAlgorithmException - if an implementation of the specified algorithm cannot be found

java.lang.NullPointerException - if algorithm is null

newCipherReference

public abstract CipherReference newCipherReference(java.lang.String uri,
                                                   java.util.List transforms)

Creates a CipherReference from the specified parameters.

Parameters:

uri - the URI that identifies the encrypted octet sequence

transforms - a list of Transforms. The list is defensively copied to protect against subsequent modification. May be null or empty.

Returns:

a CipherReference

Throws:

java.lang.IllegalArgumentException - if uri is not RFC2396 compliant

java.lang.NullPointerException - if uri is null

java.lang.ClassCastException - if transforms contains any entries that are not of type Transform

newCanonicalizationMethod

public abstract CanonicalizationMethod newCanonicalizationMethod(java.lang.String algorithm,
                                                                 C14NMethodParameterSpec params)
                                                          throws java.security.NoSuchAlgorithmException,
                                                                 java.security.InvalidAlgorithmParameterException

Creates a CanonicalizationMethod for the specified algorithm URI and parameters.

Parameters:

algorithm - the URI identifying the canonicalization algorithm

params - algorithm-specific canonicalization parameters (may be null)

Returns:

the CanonicalizationMethod

Throws:

java.security.InvalidAlgorithmParameterException - if the specified parameters are inappropriate for the requested algorithm

java.security.NoSuchAlgorithmException - if an implementation of the specified algorithm cannot be found

java.lang.NullPointerException - if algorithm is null

unmarshalEncryptedType

public abstract EncryptedType unmarshalEncryptedType(XMLDecryptContext context)
                                              throws MarshalException

Unmarshals a new EncryptedType instance from a mechanism-specific XMLDecryptContext instance.

Parameters:

context - the mechanism-specific decryption context

Returns:

the EncryptedType

Throws:

java.lang.NullPointerException - if context is null

java.lang.ClassCastException - if the type of context is inappropriate for this factory

MarshalException - if an unrecoverable exception occurs during unmarshalling

isFeatureSupported

public abstract boolean isFeatureSupported(java.lang.String feature)

Indicates whether a specified feature is supported.

Parameters:

feature - the feature name (as an absolute URI)

Returns:

true if the specified feature is supported, false otherwise

Throws:

java.lang.NullPointerException - if feature is null

newAgreementMethod

public abstract AgreementMethod newAgreementMethod(java.lang.String algorithm,
                                                   byte[] kaNonce,
                                                   KeyInfo originatorKeyInfo,
                                                   KeyInfo recipientKeyInfo,
                                                   AgreementMethodParameterSpec params)
                                            throws java.security.NoSuchAlgorithmException,
                                                   java.security.InvalidAlgorithmParameterException

Creates an AgreementMethod.

Parameters:

algorithm - the URI identifying the key agreement algorithm

kaNonce - the KA-Nonce (may be null). The value of kaNonce is cloned to protect against subsequent modification

originatorKeyInfo - the originator's key info (may be null)

recipientKeyInfo - the recipient's key info (may be null)

params - algorithm-specific agreement method parameters (may be null)

Returns:

the AgreementMethod

Throws:

java.security.InvalidAlgorithmParameterException - if the specified parameters are inappropriate for the requested algorithm

java.security.NoSuchAlgorithmException - if an implementation of the specified algorithm cannot be found

java.lang.NullPointerException - if algorithm is null

newEncryptedKey

public abstract EncryptedKey newEncryptedKey(ToBeEncryptedKey key,
                                             EncryptionMethod encMethod,
                                             KeyInfo keyInfo,
                                             EncryptionProperties properties,
                                             java.util.List references,
                                             java.lang.String id,
                                             java.lang.String carriedKeyName,
                                             java.lang.String recipient)

Creates an EncryptedKey which contains a CipherValue.

Parameters:

key - the key to be encrypted

encMethod - the encryption method (may be null)

keyInfo - the key info (may be null)

properties - the encryption properties (may be null)

references - a list of DataReferences or KeyReferences (may be null or empty)

id - the ID of the EncryptedKeyElement (may be null)

carriedKeyName - the carried key name (may be null)

recipient - the recipient (may be null)

Returns:

an EncryptedKey

Throws:

java.lang.ClassCastException - if references contains any entries that are not of type DataReference or KeyReference

java.lang.NullPointerException - if key is null

newEncryptedKey

public abstract EncryptedKey newEncryptedKey(ToBeEncryptedKey key,
                                             EncryptionMethod encMethod,
                                             KeyInfo keyInfo,
                                             EncryptionProperties properties,
                                             java.util.List references,
                                             java.lang.String id,
                                             java.lang.String carriedKeyName,
                                             java.lang.String recipient,
                                             CipherReference cipherRef)

Creates an EncryptedKey.

Parameters:

key - the key to be encrypted

encMethod - the encryption method (may be null)

keyInfo - the key info (may be null)

properties - the encryption properties (may be null)

references - a list of DataReferences or KeyReferences (may be null or empty)

id - the ID of the EncryptedKey element (may be null)

carriedKeyName - the carried key name (may be null)

recipient - the recipient (may be null)

cipherRef - the CiphereReference this EncryptedData will contain

Returns:

an EncryptedKey

Throws:

java.lang.ClassCastException - if references contains any entries that are not of type DataReference or KeyReference

java.lang.NullPointerException - if key or cipherRef is null

newOriginatorKeyInfo

public abstract KeyInfo newOriginatorKeyInfo(java.util.List content,
                                             java.lang.String id)

Creates an originator KeyInfo containing the specified list of key information.

Parameters:

content - a list of one or more XMLStructures representing key information types. The list is defensively copied to protect against subsequent modification.

id - the value of an XML ID (may be null)

Returns:

an originator KeyInfo

Throws:

java.lang.NullPointerException - if content is null

java.lang.IllegalArgumentException - if content is empty

java.lang.ClassCastException - if content contains any entities that are not of type XMLStructure

newRecipientKeyInfo

public abstract KeyInfo newRecipientKeyInfo(java.util.List content,
                                            java.lang.String id)

Creates a recipient KeyInfo containing the specified list of key information.

Parameters:

content - a list of one or more XMLStructures representing key information types. The list is defensively copied to protect against subsequent modification.

the - value of an XML ID (may be null)

Returns:

a recipient KeyInfo

Throws:

java.lang.NullPointerException - if content is null

java.lang.IllegalArgumentException - if content is empty

java.lang.ClassCastException - if content contains any entities that are not of type XMLStructure

newDHKeyValue

public abstract DHKeyValue newDHKeyValue(java.security.PublicKey key)
                                  throws java.security.KeyException

Creates a DHKeyValue from the specified key

Parameters:

key - the public key for DH algorithm

Throws:

java.security.KeyException - if the key can not be used to create the DHKeyValue

java.lang.NullPointerException - if the key is null