com.sap.cloud.crypto.keystore.api

## Interface KeyStoreService

-     public interface KeyStoreService

  Interface of the keystore service that provides read-only access to the available keystores in SAP HANA Cloud.

  The keystore service works with keystores available on four different levels:

  - Subscription level - keystores available for a certain application in a certain account
  - Account level - keystores available for all applications in a certain account
  - Application level - keystores available in a certain application
  - File system - keystores available on the file system of the application VM

  Instance of this interface can be obtained by using JNDI. A resource reference needs to be declared in the web.xml descriptor of the application. By doing so, a resource reference name is mapped to the KeyStoreService type. Then this resource reference name can be used in the JNDI lookup.
  Example of resource reference declaration in the web.xml descriptor:

       <resource-ref>
        <res-ref-name>KeyStoreService</res-ref-name>
        <res-type>com.sap.cloud.crypto.keystore.api.KeyStoreService</res-type>
       </resource-ref>

  Example code for the JNDI lookup:

       KeyStoreService keystoreService = (KeyStoreService) new InitialContext().lookup("java:comp/env/KeyStoreService");

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `KeyStore` | `getKeyStore(String keyStoreName, char[] password)` Returns a fully initialized java.security.KeyStore instance.
    `Set<String>` | `getKeyStoreNames()` Returns the names of all available keystores.
    `void` | `invalidateCache()` Explicitly invalidates the local cache of keystores.

- - ### Method Detail

    - #### getKeyStore

          KeyStore getKeyStore(String keyStoreName,
                             char[] password)
                               throws KeyStoreServiceException,
                                      KeyStoreNotFoundException

      Returns a fully initialized java.security.KeyStore instance.

      This method will search for a keystore with the specified name in the following priority:

      1. Subscription
      2. Account
      3. Application
      4. File system
      Once a keystore with the specified name has been found at a certain location, further locations will no more be searched for.

      The returned keystore provides read-only access, i.e. invoking any of the setter methods will not change the Keystore, neither the `store()` will write the keystore.
      Also there is no need to invoke the `load()` method, as the keystore is already loaded. Any invocation of the `load()` method will be ignored.

      Parameters:
        `keyStoreName` - The name of existing keystore.
        `password` - Password used to check the integrity of the keystore content, to unlock the keystore, or `null`. Usage of the password depends on the keystore type. Some keystore types do not use password (e.g. keystores with type "pem"), some use the password for integrity checks only (e.g. keystores with type "jks" or "jceks"), and some require a password to load the keystore (e.g. keystores with type "pkcs12").
        If the password is used only for integrity check and `null` is passed as a value of the parameter, the keystore will be loaded and returned. If the password is used to open the keystore, then a KeyStoreServiceException will be thrown when password is not specified.
      Returns:
        An initialized instance of KeyStore. Never returns `null`.
      Throws:
        `KeyStoreServiceException` - Thrown either in case of failed integrity check of the obtained keystore or if there is a problem to obtain the requested keystore.
        `KeyStoreNotFoundException` - Thrown if a keystore with the specified `keyStoreName` does not exist.

    - #### getKeyStoreNames

          Set<String> getKeyStoreNames()

      Returns the names of all available keystores.
      The result contains the names of the keystores available on subscription, account, application and file system level.
      Returns:
        Set with the names of all existing keystores. Returns empty set if there are not any keystores.

    - #### invalidateCache

          void invalidateCache()

      Explicitly invalidates the local cache of keystores.

      The local cache is also invalidated implicitly based on internal algorithms and specific time intervals.
      This method needs to be called only when there is a need to ensure that the next requested keystore (via `getKeyStore(String, char[])` method) will be obtained from the central storage and not from the local cache.

Copyright © 2016 SAP. All Rights Reserved.