Menu

## KickassCrypto
in package
implements IKickassCrypto Uses KICKASS_WRAPPER_PHP

KickassCrypto.php : 44

2023-04-05 jj5 - this class provides the base framework for a crypto service; you can extend it yourself or use one (or more) of the services implemented as modules in this library.

### Interfaces, Classes, Traits and Enums

IKickassCrypto
  2023-04-05 jj5 - the IKickassCrypto interface is the interface provided by an encryption service. You can use the framework to create your own encryption services or you can use one (or more) of the four encryption services provided by this library.

### Table of Contents

$active : array<string|int, mixed>
  2023-04-07 jj5 - this map is for tracking active functions which are presently on the call stack; see the enter() and leave() functions to understand how this field is used.
$inject_delay : bool
  2023-04-02 jj5 - this flag indicates whether we need to inject a random delay or not, it gets set when a call to either encrypt() or decrypt() is made. It gets set back to false after a delay has been injected so that multiple errors won't trigger multiple delays.
$telemetry : array<string|int, mixed>
  2023-03-30 jj5 - our counters are stored here
clear_error() : void
  2023-04-07 jj5 - clears the current errors, if any.
decrypt() : mixed
  2023-04-05 jj5 - decrypts the ciphertext and returns the deserialized value; returns false on failure.
delay() : void
  2023-04-05 jj5 - delays the process for a random amount of time between 1 millisecond and 10 seconds; this is used as a timing attack mitigation, it slows down attackers trying to brute force errors.
encrypt() : string|false
  2023-04-05 jj5 - encrypts the input and returns the ciphertext; returns false on failure.
GenerateSecret() : string
  2023-03-30 jj5 - this function will generate a secret key suitable for use in the config file.
get_error() : string|null
  2023-04-07 jj5 - gets the latest error as a string description or returns null if there's no error.
get_error_list() : array<string|int, mixed>
  2023-04-07 jj5 - gets the current list of errors, the list is empty if there are no errors, otherwise it contains strings which describe the errors that have occurred.
GetTelemetry() : array<string|int, mixed>
  2023-04-01 jj5 - NOTE: the telemetry might be considered sensitive data... but probably not so sensitive that it can't be logged. It's not at the same level as secrets or passphrases.
ReportCounters() : void
  2023-04-05 jj5 - this will report a list of counts to STDOUT.
ReportTelemetry() : void
  2023-04-05 jj5 - this function will print the telemetry data to STDOUT; it's suitable for use in a console.
__construct() : mixed
  2023-03-30 jj5 - we throw exceptions from the constructor if our environment is invalid; if the constructor succeeds then encryption and decryption should also usually succeed later on.
convert_secret_to_passphrase() : string|false
  2023-04-07 jj5 - converts a secret key to a passphrase by applying the hashing function.
count_class() : int
  2023-04-05 jj5 - will increment a class count metric.
count_function() : int
  2023-04-05 jj5 - will increment a function count metric.
count_length() : int
  2023-04-05 jj5 - will increment a length count metric.
count_this() : int
  2023-04-05 jj5 - will count this instance.
data_decode() : mixed
  2023-04-07 jj5 - decodes the encoded data using the nominated encoding.
data_encode() : string|false
  2023-04-05 jj5 - serializes the data based on the data encoding in use; defers to a virtual do_data_encode() method.
decode_message() : string|false
  2023-04-05 jj5 - decodes a message; defers to virtual do_decode_message().
decrypt_string() : mixed
  2023-04-05 jj5 - decrypts a binary string using the passphrase.
do_clear_error() : void
  2023-04-07 jj5 - clears the active list of errors.
do_convert_secret_to_passphrase() : string|false
  2023-04-07 jj5 - the default implementation of the passphrase hashing logic.
do_count_class() : int
  2023-04-05 jj5 - by default will increment the count for this class metric; can be overridden by implementations.
do_count_function() : int
  2023-04-05 jj5 - by default will increment the counter for this function metric; can be overridden by implementations.
do_count_length() : int
  2023-04-05 jj5 - by default will increment the count for this length metric; can be overridden by implementations.
do_count_this() : void
  2023-04-05 jj5 - by default will count the caller function (should be the constructor) and this class instance; can be overridden by implementations.
do_data_decode() : mixed
  2023-04-07 jj5 - provides the default implementation for data decoding, which provides support for decoding one of JSON, PHPS, or text.
do_data_encode() : string|false
  2023-04-05 jj5 - by default serializes data based on the data encoding in use; can be overridden by implementations.
do_decode_message() : string
  2023-04-05 jj5 - by default will decode the message and determine the data encoding using; can be overridden by implementations.
do_decrypt() : mixed
  2023-04-05 jj5 - by default handles the standard decryption process; can be overridden by implementations.
do_decrypt_string() : string|false
  2023-04-05 jj5 - this will call the encryption library (either OpenSSL or Sodium by default) and do the actual decryption.
do_delay() : mixed
  2023-04-05 jj5 - by default sleeps for a random amount of time between the minimum time given in nanoseconds and the maximum time also given in nanoseconds; can be overridden by implementations.
do_encrypt() : string|false
  2023-04-05 jj5 - by default encrypts the input value; can be overridden by implementations.
do_encrypt_string() : string|false
  2023-04-05 jj5 - this will call the encryption library (either OpenSSL or Sodium by default) and do the actual encryption.
do_error() : void
  2023-04-05 jj5 - this function will register an error.
do_get_config_chunk_size() : int
  2023-04-05 jj5 - by default returns the value of the CONFIG_ENCRYPTION_CHUNK_SIZE constant or the default value if CONFIG_ENCRYPTION_CHUNK_SIZE is not defined; can be overridden by implementations.
do_get_config_chunk_size_max() : int
  2023-04-05 jj5 - by default returns the value of the CONFIG_ENCRYPTION_CHUNK_SIZE_MAX constant or the default value if CONFIG_ENCRYPTION_CHUNK_SIZE_MAX is not defined; can be overridden by implementations.
do_get_config_data_encoding() : string
  2023-04-05 jj5 - by default returns the value of the CONFIG_ENCRYPTION_DATA_ENCODING constant or the default value if CONFIG_ENCRYPTION_DATA_ENCODING is not defined; can be overridden by implementations.
do_get_config_data_length_max() : int
  2023-04-05 jj5 - by default returns the value of the CONFIG_ENCRYPTION_DATA_LENGTH_MAX constant or the default value if CONFIG_ENCRYPTION_DATA_LENGTH_MAX is not defined; can be overridden by implementations.
do_get_config_false_enable() : bool
  2023-04-05 jj5 - by default returns the value of the CONFIG_ENCRYPTION_FALSE_ENABLE constant of the default value if CONFIG_ENCRYPTION_FALSE_ENABLE is not defined; can be overridden by implementations.
do_get_config_json_decode_options() : int
  2023-04-05 jj5 - by default returns the value of the CONFIG_ENCRYPTION_JSON_DECODE_OPTIONS constant or the default value if CONFIG_ENCRYPTION_JSON_DECODE_OPTIONS is not defined; can be overridden by implementations.
do_get_config_json_encode_options() : int
  2023-04-05 jj5 - by default returns the value of the CONFIG_ENCRYPTION_JSON_ENCODE_OPTIONS constant or the default value if CONFIG_ENCRYPTION_JSON_ENCODE_OPTIONS is not defined; can be overridden by implementations.
do_get_config_phps_enable() : bool
  2023-04-05 jj5 - by default returns the value of the CONFIG_ENCRYPTION_PHPS_ENABLE constant or the default value if CONFIG_ENCRYPTION_PHPS_ENABLE is not defined; can be overridden by implementations.
do_get_const() : mixed
  2023-04-05 jj5 - by default returns the value of the constant, or returns the default value if the constant is not defined; can be overridden by implementations.
do_get_const_data_format() : string
  2023-04-05 jj5 - the data format code; this will be prefixed to the base64 encoded ciphertext so we can determine which service we need to decrypt values.
do_get_const_key_hash() : string
  2023-04-05 jj5 - by default returns the value of the KICKASS_CRYPTO_KEY_HASH constant; can be overridden by implementations.
do_get_const_key_length_min() : int
  2023-04-05 jj5 - by default returns the value of the KICKASS_CRYPTO_KEY_LENGTH_MIN constant; can be overridden by implementations.
do_get_const_passphrase_length_min() : int
  2023-04-05 jj5 - by default returns the value of the KICKASS_CRYPTO_PASSPHRASE_LENGTH_MIN constant; can be overridden by implementations.
do_get_data_encoding() : string
  2023-04-05 jj5 - by default gets the data encoding from the config option as returned from get_config_data_encoding().
do_get_delay() : bool
  2023-04-07 jj5 - provides the default implementation of the delay calculations; can be overridden by implementations.
do_get_encryption_passphrase() : string|null
  2023-04-05 jj5 - by default returns the first passphrase from the passphrase list; can be overridden by implementations.
do_get_error() : string|null
  2023-04-07 jj5 - gets the most recent error, it's a string, or null if no error.
do_get_error_list() : array<string|int, mixed>
  2023-04-07 jj5 - gets the list of errors, it's a list of strings, it can be empty, in fact it's best if it is!
do_get_padding() : string|false
  2023-04-07 jj5 - does the actual work of generating the random padding; can be overridden by implementations.
do_get_passphrase_list() : array<string|int, mixed>
  2023-04-05 jj5 - the list of passphrases; the passphrases are generated by using the secret key hashing function on the secret keys defined in the config file.
do_handle() : void
  2023-04-01 jj5 - implementations can decide what to do when errors are handled; by default we write a log entry; can be overridden by implementations.
do_ignore() : void
  2023-04-01 jj5 - implementations can decide what to do when errors are ignored; by default we write a log entry; can be overridden by implementations.
do_increment_counter() : int
  2023-04-05 jj5 - by default will increment the value for a key in an array; will initialize to zero if missing; can be overridden by implementations.
do_is_cli() : bool
  2023-04-05 jj5 - by default checks to see if php_sapi_name() === 'cli'; can be overridden by implementations.
do_is_debug() : bool
  2023-04-05 jj5 - by default checks to see if the DEBUG constant is defined and true; can be overridden by implementations.
do_is_valid_base64() : bool
  2023-04-05 jj5 - by default checks to make sure the input is a non-empty string and then validates it with the KICKASS_CRYPTO_REGEX_BASE64 regular expression; can be overridden by implementations.
do_is_valid_config() : bool
  2023-03-30 jj5 - implementations need to define what a valid configuration is.
do_is_valid_data_encoding() : bool
  2023-04-05 jj5 - by default checks that the data encoding is one of the two supported data encodings; can be overridden by implementations.
do_is_valid_passphrase() : bool
  2023-04-06 jj5 - by default checks the string length; can be overridden by implementations.
do_is_valid_secret() : bool
  2023-04-05 jj5 - my default checks that the secret key is a string and meets the minimum length requirements; this function can be overridden by implementations.
do_json_decode() : mixed
  2023-04-07 jj5 - does the actual work of JSON decoding by calling the PHP function via its wrapper.
do_json_encode() : mixed
  2023-04-05 jj5 - by default encodes the input as JSON using the JSON encoding options read from the config file; can be overridden by implementations.
do_log_error() : bool
  2023-04-07 jj5 - provides a default implementation for log writing; can be overridden by implementations.
do_message_decode() : string|false
  2023-04-07 jj5 - does the actual work of message decoding; can be overridden by implementations.
do_message_encode() : string|false
  2023-04-07 jj5 - does the actual work of message encoding; can be overridden by implementations.
do_notify() : void
  2023-04-01 jj5 - implementations can decide what to do when errors are notified; by default we write a log entry; can be overridden by implementations.
do_parse_binary() : bool
  2023-04-05 jj5 - this function extracts the initialization vector, ciphertext, and tag from the concatenated binary data; not all service define all pieces; the OpenSSL library will use all three; the Sodium library uses the initialization vector for its nonce and it does not use the tag.
do_php_base64_decode() : mixed
do_php_base64_encode() : mixed
do_php_json_decode() : mixed
do_php_json_encode() : mixed
do_php_json_last_error() : mixed
do_php_random_bytes() : mixed
do_php_random_int() : mixed
do_php_sapi_name() : mixed
do_php_serialize() : mixed
do_php_strval() : mixed
do_php_time_nanosleep() : mixed
do_php_unserialize() : mixed
do_phps_decode() : mixed
  2023-04-07 jj5 - does the actual work of PHP deserialization by deferring to the implementation on the PHP wrapper.
do_phps_encode() : string|false
  2023-04-07 jj5 - does the actual work of PHP serialization; can be overridden by implementers; by default calls the PHP serialize() function via its wrapper.
do_report_emergency_delay() : void
  2023-04-05 jj5 - by default writes a message to the error log; can be overridden by implementations.
do_text_decode() : mixed
  2023-04-07 jj5 - does the actual work of text deserialization by deferring to the implementation on the PHP wrapper.
do_text_encode() : string|false
  2023-04-07 jj5 - does the actual work of text serialization; can be overridden by implementers; by default calls the PHP strval() function via its wrapper.
do_throw() : mixed
  2023-04-05 jj5 - by default this finds the message for the given exception code and then throws an exception with the relevant code and message; can be overridden by implementations.
emergency_delay() : void
  2023-04-05 jj5 - does an emergency delay; this doesn't give the caller any option to interfere so the emergency delay should run reliably if it's necessary.
encrypt_string() : string|false
  2023-04-05 jj5 - encrypts a plaintext string using the passphrase; defers to do_encrypt_string().
enter() : void
  2023-04-07 jj5 - registers when a function gets called so as to track the depth of a function on the call stack.
error() : bool
  2023-04-05 jj5 - registers an error; if this is the first error a random delay is injected as a timing attack mitigation.
get_config_chunk_size() : int
  2023-04-05 jj5 - gets the chunk size, it's used for padding encrypted messages.
get_config_chunk_size_max() : int
  2023-04-05 jj5 - gets the maximum chunk size, it's used for validating the chunk size.
get_config_data_encoding() : string
  2023-04-05 jj5 - gets the data encoding.
get_config_data_length_max() : int
  2023-04-05 jj5 - gets the maximum supported data length, it's used for validating the encoded data.
get_config_false_enable() : bool
  2023-04-05 jj5 - gets a boolean value indicating whether the boolean value false can be encrypted or not.
get_config_json_decode_options() : int
  2023-04-05 jj5 - gets the JSON decoding options which will be passed to the PHP json_decode() function.
get_config_json_encode_options() : int
  2023-04-05 jj5 - gets the JSON encoding options which will be passed to the PHP json_encode() function.
get_config_phps_enable() : bool
  2023-04-05 jj5 - gets a boolean value indicating whether PHPS serialization and deserialization is enabled or not.
get_const() : mixed
  2023-04-05 jj5 - gets a constant value, or returns the default value if the constant is not defined.
get_const_data_format() : string
  2023-04-05 jj5 - gets the data format constant; defers to abstract method for implementation.
get_const_key_hash() : string
  2023-04-05 jj5 - gets the name of the hashing algorithm to use for secret key hashing.
get_const_key_length_min() : int
  2023-04-05 jj5 - gets the minimum length of a secret key.
get_const_passphrase_length_min() : int
  2023-04-05 jj5 - gets the minimum length of a passphrase.
get_data_encoding() : string
  2023-04-05 jj5 - gets the data encoding; defers to virtual do_get_data_encoding().
get_data_format() : string|false
  2023-04-07 jj5 - gets the data format; the data format can be "KA0" for OpenSSL implementations and "KAS0" for Sodium implementations; if not the official implementation then the string 'X' is prepended to the data format.
get_delay() : bool
  2023-04-07 jj5 - calculates the seconds and extra nanoseconds which will be needed by the delay implementation; this function defers to do_get_delay() which can be overridden by implementations.
get_encryption_passphrase() : string
  2023-04-05 jj5 - returns the passphrase to use for encryption or null if it's missing.
get_padding() : string|false
  2023-04-07 jj5 - gets the string to use as padding; it's usually just a string of random bytes.
get_passphrase_list() : array<string|int, mixed>
  2023-04-05 jj5 - returns the list of passphrases; defers to abstract implementation.
handle() : void
  2023-04-01 jj5 - the point of handle() is simply to notify that an exception has been caught and "handled"; sometimes "handling" the exception is tantamount to ignoring it, so we call this method that we may make some noise about it (during debugging, usually). See do_handle() for the rest of the story.
ignore() : void
  2023-04-06 jj5 - the point of ignore() is simply to notify that an exception has been caught and it will be ignored.
increment_counter() : int
  2023-04-05 jj5 - will increment the value for a key in an array; will initialize to zero if missing.
is_cli() : bool
  2023-04-05 jj5 - reports if the program is running from the command-line.
is_debug() : bool
  2023-04-05 jj5 - checks to see if the program is running in DEBUG mode.
is_valid_base64() : bool
  2023-04-05 jj5 - checks the input is in valid base64 format; defers to virtual do_is_valid_base64().
is_valid_config() : bool
  2023-04-05 jj5 - checks to see if the environment configuration is valid; this function defers to the abstract method do_is_valid_config().
is_valid_data_encoding() : bool
  2023-04-05 jj5 - checks to see if the data encoding is a valid supported encoding; defers to the virtual do_is_valid_encoding() method.
is_valid_data_format() : bool
  2023-04-05 jj5 - checks to see if the data format is valid; this behavior cannot be overridden by implementations.
is_valid_passphrase() : bool
  2023-04-06 jj5 - checks to see if a passphrase is valid; this function defers to do_is_valid_passphrase();
is_valid_secret() : bool
  2023-04-05 jj5 - checks to see if a secret is valid; this function defers to do_is_valid_secret();
json_decode() : mixed
  2023-04-07 jj5 - deserialized JSON data.
json_encode() : string|false
  2023-04-05 jj5 - encodes a valud as JSON; defers to do_json_encode() for implementation.
leave() : mixed
  2023-04-07 jj5 - registers when a runction returns so as to track the depth of a function on the call stack.
log_error() : bool
  2023-04-07 jj5 - logs an error.
message_decode() : string|false
  2023-04-07 jj5 - decodes a message into binary.
message_encode() : string|false
  2023-04-07 jj5 - encodes a message.
notify() : void
  2023-04-01 jj5 - the point of notify() is simply to notify that an exception has been caught but it's going to be rethrown; it's best if this function doesn't throw an exception but it shouldn't be a huge problem if it does, the caller will throw when this function returns anyway.
parse_binary() : bool
  2023-04-05 jj5 - parses the binary message into its fixed length components.
php_base64_decode() : mixed
php_base64_encode() : mixed
php_json_decode() : mixed
php_json_encode() : mixed
php_json_last_error() : mixed
php_random_bytes() : mixed
php_random_int() : mixed
php_sapi_name() : mixed
php_serialize() : mixed
php_strval() : mixed
php_time_nanosleep() : mixed
php_unserialize() : mixed
phps_decode() : mixed
  2023-04-07 jj5 - deserializes the input data using the PHP unserialize() function.
phps_encode() : string|false
  2023-04-05 jj5 - serializes a value using PHP serialization; defers to virtual method do_phps_encode() for implementation.
text_decode() : mixed
  2023-04-07 jj5 - deserializes the input data using the PHP strval() function.
text_encode() : string|false
  2023-04-05 jj5 - serializes a value as text; defers to virtual method do_text_encode() for implementation.
throw() : void
  2023-04-05 jj5 - this function throws an exception.
try_decrypt() : mixed
  2023-04-05 jj5 - tries to decrypt a binary string using the passphrase.
write_log() : bool
  2023-04-07 jj5 - provides our internal direct implementation of log writing, in case we need to use it ourselves without potential interference from inheritors of our class.
increment_counter_internal() : mixed
  2023-04-07 jj5 - this is our private implementation for incrementing a counter for a key, we use it in enter().
report_emergency_delay() : void
  2023-04-05 jj5 - this function makes some noice is the emergency delay is invoked; the emergency delay should not usually be activated so if it is we want to give ourself our best chance of finding out about it.

### Properties

#### $active

KickassCrypto.php : 86

2023-04-07 jj5 - this map is for tracking active functions which are presently on the call stack; see the enter() and leave() functions to understand how this field is used.

`private array<string|int, mixed> $active = []`

keys are strings containing function names and values are a count of the number of instances of the function that are presently on the call stack.

#### $inject_delay

KickassCrypto.php : 77

2023-04-02 jj5 - this flag indicates whether we need to inject a random delay or not, it gets set when a call to either encrypt() or decrypt() is made. It gets set back to false after a delay has been injected so that multiple errors won't trigger multiple delays.

`private bool $inject_delay = false`

#### $telemetry

KickassCrypto.php : 64

2023-03-30 jj5 - our counters are stored here

`private static array<string|int, mixed> $telemetry = ['function' => [], 'class' => [], 'length' => []]`

- count_function() will increment the 'function' counter
- count_class() will increment the 'class' counter
- count_length() will increment the 'length' counter

2023-04-02 jj5 - the function counters count how many times some key functions were called.

2023-04-02 jj5 - the class counters count how many times certain classes were constructed.

2023-04-02 jj5 - the length counter counts the lengths of successfully encrypted data that occur, these should group due to chunking.

### Methods

#### clear_error()

KickassCrypto.php : 672

2023-04-07 jj5 - clears the current errors, if any.

`public final clear_error() : void`

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

void —

#### decrypt()

KickassCrypto.php : 390

2023-04-05 jj5 - decrypts the ciphertext and returns the deserialized value; returns false on failure.

`public final decrypt(string $ciphertext) : mixed`

##### Parameters

$ciphertext : string

  the ciphertext previously returned from the encrypt() method.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

mixed —

the decrypted and deserialized value, or false on failure.

#### delay()

KickassCrypto.php : 466

2023-04-05 jj5 - delays the process for a random amount of time between 1 millisecond and 10 seconds; this is used as a timing attack mitigation, it slows down attackers trying to brute force errors.

`public final delay() : void`

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

void —

#### encrypt()

KickassCrypto.php : 302

2023-04-05 jj5 - encrypts the input and returns the ciphertext; returns false on failure.

`public final encrypt(mixed $input) : string|false`

##### Parameters

$input : mixed

  the complex value you want encrypted.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

string|false —

the ciphertext on success, or false on failure.

#### GenerateSecret()

KickassCrypto.php : 203

2023-03-30 jj5 - this function will generate a secret key suitable for use in the config file.

`public static GenerateSecret() : string`

##### Return values

string —

an 88 character ASCII string for use as a secret key.

#### get_error()

KickassCrypto.php : 597

2023-04-07 jj5 - gets the latest error as a string description or returns null if there's no error.

`public final get_error() : string|null`

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

string|null —

the error description or null if no error.

#### get_error_list()

KickassCrypto.php : 539

2023-04-07 jj5 - gets the current list of errors, the list is empty if there are no errors, otherwise it contains strings which describe the errors that have occurred.

`public final get_error_list() : array<string|int, mixed>`

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

array<string|int, mixed> —

an array of strings, can be empty.

#### GetTelemetry()

KickassCrypto.php : 226

2023-04-01 jj5 - NOTE: the telemetry might be considered sensitive data... but probably not so sensitive that it can't be logged. It's not at the same level as secrets or passphrases.

`public static GetTelemetry() : array<string|int, mixed>`

2023-04-05 jj5 - the telemetry map will contain counters for the following:

- function: the functions which have been called and how many times.
- class: the classes which have been created and how many times.
- length: the encrypted data lengths which have been generated and how many times.

##### Return values

array<string|int, mixed> —

the telemetry map.

#### ReportCounters()

KickassCrypto.php : 263

2023-04-05 jj5 - this will report a list of counts to STDOUT.

`public static ReportCounters(array<string|int, mixed> $table) : void`

##### Parameters

$table : array<string|int, mixed>

  a key-value list; keys are strings, values are integers.

##### Return values

void —

#### ReportTelemetry()

KickassCrypto.php : 238

2023-04-05 jj5 - this function will print the telemetry data to STDOUT; it's suitable for use in a console.

`public static ReportTelemetry() : void`

##### Return values

void —

#### __construct()

KickassCrypto.php : 95

2023-03-30 jj5 - we throw exceptions from the constructor if our environment is invalid; if the constructor succeeds then encryption and decryption should also usually succeed later on.

`protected __construct() : mixed`

If encryption or decryption won't be able to succeed the constructor should throw.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

mixed —

#### convert_secret_to_passphrase()

KickassCrypto.php : 7791

2023-04-07 jj5 - converts a secret key to a passphrase by applying the hashing function.

`protected final convert_secret_to_passphrase(string $key) : string|false`

##### Parameters

$key : string

  the secret key to convert

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

string|false —

the generated passphrase or false on failure.

#### count_class()

KickassCrypto.php : 1551

2023-04-05 jj5 - will increment a class count metric.

`protected final count_class(string $class) : int`

##### Parameters

$class : string

  the name of the class.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

int —

the current count for the class.

#### count_function()

KickassCrypto.php : 1428

2023-04-05 jj5 - will increment a function count metric.

`protected final count_function(string $function) : int`

##### Parameters

$function : string

  the name of the function.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

int —

the current count for this function.

#### count_length()

KickassCrypto.php : 1674

2023-04-05 jj5 - will increment a length count metric.

`protected final count_length(int $length) : int`

##### Parameters

$length : int

  the length of the encrypted data.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

int —

the current count for the length.

#### count_this()

KickassCrypto.php : 1319

2023-04-05 jj5 - will count this instance.

`protected final count_this(string $caller) : int`

##### Parameters

$caller : string

  the name of the invoking function.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

int —

the count of instances made for this class.

#### data_decode()

KickassCrypto.php : 6617

2023-04-07 jj5 - decodes the encoded data using the nominated encoding.

`protected final data_decode(string $encoded_data[, string $data_encoding = KICKASS_CRYPTO_DATA_ENCODING_JSON ][, bool &$is_false = null ]) : mixed`

##### Parameters

$encoded_data : string

  the serialized data.

$data_encoding : string = KICKASS_CRYPTO_DATA_ENCODING_JSON

  the data encoding to use, can be JSON, PHPS, or text.

$is_false : bool = null

  set to true if the encoded data is deserialized to the boolean value false.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

mixed —

returns the decoded data (can be pretty much anything) or false on error; false can also be a valid return value, if it is then $is_false will be set.

#### data_encode()

KickassCrypto.php : 5933

2023-04-05 jj5 - serializes the data based on the data encoding in use; defers to a virtual do_data_encode() method.

`protected final data_encode(mixed $data, string $data_encoding) : string|false`

##### Parameters

$data : mixed

  input data, can be pretty much anything.

$data_encoding : string

  the data encoding to use, usually either KICKASS_CRYPTO_DATA_ENCODING_JSON for JSON encoding, KICKASS_CRYPTO_DATA_ENCODING_PHPS for PHP serialization (if it's enabled), or KICKASS_CRYPTO_DATA_ENCODING_TEXT.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

string|false —

the encoded string on success or false on failure.

#### decode_message()

KickassCrypto.php : 5398

2023-04-05 jj5 - decodes a message; defers to virtual do_decode_message().

`protected final decode_message(string $message, string &$data_encoding) : string|false`

##### Parameters

$message : string

  the encoded message.

$data_encoding : string

  a reference to the data encoding nominated in the message.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

string|false —

the decoded message or false on failure.

#### decrypt_string()

KickassCrypto.php : 5239

2023-04-05 jj5 - decrypts a binary string using the passphrase.

`protected final decrypt_string(string $binary, string $passphrase) : mixed`

##### Parameters

$binary : string

  the binary data to decrypt.

$passphrase : string

  the passphrase to use for decryption.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

mixed —

the decrypted string or false on error.

#### do_clear_error()

KickassCrypto.php : 749

2023-04-07 jj5 - clears the active list of errors.

`protected abstract do_clear_error() : void`

##### Return values

void —

#### do_convert_secret_to_passphrase()

KickassCrypto.php : 7857

2023-04-07 jj5 - the default implementation of the passphrase hashing logic.

`protected do_convert_secret_to_passphrase(string $key) : string|false`

##### Parameters

$key : string

  the secret key to hash.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

string|false —

the hashed string to use as the passphraser or false on error.

#### do_count_class()

KickassCrypto.php : 1613

2023-04-05 jj5 - by default will increment the count for this class metric; can be overridden by implementations.

`protected do_count_class(string $class) : int`

##### Parameters

$class : string

  the name of the class.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

int —

the current count for the class.

#### do_count_function()

KickassCrypto.php : 1490

2023-04-05 jj5 - by default will increment the counter for this function metric; can be overridden by implementations.

`protected do_count_function(string $function) : int`

##### Parameters

$function : string

  the name of the function.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

int —

the current count for the function.

#### do_count_length()

KickassCrypto.php : 1736

2023-04-05 jj5 - by default will increment the count for this length metric; can be overridden by implementations.

`protected do_count_length(int $length) : int`

##### Parameters

$length : int

  the length of the encrypted data.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

int —

the current count for the length.

#### do_count_this()

KickassCrypto.php : 1373

2023-04-05 jj5 - by default will count the caller function (should be the constructor) and this class instance; can be overridden by implementations.

`protected do_count_this(string $caller) : void`

##### Parameters

$caller : string

  the name of the invoking function.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

void —

#### do_data_decode()

KickassCrypto.php : 6706

2023-04-07 jj5 - provides the default implementation for data decoding, which provides support for decoding one of JSON, PHPS, or text.

`protected do_data_decode(string $encoded_data, string $data_encoding, bool &$is_false) : mixed`

##### Parameters

$encoded_data : string

  the serialized data.

$data_encoding : string

  the data encoding to use, can be JSON, PHPS, or text.

$is_false : bool

  set to true if the deserialized value is the boolean value false.

##### Tags

throws
  Exception

  may inject an exception for testing purposes, you can control this by passing $data_encoding === false and defining the KICKASS_CRYPTO_TEST_DATA_DECODE constant true.

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

mixed —

can return pretty much anything, will return false on error, but false can also be a valid return value.

#### do_data_encode()

KickassCrypto.php : 6019

2023-04-05 jj5 - by default serializes data based on the data encoding in use; can be overridden by implementations.

`protected do_data_encode(mixed $data, string $data_encoding) : string|false`

##### Parameters

$data : mixed

  input data, can be pretty much anything.

$data_encoding : string

  the data encoding to use, usually either KICKASS_CRYPTO_DATA_ENCODING_JSON for JSON encoding or KICKASS_CRYPTO_DATA_ENCODING_PHPS for PHP serialization (if it's enabled), or KICKASS_CRYPTO_DATA_ENCODING_TEXT.

##### Tags

throws
  Exception

  may be thrown for fault injection during testing, this shouldn't happen in production.

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

string|false —

the encoded string on success or false on failure.

#### do_decode_message()

KickassCrypto.php : 5487

2023-04-05 jj5 - by default will decode the message and determine the data encoding using; can be overridden by implementations.

`protected do_decode_message(string $message, string &$data_encoding) : string`

##### Parameters

$message : string

  the message to decode.

$data_encoding : string

  a reference to the data encoding extracted from the message.

##### Tags

staticvar

  int $max_data_length this is the maximum length supported by the data encoding format. Note that due to other limits this limit could never be reached.

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

string —

the decoded string or false on error.

#### do_decrypt()

KickassCrypto.php : 5044

2023-04-05 jj5 - by default handles the standard decryption process; can be overridden by implementations.

`protected do_decrypt(string $ciphertext) : mixed`

##### Parameters

$ciphertext : string

  the ciphertext to decrypt.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

mixed —

the decrypted and deserialized value on success, false otherwise.

#### do_decrypt_string()

KickassCrypto.php : 808

2023-04-05 jj5 - this will call the encryption library (either OpenSSL or Sodium by default) and do the actual decryption.

`protected abstract do_decrypt_string(string $binary, string $passphrase) : string|false`

##### Parameters

$binary : string

  the string to decrypt.

$passphrase : string

  the passphrase (in binary format, should be 32 bytes).

##### Return values

string|false —

returns the decrypted string on success or false on failure.

#### do_delay()

KickassCrypto.php : 5662

2023-04-05 jj5 - by default sleeps for a random amount of time between the minimum time given in nanoseconds and the maximum time also given in nanoseconds; can be overridden by implementations.

`protected do_delay(int $ns_min, int $ns_max) : mixed`

##### Parameters

$ns_min : int

  minimum delay in nanoseconds.

$ns_max : int

  maximum delay in nanoseconds.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

mixed —

#### do_encrypt()

KickassCrypto.php : 4415

2023-04-05 jj5 - by default encrypts the input value; can be overridden by implementations.

`protected do_encrypt(mixed $input) : string|false`

##### Parameters

$input : mixed

  the value to encrypt.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

string|false —

the ciphertext or false on failure.

#### do_encrypt_string()

KickassCrypto.php : 786

2023-04-05 jj5 - this will call the encryption library (either OpenSSL or Sodium by default) and do the actual encryption.

`protected abstract do_encrypt_string(string $plaintext, string $passphrase) : string|false`

##### Parameters

$plaintext : string

  the string to encrypt.

$passphrase : string

  the passphrase (in binary format, should be 32 bytes).

##### Return values

string|false —

returns the encrypted string on success or false on failure.

#### do_error()

KickassCrypto.php : 796

2023-04-05 jj5 - this function will register an error.

`protected abstract do_error(string $error) : void`

##### Parameters

$error : string

  the error which has occurred, should ordinarily be on of the KICKASS_CRYPTO_ERROR_* constants. The return value will be ignored.

##### Return values

void —

#### do_get_config_chunk_size()

KickassCrypto.php : 2424

2023-04-05 jj5 - by default returns the value of the CONFIG_ENCRYPTION_CHUNK_SIZE constant or the default value if CONFIG_ENCRYPTION_CHUNK_SIZE is not defined; can be overridden by implementations.

`protected do_get_config_chunk_size(int $default) : int`

##### Parameters

$default : int

  the default chunk size.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

int —

the chunk size.

#### do_get_config_chunk_size_max()

KickassCrypto.php : 2550

2023-04-05 jj5 - by default returns the value of the CONFIG_ENCRYPTION_CHUNK_SIZE_MAX constant or the default value if CONFIG_ENCRYPTION_CHUNK_SIZE_MAX is not defined; can be overridden by implementations.

`protected do_get_config_chunk_size_max(int $default) : int`

##### Parameters

$default : int

  the default maximum chunk size.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

int —

the maximum chunk size.

#### do_get_config_data_encoding()

KickassCrypto.php : 2813

2023-04-05 jj5 - by default returns the value of the CONFIG_ENCRYPTION_DATA_ENCODING constant or the default value if CONFIG_ENCRYPTION_DATA_ENCODING is not defined; can be overridden by implementations.

`protected do_get_config_data_encoding(string $default) : string`

##### Parameters

$default : string

  the default data format.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

string —

the data format.

#### do_get_config_data_length_max()

KickassCrypto.php : 2677

2023-04-05 jj5 - by default returns the value of the CONFIG_ENCRYPTION_DATA_LENGTH_MAX constant or the default value if CONFIG_ENCRYPTION_DATA_LENGTH_MAX is not defined; can be overridden by implementations.

`protected do_get_config_data_length_max(int $default) : int`

##### Parameters

$default : int

  the default maximum data length.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

int —

the maximum data length.

#### do_get_config_false_enable()

KickassCrypto.php : 3321

2023-04-05 jj5 - by default returns the value of the CONFIG_ENCRYPTION_FALSE_ENABLE constant of the default value if CONFIG_ENCRYPTION_FALSE_ENABLE is not defined; can be overridden by implementations.

`protected do_get_config_false_enable(bool $default) : bool`

##### Parameters

$default : bool

  the value to use if the config option is not defined.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

bool —

true if the boolean value false can be encrypted, false otherwise.

#### do_get_config_json_decode_options()

KickassCrypto.php : 3067

2023-04-05 jj5 - by default returns the value of the CONFIG_ENCRYPTION_JSON_DECODE_OPTIONS constant or the default value if CONFIG_ENCRYPTION_JSON_DECODE_OPTIONS is not defined; can be overridden by implementations.

`protected do_get_config_json_decode_options(int $default) : int`

##### Parameters

$default : int

  the value to use if the config option is not defined.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

int —

the JSON decoding options.

#### do_get_config_json_encode_options()

KickassCrypto.php : 2940

2023-04-05 jj5 - by default returns the value of the CONFIG_ENCRYPTION_JSON_ENCODE_OPTIONS constant or the default value if CONFIG_ENCRYPTION_JSON_ENCODE_OPTIONS is not defined; can be overridden by implementations.

`protected do_get_config_json_encode_options(int $default) : int`

##### Parameters

$default : int

  the default JSON encoding options.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

int —

the JSON encoding options.

#### do_get_config_phps_enable()

KickassCrypto.php : 3194

2023-04-05 jj5 - by default returns the value of the CONFIG_ENCRYPTION_PHPS_ENABLE constant or the default value if CONFIG_ENCRYPTION_PHPS_ENABLE is not defined; can be overridden by implementations.

`protected do_get_config_phps_enable(bool $default) : bool`

##### Parameters

$default : bool

  the value to use if the config option is not defined.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

bool —

true if PHPS serialization and deserialization is enabled, false otherwise.

#### do_get_const()

KickassCrypto.php : 3443

2023-04-05 jj5 - by default returns the value of the constant, or returns the default value if the constant is not defined; can be overridden by implementations.

`protected do_get_const(string $const, mixed $default) : mixed`

##### Parameters

$const : string

  the name of the constant.

$default : mixed

  the value to return if the constant is not defined.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

mixed —

the value of the constant or the default value if the constant is not defined.

#### do_get_const_data_format()

KickassCrypto.php : 774

2023-04-05 jj5 - the data format code; this will be prefixed to the base64 encoded ciphertext so we can determine which service we need to decrypt values.

`protected abstract do_get_const_data_format() : string`

##### Return values

string —

#### do_get_const_key_hash()

KickassCrypto.php : 2060

2023-04-05 jj5 - by default returns the value of the KICKASS_CRYPTO_KEY_HASH constant; can be overridden by implementations.

`protected do_get_const_key_hash() : string`

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

string —

the name of the hash algorithm.

#### do_get_const_key_length_min()

KickassCrypto.php : 2179

2023-04-05 jj5 - by default returns the value of the KICKASS_CRYPTO_KEY_LENGTH_MIN constant; can be overridden by implementations.

`protected do_get_const_key_length_min() : int`

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

int —

the minimum length of a secret key.

#### do_get_const_passphrase_length_min()

KickassCrypto.php : 2298

2023-04-05 jj5 - by default returns the value of the KICKASS_CRYPTO_PASSPHRASE_LENGTH_MIN constant; can be overridden by implementations.

`protected do_get_const_passphrase_length_min() : int`

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

int —

the minimum length of a passphrase.

#### do_get_data_encoding()

KickassCrypto.php : 4902

2023-04-05 jj5 - by default gets the data encoding from the config option as returned from get_config_data_encoding().

`protected do_get_data_encoding() : string`

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

string —

the data encoding.

#### do_get_delay()

KickassCrypto.php : 8147

2023-04-07 jj5 - provides the default implementation of the delay calculations; can be overridden by implementations.

`protected do_get_delay(int $ns_min, int $ns_max, int &$seconds, int &$nanoseconds) : bool`

##### Parameters

$ns_min : int

  the total number of nanoseconds, minimum.

$ns_max : int

  the total number of nanoseconds, maximum.

$seconds : int

  the number of whole seconds to delay.

$nanoseconds : int

  the extra number of nanoseconds to delay beyond the number of seconds.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

bool —

true on success or false on failure.

#### do_get_encryption_passphrase()

KickassCrypto.php : 3641

2023-04-05 jj5 - by default returns the first passphrase from the passphrase list; can be overridden by implementations.

`protected do_get_encryption_passphrase() : string|null`

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

string|null —

the passphrase or null if none.

#### do_get_error()

KickassCrypto.php : 742

2023-04-07 jj5 - gets the most recent error, it's a string, or null if no error.

`protected abstract do_get_error() : string|null`

##### Return values

string|null —

the most recent error or null if no error.

#### do_get_error_list()

KickassCrypto.php : 735

2023-04-07 jj5 - gets the list of errors, it's a list of strings, it can be empty, in fact it's best if it is!

`protected abstract do_get_error_list() : array<string|int, mixed>`

##### Return values

array<string|int, mixed> —

the list of errors, or an empty array if none.

#### do_get_padding()

KickassCrypto.php : 7978

2023-04-07 jj5 - does the actual work of generating the random padding; can be overridden by implementations.

`protected do_get_padding(int $length) : string|false`

##### Parameters

$length : int

  the length of the padding to generate.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

string|false —

the padding on success or false on failure.

#### do_get_passphrase_list()

KickassCrypto.php : 766

2023-04-05 jj5 - the list of passphrases; the passphrases are generated by using the secret key hashing function on the secret keys defined in the config file.

`protected abstract do_get_passphrase_list() : array<string|int, mixed>`

##### Return values

array<string|int, mixed> —

#### do_handle()

KickassCrypto.php : 900

2023-04-01 jj5 - implementations can decide what to do when errors are handled; by default we write a log entry; can be overridden by implementations.

`protected do_handle(Throwable $ex, string $file, int $line, string $function) : void`

##### Parameters

$ex : Throwable

  the exception which was caught.

$file : string

  the path to the file that caught the exception.

$line : int

  the line in the file where the caught exception was reported.

$function : string

  the function in which the exception was caught.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

void —

#### do_ignore()

KickassCrypto.php : 1122

2023-04-01 jj5 - implementations can decide what to do when errors are ignored; by default we write a log entry; can be overridden by implementations.

`protected do_ignore(Throwable $ex, string $file, int $line, string $function) : void`

##### Parameters

$ex : Throwable

  the exception which was caught and will be ignored.

$file : string

  the path to the file that caught the exception.

$line : int

  the line in the file where the caught exception was reported.

$function : string

  the function in which the exception was caught.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

void —

#### do_increment_counter()

KickassCrypto.php : 1872

2023-04-05 jj5 - by default will increment the value for a key in an array; will initialize to zero if missing; can be overridden by implementations.

`protected do_increment_counter(array<string|int, mixed> &$array, string|int $key) : int`

##### Parameters

$array : array<string|int, mixed>

  a reference to the array to operate on.

$key : string|int

  the key to operate on.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

int —

the current count.

#### do_is_cli()

KickassCrypto.php : 3760

2023-04-05 jj5 - by default checks to see if php_sapi_name() === 'cli'; can be overridden by implementations.

`protected do_is_cli() : bool`

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

bool —

true if running from the command-line, false otherwise.

#### do_is_debug()

KickassCrypto.php : 3879

2023-04-05 jj5 - by default checks to see if the DEBUG constant is defined and true; can be overridden by implementations.

`protected do_is_debug() : bool`

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

bool —

true if running in DEBUG mode, false otherwise.

#### do_is_valid_base64()

KickassCrypto.php : 4358

2023-04-05 jj5 - by default checks to make sure the input is a non-empty string and then validates it with the KICKASS_CRYPTO_REGEX_BASE64 regular expression; can be overridden by implementations.

`protected do_is_valid_base64(string $input) : bool`

##### Parameters

$input : string

  supposedly base64 encoded value.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

bool —

true if value is in valid base64 format, false otherwise.

#### do_is_valid_config()

KickassCrypto.php : 758

2023-03-30 jj5 - implementations need to define what a valid configuration is.

`protected abstract do_is_valid_config(string|null &$problem) : bool`

##### Parameters

$problem : string|null

  a description of the problem if invalid, null otherwisej.

##### Return values

bool —

#### do_is_valid_data_encoding()

KickassCrypto.php : 4764

2023-04-05 jj5 - by default checks that the data encoding is one of the two supported data encodings; can be overridden by implementations.

`protected do_is_valid_data_encoding(string $data_encoding) : bool`

2023-04-05 jj5 - the two supported data encodings are:

- KICKASS_CRYPTO_DATA_ENCODING_JSON
- KICKASS_CRYPTO_DATA_ENCODING_PHPS
- KICKASS_CRYPTO_DATA_ENCODING_TEXT

Note that the PHPS data encoding is only a valid and supported data encoding if get_config_phps_enable() is true.

##### Parameters

$data_encoding : string

  the data encoding.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

bool —

true if the data encoding is a valid supported value, false otherwise.

#### do_is_valid_passphrase()

KickassCrypto.php : 4239

2023-04-06 jj5 - by default checks the string length; can be overridden by implementations.

`protected do_is_valid_passphrase(mixed $passphrase) : bool`

##### Parameters

$passphrase : mixed

  a passphrase to validate.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

bool —

true on valid; false otherwise.

#### do_is_valid_secret()

KickassCrypto.php : 4104

2023-04-05 jj5 - my default checks that the secret key is a string and meets the minimum length requirements; this function can be overridden by implementations.

`protected do_is_valid_secret(string $secret) : bool`

##### Parameters

$secret : string

  the secret key

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

bool —

true if the secret is valid, false otherwise.

#### do_json_decode()

KickassCrypto.php : 6891

2023-04-07 jj5 - does the actual work of JSON decoding by calling the PHP function via its wrapper.

`protected do_json_decode(string $input, bool &$is_false) : mixed`

##### Parameters

$input : string

  the JSON to decode.

$is_false : bool

  set to true if the JSON decodes to the boolean value false.

##### Tags

staticvar

  type $false_json the JSON for the boolean value false encoded as JSON, this is used to determine if the JSON represents the value false or not; this value is calculated only once and uses the JSON encoding options that were current on the instance which did the initial encoding.

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

mixed —

returns the decoded value on success or the value false on failure.

#### do_json_encode()

KickassCrypto.php : 6191

2023-04-05 jj5 - by default encodes the input as JSON using the JSON encoding options read from the config file; can be overridden by implementations.

`protected do_json_encode(string $input) : mixed`

##### Parameters

$input : string

  JSON input.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

mixed —

returns the decoded JSON value or false on failure.

#### do_log_error()

KickassCrypto.php : 8289

2023-04-07 jj5 - provides a default implementation for log writing; can be overridden by implementations.

`protected do_log_error(string $message, string $file, int $line, string $function) : bool`

##### Parameters

$message : string

  the message to log.

$file : string

  the path of the file writing the log entry.

$line : int

  the line in the file writing the log entry.

$function : string

  the name of the function writing the log entry.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

bool —

true on success or false on failure.

#### do_message_decode()

KickassCrypto.php : 7594

2023-04-07 jj5 - does the actual work of message decoding; can be overridden by implementations.

`protected do_message_decode(string $encoded) : string|false`

##### Parameters

$encoded : string

  the encoded message.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

string|false —

the decoded message or false on failure.

#### do_message_encode()

KickassCrypto.php : 7427

2023-04-07 jj5 - does the actual work of message encoding; can be overridden by implementations.

`protected do_message_encode(string $binary) : string|false`

##### Parameters

$binary : string

  the binary data to encode.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

string|false —

the encoded string on success or false on failure.

#### do_notify()

KickassCrypto.php : 1011

2023-04-01 jj5 - implementations can decide what to do when errors are notified; by default we write a log entry; can be overridden by implementations.

`protected do_notify(Throwable $ex, string $file, int $line, string $function) : void`

##### Parameters

$ex : Throwable

  the exception which was caught and will be rethrown.

$file : string

  the path to the file that caught the exception.

$line : int

  the line in the file where the caught exception was reported.

$function : string

  the function in which the exception was caught.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

void —

#### do_parse_binary()

KickassCrypto.php : 818

2023-04-05 jj5 - this function extracts the initialization vector, ciphertext, and tag from the concatenated binary data; not all service define all pieces; the OpenSSL library will use all three; the Sodium library uses the initialization vector for its nonce and it does not use the tag.

`protected abstract do_parse_binary(mixed $binary, mixed &$iv, mixed &$ciphertext, mixed &$tag) : bool`

##### Parameters

$binary : mixed
$iv : mixed
$ciphertext : mixed
$tag : mixed

##### Return values

bool —

returns true on success; false on failure.

#### do_php_base64_decode()

KICKASS_WRAPPER_PHP.php : 92
`protected do_php_base64_decode(mixed $input, mixed $strict) : mixed`

##### Parameters

$input : mixed
$strict : mixed

##### Return values

mixed —

#### do_php_base64_encode()

KICKASS_WRAPPER_PHP.php : 70
`protected do_php_base64_encode(mixed $input) : mixed`

##### Parameters

$input : mixed

##### Return values

mixed —

#### do_php_json_decode()

KICKASS_WRAPPER_PHP.php : 138
`protected do_php_json_decode(mixed $json, mixed $associative, mixed $depth, mixed $flags) : mixed`

##### Parameters

$json : mixed
$associative : mixed
$depth : mixed
$flags : mixed

##### Return values

mixed —

#### do_php_json_encode()

KICKASS_WRAPPER_PHP.php : 114
`protected do_php_json_encode(mixed $value, mixed $flags, mixed $depth) : mixed`

##### Parameters

$value : mixed
$flags : mixed
$depth : mixed

##### Return values

mixed —

#### do_php_json_last_error()

KICKASS_WRAPPER_PHP.php : 160
`protected do_php_json_last_error() : mixed`

##### Return values

mixed —

#### do_php_random_bytes()

KICKASS_WRAPPER_PHP.php : 270
`protected do_php_random_bytes(mixed $length) : mixed`

##### Parameters

$length : mixed

##### Return values

mixed —

#### do_php_random_int()

KICKASS_WRAPPER_PHP.php : 248
`protected do_php_random_int(mixed $min, mixed $max) : mixed`

##### Parameters

$min : mixed
$max : mixed

##### Return values

mixed —

#### do_php_sapi_name()

KICKASS_WRAPPER_PHP.php : 314
`protected do_php_sapi_name() : mixed`

##### Return values

mixed —

#### do_php_serialize()

KICKASS_WRAPPER_PHP.php : 182
`protected do_php_serialize(mixed $value) : mixed`

##### Parameters

$value : mixed

##### Return values

mixed —

#### do_php_strval()

KICKASS_WRAPPER_PHP.php : 226
`protected do_php_strval(mixed $value) : mixed`

##### Parameters

$value : mixed

##### Return values

mixed —

#### do_php_time_nanosleep()

KICKASS_WRAPPER_PHP.php : 292
`protected do_php_time_nanosleep(mixed $seconds, mixed $nanoseconds) : mixed`

##### Parameters

$seconds : mixed
$nanoseconds : mixed

##### Return values

mixed —

#### do_php_unserialize()

KICKASS_WRAPPER_PHP.php : 204
`protected do_php_unserialize(mixed $value) : mixed`

##### Parameters

$value : mixed

##### Return values

mixed —

#### do_phps_decode()

KickassCrypto.php : 7081

2023-04-07 jj5 - does the actual work of PHP deserialization by deferring to the implementation on the PHP wrapper.

`protected do_phps_decode(string $input, bool &$is_false) : mixed`

##### Parameters

$input : string

  the serialized data to deserialize.

$is_false : bool

  set to true if the deserialized value is the boolean value false.

##### Tags

staticvar

  type $false_phps keeps a static copy of what the serialized boolean value false looks like, this is used to determine if the input data is the serialized value false or not.

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

mixed —

the deserialized data or false on error.

#### do_phps_encode()

KickassCrypto.php : 6371

2023-04-07 jj5 - does the actual work of PHP serialization; can be overridden by implementers; by default calls the PHP serialize() function via its wrapper.

`protected do_phps_encode(mixed $input) : string|false`

##### Parameters

$input : mixed

  can be pretty much anything.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

string|false —

the serialized value on success or false on failure.

#### do_report_emergency_delay()

KickassCrypto.php : 5872

2023-04-05 jj5 - by default writes a message to the error log; can be overridden by implementations.

`protected do_report_emergency_delay(string $type, string $file, int $line, string $function) : void`

##### Parameters

$type : string

  the type of delay, could be 'nanosleep' or 'microsleep'.

$file : string

  the file that reported the emergecny delay.

$line : int

  the line in the file where the emergency delay was reported.

$function : string

  the function from which the emergency delay was reported.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

void —

#### do_text_decode()

KickassCrypto.php : 7266

2023-04-07 jj5 - does the actual work of text deserialization by deferring to the implementation on the PHP wrapper.

`protected do_text_decode(string $input, bool &$is_false) : mixed`

##### Parameters

$input : string

  the serialized data to deserialize.

$is_false : bool

  set to false, the value false can't be represent.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

mixed —

the deserialized data or false on error.

#### do_text_encode()

KickassCrypto.php : 6534

2023-04-07 jj5 - does the actual work of text serialization; can be overridden by implementers; by default calls the PHP strval() function via its wrapper.

`protected do_text_encode(mixed $input) : string|false`

##### Parameters

$input : mixed

  something that is a string or can be turned into a string.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

string|false —

the serialized value on success or false on failure.

#### do_throw()

KickassCrypto.php : 1210

2023-04-05 jj5 - by default this finds the message for the given exception code and then throws an exception with the relevant code and message; can be overridden by implementations.

`protected do_throw(int $code, mixed $data, Throwable $previous) : mixed`

##### Parameters

$code : int

  the exception code is one of the KICKASS_CRYPTO_EXCEPTION_* constants.

$data : mixed

  the data to associate with the exception, if any.

$previous : Throwable

  the previous exception, if any.

##### Tags

throws
  KickassCryptoException

  after finding the relevant details.

##### Return values

mixed —

#### emergency_delay()

KickassCrypto.php : 5750

2023-04-05 jj5 - does an emergency delay; this doesn't give the caller any option to interfere so the emergency delay should run reliably if it's necessary.

`protected final emergency_delay() : void`

##### Tags

throws
  Exception

  may throw an exception if set up for error injection, this should only be done during testing.

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

void —

#### encrypt_string()

KickassCrypto.php : 4966

2023-04-05 jj5 - encrypts a plaintext string using the passphrase; defers to do_encrypt_string().

`protected final encrypt_string(string $plaintext, string $passphrase) : string|false`

##### Parameters

$plaintext : string

  the plaintext to encrypt.

$passphrase : string

  the passphrase to use for encryption.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

string|false —

the ciphertext on success or false on error.

#### enter()

KickassCrypto.php : 8364

2023-04-07 jj5 - registers when a function gets called so as to track the depth of a function on the call stack.

`protected enter(string $function) : void`

##### Parameters

$function : string

  the name of the function.

##### Tags

throws
  KickassCryptoException

##### Return values

void —

#### error()

KickassCrypto.php : 1249

2023-04-05 jj5 - registers an error; if this is the first error a random delay is injected as a timing attack mitigation.

`protected final error(string $function, string $error[, mixed $data = null ]) : bool`

##### Parameters

$function : string

  the name of the function registering the error.

$error : string

  the error description, usually one of the KICKASS_CRYPTO_ERROR_* constants.

$data : mixed = null

  any error assoicated with the error; this could be sensitive, do not log without scrubbing or expose without thought.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

bool —

always false.

#### get_config_chunk_size()

KickassCrypto.php : 2359

2023-04-05 jj5 - gets the chunk size, it's used for padding encrypted messages.

`protected final get_config_chunk_size([int $default = KICKASS_CRYPTO_DEFAULT_CHUNK_SIZE ]) : int`

##### Parameters

$default : int = KICKASS_CRYPTO_DEFAULT_CHUNK_SIZE

  the value to use if the config option is not defined.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

int —

the chunk size.

#### get_config_chunk_size_max()

KickassCrypto.php : 2485

2023-04-05 jj5 - gets the maximum chunk size, it's used for validating the chunk size.

`protected final get_config_chunk_size_max([int $default = KICKASS_CRYPTO_DEFAULT_CHUNK_SIZE_MAX ]) : int`

##### Parameters

$default : int = KICKASS_CRYPTO_DEFAULT_CHUNK_SIZE_MAX

  the value to use if the config option is not defined.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

int —

the maximum chunk size.

#### get_config_data_encoding()

KickassCrypto.php : 2748

2023-04-05 jj5 - gets the data encoding.

`protected final get_config_data_encoding([string $default = KICKASS_CRYPTO_DEFAULT_DATA_ENCODING ]) : string`

2023-04-05 jj5 - data formats which are supported directly are:

- KICKASS_CRYPTO_DATA_ENCODING_JSON
- KICKASS_CRYPTO_DATA_ENCODING_PHPS
- KICKASS_CRYPTO_DATA_ENCODING_TEXT

2023-04-05 jj5 - implementations can define their own data formats. Data format codes must be ASCII values make from capital letters and numbers, see is_valid_data_format() for the gory details.

##### Parameters

$default : string = KICKASS_CRYPTO_DEFAULT_DATA_ENCODING

  the value to use if the config option is not defined.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

string —

the data encoding.

#### get_config_data_length_max()

KickassCrypto.php : 2612

2023-04-05 jj5 - gets the maximum supported data length, it's used for validating the encoded data.

`protected final get_config_data_length_max([int $default = KICKASS_CRYPTO_DEFAULT_DATA_LENGTH_MAX ]) : int`

##### Parameters

$default : int = KICKASS_CRYPTO_DEFAULT_DATA_LENGTH_MAX

  the value to use if the config option is not defined.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

int —

the maximum supported data length.

#### get_config_false_enable()

KickassCrypto.php : 3256

2023-04-05 jj5 - gets a boolean value indicating whether the boolean value false can be encrypted or not.

`protected final get_config_false_enable([bool $default = KICKASS_CRYPTO_DEFAULT_FALSE_ENABLE ]) : bool`

##### Parameters

$default : bool = KICKASS_CRYPTO_DEFAULT_FALSE_ENABLE

  the value to use if the config option is not defined.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

bool —

true if the boolean value false can be encrypted, false otherwise.

#### get_config_json_decode_options()

KickassCrypto.php : 3002

2023-04-05 jj5 - gets the JSON decoding options which will be passed to the PHP json_decode() function.

`protected final get_config_json_decode_options([int $default = KICKASS_CRYPTO_DEFAULT_JSON_DECODE_OPTIONS ]) : int`

##### Parameters

$default : int = KICKASS_CRYPTO_DEFAULT_JSON_DECODE_OPTIONS

  the value to use if the config option is not defined.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

int —

the JSON decoding options.

#### get_config_json_encode_options()

KickassCrypto.php : 2875

2023-04-05 jj5 - gets the JSON encoding options which will be passed to the PHP json_encode() function.

`protected final get_config_json_encode_options([int $default = KICKASS_CRYPTO_DEFAULT_JSON_ENCODE_OPTIONS ]) : int`

##### Parameters

$default : int = KICKASS_CRYPTO_DEFAULT_JSON_ENCODE_OPTIONS

  the value to use if the config option is not defined.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

int —

the JSON encoding options.

#### get_config_phps_enable()

KickassCrypto.php : 3129

2023-04-05 jj5 - gets a boolean value indicating whether PHPS serialization and deserialization is enabled or not.

`protected final get_config_phps_enable([bool $default = KICKASS_CRYPTO_DEFAULT_PHPS_ENABLE ]) : bool`

##### Parameters

$default : bool = KICKASS_CRYPTO_DEFAULT_PHPS_ENABLE

  the value to use if the config option is not defined.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

bool —

true if PHPS serialization and deserialization is enabled, false otherwise.

#### get_const()

KickassCrypto.php : 3385

2023-04-05 jj5 - gets a constant value, or returns the default value if the constant is not defined.

`protected final get_const(string $const[, mixed $default = false ]) : mixed`

##### Parameters

$const : string

  the name of the constant.

$default : mixed = false

  the value to return if the constant is not defined.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

mixed —

the constant value or the default value if the constant is not defined.

#### get_const_data_format()

KickassCrypto.php : 1941

2023-04-05 jj5 - gets the data format constant; defers to abstract method for implementation.

`protected final get_const_data_format() : string`

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

string —

the data format constant.

#### get_const_key_hash()

KickassCrypto.php : 2000

2023-04-05 jj5 - gets the name of the hashing algorithm to use for secret key hashing.

`protected final get_const_key_hash() : string`

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

string —

the name of the PHP hashing algorithm.

#### get_const_key_length_min()

KickassCrypto.php : 2119

2023-04-05 jj5 - gets the minimum length of a secret key.

`protected final get_const_key_length_min() : int`

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

int —

the minimum length of a secret key.

#### get_const_passphrase_length_min()

KickassCrypto.php : 2238

2023-04-05 jj5 - gets the minimum length of a passphrase.

`protected final get_const_passphrase_length_min() : int`

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

int —

the minimum length of a passphrase.

#### get_data_encoding()

KickassCrypto.php : 4842

2023-04-05 jj5 - gets the data encoding; defers to virtual do_get_data_encoding().

`protected final get_data_encoding() : string`

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

string —

the data encoding.

#### get_data_format()

KickassCrypto.php : 7713

2023-04-07 jj5 - gets the data format; the data format can be "KA0" for OpenSSL implementations and "KAS0" for Sodium implementations; if not the official implementation then the string 'X' is prepended to the data format.

`protected final get_data_format() : string|false`

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

string|false —

the data format string or false on error.

#### get_delay()

KickassCrypto.php : 8063

2023-04-07 jj5 - calculates the seconds and extra nanoseconds which will be needed by the delay implementation; this function defers to do_get_delay() which can be overridden by implementations.

`protected final get_delay(int $ns_min, int $ns_max, int &$seconds, int &$nanoseconds) : bool`

##### Parameters

$ns_min : int

  the total number of nanoseconds, minimum.

$ns_max : int

  the total number of nanoseconds, maximum.

$seconds : int

  the number of whole seconds to delay.

$nanoseconds : int

  the extra number of nanoseconds to delay beyond the number of seconds.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

bool —

true on success or false on failure.

#### get_encryption_passphrase()

KickassCrypto.php : 3581

2023-04-05 jj5 - returns the passphrase to use for encryption or null if it's missing.

`protected final get_encryption_passphrase() : string`

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

string —

the encryption passphrase or null.

#### get_padding()

KickassCrypto.php : 7916

2023-04-07 jj5 - gets the string to use as padding; it's usually just a string of random bytes.

`protected final get_padding(int $length) : string|false`

##### Parameters

$length : int

  the length of the random padding to generate.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

string|false —

the padding string to use or false on error.

#### get_passphrase_list()

KickassCrypto.php : 3496

2023-04-05 jj5 - returns the list of passphrases; defers to abstract implementation.

`protected final get_passphrase_list() : array<string|int, mixed>`

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

array<string|int, mixed> —

a list of strings to use as passphrases.

#### handle()

KickassCrypto.php : 833

2023-04-01 jj5 - the point of handle() is simply to notify that an exception has been caught and "handled"; sometimes "handling" the exception is tantamount to ignoring it, so we call this method that we may make some noise about it (during debugging, usually). See do_handle() for the rest of the story.

`protected final handle(mixed $ex, mixed $file, mixed $line, mixed $function) : void`

It's very important that this function does not throw exceptions, except for AssertionError, which is allowed.

##### Parameters

$ex : mixed
$file : mixed
$line : mixed
$function : mixed

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

void —

#### ignore()

KickassCrypto.php : 1063

2023-04-06 jj5 - the point of ignore() is simply to notify that an exception has been caught and it will be ignored.

`protected final ignore(mixed $ex, mixed $file, mixed $line, mixed $function) : void`

It's very important that this function does not throw exceptions, except for AssertionError, which is allowed. This function is the safest of all.

##### Parameters

$ex : mixed
$file : mixed
$line : mixed
$function : mixed

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

void —

#### increment_counter()

KickassCrypto.php : 1800

2023-04-05 jj5 - will increment the value for a key in an array; will initialize to zero if missing.

`protected final increment_counter(array<string|int, mixed> &$array, string|int $key) : int`

##### Parameters

$array : array<string|int, mixed>

  a reference to the array to operate on.

$key : string|int

  the key to operate on.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

int —

the current count.

#### is_cli()

KickassCrypto.php : 3700

2023-04-05 jj5 - reports if the program is running from the command-line.

`protected final is_cli() : bool`

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

bool —

true if running from the command-line, false otherwise.

#### is_debug()

KickassCrypto.php : 3819

2023-04-05 jj5 - checks to see if the program is running in DEBUG mode.

`protected final is_debug() : bool`

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

bool —

true if running in DEBUG mode, false otherwise.

#### is_valid_base64()

KickassCrypto.php : 4295

2023-04-05 jj5 - checks the input is in valid base64 format; defers to virtual do_is_valid_base64().

`protected final is_valid_base64(string $input) : bool`

##### Parameters

$input : string

  the value which should be in base64 format.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

bool —

true if the input is in base64 format, false otherwise.

#### is_valid_config()

KickassCrypto.php : 3941

2023-04-05 jj5 - checks to see if the environment configuration is valid; this function defers to the abstract method do_is_valid_config().

`protected final is_valid_config([string|null &$problem = null ]) : bool`

##### Parameters

$problem : string|null = null

  a reference to the problem, if any.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

bool —

true if the config is valid, false otherwise.

#### is_valid_data_encoding()

KickassCrypto.php : 4688

2023-04-05 jj5 - checks to see if the data encoding is a valid supported encoding; defers to the virtual do_is_valid_encoding() method.

`protected final is_valid_data_encoding(string $data_encoding) : bool`

##### Parameters

$data_encoding : string

  the data encoding to validate.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

bool —

true if the data encoding is value, false otherwise.

#### is_valid_data_format()

KickassCrypto.php : 4617

2023-04-05 jj5 - checks to see if the data format is valid; this behavior cannot be overridden by implementations.

`protected final is_valid_data_format(string $data_format) : bool`

##### Parameters

$data_format : string

  the data format string.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

bool —

true if the data format is valid, false otherwise.

#### is_valid_passphrase()

KickassCrypto.php : 4160

2023-04-06 jj5 - checks to see if a passphrase is valid; this function defers to do_is_valid_passphrase();

`protected final is_valid_passphrase(string $passphrase) : bool`

##### Parameters

$passphrase : string

  the passphrase key

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

bool —

true if the passphrase key is valid, false otherwise.

#### is_valid_secret()

KickassCrypto.php : 4027

2023-04-05 jj5 - checks to see if a secret is valid; this function defers to do_is_valid_secret();

`protected final is_valid_secret(string $secret) : bool`

##### Parameters

$secret : string

  the secret key

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

bool —

true if the secret key is valid, false otherwise.

#### json_decode()

KickassCrypto.php : 6808

2023-04-07 jj5 - deserialized JSON data.

`protected final json_decode(string $input, bool &$is_false) : mixed`

##### Parameters

$input : string

  the JSON.

$is_false : bool

  set to true if the JSON deserializes to the boolean value false.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

mixed —

can return pretty much anything, will return false on failure but false can be a valid return value.

#### json_encode()

KickassCrypto.php : 6113

2023-04-05 jj5 - encodes a valud as JSON; defers to do_json_encode() for implementation.

`protected final json_encode(mixed $input) : string|false`

##### Parameters

$input : mixed

  input can be almost anything.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

string|false —

the JSON string on success, false on failure.

#### leave()

KickassCrypto.php : 8410

2023-04-07 jj5 - registers when a runction returns so as to track the depth of a function on the call stack.

`protected leave(string $function) : mixed`

##### Parameters

$function : string

  the name of the function.

##### Return values

mixed —

#### log_error()

KickassCrypto.php : 8229

2023-04-07 jj5 - logs an error.

`protected final log_error(string $message, string $file, int $line, string $function) : bool`

##### Parameters

$message : string

  the message to log.

$file : string

  the path of the file writing the log entry.

$line : int

  the line in the file writing the log entry.

$function : string

  the name of the function writing the log entry.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

bool —

true on success or false on failure.

#### message_decode()

KickassCrypto.php : 7516

2023-04-07 jj5 - decodes a message into binary.

`protected final message_decode(string $encoded) : string|false`

##### Parameters

$encoded : string

  the encoded message.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

string|false —

the decoded message or false on failure.

#### message_encode()

KickassCrypto.php : 7349

2023-04-07 jj5 - encodes a message.

`protected final message_encode(string $binary) : string|false`

##### Parameters

$binary : string

  the binary data to encode.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

string|false —

the encoded value on success or false on failure.

#### notify()

KickassCrypto.php : 954

2023-04-01 jj5 - the point of notify() is simply to notify that an exception has been caught but it's going to be rethrown; it's best if this function doesn't throw an exception but it shouldn't be a huge problem if it does, the caller will throw when this function returns anyway.

`protected final notify(mixed $ex, mixed $file, mixed $line, mixed $function) : void`

##### Parameters

$ex : mixed
$file : mixed
$line : mixed
$function : mixed

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

void —

#### parse_binary()

KickassCrypto.php : 5307

2023-04-05 jj5 - parses the binary message into its fixed length components.

`protected final parse_binary(string $binary, string &$iv, string &$ciphertext, string &$tag) : bool`

##### Parameters

$binary : string

  the binary message.

$iv : string

  the initialization vector for OpenSLL or the nonce for Sodium.

$ciphertext : string

  the ciphertext.

$tag : string

  the tag, only provided by OpenSSL, false for Sodium.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

bool —

true on success, false otherwise.

#### php_base64_decode()

KICKASS_WRAPPER_PHP.php : 76
`protected final php_base64_decode(mixed $input, mixed $strict) : mixed`

##### Parameters

$input : mixed
$strict : mixed

##### Return values

mixed —

#### php_base64_encode()

KICKASS_WRAPPER_PHP.php : 54
`protected final php_base64_encode(mixed $input) : mixed`

##### Parameters

$input : mixed

##### Return values

mixed —

#### php_json_decode()

KICKASS_WRAPPER_PHP.php : 120
`protected final php_json_decode(mixed $json, mixed $associative, mixed $depth, mixed $flags) : mixed`

##### Parameters

$json : mixed
$associative : mixed
$depth : mixed
$flags : mixed

##### Return values

mixed —

#### php_json_encode()

KICKASS_WRAPPER_PHP.php : 98
`protected final php_json_encode(mixed $value, mixed $flags[, mixed $depth = 512 ]) : mixed`

##### Parameters

$value : mixed
$flags : mixed
$depth : mixed = 512

##### Return values

mixed —

#### php_json_last_error()

KICKASS_WRAPPER_PHP.php : 144
`protected final php_json_last_error() : mixed`

##### Return values

mixed —

#### php_random_bytes()

KICKASS_WRAPPER_PHP.php : 254
`protected final php_random_bytes(mixed $length) : mixed`

##### Parameters

$length : mixed

##### Return values

mixed —

#### php_random_int()

KICKASS_WRAPPER_PHP.php : 232
`protected final php_random_int(mixed $min, mixed $max) : mixed`

##### Parameters

$min : mixed
$max : mixed

##### Return values

mixed —

#### php_sapi_name()

KICKASS_WRAPPER_PHP.php : 298
`protected final php_sapi_name() : mixed`

##### Return values

mixed —

#### php_serialize()

KICKASS_WRAPPER_PHP.php : 166
`protected final php_serialize(mixed $value) : mixed`

##### Parameters

$value : mixed

##### Return values

mixed —

#### php_strval()

KICKASS_WRAPPER_PHP.php : 210
`protected final php_strval(mixed $value) : mixed`

##### Parameters

$value : mixed

##### Return values

mixed —

#### php_time_nanosleep()

KICKASS_WRAPPER_PHP.php : 276
`protected final php_time_nanosleep(mixed $seconds, mixed $nanoseconds) : mixed`

##### Parameters

$seconds : mixed
$nanoseconds : mixed

##### Return values

mixed —

#### php_unserialize()

KICKASS_WRAPPER_PHP.php : 188
`protected final php_unserialize(mixed $value) : mixed`

##### Parameters

$value : mixed

##### Return values

mixed —

#### phps_decode()

KickassCrypto.php : 7000

2023-04-07 jj5 - deserializes the input data using the PHP unserialize() function.

`protected final phps_decode(string $input, bool &$is_false) : mixed`

##### Parameters

$input : string

  the serialized data.

$is_false : bool

  set to true if the deserialized data is the boolean value false.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

mixed —

the deserialized data on success or false on failure, the value false can be returned on success if that's what the serialized data represented.

#### phps_encode()

KickassCrypto.php : 6286

2023-04-05 jj5 - serializes a value using PHP serialization; defers to virtual method do_phps_encode() for implementation.

`protected final phps_encode(mixed $input) : string|false`

##### Parameters

$input : mixed

  can be pretty much anything, the PHP serialization has good support for odd values such as object instances and weird floats.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

string|false —

the serialized input or false on error.

#### text_decode()

KickassCrypto.php : 7182

2023-04-07 jj5 - deserializes the input data using the PHP strval() function.

`protected final text_decode(string $input, bool &$is_false) : mixed`

##### Parameters

$input : string

  the serialized data.

$is_false : bool

  always set to false, this format can't represent false.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

mixed —

the deserialized data on success or false on failure.

#### text_encode()

KickassCrypto.php : 6455

2023-04-05 jj5 - serializes a value as text; defers to virtual method do_text_encode() for implementation.

`protected final text_encode(mixed $input) : string|false`

##### Parameters

$input : mixed

  should be a string or something that strval() will turn into a string.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

string|false —

the serialized input or false on error.

#### throw()

KickassCrypto.php : 1171

2023-04-05 jj5 - this function throws an exception.

`protected final throw(int $code[, type $data = null ][, type $previous = null ]) : void`

##### Parameters

$code : int

  the exception code of the exception to throw, this is one of the KICKASS_CRYPTO_EXCEPTION_* constants.

$data : type = null

  optional data to associate with the exception.

$previous : type = null

  the previous exception, if any.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

throws
  KickassCryptoException

##### Return values

void —

#### try_decrypt()

KickassCrypto.php : 5156

2023-04-05 jj5 - tries to decrypt a binary string using the passphrase.

`protected final try_decrypt(string $binary, string $passphrase[, string &$data_encoding = null ]) : mixed`

##### Parameters

$binary : string

  the binary data to decrypt.

$passphrase : string

  the passphrase to use for decryption.

$data_encoding : string = null

  a reference to the data encoding, this is set if its possible to determine.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

mixed —

the decoded message on success, false otherwise.

#### write_log()

KickassCrypto.php : 8348

2023-04-07 jj5 - provides our internal direct implementation of log writing, in case we need to use it ourselves without potential interference from inheritors of our class.

`protected final write_log(string $message, string $file, int $line, string $function) : bool`

##### Parameters

$message : string

  the message to log.

$file : string

  the path of the file writing the log entry.

$line : int

  the line in the file writing the log entry.

$function : string

  the name of the function writing the log entry.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

bool —

true on success or false on failure.

#### increment_counter_internal()

KickassCrypto.php : 8443

2023-04-07 jj5 - this is our private implementation for incrementing a counter for a key, we use it in enter().

`private increment_counter_internal(array<string|int, mixed> &$array, string $key) : mixed`

##### Parameters

$array : array<string|int, mixed>

  a reference to the array to manage.

$key : string

  the key of the counter to increment.

##### Return values

mixed —

#### report_emergency_delay()

KickassCrypto.php : 8482

2023-04-05 jj5 - this function makes some noice is the emergency delay is invoked; the emergency delay should not usually be activated so if it is we want to give ourself our best chance of finding out about it.

`private report_emergency_delay(string $type, string $file, int $line, string $function) : void`

##### Parameters

$type : string

  the type of delay, could be 'nanosleep' or 'microsleep'.

$file : string

  the file that reported the emergecny delay.

$line : int

  the line in the file where the emergency delay was reported.

$function : string

  the function from which the emergency delay was reported.

##### Tags

throws
  AssertionError

  potentially thrown during testing when assertions are enabled.

##### Return values

void —

## Search results