Name

OpenXPKI::Crypto::VolatileVault

Description

This class implements a volatile storage for holding sensitive information during the runtime of a program.

  use OpenXPKI::Crypto::VolatileVault;
  my $token = ...
  my $vault = OpenXPKI::Crypto::VolatileVault->new(
    {
        TOKEN => $token,
    });
  my $encrypted = $vault->encrypt('supersecretdata');

  ...

  my $tmp = $vault->decrypt($encrypted);

The constructor will generate a random symmetric key and store it in an instance variable. The class uses inside-out objects via Class::Std to make sure that the secret key is strictly internal to the instance and not accessible from the outside.

Encrypted data includes an instance ID that allows a particular instance to determine if it has created a given piece of encrypted data, hence it can check if it is capable of decrypting the data without actually trying to do so.

new()

Creates a new vault object instance. Requires an initialized default token to be passed via the named parameter TOKEN.

Accepts a named parameter ENCODING which sets the instance's default encoding for the encrypted data string. ENCODING may be one of 'raw' (binary), 'base64' (Base64 with newlines) and 'base64-oneline' (Base64 without any whitespace or newlines). Default is 'base64-oneline'.

Specifying keys

It is possible to specify a symmetric key and IV to use by passing KEY and IV values to the constructor. KEY and IV must be specified using upper case hexadecimal digits (no whitespace allowed). The caller must make sure that KEY and IV do make sense (are long enough etc.). Specifying a KEY without IV yields an exception.

If you set the IV to undef, a new IV will be created for each encryption call and the IV is persisted in the header data of the ciphertext.

Exporting keys

It is also possible to mark the internally used key and iv as exportable. This can be forced by explicity setting the EXPORTABLE variable. EXPORTABLE is interpreted as an integer and decremented every time key and iv are exported. Exporting the values is only possible as long as the counter is greater than zero. Setting EXPORTABLE to -1 allows unlimited key exports. Setting EXPORTABLE to 0 in the constructor is identical to not allowing export at all. The constructor throws an exception if EXPORTABLE is not an integer greater or equal -1.

encrypt()

If the first argument to encrypt() is a hash reference the method accepts the named arguments 'DATA' and 'ENCODING'.

DATA contains the scalar data to encrypt.

ENCODING defaults to the default encoding for the instance and may be one of 'base64' (base64 encoding), 'base64-oneline' (base64 encoding on one single line without any whitespace or line breaks) or 'raw' (binary data).

If the first argument to encrypt() is a scalar instead of a hash reference it is assumed to contain the data to encrypt (just like a DATA named argument).

During the lifetime of the instance the caller may call the encrypt() method in order to protect sensitive data. The method encrypts the specified data with the secret key and returns the encrypted value. This encrypted data may now be stored in insecure places because the decryption is only possible via the same class instance that encrypted it in the first plase.

WARNING: after destruction of the class instance decryption of data encrypted by this instance is impossible.

The method returns the enrypted data that may be stored in unsafe storage and may be passed to decrypt() of the same instance in order to access the stored data.

decrypt()

Accepts a scalar argument containing the encrypted data to encrypt and returns the original clear text. This only works if the encrypted data was created by the same object instance of this class.

can_decrypt()

Accepts one scalar attribute and checks if the class instance would be able to decrypt the data. Returns true if this instance can decrypt it.

There is a small probability that the method returns a false positive (if a previous instance used the same instance ID).

The method throws an exception if the data to be decrypted is not recognized to be a valid VolatileVault data block.

export_key()

Exports the internally used symmetric key and IV. Exporting is only possible if the object was created with the EXPORTABLE option. Every call to export_key() decrements the internal export counter; a key export is only possible as long as the maximum export counter has not been exceeded. (See constructor description.) If exporting the key is not explicitly allowed the method throws an exception. The returned key is returned in a hash reference with KEY, IV and ALGORITHM keys. The values for KEY and IV are hexadecimal (uppercase) numbers specifying the key and initialization vector.

IV is set to undef if dynamic IV generation is used.

lock_vault()

If the vault was created with the EXPORTABLE option, it allows to export the internally used private key via export_key(). Once the lock_vault() method is called, the export option is immediately shut down (max export counter is set to 0) and it is no longer possible to export the internally used key.

get_key_id()

Returns a key id which may be used to identify the used symmetric key. The returned key id is a truncated base64 encoded SHA1 hash (8 characters) of key and iv. Collisions may occur.

If the named argument LONG is set, the returned key id is the full base64 encoded SHA1 hash of the key.

Advanced usage

Provide externally generated key and IV:

  use OpenXPKI::Crypto::VolatileVault;
  my $token = ...
  my $key = 'DEADBEEFCAFEBABE';
  my $iv = '012345678';
  my $vault = OpenXPKI::Crypto::VolatileVault->new(
    {
        TOKEN => $token,
        KEY => $key,
        IV => $iv,
    });
  my $encrypted = $vault->encrypt('supersecretdata');

  ...

  my $tmp = $vault->decrypt($encrypted);

Let VolatileVault pick its own random key but allow exporting the key.

  use OpenXPKI::Crypto::VolatileVault;
  my $token = ...
  my $vault = OpenXPKI::Crypto::VolatileVault->new(
    {
        TOKEN => $token,
        EXPORTABLE => 2,
    });
  my $encrypted = $vault->encrypt('supersecretdata');

  ...

  my $tmp = $vault->decrypt($encrypted);

  my $key;
  $key = $vault->export_key(); # works
  $key = $vault->export_key(); # works
  $key = $vault->export_key(); # fails (export was only allowed 2 times above)