Overview | Package | Class | Tree | Deprecated | Index | Help
| Oracle Security Developer Tools XML Security Java API Reference 10g Release 3 (10.1.3) B25383-01
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## oracle.security.xmlsec.keys.retrieval
Class KeyRetriever

`java.lang.Object
oracle.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 `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 oracle.security.crypto.core.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 oracle.security.crypto.core.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 oracle.security.crypto.core.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 oracle.security.crypto.core.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 oracle.security.crypto.core.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 oracle.security.crypto.core.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 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 `KeyInfoData`s 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 `KeyInfoData`s 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 `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

### 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 `KeyRetriever`s 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 `KeyRetriever`s.
  Throws:
    `StorageAuthenticationException` - If an error occurs in authenticating to any of the registered `KeyRetriever`s.
    `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 `KeyRetriever`s 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 `KeyRetriever`s.
  Throws:
    `StorageAuthenticationException` - If an error occurs in authenticating to any of the registered `KeyRetriever`s.
    `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 `KeyRetriever`s 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 `KeyRetriever`s.
  Throws:
    `StorageAuthenticationException` - If an error occurs in authenticating to any of the registered `KeyRetriever`s.
    `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 `KeyRetriever`s 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 `KeyRetriever`s.
  Throws:
    `StorageAuthenticationException` - If an error occurs in authenticating to any of the registered `KeyRetriever`s.
    `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 `KeyRetriever`s 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 `KeyRetriever`s.
  Throws:
    `StorageAuthenticationException` - If an error occurs in authenticating to any of the registered `KeyRetriever`s.
    `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 `KeyRetriever`s 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 `KeyRetriever`s.
  Throws:
    `StorageAuthenticationException` - If an error occurs in authenticating to any of the registered `KeyRetriever`s.
    `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 `KeyRetriever`s 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 `KeyRetriever`s.
  Throws:
    `StorageAuthenticationException` - If an error occurs in authenticating to any of the registered `KeyRetriever`s.
    `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 `KeyRetriever`s 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 `KeyRetriever`s.
  Throws:
    `StorageAuthenticationException` - If an error occurs in authenticating to any of the registered `KeyRetriever`s.
    `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 `KeyInfoData`s 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 `KeyInfoData`s 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 `KeyInfoData`s 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 `KeyInfoData`s 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`

Overview | Package | Class | Tree | Deprecated | Index | Help
| Oracle Security Developer Tools XML Security Java API Reference 10g Release 3 (10.1.3) B25383-01
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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