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 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 XMLStructure
s 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 XMLStructure
s of a particular
KeyInfo
object. The behavior is undefined if
XMLStructure
s 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.
- Since:
- 1.6
-
Constructor Summary
ModifierConstructorDescriptionprotected
Default constructor, for invocation by subclasses. -
Method Summary
Modifier and TypeMethodDescriptionstatic KeyInfoFactory
Returns aKeyInfoFactory
that supports the default XML processing mechanism and representation type ("DOM").static KeyInfoFactory
getInstance
(String mechanismType) Returns aKeyInfoFactory
that supports the specified XML processing mechanism and representation type (ex: "DOM").static KeyInfoFactory
getInstance
(String mechanismType, String provider) Returns aKeyInfoFactory
that supports the requested XML processing mechanism and representation type (ex: "DOM"), as supplied by the specified provider.static KeyInfoFactory
getInstance
(String mechanismType, Provider provider) Returns aKeyInfoFactory
that supports the requested XML processing mechanism and representation type (ex: "DOM"), as supplied by the specified provider.final String
Returns the type of the XML processing mechanism and representation supported by thisKeyInfoFactory
(ex: "DOM")final Provider
Returns the provider of thisKeyInfoFactory
.abstract URIDereferencer
Returns a reference to theURIDereferencer
that is used by default to dereference URIs inRetrievalMethod
objects.abstract boolean
isFeatureSupported
(String feature) Indicates whether a specified feature is supported.abstract KeyInfo
newKeyInfo
(List<? extends XMLStructure> content) Creates aKeyInfo
containing the specified list of key information types.abstract KeyInfo
newKeyInfo
(List<? extends XMLStructure> content, String id) Creates aKeyInfo
containing the specified list of key information types and optional id.abstract KeyName
newKeyName
(String name) Creates aKeyName
from the specified name.abstract KeyValue
newKeyValue
(PublicKey key) Creates aKeyValue
from the specified public key.abstract PGPData
newPGPData
(byte[] keyId) Creates aPGPData
from the specified PGP public key identifier.abstract PGPData
newPGPData
(byte[] keyId, byte[] keyPacket, List<? extends XMLStructure> other) Creates aPGPData
from the specified PGP public key identifier, and optional key material packet and list of external elements.abstract PGPData
newPGPData
(byte[] keyPacket, List<? extends XMLStructure> other) Creates aPGPData
from the specified PGP key material packet and optional list of external elements.abstract RetrievalMethod
newRetrievalMethod
(String uri) Creates aRetrievalMethod
from the specified URI.abstract RetrievalMethod
newRetrievalMethod
(String uri, String type, List<? extends Transform> transforms) Creates aRetrievalMethod
from the specified parameters.abstract X509Data
newX509Data
(List<?> content) Creates aX509Data
containing the specified list of X.509 content.abstract X509IssuerSerial
newX509IssuerSerial
(String issuerName, BigInteger serialNumber) Creates anX509IssuerSerial
from the specified X.500 issuer distinguished name and serial number.abstract KeyInfo
unmarshalKeyInfo
(XMLStructure xmlStructure) Unmarshals a newKeyInfo
instance from a mechanism-specificXMLStructure
(ex:DOMStructure
) instance.
-
Constructor Details
-
KeyInfoFactory
protected KeyInfoFactory()Default constructor, for invocation by subclasses.
-
-
Method Details
-
getInstance
Returns aKeyInfoFactory
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 securityProvider
s, starting with the most preferredProvider
. A newKeyInfoFactory
object from the firstProvider
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 bySecurity.getProviders()
. - Parameters:
mechanismType
- the type of the XML processing mechanism and representation. See theKeyInfoFactory
section in the Java Security Standard Algorithm Names Specification for a list of standard mechanism types.- Returns:
- a new
KeyInfoFactory
- Throws:
NullPointerException
- ifmechanismType
isnull
NoSuchMechanismException
- if noProvider
supports aKeyInfoFactory
implementation for the specified mechanism- See Also:
-
getInstance
Returns aKeyInfoFactory
that supports the requested XML processing mechanism and representation type (ex: "DOM"), as supplied by the specified provider. Note that the specifiedProvider
object does not have to be registered in the provider list.- Parameters:
mechanismType
- the type of the XML processing mechanism and representation. See theKeyInfoFactory
section in the Java Security Standard Algorithm Names Specification for a list of standard mechanism types.provider
- theProvider
object- Returns:
- a new
KeyInfoFactory
- Throws:
NullPointerException
- ifmechanismType
orprovider
arenull
NoSuchMechanismException
- if aKeyInfoFactory
implementation for the specified mechanism is not available from the specifiedProvider
object- See Also:
-
getInstance
public static KeyInfoFactory getInstance(String mechanismType, String provider) throws NoSuchProviderException Returns aKeyInfoFactory
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
- the type of the XML processing mechanism and representation. See theKeyInfoFactory
section in the Java Security Standard Algorithm Names Specification for a list of standard mechanism types.provider
- the string name of the provider- Returns:
- a new
KeyInfoFactory
- Throws:
NoSuchProviderException
- if the specified provider is not registered in the security provider listNullPointerException
- ifmechanismType
orprovider
arenull
NoSuchMechanismException
- if aKeyInfoFactory
implementation for the specified mechanism is not available from the specified provider- See Also:
-
getInstance
Returns aKeyInfoFactory
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 securityProvider
s, starting with the most preferredProvider
. A newKeyInfoFactory
object from the firstProvider
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 bySecurity.getProviders()
. - Returns:
- a new
KeyInfoFactory
- Throws:
NoSuchMechanismException
- if noProvider
supports aKeyInfoFactory
implementation for the DOM mechanism- See Also:
-
getMechanismType
Returns the type of the XML processing mechanism and representation supported by thisKeyInfoFactory
(ex: "DOM")- Returns:
- the XML processing mechanism type supported by this
KeyInfoFactory
-
getProvider
Returns the provider of thisKeyInfoFactory
.- Returns:
- the provider of this
KeyInfoFactory
-
newKeyInfo
Creates aKeyInfo
containing the specified list of key information types.- Parameters:
content
- a list of one or moreXMLStructure
s representing key information types. The list is defensively copied to protect against subsequent modification.- Returns:
- a
KeyInfo
- Throws:
NullPointerException
- ifcontent
isnull
IllegalArgumentException
- ifcontent
is emptyClassCastException
- ifcontent
contains any entries that are not of typeXMLStructure
-
newKeyInfo
Creates aKeyInfo
containing the specified list of key information types and optional id. Theid
parameter represents the value of an XMLID
attribute and is useful for referencing theKeyInfo
from other XML structures.- Parameters:
content
- a list of one or moreXMLStructure
s representing key information types. The list is defensively copied to protect against subsequent modification.id
- the value of an XMLID
(may benull
)- Returns:
- a
KeyInfo
- Throws:
NullPointerException
- ifcontent
isnull
IllegalArgumentException
- ifcontent
is emptyClassCastException
- ifcontent
contains any entries that are not of typeXMLStructure
-
newKeyName
Creates aKeyName
from the specified name.- Parameters:
name
- the name that identifies the key- Returns:
- a
KeyName
- Throws:
NullPointerException
- ifname
isnull
-
newKeyValue
Creates aKeyValue
from the specified public key.- Parameters:
key
- the public key- Returns:
- a
KeyValue
- Throws:
KeyException
- if thekey
's algorithm is not recognized or supported by thisKeyInfoFactory
NullPointerException
- ifkey
isnull
-
newPGPData
Creates aPGPData
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
- ifkeyId
isnull
IllegalArgumentException
- if the key id is not in the correct format
-
newPGPData
public abstract PGPData newPGPData(byte[] keyId, byte[] keyPacket, List<? extends XMLStructure> other) Creates aPGPData
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 benull
.other
- a list ofXMLStructure
s representing elements from an external namespace. The list is defensively copied to protect against subsequent modification. May benull
or empty.- Returns:
- a
PGPData
- Throws:
NullPointerException
- ifkeyId
isnull
IllegalArgumentException
- if thekeyId
orkeyPacket
is not in the correct format. ForkeyPacket
, 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
- ifother
contains any entries that are not of typeXMLStructure
-
newPGPData
Creates aPGPData
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 ofXMLStructure
s representing elements from an external namespace. The list is defensively copied to protect against subsequent modification. May benull
or empty.- Returns:
- a
PGPData
- Throws:
NullPointerException
- ifkeyPacket
isnull
IllegalArgumentException
- ifkeyPacket
is not in the correct format. ForkeyPacket
, 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
- ifother
contains any entries that are not of typeXMLStructure
-
newRetrievalMethod
Creates aRetrievalMethod
from the specified URI.- Parameters:
uri
- the URI that identifies theKeyInfo
information to be retrieved- Returns:
- a
RetrievalMethod
- Throws:
NullPointerException
- ifuri
isnull
IllegalArgumentException
- ifuri
is not RFC 2396 compliant
-
newRetrievalMethod
public abstract RetrievalMethod newRetrievalMethod(String uri, String type, List<? extends Transform> transforms) Creates aRetrievalMethod
from the specified parameters.- Parameters:
uri
- the URI that identifies theKeyInfo
information to be retrievedtype
- a URI that identifies the type ofKeyInfo
information to be retrieved (may benull
)transforms
- a list ofTransform
s. The list is defensively copied to protect against subsequent modification. May benull
or empty.- Returns:
- a
RetrievalMethod
- Throws:
NullPointerException
- ifuri
isnull
IllegalArgumentException
- ifuri
is not RFC 2396 compliantClassCastException
- iftransforms
contains any entries that are not of typeTransform
-
newX509Data
Creates aX509Data
containing the specified list of X.509 content.- Parameters:
content
- a list of one or more X.509 content types. Valid types areString
(subject names),byte[]
(subject key ids),X509Certificate
,X509CRL
, orXMLStructure
(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:
- a
X509Data
- Throws:
NullPointerException
- ifcontent
isnull
IllegalArgumentException
- ifcontent
is empty, or if a subject name is not RFC 2253 compliant or one of the attribute type keywords is not recognized.ClassCastException
- ifcontent
contains any entries that are not of one of the valid types mentioned above
-
newX509IssuerSerial
Creates anX509IssuerSerial
from the specified X.500 issuer distinguished name and serial number.- Parameters:
issuerName
- 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
- the serial number- Returns:
- an
X509IssuerSerial
- Throws:
NullPointerException
- ifissuerName
orserialNumber
arenull
IllegalArgumentException
- if the issuer name is not RFC 2253 compliant or one of the attribute type keywords is not recognized.
-
isFeatureSupported
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
- iffeature
isnull
-
getURIDereferencer
Returns a reference to theURIDereferencer
that is used by default to dereference URIs inRetrievalMethod
objects.- Returns:
- a reference to the default
URIDereferencer
-
unmarshalKeyInfo
Unmarshals a newKeyInfo
instance from a mechanism-specificXMLStructure
(ex:DOMStructure
) instance.- Parameters:
xmlStructure
- a mechanism-specific XML structure from which to unmarshal the keyinfo from- Returns:
- the
KeyInfo
- Throws:
NullPointerException
- ifxmlStructure
isnull
ClassCastException
- if the type ofxmlStructure
is inappropriate for this factoryMarshalException
- if an unrecoverable exception occurs during unmarshalling
-