|
Oracle Fusion Middleware XML Security Java API Reference for Oracle Security Developer Tools 11g Release 1 (11.1.1) E10680-03 |
||||||||
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
public abstract class 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 java.security.cert.X509Certificate |
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 java.security.cert.X509Certificate |
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 java.security.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 java.security.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 java.security.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 java.security.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 javax.crypto.SecretKey |
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 javax.crypto.SecretKey |
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. |
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 KeyInfoData s 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 KeyInfoData s 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 KeyInfoData s 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 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. |
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 |
---|
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 void removeKeyRetriever(KeyRetriever retriever)
KeyRetriever
instance for use in key retrieval operations.public static void setCertificateValidator(CertificateValidator cv)
CertificateValidator
instance for validating certificatescv
-public static void validateCertificate(java.security.cert.X509Certificate cert) throws KeyRetrievalException
validateCertificate(CertPath)
for a single certificatecert
-KeyRetrievalException
public static void validateCertificate(java.util.Vector certs) throws KeyRetrievalException
validateCertificate(CertPath)
for a vector of certificatecerts
-KeyRetrievalException
public static void validateCertificate(java.security.cert.CertPath cp) throws KeyRetrievalException
certList
-KeyRetrievalException
public static java.security.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 java.security.cert.X509Certificate 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.X509Certificate
, 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 java.security.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 javax.crypto.SecretKey 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.SecretKey
, 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 java.security.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 java.security.cert.X509Certificate 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.X509Certificate
, 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 java.security.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 javax.crypto.SecretKey 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.SecretKey
, 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 java.security.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 java.security.cert.X509Certificate 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.X509Certificate
, or null
if none could be located.StorageAuthenticationException
- If an error occurs authenticating to the key source.KeyRetrievalException
protected java.security.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 javax.crypto.SecretKey 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.SecretKey
, or null
if none could be located.StorageAuthenticationException
- If an error occurs authenticating to the key source.KeyRetrievalException
protected java.security.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 java.security.cert.X509Certificate 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.X509Certificate
, or null
if none could be located.StorageAuthenticationException
- If an error occurs authenticating to the key source.KeyRetrievalException
protected java.security.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 javax.crypto.SecretKey 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.SecretKey
, or null
if none could be located.StorageAuthenticationException
- If an error occurs authenticating to the key source.KeyRetrievalException
|
Oracle Fusion Middleware XML Security Java API Reference for Oracle Security Developer Tools 11g Release 1 (11.1.1) E10680-03 |
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |