com.pingidentity.sdk.key

Interface MasterKeyEncryptor

public interface MasterKeyEncryptor

An encryptor that can be used to encrypt PingAccess' master key file (pa.jwk).

The encryptor can return a key identifier (via its initialize method) which can be associated with the master key file. This allows PingAccess configuration archives to be transferred between different installations. Alternatively, a null key identifier can be returned if the encryptor chooses to manage its key identifier for certain deployment requirements, such as tying the key to the machine's MAC address.

If a master key file was previously unencrypted, it will be immediately encrypted after initialization. If a key identifier is returned and has changed, then the master key file will be immediately encrypted.

An encryptor implementation class can be specified in a file named pa.jwk.properties in the conf directory with the key "pa.hostkey.masterKeyEncryptor". The pa.jwk.properties file does not exist by default. It will need to be created if a custom encryptor is to be used.

For example:
pa.hostkey.masterKeyEncryptor=com.company.MyMasterKeyEncryptor

Method Summary

Modifier and Type	Method and Description
byte[]	decrypt(byte[] cipherText) Decrypts the master key's cipher text.
byte[]	encrypt(byte[] plainText) Encrypts the data that will eventually be stored in the master key file.
String	initialize(String keyId) Initializes the MasterKeyEncryptor allowing implementations to perform any external key management operations, such as creating/loading an external key.

Method Detail

initialize

String initialize(String keyId)
           throws MasterKeyEncryptorException

Initializes the MasterKeyEncryptor allowing implementations to perform any external key management operations, such as creating/loading an external key.

The key identifier that is used to encrypt/decrypt the master key file is passed into the initialize method. The key identifier may be null if the master key file was not previously encrypted, or if this MasterKeyEncryptor doesn't need a key identifier and previously returned null in an earlier initialization.

This method is called every time a master key file is loaded. This occurs when PingAccess starts up.

Parameters:

keyId - The key identifier associated with the master key file. May be null.

Returns:

The key identifier to associate with the master key file. Can be null.

Throws:

MasterKeyEncryptorException - Thrown if failed to initialize.

encrypt

byte[] encrypt(byte[] plainText)
        throws MasterKeyEncryptorException

Encrypts the data that will eventually be stored in the master key file.

Parameters:

plainText - The master key file's plain text.

Returns:

The cipher text that will be saved to the master key file.

Throws:

MasterKeyEncryptorException - Thrown if failed to encrypt.

decrypt

byte[] decrypt(byte[] cipherText)
        throws MasterKeyEncryptorException

Decrypts the master key's cipher text.

Parameters:

cipherText - The master key's cipher text.

Returns:

The plain text contents of the master key file.

Throws:

MasterKeyEncryptorException - Thrown if failed to decrypt.