Oracle Security Developer Tools XML Security Java API Reference
10g Release 3 (10.1.4.0.1)

B28178-01


oracle.security.xmlsec.keys.retrieval
Class KeyRetriever

java.lang.Object
  extended byoracle.security.xmlsec.keys.retrieval.KeyRetriever

Direct Known Subclasses:
KeyInfoTool, PKCS12KeyRetriever, PKCS8KeyRetriever

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
protected KeyRetriever()
          Creates a new KeyRetriever instance.

 

Method Summary
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 oracle.security.crypto.cert.X509 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 oracle.security.crypto.cert.X509 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 oracle.security.crypto.core.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 oracle.security.crypto.core.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 oracle.security.crypto.core.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 oracle.security.crypto.core.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 oracle.security.crypto.core.SymmetricKey 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 oracle.security.crypto.core.SymmetricKey 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.
protected  oracle.security.crypto.cert.X509 retrieveCertificate(KeyInfoData keyInfo)
          Retrieves the certificate identified by the given KeyInfoData.
protected  oracle.security.crypto.cert.X509 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  oracle.security.crypto.core.PrivateKey retrievePrivateKey(KeyInfoData keyInfo)
          Retrieves the private key identified by the given KeyInfoData.
protected  oracle.security.crypto.core.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  oracle.security.crypto.core.PublicKey retrievePublicKey(KeyInfoData keyInfo)
          Retrieves the public key identified by the given KeyInfoData.
protected  oracle.security.crypto.core.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  oracle.security.crypto.core.SymmetricKey retrieveSymmetricKey(KeyInfoData keyInfo)
          Retrieves the secret key identified by the given KeyInfoData.
protected  oracle.security.crypto.core.SymmetricKey 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.

 

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.

getPublicKey

public static oracle.security.crypto.core.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 oracle.security.crypto.cert.X509 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 X509, 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 oracle.security.crypto.core.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 oracle.security.crypto.core.SymmetricKey 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 SymmetricKey, 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 oracle.security.crypto.core.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 oracle.security.crypto.cert.X509 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 X509, 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 oracle.security.crypto.core.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 oracle.security.crypto.core.SymmetricKey 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 SymmetricKey, 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 oracle.security.crypto.core.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 oracle.security.crypto.cert.X509 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 X509, or null if none could be located.
Throws:
StorageAuthenticationException - If an error occurs authenticating to the key source.
KeyRetrievalException

retrievePrivateKey

protected oracle.security.crypto.core.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 oracle.security.crypto.core.SymmetricKey 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 SymmetricKey, or null if none could be located.
Throws:
StorageAuthenticationException - If an error occurs authenticating to the key source.
KeyRetrievalException

retrievePublicKey

protected oracle.security.crypto.core.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 oracle.security.crypto.cert.X509 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 X509, or null if none could be located.
Throws:
StorageAuthenticationException - If an error occurs authenticating to the key source.
KeyRetrievalException

retrievePrivateKey

protected oracle.security.crypto.core.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 oracle.security.crypto.core.SymmetricKey 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 SymmetricKey, or null if none could be located.
Throws:
StorageAuthenticationException - If an error occurs authenticating to the key source.
KeyRetrievalException

Oracle Security Developer Tools XML Security Java API Reference
10g Release 3 (10.1.4.0.1)

B28178-01


Copyright © 2005 ,2006 , Oracle. All rights reserved.