javax.xml.crypto.dsig.keyinfo
Class KeyInfoFactory

java.lang.Object
  |
  +--javax.xml.crypto.dsig.keyinfo.KeyInfoFactory

public abstract class KeyInfoFactory

extends Object

A factory for creating KeyInfo objects from scratch.

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

KeyInfoFactory factory = KeyInfoFactory.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. See the Service Providers section of the API overview for a list of standard mechanism types.

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

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 KeyInfoFactory instance concurrently should synchronize amongst themselves and provide the necessary locking. Multiple threads each manipulating a different KeyInfoFactory instance need not synchronize.

Constructor Summary

protected

KeyInfoFactory() Default constructor, for invocation by subclasses.

Method Summary

static KeyInfoFactory	getInstance() Returns a KeyInfoFactory that supports the default XML processing mechanism and representation type ("DOM").
static KeyInfoFactory	getInstance(String mechanismType) Returns a KeyInfoFactory that supports the specified XML processing mechanism and representation type (ex: "DOM").
static KeyInfoFactory	getInstance(String mechanismType, Provider provider) Returns a KeyInfoFactory that supports the requested XML processing mechanism and representation type (ex: "DOM"), as supplied by the specified provider.
static KeyInfoFactory	getInstance(String mechanismType, String provider) Returns a KeyInfoFactory that supports the requested XML processing mechanism and representation type (ex: "DOM"), as supplied by the specified provider.
String	getMechanismType() Returns the type of the XML processing mechanism and representation supported by this KeyInfoFactory (ex: "DOM")
Provider	getProvider() Returns the provider of this KeyInfoFactory.
abstract URIDereferencer	getURIDereferencer() Returns a reference to the URIDereferencer that is used by default to dereference URIs in RetrievalMethod objects.
abstract boolean	isFeatureSupported(String feature) Indicates whether a specified feature is supported.
abstract KeyInfo	newKeyInfo(List content) Creates a KeyInfo containing the specified list of key information types.
abstract KeyInfo	newKeyInfo(List content, String id) Creates a KeyInfo containing the specified list of key information types and optional id.
abstract KeyName	newKeyName(String name) Creates a KeyName from the specified name.
abstract KeyValue	newKeyValue(PublicKey key) Creates a KeyValue from the specified public key.
abstract PGPData	newPGPData(byte[] keyId) Creates a PGPData from the specified PGP public key identifier.
abstract PGPData	newPGPData(byte[] keyId, byte[] keyPacket, List other) Creates a PGPData from the specified PGP public key identifier, and optional key material packet and list of external elements.
abstract PGPData	newPGPData(byte[] keyPacket, List other) Creates a PGPData from the specified PGP key material packet and optional list of external elements.
abstract RetrievalMethod	newRetrievalMethod(String uri) Creates a RetrievalMethod from the specified URI.
abstract RetrievalMethod	newRetrievalMethod(String uri, String type, List transforms) Creates a RetrievalMethod from the specified parameters.
abstract X509Data	newX509Data(List content) Creates a X509Data containing the specified list of X.509 content.
abstract X509IssuerSerial	newX509IssuerSerial(String issuerName, BigInteger serialNumber) Creates an X509IssuerSerial from the specified X.500 issuer distinguished name and serial number.

Methods inherited from class java.lang.Object

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

Constructor Detail

KeyInfoFactory

protected KeyInfoFactory()

Default constructor, for invocation by subclasses.

Method Detail

getInstance

public static KeyInfoFactory getInstance(String mechanismType)

Returns a KeyInfoFactory 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 a KeyInfoFactory implementation of the desired mechanism type.

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.

Returns:

a new KeyInfoFactory

Throws:

NullPointerException - if mechanismType is null

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

getInstance

public static KeyInfoFactory getInstance(String mechanismType,
                                         Provider provider)

Returns a KeyInfoFactory 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 KeyInfoFactory

Throws:

NullPointerException - if mechanismType or provider are null

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

getInstance

public static KeyInfoFactory getInstance(String mechanismType,
                                         String provider)
                                  throws NoSuchProviderException

Returns a KeyInfoFactory 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 KeyInfoFactory

Throws:

NoSuchProviderException - if provider has not been configured

NullPointerException - if mechanismType or provider are null

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

getInstance

public static KeyInfoFactory getInstance()

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

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

Returns:

a new KeyInfoFactory

Throws:

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

getMechanismType

public final String getMechanismType()

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

Returns:

the XML processing mechanism type supported by this KeyInfoFactory

getProvider

public final Provider getProvider()

Returns the provider of this KeyInfoFactory.

Returns:

the provider of this KeyInfoFactory

newKeyInfo

public abstract KeyInfo newKeyInfo(List content)

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

Parameters:

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

Returns:

a KeyInfo

Throws:

NullPointerException - if content is null

IllegalArgumentException - if content is empty

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

newKeyInfo

public abstract KeyInfo newKeyInfo(List content,
                                   String id)

Creates a KeyInfo containing the specified list of key information types and optional id. The id parameter represents the value of an XML ID attribute and is useful for referencing the KeyInfo from other XML structures.

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 KeyInfo

Throws:

NullPointerException - if content is null

IllegalArgumentException - if content is empty

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

newKeyName

public abstract KeyName newKeyName(String name)

Creates a KeyName from the specified name.

Parameters:

name - the name that identifies the key

Returns:

a KeyName

Throws:

NullPointerException - if name is null

newKeyValue

public abstract KeyValue newKeyValue(PublicKey key)
                              throws KeyException

Creates a KeyValue from the specified public key.

Parameters:

key - the public key

Returns:

a KeyValue

Throws:

KeyException - if the key's algorithm is not recognized or supported by this KeyInfoFactory

NullPointerException - if key is null

newPGPData

public abstract PGPData newPGPData(byte[] keyId)

Creates a PGPData from the specified PGP public key identifier.

Parameters:

keyId - a PGP public key identifier as defined in RFC 2440, section 11.2. The array is cloned to protect against subsequent modification.

Returns:

a PGPData

Throws:

NullPointerException - if keyId is null

IllegalArgumentException - if the key id is not in the correct format

newPGPData

public abstract PGPData newPGPData(byte[] keyId,
                                   byte[] keyPacket,
                                   List other)

Creates a PGPData from the specified PGP public key identifier, and optional key material packet and list of external elements.

Parameters:

keyId - a PGP public key identifier as defined in RFC 2440, section 11.2. The array is cloned to protect against subsequent modification.

keyPacket - a PGP key material packet as defined in RFC 2440, section 5.5. The array is cloned to protect against subsequent modification. May be null.

other - a list of XMLStructures representing elements from an external namespace. The list is defensively copied to protect against subsequent modification. May be null or empty.

Returns:

a PGPData

Throws:

NullPointerException - if keyId is null

IllegalArgumentException - if the key id or key packet is not in the correct format

ClassCastException - if other contains any entries that are not of type XMLStructure

newPGPData

public abstract PGPData newPGPData(byte[] keyPacket,
                                   List other)

Creates a PGPData from the specified PGP key material packet and optional list of external elements.

Parameters:

keyPacket - a PGP key material packet as defined in RFC 2440, section 5.5. The array is cloned to protect against subsequent modification.

other - a list of XMLStructures representing elements from an external namespace. The list is defensively copied to protect against subsequent modification. May be null or empty.

Returns:

a PGPData

Throws:

NullPointerException - if keyPacket is null

IllegalArgumentException - if the key packet is not in the correct format

ClassCastException - if other contains any entries that are not of type XMLStructure

newRetrievalMethod

public abstract RetrievalMethod newRetrievalMethod(String uri)

Creates a RetrievalMethod from the specified URI.

Parameters:

uri - the URI that identifies the KeyInfo information to be retrieved

Returns:

a RetrievalMethod

Throws:

NullPointerException - if uri is null

IllegalArgumentException - if uri is not RFC 2396 compliant

newRetrievalMethod

public abstract RetrievalMethod newRetrievalMethod(String uri,
                                                   String type,
                                                   List transforms)

Creates a RetrievalMethod from the specified parameters.

Parameters:

uri - the URI that identifies the KeyInfo information to be retrieved

type - a URI that identifies the type of KeyInfo information to be retrieved (may be null)

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

Returns:

a RetrievalMethod

Throws:

NullPointerException - if uri is null

IllegalArgumentException - if uri is not RFC 2396 compliant

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

newX509Data

public abstract X509Data newX509Data(List content)

Creates a X509Data containing the specified list of X.509 content.

Parameters:

content - a list of one or more X.509 content types. Valid types are String (subject names), byte[] (subject key ids), X509Certificate, X509CRL, or XMLStructure (X509IssuerSerial objects or elements from an external namespace). The list is defensively copied to protect against subsequent modification.

Returns:

a X509Data

Throws:

NullPointerException - if content is null

IllegalArgumentException - if content is empty

ClassCastException - if content contains any entries that are not of one of the valid types mentioned above

newX509IssuerSerial

public abstract X509IssuerSerial newX509IssuerSerial(String issuerName,
                                                     BigInteger serialNumber)

Creates an X509IssuerSerial from the specified X.500 issuer distinguished name and serial number.

Parameters:

issuerName - the issuer's distinguished name in RFC 2253 String format

serialNumber - the serial number

Returns:

an X509IssuerSerial

Throws:

NullPointerException - if issuerName or serialNumber are null

IllegalArgumentException - if the issuer name is not RFC 2253 compliant

isFeatureSupported

public abstract boolean isFeatureSupported(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:

NullPointerException - if feature is null

getURIDereferencer

public abstract URIDereferencer getURIDereferencer()

Returns a reference to the URIDereferencer that is used by default to dereference URIs in RetrievalMethod objects.

Returns:

a reference to the default URIDereferencer