Package com.adobe.granite.keystore

Interface KeyStoreService

  • @ProviderType
public interface KeyStoreService
    Provides secure access to KeyManager instances for accessing private keys and the system-wide TrustManager for validating signatures and certificates.

    • Field Detail

      • NAME

        static final java.lang.String NAME
        Name of the KeyStoreService service
        See Also:
        Constant Field Values

    • Method Detail

      • getKeyStore

        java.security.KeyStore getKeyStore​(ResourceResolver resolver)
                            throws SlingIOException,
                                   java.lang.SecurityException,
                                   java.lang.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
        java.lang.SecurityException - if the key store cannot be instantiated due to security errors
        java.lang.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

        java.security.KeyStore getKeyStore​(ResourceResolver resolver,
                                   java.lang.String userId)
                            throws SlingIOException,
                                   java.lang.SecurityException,
                                   java.lang.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
        java.lang.SecurityException - if the key store cannot be instantiated due to security errors
        java.lang.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[]))

      • changeKeyStorePassword

        void changeKeyStorePassword​(ResourceResolver resolver,
                            java.lang.String userId,
                            char[] currentPassword,
                            char[] newPassword)
                     throws SlingIOException,
                            java.lang.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
        java.lang.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,
                              java.lang.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
        java.lang.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,
                        java.lang.String userId,
                        java.security.KeyPair keyPair,
                        java.lang.String alias)
                 throws SlingIOException,
                        java.lang.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
        java.lang.SecurityException - if the key store cannot be instantiated due to security errors
        java.lang.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

        java.security.KeyPair getKeyStoreKeyPair​(ResourceResolver resolver,
                                         java.lang.String userId,
                                         java.lang.String alias)
                                  throws SlingIOException,
                                         java.lang.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
        java.lang.SecurityException - if the key store cannot be instantiated due to security errors
        java.lang.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

        java.security.KeyStore createKeyStore​(ResourceResolver resolver,
                                      java.lang.String userId,
                                      char[] password)
                               throws SlingIOException,
                                      java.lang.SecurityException,
                                      java.lang.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
        java.lang.SecurityException - if the key store cannot be instantiated due to security errors
        java.lang.IllegalArgumentException - if any of the parameters are null

      • createKeyStore

        java.security.KeyStore createKeyStore​(ResourceResolver resolver,
                                      char[] password)
                               throws SlingIOException,
                                      java.lang.SecurityException,
                                      java.lang.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
        java.lang.SecurityException - if the key store cannot be instantiated due to security errors
        java.lang.IllegalArgumentException - if any of the parameters are null

      • createTrustStore

        java.security.KeyStore createTrustStore​(ResourceResolver resolver,
                                        char[] password)
                                 throws SlingIOException,
                                        java.lang.SecurityException,
                                        java.lang.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
        java.lang.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
        java.lang.IllegalArgumentException - if any of the parameters are null

      • keyStoreExists

        boolean keyStoreExists​(ResourceResolver resolver,
                       java.lang.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,
                         java.lang.String userId,
                         java.lang.String alias,
                         java.security.Key key,
                         java.security.cert.Certificate[] chain)
                  throws java.lang.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:
        java.lang.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[]))