Overview | Package | Class | Use | Tree | Serialized | Deprecated | Index | Help
| XML Digital Signature and Encryption, 1.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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 `XMLStructure`s of a particular `EncryptedType` that is to be generated. The behavior is undefined if `XMLStructure`s 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 `EncryptionProperty`s 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 `XMLStructure`s, 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 `XMLStructure`s (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 `XMLStructure`s (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 `XMLStructure`s, target URI and optional id.

  Parameters:
    `content` - a list of one or more `XMLStructure`s. 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 `EncryptionProperty`s and optional id.

  Parameters:
    `properties` - a list of one or more `EncryptionProperty`s. 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 `Transform`s. 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 `DataReference`s or `KeyReference`s (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 `DataReference`s or `KeyReference`s (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

Overview | Package | Class | Use | Tree | Serialized | Deprecated | Index | Help
| XML Digital Signature and Encryption, 1.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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