public abstract class KeyInfoFactory extends Object
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.
Modifier | Constructor | Description |
---|---|---|
protected |
Default constructor, for invocation by subclasses. |
Modifier and Type | Method | Description |
---|---|---|
static KeyInfoFactory |
getInstance() |
Returns a KeyInfoFactory that supports the default XML processing mechanism and representation type ("DOM"). |
static KeyInfoFactory |
getInstance |
Returns a KeyInfoFactory that supports the specified XML processing mechanism and representation type (ex: "DOM"). |
static KeyInfoFactory |
getInstance |
Returns a KeyInfoFactory that supports the requested XML processing mechanism and representation type (ex: "DOM"), as supplied by the specified provider. |
static KeyInfoFactory |
getInstance |
Returns a KeyInfoFactory that supports the requested XML processing mechanism and representation type (ex: "DOM"), as supplied by the specified provider. |
final String |
getMechanismType() |
Returns the type of the XML processing mechanism and representation supported by this KeyInfoFactory (ex: "DOM") |
final 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 |
Indicates whether a specified feature is supported. |
abstract KeyInfo |
newKeyInfo |
Creates a KeyInfo containing the specified list of key information types. |
abstract KeyInfo |
newKeyInfo |
Creates a KeyInfo containing the specified list of key information types and optional id. |
abstract KeyName |
newKeyName |
Creates a KeyName from the specified name. |
abstract KeyValue |
newKeyValue |
Creates a KeyValue from the specified public key. |
abstract PGPData |
newPGPData |
Creates a PGPData from the specified PGP public key identifier. |
abstract PGPData |
newPGPData |
Creates a PGPData from the specified PGP public key identifier, and optional key material packet and list of external elements. |
abstract PGPData |
newPGPData |
Creates a PGPData from the specified PGP key material packet and optional list of external elements. |
abstract RetrievalMethod |
newRetrievalMethod |
Creates a RetrievalMethod from the specified URI. |
abstract RetrievalMethod |
newRetrievalMethod |
Creates a RetrievalMethod from the specified parameters. |
abstract X509Data |
newX509Data |
Creates a X509Data containing the specified list of X.509 content. |
abstract X509IssuerSerial |
newX509IssuerSerial |
Creates an X509IssuerSerial from the specified X.500 issuer distinguished name and serial number. |
abstract KeyInfo |
unmarshalKeyInfo |
Unmarshals a new KeyInfo instance from a mechanism-specific XMLStructure (ex: DOMStructure ) instance. |
protected KeyInfoFactory()
public static KeyInfoFactory getInstance(String mechanismType)
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 Provider
s, 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.
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()
.mechanismType
- 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.KeyInfoFactory
NullPointerException
- if mechanismType
is null
NoSuchMechanismException
- if no Provider
supports a KeyInfoFactory
implementation for the specified mechanismpublic static KeyInfoFactory getInstance(String mechanismType, Provider provider)
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.mechanismType
- 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
- the Provider
objectKeyInfoFactory
NullPointerException
- if mechanismType
or provider
are null
NoSuchMechanismException
- if a KeyInfoFactory
implementation for the specified mechanism is not available from the specified Provider
objectpublic static KeyInfoFactory getInstance(String mechanismType, String provider) throws NoSuchProviderException
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.
mechanismType
- 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
- the string name of the providerKeyInfoFactory
NoSuchProviderException
- if the specified provider is not registered in the security provider listNullPointerException
- if mechanismType
or provider
are null
NoSuchMechanismException
- if a KeyInfoFactory
implementation for the specified mechanism is not available from the specified providerpublic static KeyInfoFactory getInstance()
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 Provider
s, 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.
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()
.KeyInfoFactory
NoSuchMechanismException
- if no Provider
supports a KeyInfoFactory
implementation for the DOM mechanismpublic final String getMechanismType()
KeyInfoFactory
(ex: "DOM")KeyInfoFactory
public final Provider getProvider()
KeyInfoFactory
.KeyInfoFactory
public abstract KeyInfo newKeyInfo(List<? extends XMLStructure> content)
KeyInfo
containing the specified list of key information types.content
- a list of one or more XMLStructure
s representing key information types. The list is defensively copied to protect against subsequent modification.KeyInfo
NullPointerException
- if content
is null
IllegalArgumentException
- if content
is emptyClassCastException
- if content
contains any entries that are not of type XMLStructure
public abstract KeyInfo newKeyInfo(List<? extends XMLStructure> content, String id)
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.content
- a list of one or more XMLStructure
s representing key information types. The list is defensively copied to protect against subsequent modification.id
- the value of an XML ID
(may be null
)KeyInfo
NullPointerException
- if content
is null
IllegalArgumentException
- if content
is emptyClassCastException
- if content
contains any entries that are not of type XMLStructure
public abstract KeyName newKeyName(String name)
KeyName
from the specified name.name
- the name that identifies the keyKeyName
NullPointerException
- if name
is null
public abstract KeyValue newKeyValue(PublicKey key) throws KeyException
KeyValue
from the specified public key.key
- the public keyKeyValue
KeyException
- if the key
's algorithm is not recognized or supported by this KeyInfoFactory
NullPointerException
- if key
is null
public abstract PGPData newPGPData(byte[] keyId)
PGPData
from the specified PGP public key identifier.keyId
- a PGP public key identifier as defined in RFC 2440, section 11.2. The array is cloned to protect against subsequent modification.PGPData
NullPointerException
- if keyId
is null
IllegalArgumentException
- if the key id is not in the correct formatpublic abstract PGPData newPGPData(byte[] keyId, byte[] keyPacket, List<? extends XMLStructure> other)
PGPData
from the specified PGP public key identifier, and optional key material packet and list of external elements.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 XMLStructure
s representing elements from an external namespace. The list is defensively copied to protect against subsequent modification. May be null
or empty.PGPData
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
public abstract PGPData newPGPData(byte[] keyPacket, List<? extends XMLStructure> other)
PGPData
from the specified PGP key material packet and optional list of external elements.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 XMLStructure
s representing elements from an external namespace. The list is defensively copied to protect against subsequent modification. May be null
or empty.PGPData
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
public abstract RetrievalMethod newRetrievalMethod(String uri)
RetrievalMethod
from the specified URI.uri
- the URI that identifies the KeyInfo
information to be retrievedRetrievalMethod
NullPointerException
- if uri
is null
IllegalArgumentException
- if uri
is not RFC 2396 compliantpublic abstract RetrievalMethod newRetrievalMethod(String uri, String type, List<? extends Transform> transforms)
RetrievalMethod
from the specified parameters.uri
- the URI that identifies the KeyInfo
information to be retrievedtype
- a URI that identifies the type of KeyInfo
information to be retrieved (may be null
)transforms
- a list of Transform
s. The list is defensively copied to protect against subsequent modification. May be null
or empty.RetrievalMethod
NullPointerException
- if uri
is null
IllegalArgumentException
- if uri
is not RFC 2396 compliantClassCastException
- if transforms
contains any entries that are not of type Transform
public abstract X509Data newX509Data(List<?> content)
X509Data
containing the specified list of X.509 content.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). 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.X509Data
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 abovepublic abstract X509IssuerSerial newX509IssuerSerial(String issuerName, BigInteger serialNumber)
X509IssuerSerial
from the specified X.500 issuer distinguished name and serial number.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 numberX509IssuerSerial
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.public abstract boolean isFeatureSupported(String feature)
feature
- the feature name (as an absolute URI)true
if the specified feature is supported, false
otherwiseNullPointerException
- if feature
is null
public abstract URIDereferencer getURIDereferencer()
URIDereferencer
that is used by default to dereference URIs in RetrievalMethod
objects.URIDereferencer
public abstract KeyInfo unmarshalKeyInfo(XMLStructure xmlStructure) throws MarshalException
KeyInfo
instance from a mechanism-specific XMLStructure
(ex: DOMStructure
) instance.xmlStructure
- a mechanism-specific XML structure from which to unmarshal the keyinfo fromKeyInfo
NullPointerException
- if xmlStructure
is null
ClassCastException
- if the type of xmlStructure
is inappropriate for this factoryMarshalException
- if an unrecoverable exception occurs during unmarshalling
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.xml.crypto/javax/xml/crypto/dsig/keyinfo/KeyInfoFactory.html