Skip to content


Specify the name of the class that will be used to provide the encryption/decryption KeysetHandle.

Key: encryption.keyset-handle-provider-class
Type: String
Can be set in: global.cfg


The sets the fully qualified name of the class that will be used to provide the encryption/decryption KeysetHandle.

A custom class could, for example:

  • Read the Keyset from some remote service.
  • Decrypt a local file containing the Keyset with some master key.

The class must implement:




 * Interface for defining how an encryption/decryption KeysetHandle (defined by is
 * provided to Funnelback for the purposes of encrypting/decrypting passwords that are stored by Funnelback.
 * Custom implementations are presumed to go beyond the built-in implementation by using a master key to encrypt/decrypt
 * the keyset's local storage or fetching it in some other more-secure, environment-specific way.
public interface KeysetHandleProvider {
     * @param searchHome The Funnelback installation's root directory, commonly /opt/funnelback or C:\funnelback which
     *                   the implementation may wish to use to find config files or look up settings.
     * @return the KeysetHandle (see to be used to encrypt/decrypt passwords.
    public KeysetHandle getKeysetHandle(File searchHome) throws GeneralSecurityException, IOException;

Default Value

By default the class will store the keyset in a file at $SEARCH_HOME/conf/keyset in a non-human-readable but unencrypted form, and will automatically create a new keyset if that file does not exist.


This shows a stub example of implementing a custom class which implements the KeysetHandleProvider interface.

The groovy script would be placed into:


The groovy (or Java) code is:

package foo;




public class ExampleKeysetHandleProvider implements KeysetHandleProvider {
    public KeysetHandle getKeysetHandle(File searchHome) throws GeneralSecurityException, IOException {
        KeysetHandle result = // Do whatever work is required to fetch and decrypt the keyset.
        // See
        // for details of the built-in key management system support and
        // for a simple example of decrypting a keyset with a master key.
        return result;

Supporting .jar files may be placed in the $SEARCH_HOME/lib/java/encryption directory to have them be made available on the classpath when the KeysetHandleProvider is instantiated and called. This would be necessary, for example, to make the Amazon KMS (key management system) supporting libraries available.

The global.cfg file will then need to contain:


The change will come into affect immediately, no restart is required.


Funnelback logo