org.eclipse.aether.repository

## Class AuthenticationContext

- java.lang.Object
- - org.eclipse.aether.repository.AuthenticationContext

- All Implemented Interfaces:
    Closeable, AutoCloseable

      public final class AuthenticationContext
      extends Object
      implements Closeable

  A glorified map of key value pairs holding (cleartext) authentication data. Authentication contexts are used internally when network operations need to access secured repositories or proxies. Each authentication context manages the credentials required to access a single host. Unlike `Authentication` callbacks which exist for a potentially long time like the duration of a repository system session, an authentication context has a supposedly short lifetime and should be `closed` as soon as the corresponding network operation has finished:

       AuthenticationContext context = AuthenticationContext.forRepository( session, repository );
       try {
           // get credentials
           char[] password = context.get( AuthenticationContext.PASSWORD, char[].class );
           // perform network operation using retrieved credentials
           ...
       } finally {
           // erase confidential authentication data from heap memory
           AuthenticationContext.close( context );
       }

  The same authentication data can often be presented using different data types, e.g. a password can be presented using a character array or (less securely) using a string. For ease of use, an authentication context treats the following groups of data types as equivalent and converts values automatically during retrieval:
  - `String`, `char[]`
  - `String`, `File`
  An authentication context is thread-safe.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `HOST_KEY_ACCEPTANCE` The key used to store the acceptance policy for unknown host keys.
    `static String` | `HOST_KEY_LOCAL` The key used to store the fingerprint of the public key expected from remote host as recorded in a known hosts database.
    `static String` | `HOST_KEY_REMOTE` The key used to store the fingerprint of the public key advertised by remote host.
    `static String` | `NTLM_DOMAIN` The key used to store the NTLM domain.
    `static String` | `NTLM_WORKSTATION` The key used to store the NTML workstation.
    `static String` | `PASSWORD` The key used to store the password.
    `static String` | `PRIVATE_KEY_PASSPHRASE` The key used to store the passphrase protecting the private key.
    `static String` | `PRIVATE_KEY_PATH` The key used to store the pathname to a private key file.
    `static String` | `SSL_CONTEXT` The key used to store the SSL context.
    `static String` | `SSL_HOSTNAME_VERIFIER` The key used to store the SSL hostname verifier.
    `static String` | `USERNAME` The key used to store the username.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` Closes this authentication context and erases sensitive authentication data from heap memory.
    `static void` | `close(AuthenticationContext context)` Closes the specified authentication context.
    `static AuthenticationContext` | `forProxy(RepositorySystemSession session, RemoteRepository repository)` Gets an authentication context for the proxy of the specified repository.
    `static AuthenticationContext` | `forRepository(RepositorySystemSession session, RemoteRepository repository)` Gets an authentication context for the specified repository.
    `String` | `get(String key)` Gets the authentication data for the specified key.
    `<T> T` | `get(String key, Class<T> type)` Gets the authentication data for the specified key.
    `<T> T` | `get(String key, Map<String,String> data, Class<T> type)` Gets the authentication data for the specified key.
    `Proxy` | `getProxy()` Gets the proxy (if any) to be authenticated with.
    `RemoteRepository` | `getRepository()` Gets the repository requiring authentication.
    `RepositorySystemSession` | `getSession()` Gets the repository system session during which the authentication happens.
    `void` | `put(String key, Object value)` Puts the specified authentication data into this context.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### USERNAME

          public static final String USERNAME

      The key used to store the username. The corresponding authentication data should be of type `String`.
      See Also:
        Constant Field Values

    - #### PASSWORD

          public static final String PASSWORD

      The key used to store the password. The corresponding authentication data should be of type `char[]` or `String`.
      See Also:
        Constant Field Values

    - #### NTLM_DOMAIN

          public static final String NTLM_DOMAIN

      The key used to store the NTLM domain. The corresponding authentication data should be of type `String`.
      See Also:
        Constant Field Values

    - #### NTLM_WORKSTATION

          public static final String NTLM_WORKSTATION

      The key used to store the NTML workstation. The corresponding authentication data should be of type `String`.
      See Also:
        Constant Field Values

    - #### PRIVATE_KEY_PATH

          public static final String PRIVATE_KEY_PATH

      The key used to store the pathname to a private key file. The corresponding authentication data should be of type `String` or `File`.
      See Also:
        Constant Field Values

    - #### PRIVATE_KEY_PASSPHRASE

          public static final String PRIVATE_KEY_PASSPHRASE

      The key used to store the passphrase protecting the private key. The corresponding authentication data should be of type `char[]` or `String`.
      See Also:
        Constant Field Values

    - #### HOST_KEY_ACCEPTANCE

          public static final String HOST_KEY_ACCEPTANCE

      The key used to store the acceptance policy for unknown host keys. The corresponding authentication data should be of type `Boolean`. When querying this authentication data, the extra data should provide `HOST_KEY_REMOTE` and `HOST_KEY_LOCAL`, e.g. to enable a well-founded decision of the user during an interactive prompt.
      See Also:
        Constant Field Values

    - #### HOST_KEY_REMOTE

          public static final String HOST_KEY_REMOTE

      The key used to store the fingerprint of the public key advertised by remote host. Note that this key is used to query the extra data passed to `get(String, Map, Class)` when getting `HOST_KEY_ACCEPTANCE`, not the authentication data in a context.
      See Also:
        Constant Field Values

    - #### HOST_KEY_LOCAL

          public static final String HOST_KEY_LOCAL

      The key used to store the fingerprint of the public key expected from remote host as recorded in a known hosts database. Note that this key is used to query the extra data passed to `get(String, Map, Class)` when getting `HOST_KEY_ACCEPTANCE`, not the authentication data in a context.
      See Also:
        Constant Field Values

    - #### SSL_CONTEXT

          public static final String SSL_CONTEXT

      The key used to store the SSL context. The corresponding authentication data should be of type `SSLContext`.
      See Also:
        Constant Field Values

    - #### SSL_HOSTNAME_VERIFIER

          public static final String SSL_HOSTNAME_VERIFIER

      The key used to store the SSL hostname verifier. The corresponding authentication data should be of type `HostnameVerifier`.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### forRepository

          public static AuthenticationContext forRepository(RepositorySystemSession session,
                                            RemoteRepository repository)

      Gets an authentication context for the specified repository.
      Parameters:
        `session` - The repository system session during which the repository is accessed, must not be `null`.
        `repository` - The repository for which to create an authentication context, must not be `null`.
      Returns:
        An authentication context for the repository or `null` if no authentication is configured for it.

    - #### forProxy

          public static AuthenticationContext forProxy(RepositorySystemSession session,
                                       RemoteRepository repository)

      Gets an authentication context for the proxy of the specified repository.
      Parameters:
        `session` - The repository system session during which the repository is accessed, must not be `null`.
        `repository` - The repository for whose proxy to create an authentication context, must not be `null`.
      Returns:
        An authentication context for the proxy or `null` if no proxy is set or no authentication is configured for it.

    - #### getSession

          public RepositorySystemSession getSession()

      Gets the repository system session during which the authentication happens.
      Returns:
        The repository system session, never `null`.

    - #### getRepository

          public RemoteRepository getRepository()

      Gets the repository requiring authentication. If `getProxy()` is not `null`, the data gathered by this authentication context does not apply to the repository's host but rather the proxy.
      Returns:
        The repository to be contacted, never `null`.

    - #### getProxy

          public Proxy getProxy()

      Gets the proxy (if any) to be authenticated with.
      Returns:
        The proxy or `null` if authenticating directly with the repository's host.

    - #### get

          public String get(String key)

      Gets the authentication data for the specified key.
      Parameters:
        `key` - The key whose authentication data should be retrieved, must not be `null`.
      Returns:
        The requested authentication data or `null` if none.

    - #### get

          public <T> T get(String key,
                  Class<T> type)

      Gets the authentication data for the specified key.
      Type Parameters:
        `T` - The data type of the authentication data.
      Parameters:
        `key` - The key whose authentication data should be retrieved, must not be `null`.
        `type` - The expected type of the authentication data, must not be `null`.
      Returns:
        The requested authentication data or `null` if none or if the data doesn't match the expected type.

    - #### get

          public <T> T get(String key,
                  Map<String,String> data,
                  Class<T> type)

      Gets the authentication data for the specified key.
      Type Parameters:
        `T` - The data type of the authentication data.
      Parameters:
        `key` - The key whose authentication data should be retrieved, must not be `null`.
        `data` - Any (read-only) extra data in form of key value pairs that might be useful when getting the authentication data, may be `null`.
        `type` - The expected type of the authentication data, must not be `null`.
      Returns:
        The requested authentication data or `null` if none or if the data doesn't match the expected type.

    - #### put

          public void put(String key,
                 Object value)

      Puts the specified authentication data into this context. This method should only be called from implementors of `Authentication.fill(AuthenticationContext, String, Map)`. Passed in character arrays are not cloned and become owned by this context, i.e. get erased when the context gets closed.
      Parameters:
        `key` - The key to associate the authentication data with, must not be `null`.
        `value` - The (cleartext) authentication data to store, may be `null`.

    - #### close

          public void close()

      Closes this authentication context and erases sensitive authentication data from heap memory. Closing an already closed context has no effect.
      Specified by:
        `close` in interface `Closeable`
      Specified by:
        `close` in interface `AutoCloseable`

    - #### close

          public static void close(AuthenticationContext context)

      Closes the specified authentication context. This is a convenience method doing a `null` check before calling `close()` on the given context.
      Parameters:
        `context` - The authentication context to close, may be `null`.

Copyright © 2010-2014 The Eclipse Foundation. All Rights Reserved.