Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
OpenXPKI::Crypto::VolaUserVContributed Perl OpenXPKI::Crypto::VolatileVault(3)

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.

       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.

   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)

perl v5.24.1			  2017-07-03OpenXPKI::Crypto::VolatileVault(3)

Name | Description

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=OpenXPKI::Crypto::VolatileVault&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help