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 Cloud Platform.

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.