XML Digital Signature and Encryption, 1.0

javax.xml.crypto.enc
Class XMLEncryptionFactory

java.lang.Object
  extended by 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.


Constructor Summary
protected XMLEncryptionFactory()
          Default constructor, for invocation by subclasses.
 
Method Summary
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
 

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

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)
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.
id - 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

XML Digital Signature and Encryption, 1.0

Copyright © 2003-2004, IBM Corporation and Sun Microsystems, Inc. All rights reserved.
Please send comments to: jsr-106-comments@jcp.org