APIdia Launch Partner
Top Description Fields Constructors Methods
javax.xml.crypto.dsig.keyinfo

public abstract Class KeyInfoFactory

extends Object
Class Inheritance
Known Direct Subclasses
org.jcp.xml.dsig.internal.dom.DOMKeyInfoFactory
Imports
java.math.BigInteger, java.security.KeyException, .NoSuchAlgorithmException, .NoSuchProviderException, .Provider, .Provider.Service, .PublicKey, .Security, java.security.cert.X509CRL, java.util.List, javax.xml.crypto.MarshalException, .NoSuchMechanismException, .URIDereferencer, .XMLStructure, javax.xml.crypto.dom.DOMStructure, javax.xml.crypto.dsig.*
A factory for creating KeyInfo objects from scratch or for unmarshalling a KeyInfo object from a corresponding XML representation.

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. See the KeyInfoFactory section in the Java Security Standard Algorithm Names Specification for a list of standard mechanism types.

KeyInfoFactory implementations are registered and loaded using the java.security.Provider mechanism. For example, a service provider that supports the DOM mechanism would be specified in the Provider subclass as: 

    put("KeyInfoFactory.DOM", "org.example.DOMKeyInfoFactory");

Also, the XMLStructures that are created by this factory may contain state specific to the KeyInfo and are not intended to be reusable.

An implementation MUST minimally support the default mechanism type: DOM.

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.

Authors
Sean Mullan, JSR 105 Expert Group
Since
1.6
External Specification
Java Security Standard Algorithm Names

Field Summary

Modifier and TypeField and Description
private String
mechanismType

private Provider
provider

Constructor Summary

AccessConstructor and Description
protected
KeyInfoFactory()

Default constructor, for invocation by subclasses.

Method Summary

Modifier and TypeMethod and Description
public static KeyInfoFactory

Returns:

a new KeyInfoFactory
getInstance(String
the type of the XML processing mechanism and representation. See the KeyInfoFactory section in the Java Security Standard Algorithm Names Specification for a list of standard mechanism types.
mechanismType)

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

public static KeyInfoFactory

Returns:

a new KeyInfoFactory
getInstance(String
the type of the XML processing mechanism and representation. See the KeyInfoFactory section in the Java Security Standard Algorithm Names Specification for a list of standard mechanism types.
mechanismType, Provider
the Provider object
provider)

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

public static KeyInfoFactory

Returns:

a new KeyInfoFactory
getInstance(String
the type of the XML processing mechanism and representation. See the KeyInfoFactory section in the Java Security Standard Algorithm Names Specification for a list of standard mechanism types.
mechanismType, String
the string name of the provider
provider)

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

public static KeyInfoFactory

Returns:

a new KeyInfoFactory
getInstance()

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

public final String

Returns:

the XML processing mechanism type supported by this KeyInfoFactory
getMechanismType()

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

public final Provider

Returns:

the provider of this KeyInfoFactory
getProvider()

Returns the provider of this KeyInfoFactory.

public abstract URIDereferencer

Returns:

a reference to the default URIDereferencer
getURIDereferencer()

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

public abstract boolean

Returns:

true if the specified feature is supported, false otherwise
isFeatureSupported(String
the feature name (as an absolute URI)
feature)

Indicates whether a specified feature is supported.

public abstract KeyInfo

Returns:

a KeyInfo
newKeyInfo(List<? extends XMLStructure>
a list of one or more XMLStructures representing key information types. The list is defensively copied to protect against subsequent modification.
content)

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

public abstract KeyInfo

Returns:

a KeyInfo
newKeyInfo(List<? extends XMLStructure>
a list of one or more XMLStructures representing key information types. The list is defensively copied to protect against subsequent modification.
content, String
the value of an XML ID (may be null)
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.

public abstract KeyName

Returns:

a KeyName
newKeyName(String
the name that identifies the key
name)

Creates a KeyName from the specified name.

public abstract KeyValue

Returns:

a KeyValue
newKeyValue(PublicKey
the public key
key)

Creates a KeyValue from the specified public key.

public abstract PGPData

Returns:

a PGPData
newPGPData(byte[]
a PGP public key identifier as defined in RFC 2440, section 11.2. The array is cloned to protect against subsequent modification.
keyId)

Creates a PGPData from the specified PGP public key identifier.

public abstract PGPData

Returns:

a PGPData
newPGPData(byte[]
a PGP public key identifier as defined in RFC 2440, section 11.2. The array is cloned to protect against subsequent modification.
keyId, byte[]
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.
keyPacket, List<? extends XMLStructure>
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.
other)

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

public abstract PGPData

Returns:

a PGPData
newPGPData(byte[]
a PGP key material packet as defined in RFC 2440, section 5.5. The array is cloned to protect against subsequent modification.
keyPacket, List<? extends XMLStructure>
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.
other)

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

public abstract RetrievalMethod

Returns:

a RetrievalMethod
newRetrievalMethod(String
the URI that identifies the KeyInfo information to be retrieved
uri)

Creates a RetrievalMethod from the specified URI.

public abstract RetrievalMethod

Returns:

a RetrievalMethod
newRetrievalMethod(String
the URI that identifies the KeyInfo information to be retrieved
uri, String
a URI that identifies the type of KeyInfo information to be retrieved (may be null)
type, List<? extends Transform>
a list of Transforms. The list is defensively copied to protect against subsequent modification. May be null or empty.
transforms)

Creates a RetrievalMethod from the specified parameters.

public abstract X509Data

Returns:

a X509Data
newX509Data(List<?>
a list of one or more X.509 content types. Valid types are String (subject names), byte[] (subject key ids), java.security.cert.X509Certificate, X509CRL, or XMLStructure (X509IssuerSerial objects or elements from an external namespace). Subject names are distinguished names in RFC 2253 String format. Implementations MUST support the attribute type keywords defined in RFC 2253 (CN, L, ST, O, OU, C, STREET, DC and UID). Implementations MAY support additional keywords. The list is defensively copied to protect against subsequent modification.
content)

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

public abstract X509IssuerSerial

Returns:

an X509IssuerSerial
newX509IssuerSerial(String
the issuer's distinguished name in RFC 2253 String format. Implementations MUST support the attribute type keywords defined in RFC 2253 (CN, L, ST, O, OU, C, STREET, DC and UID). Implementations MAY support additional keywords.
issuerName, BigInteger
the serial number
serialNumber)

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

public abstract KeyInfo

Returns:

the KeyInfo
unmarshalKeyInfo(XMLStructure
a mechanism-specific XML structure from which to unmarshal the keyinfo from
xmlStructure)

Unmarshals a new KeyInfo instance from a mechanism-specific XMLStructure (ex: DOMStructure) instance.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

mechanismTypeback to summary
private String mechanismType
providerback to summary
private Provider provider

Constructor Detail

KeyInfoFactoryback to summary
protected KeyInfoFactory()

Default constructor, for invocation by subclasses.

Method Detail

getInstanceback to summary
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. It traverses the list of registered security Providers, starting with the most preferred Provider. A new KeyInfoFactory object from the first Provider that supports the specified mechanism is returned.

Note that the list of registered providers may be retrieved via the Security.getProviders() method.

Implementation Note

The JDK Reference Implementation additionally uses the jdk.security.provider.preferred Security property to determine the preferred provider order for the specified algorithm. This may be different than the order of providers returned by Security.getProviders().

Parameters
mechanismType:String

the type of the XML processing mechanism and representation. See the KeyInfoFactory section in the Java Security Standard Algorithm Names Specification for a list of standard mechanism types.

Returns:KeyInfoFactory

a new KeyInfoFactory

Exceptions
NullPointerException:
if mechanismType is null
NoSuchMechanismException:
if no Provider supports a KeyInfoFactory implementation for the specified mechanism
External Specification
Java Security Standard Algorithm Names
See Also
Provider
getInstanceback to summary
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. Note that the specified Provider object does not have to be registered in the provider list.

Parameters
mechanismType:String

the type of the XML processing mechanism and representation. See the KeyInfoFactory section in the Java Security Standard Algorithm Names Specification for a list of standard mechanism types.

provider:Provider

the Provider object

Returns:KeyInfoFactory

a new KeyInfoFactory

Exceptions
NullPointerException:
if mechanismType or provider are null
NoSuchMechanismException:
if a KeyInfoFactory implementation for the specified mechanism is not available from the specified Provider object
External Specification
Java Security Standard Algorithm Names
See Also
Provider
getInstanceback to summary
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. The specified provider must be registered in the security provider list.

Note that the list of registered providers may be retrieved via the Security.getProviders() method.

Parameters
mechanismType:String

the type of the XML processing mechanism and representation. See the KeyInfoFactory section in the Java Security Standard Algorithm Names Specification for a list of standard mechanism types.

provider:String

the string name of the provider

Returns:KeyInfoFactory

a new KeyInfoFactory

Exceptions
NoSuchProviderException:
if the specified provider is not registered in the security provider list
NullPointerException:
if mechanismType or provider are null
NoSuchMechanismException:
if a KeyInfoFactory implementation for the specified mechanism is not available from the specified provider
External Specification
Java Security Standard Algorithm Names
See Also
Provider
getInstanceback to summary
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. It traverses the list of registered security Providers, starting with the most preferred Provider. A new KeyInfoFactory object from the first Provider that supports the DOM mechanism is returned.

Note that the list of registered providers may be retrieved via the Security.getProviders() method.

Implementation Note

The JDK Reference Implementation additionally uses the jdk.security.provider.preferred Security property to determine the preferred provider order for the specified algorithm. This may be different than the order of providers returned by Security.getProviders().

Returns:KeyInfoFactory

a new KeyInfoFactory

Exceptions
NoSuchMechanismException:
if no Provider supports a KeyInfoFactory implementation for the DOM mechanism
See Also
Provider
getMechanismTypeback to summary
public final String getMechanismType()

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

Returns:String

the XML processing mechanism type supported by this KeyInfoFactory

getProviderback to summary
public final Provider getProvider()

Returns the provider of this KeyInfoFactory.

Returns:Provider

the provider of this KeyInfoFactory

getURIDereferencerback to summary
public abstract URIDereferencer getURIDereferencer()

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

Returns:URIDereferencer

a reference to the default URIDereferencer

isFeatureSupportedback to summary
public abstract boolean isFeatureSupported(String feature)

Indicates whether a specified feature is supported.

Parameters
feature:String

the feature name (as an absolute URI)

Returns:boolean

true if the specified feature is supported, false otherwise

Exceptions
NullPointerException:
if feature is null
newKeyInfoback to summary
public abstract KeyInfo newKeyInfo(List<? extends XMLStructure> content)

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

Parameters
content:List<? extends XMLStructure>

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

Returns:KeyInfo

a KeyInfo

Exceptions
NullPointerException:
if content is null
IllegalArgumentException:
if content is empty
ClassCastException:
if content contains any entries that are not of type XMLStructure
newKeyInfoback to summary
public abstract KeyInfo newKeyInfo(List<? extends XMLStructure> 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:List<? extends XMLStructure>

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

id:String

the value of an XML ID (may be null)

Returns:KeyInfo

a KeyInfo

Exceptions
NullPointerException:
if content is null
IllegalArgumentException:
if content is empty
ClassCastException:
if content contains any entries that are not of type XMLStructure
newKeyNameback to summary
public abstract KeyName newKeyName(String name)

Creates a KeyName from the specified name.

Parameters
name:String

the name that identifies the key

Returns:KeyName

a KeyName

Exceptions
NullPointerException:
if name is null
newKeyValueback to summary
public abstract KeyValue newKeyValue(PublicKey key) throws KeyException

Creates a KeyValue from the specified public key.

Parameters
key:PublicKey

the public key

Returns:KeyValue

a KeyValue

Exceptions
KeyException:
if the key's algorithm is not recognized or supported by this KeyInfoFactory
NullPointerException:
if key is null
newPGPDataback to summary
public abstract PGPData newPGPData(byte[] keyId)

Creates a PGPData from the specified PGP public key identifier.

Parameters
keyId:byte[]

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

Returns:PGPData

a PGPData

Exceptions
NullPointerException:
if keyId is null
IllegalArgumentException:
if the key id is not in the correct format
newPGPDataback to summary
public abstract PGPData newPGPData(byte[] keyId, byte[] keyPacket, List<? extends XMLStructure> other)

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

Parameters
keyId:byte[]

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

keyPacket:byte[]

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:List<? extends XMLStructure>

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:PGPData

a PGPData

Exceptions
NullPointerException:
if keyId is null
IllegalArgumentException:
if the keyId or keyPacket is not in the correct format. For keyPacket, the format of the packet header is checked and the tag is verified that it is of type key material. The contents and format of the packet body are not checked.
ClassCastException:
if other contains any entries that are not of type XMLStructure
newPGPDataback to summary
public abstract PGPData newPGPData(byte[] keyPacket, List<? extends XMLStructure> other)

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

Parameters
keyPacket:byte[]

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

other:List<? extends XMLStructure>

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:PGPData

a PGPData

Exceptions
NullPointerException:
if keyPacket is null
IllegalArgumentException:
if keyPacket is not in the correct format. For keyPacket, the format of the packet header is checked and the tag is verified that it is of type key material. The contents and format of the packet body are not checked.
ClassCastException:
if other contains any entries that are not of type XMLStructure
newRetrievalMethodback to summary
public abstract RetrievalMethod newRetrievalMethod(String uri)

Creates a RetrievalMethod from the specified URI.

Parameters
uri:String

the URI that identifies the KeyInfo information to be retrieved

Returns:RetrievalMethod

a RetrievalMethod

Exceptions
NullPointerException:
if uri is null
IllegalArgumentException:
if uri is not RFC 2396 compliant
newRetrievalMethodback to summary
public abstract RetrievalMethod newRetrievalMethod(String uri, String type, List<? extends Transform> transforms)

Creates a RetrievalMethod from the specified parameters.

Parameters
uri:String

the URI that identifies the KeyInfo information to be retrieved

type:String

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

transforms:List<? extends Transform>

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

Returns:RetrievalMethod

a RetrievalMethod

Exceptions
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
newX509Databack to summary
public abstract X509Data newX509Data(List<?> content)

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

Parameters
content:List<?>

a list of one or more X.509 content types. Valid types are String (subject names), byte[] (subject key ids), java.security.cert.X509Certificate, X509CRL, or XMLStructure (X509IssuerSerial objects or elements from an external namespace). Subject names are distinguished names in RFC 2253 String format. Implementations MUST support the attribute type keywords defined in RFC 2253 (CN, L, ST, O, OU, C, STREET, DC and UID). Implementations MAY support additional keywords. The list is defensively copied to protect against subsequent modification.

Returns:X509Data

a X509Data

Exceptions
NullPointerException:
if content is null
IllegalArgumentException:
if content is empty, or if a subject name is not RFC 2253 compliant or one of the attribute type keywords is not recognized.
ClassCastException:
if content contains any entries that are not of one of the valid types mentioned above
newX509IssuerSerialback to summary
public abstract X509IssuerSerial newX509IssuerSerial(String issuerName, BigInteger serialNumber)

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

Parameters
issuerName:String

the issuer's distinguished name in RFC 2253 String format. Implementations MUST support the attribute type keywords defined in RFC 2253 (CN, L, ST, O, OU, C, STREET, DC and UID). Implementations MAY support additional keywords.

serialNumber:BigInteger

the serial number

Returns:X509IssuerSerial

an X509IssuerSerial

Exceptions
NullPointerException:
if issuerName or serialNumber are null
IllegalArgumentException:
if the issuer name is not RFC 2253 compliant or one of the attribute type keywords is not recognized.
unmarshalKeyInfoback to summary
public abstract KeyInfo unmarshalKeyInfo(XMLStructure xmlStructure) throws MarshalException

Unmarshals a new KeyInfo instance from a mechanism-specific XMLStructure (ex: DOMStructure) instance.

Parameters
xmlStructure:XMLStructure

a mechanism-specific XML structure from which to unmarshal the keyinfo from

Returns:KeyInfo

the KeyInfo

Exceptions
MarshalException:
if an unrecoverable exception occurs during unmarshalling
NullPointerException:
if xmlStructure is null
ClassCastException:
if the type of xmlStructure is inappropriate for this factory