|
Oracle Security Developer Tools XML Security Java API Reference 10g Release 2 (10.1.2.0.2) B15571-01 |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object
oracle.security.xmlsec.keys.retrieval.KeyRetriever
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.
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 KeyRetriever s 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 KeyRetriever s and returning the first successfully retrieved certificate. |
static PrivateKey |
getPrivateKey(KeyInfoData keyInfo) Retrieves the private key corresponding to the given KeyInfoData by iterating over the registered KeyRetriever s and returning the first successfully retrieved private key. |
static PrivateKey |
getPrivateKey(XSKeyInfo keyInfo) Retrieves the private key corresponding to the given XSKeyInfo by iterating over the registered KeyRetriever s and returning the first successfully retrieved key. |
static PublicKey |
getPublicKey(KeyInfoData keyInfo) Retrieves the public key corresponding to the given KeyInfoData by iterating over the registered KeyRetriever s and returning the first successfully retrieved key. |
static PublicKey |
getPublicKey(XSKeyInfo keyInfo) Retrieves the public key corresponding to the given XSKeyInfo by iterating over the registered KeyRetriever s and returning the first successfully retrieved key. |
static SymmetricKey |
getSymmetricKey(KeyInfoData keyInfo) Retrieves the secret key corresponding to the given KeyInfoData by iterating over the registered KeyRetriever s and returning the first successfully retrieved secret key. |
static SymmetricKey |
getSymmetricKey(XSKeyInfo keyInfo) Retrieves the secret key corresponding to the given XSKeyInfo by iterating over the registered KeyRetriever s 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 KeyInfoData s contained in the XSKeyInfo and calling retrieveCertificate(KeyInfoData) . |
protected PrivateKey |
retrievePrivateKey(KeyInfoData keyInfo) Retrieves the private key identified by the given KeyInfoData . |
protected PrivateKey |
retrievePrivateKey(XSKeyInfo keyInfo) Retrieves the private key identified by the given XSKeyInfo , by iterating over the KeyInfoData s contained in the XSKeyInfo and calling retrievePrivateKey(KeyInfoData) . |
protected PublicKey |
retrievePublicKey(KeyInfoData keyInfo) Retrieves the public key identified by the given KeyInfoData . |
protected PublicKey |
retrievePublicKey(XSKeyInfo keyInfo) Retrieves the public key identified by the given XSKeyInfo , by iterating over the KeyInfoData s contained in the XSKeyInfo and calling retrievePublicKey(KeyInfoData) . |
protected SymmetricKey |
retrieveSymmetricKey(KeyInfoData keyInfo) Retrieves the secret key identified by the given KeyInfoData . |
protected SymmetricKey |
retrieveSymmetricKey(XSKeyInfo keyInfo) Retrieves the secret key identified by the given XSKeyInfo , by iterating over the KeyInfoData s 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 |
protected KeyRetriever()
KeyRetriever
instance.Method Detail |
public void setAuthenticator(StorageAuthenticator authenticator)
StorageAuthenticator
to be used to authenticate to the key source.authenticator
- An instance of a StorageAuthenticator
implementation to be used to authenticate to the key source.public StorageAuthenticator getAuthenticator()
StorageAuthenticator
to be used to authenticate to the key source.StorageAuthenticator
implementation, or null
if none has been set.public static void addKeyRetriever(KeyRetriever retriever)
KeyRetriever
instance for use in key retrieval operations.public static PublicKey getPublicKey(XSKeyInfo keyInfo) throws KeyRetrievalException
XSKeyInfo
by iterating over the registered KeyRetriever
s and returning the first successfully retrieved key.keyInfo
- The XSKeyInfo
identifying the requested public key.PublicKey
, or null
if none is found among the registered KeyRetriever
s.StorageAuthenticationException
- If an error occurs in authenticating to any of the registered KeyRetriever
s.KeyRetrievalException
public static oracle.security.crypto.cert.X509 getCertificate(XSKeyInfo keyInfo) throws KeyRetrievalException
XSKeyInfo
by iterating over the registered KeyRetriever
s and returning the first successfully retrieved certificate.keyInfo
- The XSKeyInfo
identifying the requested certificate.X509
, or null
if none is found among the registered KeyRetriever
s.StorageAuthenticationException
- If an error occurs in authenticating to any of the registered KeyRetriever
s.KeyRetrievalException
public static PrivateKey getPrivateKey(XSKeyInfo keyInfo) throws KeyRetrievalException
XSKeyInfo
by iterating over the registered KeyRetriever
s and returning the first successfully retrieved key.keyInfo
- The XSKeyInfo
identifying the requested private key.PrivateKey
, or null
if none is found among the registered KeyRetriever
s.StorageAuthenticationException
- If an error occurs in authenticating to any of the registered KeyRetriever
s.KeyRetrievalException
public static SymmetricKey getSymmetricKey(XSKeyInfo keyInfo) throws KeyRetrievalException
XSKeyInfo
by iterating over the registered KeyRetriever
s and returning the first successfully retrieved key.keyInfo
- The XSKeyInfo
identifying the requested secret key.SymmetricKey
, or null
if none is found among the registered KeyRetriever
s.StorageAuthenticationException
- If an error occurs in authenticating to any of the registered KeyRetriever
s.KeyRetrievalException
public static PublicKey getPublicKey(KeyInfoData keyInfo) throws KeyRetrievalException
KeyInfoData
by iterating over the registered KeyRetriever
s and returning the first successfully retrieved key.keyInfo
- The KeyInfoData
identifying the requested public key.PublicKey
, or null
if none is found among the registered KeyRetriever
s.StorageAuthenticationException
- If an error occurs in authenticating to any of the registered KeyRetriever
s.KeyRetrievalException
public static oracle.security.crypto.cert.X509 getCertificate(KeyInfoData keyInfo) throws KeyRetrievalException
KeyInfoData
by iterating over the registered KeyRetriever
s and returning the first successfully retrieved certificate.keyInfo
- The KeyInfoData
identifying the requested certificate.X509
, or null
if none is found among the registered KeyRetriever
s.StorageAuthenticationException
- If an error occurs in authenticating to any of the registered KeyRetriever
s.KeyRetrievalException
public static PrivateKey getPrivateKey(KeyInfoData keyInfo) throws KeyRetrievalException
KeyInfoData
by iterating over the registered KeyRetriever
s and returning the first successfully retrieved private key.keyInfo
- The KeyInfoData
identifying the requested private key.PrivateKey
, or null
if none is found among the registered KeyRetriever
s.StorageAuthenticationException
- If an error occurs in authenticating to any of the registered KeyRetriever
s.KeyRetrievalException
public static SymmetricKey getSymmetricKey(KeyInfoData keyInfo) throws KeyRetrievalException
KeyInfoData
by iterating over the registered KeyRetriever
s and returning the first successfully retrieved secret key.keyInfo
- The KeyInfoData
identifying the requested secret key.SymmetricKey
, or null
if none is found among the registered KeyRetriever
s.StorageAuthenticationException
- If an error occurs in authenticating to any of the registered KeyRetriever
s.KeyRetrievalException
protected PublicKey retrievePublicKey(KeyInfoData keyInfo) throws KeyRetrievalException
KeyInfoData
. If this method is not overridden it always returns null
.keyInfo
- A KeyInfoData
to be used to locate the public key.PublicKey
, or null
if none could be located.StorageAuthenticationException
- If an error occurs authenticating to the key source.KeyRetrievalException
protected oracle.security.crypto.cert.X509 retrieveCertificate(KeyInfoData keyInfo) throws KeyRetrievalException
KeyInfoData
. If this method is not overridden it always returns null
.keyInfo
- A KeyInfoData
to be used to locate the certificate.X509
, or null
if none could be located.StorageAuthenticationException
- If an error occurs authenticating to the key source.KeyRetrievalException
protected PrivateKey retrievePrivateKey(KeyInfoData keyInfo) throws KeyRetrievalException
KeyInfoData
. If this method is not overridden it always returns null
.keyInfo
- A KeyInfoData
to be used to locate the private key.PrivateKey
, or null
if none could be located.StorageAuthenticationException
- If an error occurs authenticating to the key source.KeyRetrievalException
protected SymmetricKey retrieveSymmetricKey(KeyInfoData keyInfo) throws KeyRetrievalException
KeyInfoData
. If this method is not overridden it always returns null
.keyInfo
- A KeyInfoData
to be used to locate the secret key.SymmetricKey
, or null
if none could be located.StorageAuthenticationException
- If an error occurs authenticating to the key source.KeyRetrievalException
protected PublicKey retrievePublicKey(XSKeyInfo keyInfo) throws KeyRetrievalException
XSKeyInfo
, by iterating over the KeyInfoData
s contained in the XSKeyInfo
and calling retrievePublicKey(KeyInfoData)
.keyInfo
- A XSKeyInfo
to be used to locate the public key.PublicKey
, or null
if none could be located.StorageAuthenticationException
- If an error occurs authenticating to the key source.KeyRetrievalException
protected oracle.security.crypto.cert.X509 retrieveCertificate(XSKeyInfo keyInfo) throws KeyRetrievalException
XSKeyInfo
, by iterating over the KeyInfoData
s contained in the XSKeyInfo
and calling retrieveCertificate(KeyInfoData)
.keyInfo
- A XSKeyInfo
to be used to locate the certificate.X509
, or null
if none could be located.StorageAuthenticationException
- If an error occurs authenticating to the key source.KeyRetrievalException
protected PrivateKey retrievePrivateKey(XSKeyInfo keyInfo) throws KeyRetrievalException
XSKeyInfo
, by iterating over the KeyInfoData
s contained in the XSKeyInfo
and calling retrievePrivateKey(KeyInfoData)
.keyInfo
- A XSKeyInfo
to be used to locate the private key.PrivateKey
, or null
if none could be located.StorageAuthenticationException
- If an error occurs authenticating to the key source.KeyRetrievalException
protected SymmetricKey retrieveSymmetricKey(XSKeyInfo keyInfo) throws KeyRetrievalException
XSKeyInfo
, by iterating over the KeyInfoData
s contained in the XSKeyInfo
and calling retrieveSymmetricKey(KeyInfoData)
.keyInfo
- A XSKeyInfo
to be used to locate the secret key.SymmetricKey
, or null
if none could be located.StorageAuthenticationException
- If an error occurs authenticating to the key source.KeyRetrievalException
|
Oracle Security Developer Tools XML Security Java API Reference 10g Release 2 (10.1.2.0.2) B15571-01 |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |