Help Center

Menu

encryption.keyset-handle-provider-class

Background

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:

package com.funnelback.config.security;

import com.google.crypto.tink.KeysetHandle;

import java.io.File;
import java.io.IOException;
import java.security.GeneralSecurityException;

/**
 * Interface for defining how an encryption/decryption KeysetHandle (defined by https://github.com/google/tink/) 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 https://github.com/google/tink/) to be used to encrypt/decrypt passwords.
     */
    public KeysetHandle getKeysetHandle(File searchHome) throws GeneralSecurityException, IOException;
}

Setting the key

Set this configuration key in the server configuration.

Use the configuration key editor to add or edit the encryption.keyset-handle-provider-class key, and set the value. This can be set to any valid String value.

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.

encryption.keyset-handle-provider-class=com.funnelback.config.security.CleartextAutocreatingKeysetHandleProvider

Examples

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

The groovy script would be placed into:

$SEARCH_HOME/lib/java/groovy/com/foo/ExampleKeysetHandleProvider.groovy

The groovy (or Java) code is:

package foo;

import com.google.crypto.tink.KeysetHandle;

import com.funnelback.config.security.share.KeysetHandleProvider;

import java.io.File;
import java.io.IOException;
import java.security.GeneralSecurityException;

public class ExampleKeysetHandleProvider implements KeysetHandleProvider {
    @Override
    public KeysetHandle getKeysetHandle(File searchHome) throws GeneralSecurityException, IOException {
        KeysetHandle result = // Do whatever work is required to fetch and decrypt the keyset.

        // See https://github.com/google/tink/blob/master/docs/KEY-MANAGEMENT.md#key-management-systems
        // for details of the built-in key management system support and
        // https://github.com/google/tink/blob/master/docs/JAVA-HOWTO.md#loading-existing-keysets
        // 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:

encryption.keyset-handle-provider-class=foo.ExampleKeysetHandleProvider

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