API.txt in AES encryption 8.2

Here's a brief and simple run-through of the functions which might be
interesting from a developers point of view. Most (see exceptions below) of
the functions are implementation independent, so behaviour should be consistent
regardless of which implementation (mcrypt, phpseclib or custom) is used.

Implementation independence exceptions:

1. AES::make_iv is mute when using phpseclib since that implementation handle
its own IV internally.

2. The $custom_cipher and $custom_iv arguments to AES::encrypt and AES::decrypt
are ignored when using phpseclib, since that implementation doesn't support
changing these values. Passing these arguments as anything else than null will
generate warnings when using phpseclib.

--------------------------------------------------------------------------------
Function:
string|false AES::encrypt($string, $base64encode = true, $custom_key = null,
  $custom_cipher = null, $custom_iv = null, $custom_implementation = null)

Description:
Encrypts a string.

Arguments:
string $string The string to encrypt.
(optional) bool $base64encode Whether to return the string base64 encoded
  (recommended for database insertion).
(optional) string $custom_key Use this as the key rather than the stored
  one for this operation.
(optional) string $custom_cipher Use this cipher rather than the default one.
  (only with Mcrypt - ignored with phpseclib)
(optional) string $custom_iv Use this initialization vector instead of the
  default one.
(optional) string $force_implementation Can be "phpseclib", "mcrypt" or name
  of plugin implementing own algorithm.

  Warning: The function does not check if the requested implementation actually
  exists.

Returns:
The encrypted string on success, false on error.

--------------------------------------------------------------------------------
Function:
string|false AES::decrypt($string, $base64encoded = true, $custom_key = null,
  $custom_cipher = null, $custom_iv = null, $force_implementation = null)

Description:
Decrypts a string of encrypted data.

Arguments:
string $string The string to decrypt.
(optional) bool $base64encode Whether this encrypted string is base64 encoded
  or not.
(optional) string $custom_key Use this as the key rather than the stored one
  for this operation.
(optional) string $custom_cipher Use this cipher rather than the default one.
  (only with Mcrypt - ignored with phpseclib)
(optional) string $custom_iv Use this initialization vector instead of the
  default one.
(optional) string $force_implementation Can be "phpseclib", "mcrypt" or name
  of plugin implementing own algorithm.

  Warning: The function does not check if the requested implementation actually
  exists.

Returns:
The decrypted string on success, false on error.

---------------------------------------------------------------------------------
Function:
string AES::get_key()

Description:
Gets the current key used for the encryption system. If there's currently no key
defined, this function will generate one, store it, and return it.

Arguments:
none

Returns:
The key.

---------------------------------------------------------------------------------
Function:
string AES::make_key()

Description:
Generates a new key.

Arguments:
none

Returns:
The newly generated key.

--------------------------------------------------------------------------------
Function:
void AES::make_iv($ignore_implementation = false)

Description:
Generates a new initialization vector and stores it (overwrites old IV!).
NOTE: Only use this with the Mcrypt implementation, phpseclib has its own IV
management.

Arguments:
(optional) bool $ignore_implementation Forces aes_make_iv to create and store
a new IV even if the phpseclib implementation is used.

Returns:
nothing

--------------------------------------------------------------------------------
Custom encryption mechanism.
To use the module with own AES implementation or even custom encryption
algorithm a plugin should be created.

An example plugin is available in the file src/Plugin/AES/Reverse.php