com.adobe.granite.keystore

Interface KeyStoreService

public interface KeyStoreService

Provides secure access to KeyManager instances for accessing private keys and the system-wide TrustManager for validating signatures and certificates.

Method Summary

Methods

Modifier and Type	Method and Description
void	addKeyStoreKeyEntry(ResourceResolver resolver, String userId, String alias, Key key, Certificate[] chain) Adds a private key entry with a certificate chain to the key store owned by the user with the user id equal to userId.
void	addKeyStoreKeyPair(ResourceResolver resolver, String userId, KeyPair keyPair, String alias) Saves a KeyPair in the KeyStore owned by the user whose user id is userId, under the specified alias.
void	changeKeyStorePassword(ResourceResolver resolver, String userId, char[] currentPassword, char[] newPassword) Changes the password used to protect a user's key store.
void	changeTrustStorePassword(ResourceResolver resolver, char[] currentPassword, char[] newPassword) Changes the password used to protect the global trust store.
KeyStore	createKeyStore(ResourceResolver resolver, char[] password) Creates and returns a raw KeyStore for the user identified by the resolver.
KeyStore	createKeyStore(ResourceResolver resolver, String userId, char[] password) Creates and returns a raw KeyStore for the user whose user id is userId.
KeyStore	createTrustStore(ResourceResolver resolver, char[] password) Creates and returns the global trust store.
KeyManager	getKeyManager(ResourceResolver resolver) Returns the private KeyManager of the user identified by the given ResourceResolver.
KeyStore	getKeyStore(ResourceResolver resolver) Returns the raw KeyStore owned by the user identified by the ResourceResolver.
KeyStore	getKeyStore(ResourceResolver resolver, String userId) Returns the raw KeyStore owned by the user whose user id is userId.
KeyStore.Entry	getKeyStoreEntry(ResourceResolver resolver, String userId, String alias) Retrieves a protected entry from the key store owned by the user with the user id equal to userId for entries stored using the key store's password (see com.adobe.granite.keystore.KeyStoreService#addKeyStoreKeyEntry(org.apache.sling.api.resource.ResourceResolver, String, String, java.security.Key, java.security.cert.Certificate[]) .
KeyPair	getKeyStoreKeyPair(ResourceResolver resolver, String userId, String alias) Retrieve a KeyPair from the KeyStore owned by the user whose user id is userId, stored under the specified alias.
TrustManager	getTrustManager(ResourceResolver resolver) Returns the system wide TrustManager.
KeyStore	getTrustStore(ResourceResolver resolver) Returns the global trust store if it's accessible to the user identified by the ResourceResolver.
boolean	keyStoreExists(ResourceResolver resolver, String userId) Checks if a key store was created for the user whose user id is userId.
boolean	trustStoreExists(ResourceResolver resolver) Checks if the global trust store was created.

Method Detail

getKeyManager

KeyManager getKeyManager(ResourceResolver resolver)
                         throws SlingIOException,
                                SecurityException,
                                IllegalArgumentException,
                                KeyStoreNotInitialisedException

Returns the private KeyManager of the user identified by the given ResourceResolver.

Parameters:

resolver - a resolver identifying the user whose KeyStore is used for building the KeyManager

Returns:

the private key manager of the user identified by the given resolver; this method does not return null

Throws:

SlingIOException - if an error occurs instantiating the KeyManager with data from persistence

SecurityException - if the underlying key store cannot be instantiated due to security errors

IllegalArgumentException - if any of the parameters are null

KeyStoreNotInitialisedException - if the key store has not been created (see #createKeyStore(org.apache.sling.api.resource.ResourceResolver, char[]))

getKeyStore

KeyStore getKeyStore(ResourceResolver resolver)
                     throws SlingIOException,
                            SecurityException,
                            IllegalArgumentException,
                            KeyStoreNotInitialisedException

Returns the raw KeyStore owned by the user identified by the ResourceResolver. This key store allows managing the keys in the store.

The load and store methods of the returned KeyStore instance always throw a KeyStoreException because the actual storage is managed by the KeyStoreService service behind the scenes.

The ResourceResolver has to be open as long as write operations are performed with the KeyStore.

Parameters:

resolver - a resolver identifying the user for which the KeyStore will be obtained

Returns:

the key store owned by the user identified by the given resolver; this method does not return null

Throws:

SlingIOException - if an error occurs loading the KeyStore data from persistence

SecurityException - if the key store cannot be instantiated due to security errors

IllegalArgumentException - if any of the parameters are null

KeyStoreNotInitialisedException - if the key store has not been created (see #createKeyStore(org.apache.sling.api.resource.ResourceResolver, char[]))

getKeyStore

KeyStore getKeyStore(ResourceResolver resolver,
                   String userId)
                     throws SlingIOException,
                            SecurityException,
                            IllegalArgumentException,
                            KeyStoreNotInitialisedException

Returns the raw KeyStore owned by the user whose user id is userId. The given resource resolver must have the proper access rights in order to access the given user's key store. This key store allows managing the keys in the store.

The load and store methods of the returned KeyStore instance always throw a KeyStoreException because the actual storage is managed by the KeyStoreService service behind the scenes.

The ResourceResolver has to be open as long as write operations are performed with the KeyStore.

Parameters:

resolver - the resource resolver to use for accessing the key store owned by the user given as parameter

userId - the ID of the user who owns the returned key store

Returns:

the key store owned by the user identified by the given user ID. null is never returned.

Throws:

SlingIOException - if an error occurs loading the KeyStore data from persistence

SecurityException - if the key store cannot be instantiated due to security errors

IllegalArgumentException - if any of the parameters are null

KeyStoreNotInitialisedException - if the key store has not been created (see #createKeyStore(org.apache.sling.api.resource.ResourceResolver, char[]))

getTrustManager

TrustManager getTrustManager(ResourceResolver resolver)
                             throws SlingIOException,
                                    SecurityException,
                                    KeyStoreNotInitialisedException

Returns the system wide TrustManager.

Parameters:

resolver - a resolver identifying a user allowed to access the TrustManager

Returns:

the global trust manager; this method does not return null

Throws:

SlingIOException - if an error occurs instantiating the TrustManager with data from persistence

SecurityException - if the ResourceResolver is not allowed to access the global trust store

IllegalArgumentException - if the resolver is null

KeyStoreNotInitialisedException - if the trust store has not been created (see #createTrustStore(org.apache.sling.api.resource.ResourceResolver, char[]))

getTrustStore

KeyStore getTrustStore(ResourceResolver resolver)
                       throws SlingIOException,
                              SecurityException,
                              IllegalArgumentException,
                              KeyStoreNotInitialisedException

Returns the global trust store if it's accessible to the user identified by the ResourceResolver. This key store allows managing the keys in the store.

The load and store methods of the returned KeyStore instance always throw a KeyStoreException because the actual storage is managed by the KeyStoreService service behind the scenes.

The ResourceResolver has to be open as long as write operations are performed with the KeyStore.

Parameters:

resolver - a resolver identifying a user allowed to access the global trust store

Throws:

SlingIOException - if an error occurs loading the KeyStore data from persistence

SecurityException - if the ResourceResolver is not allowed access to the global trust store or if the store cannot be instantiated due to security errors

IllegalArgumentException - if any of the parameters are null

KeyStoreNotInitialisedException - if the trust store has not been created (see #createTrustStore(org.apache.sling.api.resource.ResourceResolver, char[]))

changeKeyStorePassword

void changeKeyStorePassword(ResourceResolver resolver,
                          String userId,
                          char[] currentPassword,
                          char[] newPassword)
                            throws SlingIOException,
                                   SecurityException,
                                   KeyStoreNotInitialisedException

Changes the password used to protect a user's key store. For security reasons the password char arrays parameters should be cleaned after successfully calling this method (see Arrays.fill(char[], char)).

Parameters:

resolver - a resource resolver to use for accessing the key store owned by the user given as parameter

userId - the ID of the user who owns the key store

currentPassword - the key store's current password; please make sure to clean this array after calling this method for security purposes

newPassword - the key store's new password; please make sure to clean this array after calling this method for security purposes

Throws:

SlingIOException - if an error occurs loading the KeyStore data from persistence

SecurityException - if the currentPassword doesn't match the key store's password or if the key store cannot be instantiated due to security errors

KeyStoreNotInitialisedException - if the key store has not been created (see #createKeyStore(org.apache.sling.api.resource.ResourceResolver, char[]))

changeTrustStorePassword

void changeTrustStorePassword(ResourceResolver resolver,
                            char[] currentPassword,
                            char[] newPassword)
                              throws SlingIOException,
                                     SecurityException,
                                     KeyStoreNotInitialisedException

Changes the password used to protect the global trust store. For security reasons the password char arrays parameters should be cleaned after successfully calling this method (see Arrays.fill(char[], char)).

Parameters:

resolver - a resource resolver with write access to the trust store

currentPassword - the trust store's current password; please make sure to clean this array after calling this method for security purposes

newPassword - the trust store's new password; please make sure to clean this array after calling this method for security purposes

Throws:

SlingIOException - if an error occurs loading the trust store data from persistence

SecurityException - if the currentPassword doesn't match the key store's password or if the passed resolver doesn't have enough rights to modify the trust store

KeyStoreNotInitialisedException - if the trust store has not been created (see #createTrustStore(org.apache.sling.api.resource.ResourceResolver, char[]))

addKeyStoreKeyPair

void addKeyStoreKeyPair(ResourceResolver resolver,
                      String userId,
                      KeyPair keyPair,
                      String alias)
                        throws SlingIOException,
                               SecurityException,
                               KeyStoreNotInitialisedException

Saves a KeyPair in the KeyStore owned by the user whose user id is userId, under the specified alias. The given resource resolver must have the proper access rights in order to access the given user's key store. If an entry already exists for the specified alias, it is overridden.

Parameters:

resolver - the resource resolver to use for accessing the key store owned by the user given as parameter

userId - the id of the user who owns the key store

keyPair - the KeyPair to save

alias - save the KeyPair under this alias

Throws:

SlingIOException - if an error occurs loading the KeyStore data from persistence

SecurityException - if the key store cannot be instantiated due to security errors

IllegalArgumentException - if any of the parameters are null

KeyStoreNotInitialisedException - if the key store has not been created (see #createKeyStore(org.apache.sling.api.resource.ResourceResolver, char[]))

getKeyStoreKeyPair

KeyPair getKeyStoreKeyPair(ResourceResolver resolver,
                         String userId,
                         String alias)
                           throws SlingIOException,
                                  SecurityException,
                                  KeyStoreNotInitialisedException

Retrieve a KeyPair from the KeyStore owned by the user whose user id is userId, stored under the specified alias. The given resource resolver must have the proper access rights in order to access the given user's key store.

Parameters:

resolver - the resource resolver to use for accessing the key store owned by the user given as parameter

userId - the id of the user who owns the key store

alias - retrieve the KeyPair stored under this alias

Returns:

the KeyPair or null if no KeyPair was stored with the given alias.

Throws:

SlingIOException - if an error occurs loading the KeyStore data from persistence

SecurityException - if the key store cannot be instantiated due to security errors

IllegalArgumentException - if any of the parameters are null

KeyStoreNotInitialisedException - if the key store has not been created (see #createKeyStore(org.apache.sling.api.resource.ResourceResolver, char[]))

createKeyStore

KeyStore createKeyStore(ResourceResolver resolver,
                      String userId,
                      char[] password)
                        throws SlingIOException,
                               SecurityException,
                               IllegalArgumentException

Creates and returns a raw KeyStore for the user whose user id is userId. For security reasons the password char array parameter should be cleaned after successfully calling this method (see Arrays.fill(char[], char)).

The load and store methods of the returned KeyStore instance always throw a KeyStoreException because the actual storage is managed by the KeyStoreService service behind the scenes.

The ResourceResolver has to be open as long as write operations are performed with the KeyStore. Also, it must have the proper access rights in order to create the given user's key store.

Calling this method several times with the same parameters has no effect on an already created key store. However, calling this method with a different password will throw a SlingIOException.

Parameters:

resolver - a resolver that will be used to create the KeyStore

userId - the user for which the KeyStore will be created

password - the password used for protecting the returned KeyStore; please make sure to clean this array after calling this method for security purposes

Returns:

the key store owned by the user whose user id is userId; this method does not return null

Throws:

SlingIOException - if an error occurs storing the KeyStore data to the persistence layer

SecurityException - if the key store cannot be instantiated due to security errors

IllegalArgumentException - if any of the parameters are null

createKeyStore

KeyStore createKeyStore(ResourceResolver resolver,
                      char[] password)
                        throws SlingIOException,
                               SecurityException,
                               IllegalArgumentException

Creates and returns a raw KeyStore for the user identified by the resolver. For security reasons the password char array parameter should be cleaned after successfully calling this method (see Arrays.fill(char[], char)).

The load and store methods of the returned KeyStore instance always throw a KeyStoreException because the actual storage is managed by the KeyStoreService service behind the scenes.

The ResourceResolver has to be open as long as write operations are performed with the KeyStore.

Calling this method several times with the same parameters has no effect on an already created key store. However, calling this method with a different password will throw a SlingIOException.

Parameters:

resolver - a resolver identifying the user for which the KeyStore will be created

password - the password used for protecting the returned KeyStore; please make sure to clean this array after calling this method for security purposes

Returns:

key store owned by the user identified by the given resolver; this method does not return null

Throws:

SlingIOException - if an error occurs storing the KeyStore data to the persistence layer

SecurityException - if the key store cannot be instantiated due to security errors

IllegalArgumentException - if any of the parameters are null

createTrustStore

KeyStore createTrustStore(ResourceResolver resolver,
                        char[] password)
                          throws SlingIOException,
                                 SecurityException,
                                 IllegalArgumentException

Creates and returns the global trust store. The resolver provided should have enough access rights in order to successfully create the trust store. For security reasons the password char array parameter should be cleaned after successfully calling this method (see Arrays.fill(char[], char)).

The load and store methods of the returned KeyStore instance always throw a KeyStoreException because the actual storage is managed by the KeyStoreService service behind the scenes.

The ResourceResolver has to be open as long as write operations are performed with the KeyStore.

Calling this method several times with the same parameters has no effect on an already created trust store. However, calling this method with a different password will throw a SlingIOException.

Parameters:

resolver - a resolver identifying a user allowed to create the global trust store

password - the password used for protecting the returned KeyStore; please make sure to clean this array after calling this method for security purposes

Returns:

the global trust store; this method does not return null

Throws:

SlingIOException - if an error occurs storing the KeyStore data to the persistence layer

SecurityException - if the ResourceResolver is not allowed access to the global trust store location or if the store cannot be instantiated due to security errors

IllegalArgumentException - if any of the parameters are null

keyStoreExists

boolean keyStoreExists(ResourceResolver resolver,
                     String userId)

Checks if a key store was created for the user whose user id is userId. The given resource resolver must have the proper access rights in order to check the existence of the given user's key store.

Parameters:

resolver - the resource resolver to use for checking the existence of a key store for the user whose user id is userId

userId - the id of the user who owns the checked key store

Returns:

true if the key store exists, false otherwise

trustStoreExists

boolean trustStoreExists(ResourceResolver resolver)

Checks if the global trust store was created.

Parameters:

resolver - the resolver used for checking the trust store's existence

Returns:

true if the trust store exists, false otherwise

addKeyStoreKeyEntry

void addKeyStoreKeyEntry(ResourceResolver resolver,
                       String userId,
                       String alias,
                       Key key,
                       Certificate[] chain)
                         throws SecurityException,
                                KeyStoreNotInitialisedException

Adds a private key entry with a certificate chain to the key store owned by the user with the user id equal to userId. This method makes sure the entries are protected with the store's password for ease of use instead of requiring a password for each key.

Parameters:

resolver - a resource resolver to use for accessing the key store owned by the user given as parameter

userId - the id of the user who owns the key store

alias - the alias under which the key entry will be saved in the key store

key - the private key that will be added to the key store

chain - the private key's certificate chain

Throws:

SecurityException - if the underlying key store cannot be instantiated due to security errors

KeyStoreNotInitialisedException - if the key store has not been created (see #createKeyStore(org.apache.sling.api.resource.ResourceResolver, char[]))

getKeyStoreEntry

KeyStore.Entry getKeyStoreEntry(ResourceResolver resolver,
                              String userId,
                              String alias)
                                throws SecurityException,
                                       KeyStoreNotInitialisedException

Retrieves a protected entry from the key store owned by the user with the user id equal to userId for entries stored using the key store's password (see com.adobe.granite.keystore.KeyStoreService#addKeyStoreKeyEntry(org.apache.sling.api.resource.ResourceResolver, String, String, java.security.Key, java.security.cert.Certificate[]) .

Parameters:

resolver - a resource resolver to use for accessing the key store owned by the user given as parameter

userId - the id of the user who owns the key store

alias - the alias under which the key entry will be saved in the key store

Returns:

the entry stored in the key store under alias

Throws:

SecurityException - if the underlying key store cannot be instantiated due to security errors

KeyStoreNotInitialisedException - if the key store has not been created (see #createKeyStore(org.apache.sling.api.resource.ResourceResolver, char[]))