javax.xml.crypto.dsig.keyinfo
Class KeyInfoFactory
- java.lang.Object
javax.xml.crypto.dsig.keyinfo.KeyInfoFactory
- public abstract class KeyInfoFactory
- extends java.lang.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 section of the API overview. See the Service Providers section of the API overview 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.
Constructor Summary
Modifier | Constructor and Description |
---|---|
|
KeyInfoFactory()
Default constructor, for invocation by subclasses.
|
Method Summary
Modifier and Type | Method and Description |
---|---|
|
getInstance()
Returns a
KeyInfoFactory that supports the
default XML processing mechanism and representation type ("DOM").
|
|
getInstance(java.lang.String mechanismType)
Returns a
KeyInfoFactory that supports the
specified XML processing mechanism and representation type (ex: "DOM").
|
|
getInstance(java.lang.String mechanismType,java.security.Provider provider)
Returns a
KeyInfoFactory that supports the
requested XML processing mechanism and representation type (ex: "DOM"),
as supplied by the specified provider.
|
|
getInstance(java.lang.String mechanismType,java.lang.String provider)
Returns a
KeyInfoFactory that supports the
requested XML processing mechanism and representation type (ex: "DOM"),
as supplied by the specified provider.
|
|
getMechanismType()
Returns the type of the XML processing mechanism and representation
supported by this
KeyInfoFactory (ex: "DOM")
|
|
getProvider()
Returns the provider of this
KeyInfoFactory .
|
|
getURIDereferencer()
Returns a reference to the
URIDereferencer that is used by
default to dereference URIs in RetrievalMethod objects.
|
|
isFeatureSupported(java.lang.String feature)
Indicates whether a specified feature is supported.
|
|
newKeyInfo(java.util.List content)
Creates a
KeyInfo containing the specified list of
key information types.
|
|
newKeyInfo(java.util.List content,java.lang.String id)
Creates a
KeyInfo containing the specified list of key
information types and optional id.
|
|
newKeyName(java.lang.String name)
Creates a
KeyName from the specified name.
|
|
newKeyValue(java.security.PublicKey key)
Creates a
KeyValue from the specified public key.
|
|
newPGPData(byte[] keyId)
Creates a
PGPData from the specified PGP public key
identifier.
|
|
newPGPData(byte[] keyId,byte[] keyPacket,java.util.List other)
Creates a
PGPData from the specified PGP public key
identifier, and optional key material packet and list of external
elements.
|
|
newPGPData(byte[] keyPacket,java.util.List other)
Creates a
PGPData from the specified PGP key material
packet and optional list of external elements.
|
|
newRetrievalMethod(java.lang.String uri)
Creates a
RetrievalMethod from the specified URI.
|
|
newRetrievalMethod(java.lang.String uri,java.lang.String type,java.util.List transforms)
Creates a
RetrievalMethod from the specified parameters.
|
|
newX509Data(java.util.List content)
Creates a
X509Data containing the specified list of
X.509 content.
|
|
newX509IssuerSerial(java.lang.String issuerName,java.math.BigInteger serialNumber)
Creates an
X509IssuerSerial from the specified X.500 issuer
distinguished name and serial number.
|
|
unmarshalKeyInfo(XMLStructure xmlStructure)
Unmarshals a new
KeyInfo instance from a
mechanism-specific XMLStructure (ex: DOMStructure )
instance.
|
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail
KeyInfoFactory
- protected KeyInfoFactory()
Method Detail
getInstance
- public static KeyInfoFactory getInstance( java.lang.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.
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. KeyInfoFactory
java.lang.NullPointerException
- if mechanismType
is
null
NoSuchMechanismException
- if no Provider
supports a
KeyInfoFactory
implementation for the specified mechanism Provider
getInstance
- public static KeyInfoFactory getInstance( java.lang.String mechanismType,
- java.security.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 Service
Providers section of the API overview for a list of standard
mechanism types. provider
- the Provider
object KeyInfoFactory
java.lang.NullPointerException
- if mechanismType
or
provider
are null
NoSuchMechanismException
- if a KeyInfoFactory
implementation for the specified mechanism is not available from the
specified Provider
object Provider
getInstance
- public static KeyInfoFactory getInstance( java.lang.String mechanismType,
- java.lang.String provider)
- throws java.security.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 Service
Providers section of the API overview for a list of standard
mechanism types. provider
- the string name of the provider KeyInfoFactory
java.security.NoSuchProviderException
- if the specified provider is not
registered in the security provider list java.lang.NullPointerException
- if mechanismType
or
provider
are null
NoSuchMechanismException
- if a KeyInfoFactory
implementation for the specified mechanism is not available from the
specified provider Provider
getInstance
- public 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.
KeyInfoFactory
NoSuchMechanismException
- if no Provider
supports a
KeyInfoFactory
implementation for the DOM mechanism Provider
getMechanismType
- public final java.lang.String getMechanismType( )
KeyInfoFactory
(ex: "DOM")
KeyInfoFactory
getProvider
- public final java.security.Provider getProvider( )
KeyInfoFactory
.
KeyInfoFactory
newKeyInfo
- public abstract KeyInfo newKeyInfo( java.util.List 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
java.lang.NullPointerException
- if content
is null
java.lang.IllegalArgumentException
- if content
is empty newKeyInfo
- public abstract KeyInfo newKeyInfo( java.util.List content,
- java.lang.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
java.lang.NullPointerException
- if content
is null
java.lang.IllegalArgumentException
- if content
is empty newKeyName
- public abstract KeyName newKeyName( java.lang.String name)
KeyName
from the specified name.
name
- the name that identifies the key KeyName
java.lang.NullPointerException
- if name
is null
newKeyValue
- public abstract KeyValue newKeyValue( java.security.PublicKey key)
- throws java.security.KeyException
KeyValue
from the specified public key.
key
- the public key KeyValue
java.security.KeyException
- if the key
's algorithm is not
recognized or supported by this KeyInfoFactory
java.lang.NullPointerException
- if key
is null
newPGPData
- 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
java.lang.NullPointerException
- if keyId
is null
java.lang.IllegalArgumentException
- if the key id is not in the correct
format newPGPData
- public abstract PGPData newPGPData( byte[] keyId,
- byte[] keyPacket,
- java.util.List 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
java.lang.NullPointerException
- if keyId
is null
java.lang.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. newPGPData
- public abstract PGPData newPGPData( byte[] keyPacket,
- java.util.List 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
java.lang.NullPointerException
- if keyPacket
is
null
java.lang.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. newRetrievalMethod
- public abstract RetrievalMethod newRetrievalMethod( java.lang.String uri)
RetrievalMethod
from the specified URI.
uri
- the URI that identifies the KeyInfo
information
to be retrieved RetrievalMethod
java.lang.NullPointerException
- if uri
is null
java.lang.IllegalArgumentException
- if uri
is not RFC 2396
compliant newRetrievalMethod
- public abstract RetrievalMethod newRetrievalMethod( java.lang.String uri,
- java.lang.String type,
- java.util.List transforms)
RetrievalMethod
from the specified 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 Transform
s. The list is defensively
copied to protect against subsequent modification. May be
null
or empty. RetrievalMethod
java.lang.NullPointerException
- if uri
is null
java.lang.IllegalArgumentException
- if uri
is not RFC 2396
compliant newX509Data
- public abstract X509Data newX509Data( java.util.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
java.lang.NullPointerException
- if content
is null
java.lang.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. java.lang.ClassCastException
- if content
contains any entries
that are not of one of the valid types mentioned above newX509IssuerSerial
- public abstract X509IssuerSerial newX509IssuerSerial( java.lang.String issuerName,
- java.math.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 number X509IssuerSerial
java.lang.NullPointerException
- if issuerName
or
serialNumber
are null
java.lang.IllegalArgumentException
- if the issuer name is not RFC 2253
compliant or one of the attribute type keywords is not recognized. isFeatureSupported
- public abstract boolean isFeatureSupported( java.lang.String feature)
feature
- the feature name (as an absolute URI) true
if the specified feature is supported,
false
otherwise java.lang.NullPointerException
- if feature
is null
getURIDereferencer
- public abstract URIDereferencer getURIDereferencer( )
URIDereferencer
that is used by
default to dereference URIs in RetrievalMethod
objects.
URIDereferencer
unmarshalKeyInfo
- 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 from KeyInfo
java.lang.NullPointerException
- if xmlStructure
is
null
java.lang.ClassCastException
- if the type of xmlStructure
is
inappropriate for this factory MarshalException
- if an unrecoverable exception occurs during
unmarshalling