oracle.security.xmlsec.keys.retrieval

Class KeyRetriever

java.lang.Object

oracle.security.xmlsec.keys.retrieval.KeyRetriever

Direct Known Subclasses:

KeyInfoTool, KeyStoreKeyRetriever, PKCS12KeyRetriever, PKCS8KeyRetriever, WSSKeyRetriever

public abstract class KeyRetriever
extends java.lang.Object

Class that performs key retrieval operations for different key types and storage, using registered instances of KeyRetriever subclasses.

The KeyRetriever class serves as a utility for extracting keys from XSKeyInfo instances, as well as a registry for KeyRetriever sub-class instances that are implemented to retrieve keys from sources outside the XSKeyInfo.

The static methods for finding keys -- getPublicKey(), getCertificate(), getPrivateKey() and getSymmetricKey() -- take as an argument either a XSKeyInfo or a KeyInfoData child element. These methods first examine the given KeyInfo to see if it actually contains the key (or certificate). If the key is not found, the retrieval methods then search the registered KeyRetriever instances for a key matching the information contained in the KeyInfo (e.g., a KeyName).

To register a KeyRetriever instance with the KeyRetriever, use the addKeyRetriever(oracle.security.xmlsec.keys.retrieval.KeyRetriever) method For example, to sign using a private key that is stored in a PKCS#12 file, an application might include code like the following:

                import oracle.security.xmlsec.dsig.*;
                import oracle.security.xmlsec.keys.*;
                import oracle.security.xmlsec.keys.retrieval.*;
                
                // ...
                
                // Create a KeyRetriever instance for the PKCS#12 file.
                PKCS12Retriever p12ret = new PKCS12Retriever("my-key.p12");
                
                // Set a StorageAuthenticator implementation for the PKCS#12.
                p12Store.setAuthenticator(new ConsolePasswordAuthenticator());
                
                // Register the PKCS12Retriever instance with the KeyRetriever.
                KeyRetriever.addKeyStorage(p12ret);
                
                // Create the XML signature and set up the algorithms
                // and the data to be signed.
                XSSignature sig = XSSignature.newInstance("SignatureID");
                XSSignedInfo signedInfo = sig.createSignedInfo( ... );
                XSReference ref = sig.createReference( ... );
                signedInfo.addReference(ref);
                sig.setSignedInfo(signedInfo);
                
                // Create a KeyInfo containing the PKCS#12 friendly name.
                XSKeyInfo keyInfo = sig.createKeyInfo();
                XSKeyName keyName = keyInfo.createKeyName("My Signing Key");
                keyInfo.addKeyInfoData(keyName);
                sig.setKeyInfo(keyInfo);
                
                // Compute the XML signature.
                sig.sign("SigValueID");
        

The StorageAuthenticator interface is intended to be implemented to support a given application's key storage and retrieval infrastructure. In the code example above, the class ConsolePasswordAuthenticator would be an implementation of the StorageAuthenticator interface that prompts on the command line for a password to be used for the PKCS#12 file.

As another example, if a particular application will need to obtain keys from a database, the developer might create a DatabaseKeyRetriever class that extends the KeyRetriever abstract class. If the database requires username and password authentication and the application employs a graphical user interface, a DialogUserAuthenticator class might be created that implements the StorageAuthenticator interface.

Since:

1.2

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	KeyRetriever() Creates a new KeyRetriever instance.

Method Summary

Modifier and Type	Method and Description
static void	addKeyRetriever(KeyRetriever retriever) Registers a KeyRetriever instance for use in key retrieval operations.
StorageAuthenticator	getAuthenticator() Returns the StorageAuthenticator to be used to authenticate to the key source.
static java.security.cert.X509Certificate	getCertificate(KeyInfoData keyInfo) Retrieves the certificate corresponding to the given KeyInfoData by iterating over the registered KeyRetrievers and returning the first successfully retrieved certificate.
static java.security.cert.X509Certificate	getCertificate(XSKeyInfo keyInfo) Retrieves the certificate corresponding to the given XSKeyInfo by iterating over the registered KeyRetrievers and returning the first successfully retrieved certificate.
static java.security.PrivateKey	getPrivateKey(KeyInfoData keyInfo) Retrieves the private key corresponding to the given KeyInfoData by iterating over the registered KeyRetrievers and returning the first successfully retrieved private key.
static java.security.PrivateKey	getPrivateKey(XSKeyInfo keyInfo) Retrieves the private key corresponding to the given XSKeyInfo by iterating over the registered KeyRetrievers and returning the first successfully retrieved key.
static java.security.PublicKey	getPublicKey(KeyInfoData keyInfo) Retrieves the public key corresponding to the given KeyInfoData by iterating over the registered KeyRetrievers and returning the first successfully retrieved key.
static java.security.PublicKey	getPublicKey(XSKeyInfo keyInfo) Retrieves the public key corresponding to the given XSKeyInfo by iterating over the registered KeyRetrievers and returning the first successfully retrieved key.
static javax.crypto.SecretKey	getSymmetricKey(KeyInfoData keyInfo) Retrieves the secret key corresponding to the given KeyInfoData by iterating over the registered KeyRetrievers and returning the first successfully retrieved secret key.
static javax.crypto.SecretKey	getSymmetricKey(XSKeyInfo keyInfo) Retrieves the secret key corresponding to the given XSKeyInfo by iterating over the registered KeyRetrievers and returning the first successfully retrieved key.
static void	removeKeyRetriever(KeyRetriever retriever) Unregisters a KeyRetriever instance for use in key retrieval operations.
protected java.security.cert.X509Certificate	retrieveCertificate(KeyInfoData keyInfo) Retrieves the certificate identified by the given KeyInfoData.
protected java.security.cert.X509Certificate	retrieveCertificate(XSKeyInfo keyInfo) Retrieves the certificate identified by the given XSKeyInfo, by iterating over the KeyInfoDatas contained in the XSKeyInfo and calling retrieveCertificate(KeyInfoData).
protected java.security.PrivateKey	retrievePrivateKey(KeyInfoData keyInfo) Retrieves the private key identified by the given KeyInfoData.
protected java.security.PrivateKey	retrievePrivateKey(XSKeyInfo keyInfo) Retrieves the private key identified by the given XSKeyInfo, by iterating over the KeyInfoDatas contained in the XSKeyInfo and calling retrievePrivateKey(KeyInfoData).
protected java.security.PublicKey	retrievePublicKey(KeyInfoData keyInfo) Retrieves the public key identified by the given KeyInfoData.
protected java.security.PublicKey	retrievePublicKey(XSKeyInfo keyInfo) Retrieves the public key identified by the given XSKeyInfo, by iterating over the KeyInfoDatas contained in the XSKeyInfo and calling retrievePublicKey(KeyInfoData).
protected javax.crypto.SecretKey	retrieveSymmetricKey(KeyInfoData keyInfo) Retrieves the secret key identified by the given KeyInfoData.
protected javax.crypto.SecretKey	retrieveSymmetricKey(XSKeyInfo keyInfo) Retrieves the secret key identified by the given XSKeyInfo, by iterating over the KeyInfoDatas contained in the XSKeyInfo and calling retrieveSymmetricKey(KeyInfoData).
void	setAuthenticator(StorageAuthenticator authenticator) Sets the StorageAuthenticator to be used to authenticate to the key source.
static void	setCertificateValidator(CertificateValidator cv) Sets a CertificateValidator instance for validating certificates
static void	validateCertificate(java.security.cert.CertPath cp) For Internal use - call the registered certificate validator to validate this certList, return exception if invalid
static void	validateCertificate(java.util.Vector certs) For internal use - wrapper around validateCertificate(CertPath) for a vector of certificate
static void	validateCertificate(java.security.cert.X509Certificate cert) For internal use - wrapper around validateCertificate(CertPath) for a single certificate

Methods inherited from class java.lang.Object

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

Constructor Detail

KeyRetriever

protected KeyRetriever()

Creates a new KeyRetriever instance.

Method Detail

setAuthenticator

public void setAuthenticator(StorageAuthenticator authenticator)

Sets the StorageAuthenticator to be used to authenticate to the key source.

Parameters:

authenticator - An instance of a StorageAuthenticator implementation to be used to authenticate to the key source.

getAuthenticator

public StorageAuthenticator getAuthenticator()

Returns the StorageAuthenticator to be used to authenticate to the key source.

Returns:

An instance of a StorageAuthenticator implementation, or null if none has been set.

addKeyRetriever

public static void addKeyRetriever(KeyRetriever retriever)

Registers a KeyRetriever instance for use in key retrieval operations.

removeKeyRetriever

public static void removeKeyRetriever(KeyRetriever retriever)

Unregisters a KeyRetriever instance for use in key retrieval operations.

setCertificateValidator

public static void setCertificateValidator(CertificateValidator cv)

Sets a CertificateValidator instance for validating certificates

Parameters:

cv -

validateCertificate

public static void validateCertificate(java.security.cert.X509Certificate cert)
                                throws KeyRetrievalException

For internal use - wrapper around validateCertificate(CertPath) for a single certificate

Parameters:

cert -

Throws:

KeyRetrievalException

validateCertificate

public static void validateCertificate(java.util.Vector certs)
                                throws KeyRetrievalException

For internal use - wrapper around validateCertificate(CertPath) for a vector of certificate

Parameters:

certs -

Throws:

KeyRetrievalException

validateCertificate

public static void validateCertificate(java.security.cert.CertPath cp)
                                throws KeyRetrievalException

For Internal use - call the registered certificate validator to validate this certList, return exception if invalid

Parameters:

cp -

Throws:

KeyRetrievalException

getPublicKey

public static java.security.PublicKey getPublicKey(XSKeyInfo keyInfo)
                                            throws KeyRetrievalException

Retrieves the public key corresponding to the given XSKeyInfo by iterating over the registered KeyRetrievers and returning the first successfully retrieved key.

Parameters:

keyInfo - The XSKeyInfo identifying the requested public key.

Returns:

A PublicKey, or null if none is found among the registered KeyRetrievers.

Throws:

StorageAuthenticationException - If an error occurs in authenticating to any of the registered KeyRetrievers.

KeyRetrievalException

getCertificate

public static java.security.cert.X509Certificate getCertificate(XSKeyInfo keyInfo)
                                                         throws KeyRetrievalException

Retrieves the certificate corresponding to the given XSKeyInfo by iterating over the registered KeyRetrievers and returning the first successfully retrieved certificate.

Parameters:

keyInfo - The XSKeyInfo identifying the requested certificate.

Returns:

A X509Certificate, or null if none is found among the registered KeyRetrievers.

Throws:

StorageAuthenticationException - If an error occurs in authenticating to any of the registered KeyRetrievers.

KeyRetrievalException

getPrivateKey

public static java.security.PrivateKey getPrivateKey(XSKeyInfo keyInfo)
                                              throws KeyRetrievalException

Retrieves the private key corresponding to the given XSKeyInfo by iterating over the registered KeyRetrievers and returning the first successfully retrieved key.

Parameters:

keyInfo - The XSKeyInfo identifying the requested private key.

Returns:

A PrivateKey, or null if none is found among the registered KeyRetrievers.

Throws:

StorageAuthenticationException - If an error occurs in authenticating to any of the registered KeyRetrievers.

KeyRetrievalException

getSymmetricKey

public static javax.crypto.SecretKey getSymmetricKey(XSKeyInfo keyInfo)
                                              throws KeyRetrievalException

Retrieves the secret key corresponding to the given XSKeyInfo by iterating over the registered KeyRetrievers and returning the first successfully retrieved key.

Parameters:

keyInfo - The XSKeyInfo identifying the requested secret key.

Returns:

A SecretKey, or null if none is found among the registered KeyRetrievers.

Throws:

StorageAuthenticationException - If an error occurs in authenticating to any of the registered KeyRetrievers.

KeyRetrievalException

getPublicKey

public static java.security.PublicKey getPublicKey(KeyInfoData keyInfo)
                                            throws KeyRetrievalException

Retrieves the public key corresponding to the given KeyInfoData by iterating over the registered KeyRetrievers and returning the first successfully retrieved key.

Parameters:

keyInfo - The KeyInfoData identifying the requested public key.

Returns:

A PublicKey, or null if none is found among the registered KeyRetrievers.

Throws:

StorageAuthenticationException - If an error occurs in authenticating to any of the registered KeyRetrievers.

KeyRetrievalException

getCertificate

public static java.security.cert.X509Certificate getCertificate(KeyInfoData keyInfo)
                                                         throws KeyRetrievalException

Retrieves the certificate corresponding to the given KeyInfoData by iterating over the registered KeyRetrievers and returning the first successfully retrieved certificate.

Parameters:

keyInfo - The KeyInfoData identifying the requested certificate.

Returns:

A X509Certificate, or null if none is found among the registered KeyRetrievers.

Throws:

StorageAuthenticationException - If an error occurs in authenticating to any of the registered KeyRetrievers.

KeyRetrievalException

getPrivateKey

public static java.security.PrivateKey getPrivateKey(KeyInfoData keyInfo)
                                              throws KeyRetrievalException

Retrieves the private key corresponding to the given KeyInfoData by iterating over the registered KeyRetrievers and returning the first successfully retrieved private key.

Parameters:

keyInfo - The KeyInfoData identifying the requested private key.

Returns:

A PrivateKey, or null if none is found among the registered KeyRetrievers.

Throws:

StorageAuthenticationException - If an error occurs in authenticating to any of the registered KeyRetrievers.

KeyRetrievalException

getSymmetricKey

public static javax.crypto.SecretKey getSymmetricKey(KeyInfoData keyInfo)
                                              throws KeyRetrievalException

Retrieves the secret key corresponding to the given KeyInfoData by iterating over the registered KeyRetrievers and returning the first successfully retrieved secret key.

Parameters:

keyInfo - The KeyInfoData identifying the requested secret key.

Returns:

A SecretKey, or null if none is found among the registered KeyRetrievers.

Throws:

StorageAuthenticationException - If an error occurs in authenticating to any of the registered KeyRetrievers.

KeyRetrievalException

retrievePublicKey

protected java.security.PublicKey retrievePublicKey(KeyInfoData keyInfo)
                                             throws KeyRetrievalException

Retrieves the public key identified by the given KeyInfoData. If this method is not overridden it always returns null.

Parameters:

keyInfo - A KeyInfoData to be used to locate the public key.

Returns:

A PublicKey, or null if none could be located.

Throws:

StorageAuthenticationException - If an error occurs authenticating to the key source.

KeyRetrievalException

retrieveCertificate

protected java.security.cert.X509Certificate retrieveCertificate(KeyInfoData keyInfo)
                                                          throws KeyRetrievalException

Retrieves the certificate identified by the given KeyInfoData. If this method is not overridden it always returns null.

Parameters:

keyInfo - A KeyInfoData to be used to locate the certificate.

Returns:

A X509Certificate, or null if none could be located.

Throws:

StorageAuthenticationException - If an error occurs authenticating to the key source.

KeyRetrievalException

retrievePrivateKey

protected java.security.PrivateKey retrievePrivateKey(KeyInfoData keyInfo)
                                               throws KeyRetrievalException

Retrieves the private key identified by the given KeyInfoData. If this method is not overridden it always returns null.

Parameters:

keyInfo - A KeyInfoData to be used to locate the private key.

Returns:

A PrivateKey, or null if none could be located.

Throws:

StorageAuthenticationException - If an error occurs authenticating to the key source.

KeyRetrievalException

retrieveSymmetricKey

protected javax.crypto.SecretKey retrieveSymmetricKey(KeyInfoData keyInfo)
                                               throws KeyRetrievalException

Retrieves the secret key identified by the given KeyInfoData. If this method is not overridden it always returns null.

Parameters:

keyInfo - A KeyInfoData to be used to locate the secret key.

Returns:

A SecretKey, or null if none could be located.

Throws:

StorageAuthenticationException - If an error occurs authenticating to the key source.

KeyRetrievalException

retrievePublicKey

protected java.security.PublicKey retrievePublicKey(XSKeyInfo keyInfo)
                                             throws KeyRetrievalException

Retrieves the public key identified by the given XSKeyInfo, by iterating over the KeyInfoDatas contained in the XSKeyInfo and calling retrievePublicKey(KeyInfoData).

Parameters:

keyInfo - A XSKeyInfo to be used to locate the public key.

Returns:

A PublicKey, or null if none could be located.

Throws:

StorageAuthenticationException - If an error occurs authenticating to the key source.

KeyRetrievalException

retrieveCertificate

protected java.security.cert.X509Certificate retrieveCertificate(XSKeyInfo keyInfo)
                                                          throws KeyRetrievalException

Retrieves the certificate identified by the given XSKeyInfo, by iterating over the KeyInfoDatas contained in the XSKeyInfo and calling retrieveCertificate(KeyInfoData).

Parameters:

keyInfo - A XSKeyInfo to be used to locate the certificate.

Returns:

A X509Certificate, or null if none could be located.

Throws:

StorageAuthenticationException - If an error occurs authenticating to the key source.

KeyRetrievalException

retrievePrivateKey

protected java.security.PrivateKey retrievePrivateKey(XSKeyInfo keyInfo)
                                               throws KeyRetrievalException

Retrieves the private key identified by the given XSKeyInfo, by iterating over the KeyInfoDatas contained in the XSKeyInfo and calling retrievePrivateKey(KeyInfoData).

Parameters:

keyInfo - A XSKeyInfo to be used to locate the private key.

Returns:

A PrivateKey, or null if none could be located.

Throws:

StorageAuthenticationException - If an error occurs authenticating to the key source.

KeyRetrievalException

retrieveSymmetricKey

protected javax.crypto.SecretKey retrieveSymmetricKey(XSKeyInfo keyInfo)
                                               throws KeyRetrievalException

Retrieves the secret key identified by the given XSKeyInfo, by iterating over the KeyInfoDatas contained in the XSKeyInfo and calling retrieveSymmetricKey(KeyInfoData).

Parameters:

keyInfo - A XSKeyInfo to be used to locate the secret key.

Returns:

A SecretKey, or null if none could be located.

Throws:

StorageAuthenticationException - If an error occurs authenticating to the key source.

KeyRetrievalException