ApiKey

Key
in package

Application

Class Key: Represents a cryptographic key with associated metadata and functionality for generating, validating, and parsing tokens.

Properties

$created : int
$data : string
$debug : bool: A static flag to enable or disable debug output.
$hashed_public_key : string
$ip : string
$label : string
$public_key : string: The public key associated with this Key object.
$ttl : int
$APP_KEY : string
$HASH_ALGO : string
$KEY_LENGTH : int

Methods

__construct() : mixed: Key constructor.
anatomy() : array<string|int, mixed>: Analyzes a token and provides its anatomy in relation to a given Key object.
create() : self: Creates a new Key object with pre-defined hashed public key and data.
dict() : array<string|int, mixed>: Returns an associative array representing the Key object's label, IP address, and data.
file() : string: Constructs a file path based on a given timestamp and an optional filename.
file_path() : string: Generates the specific file path for this instance's data storage.
hmac() : string: Computes the HMAC (Hash-based Message Authentication Code) of a given text.
parse() : array<string|int, mixed>: Parses a token to extract the public key and the shared key (HMAC of the private key).
test() : void: Performs a series of tests to verify the functionality of the Key class.
token() : string: Generates a token by concatenating the public key and the HMAC of the private key.
valid() : bool: Validates a given token against the current Key object's private key and application key.
data() : string: Manages the internal data of the object, allowing retrieval in hexadecimal format or setting it from a hexadecimal string.
private_key() : array<string|int, mixed>: Extracts the private key from the `$data` property.
random_key() : string: Generates a random key of the specified length.

$created


    public
        int
    $created
     = 0

$data


    public
        string
    $data
     = ''

$debug

A static flag to enable or disable debug output.


    public
    static    bool
    $debug
     = false

Defaults to false.

$hashed_public_key


    public
        string
    $hashed_public_key
     = ''

$ip


    public
        string
    $ip

$label


    public
        string
    $label

$public_key

The public key associated with this Key object.


    public
        string
    $public_key

$ttl


    public
        int
    $ttl
     = 0

$APP_KEY


    private
        string
    $APP_KEY

$HASH_ALGO


    private
        string
    $HASH_ALGO
     = API_KEY_DEFAULT_ALGO

$KEY_LENGTH


    private
        int
    $KEY_LENGTH
     = API_KEY_DEFAULT_LENGTH

__construct()

Key constructor.


    public
                    __construct(string $label, string $ip, string $APP_KEY[, int $KEY_LENGTH = API_KEY_DEFAULT_LENGTH ][, string $HASH_ALGO = API_KEY_DEFAULT_ALGO ][, string $hashed_public_key = '' ][, string $data = '' ][, int $created = 0 ][, int $ttl = 0 ]) : mixed

Initializes a new Key object. If $hashed_public_key or $data are not provided, it generates a new public key, a corresponding hashed public key, and associated data.

Parameters

$label : string: A label for this key.
$ip : string: The IP address associated with this key.
$APP_KEY : string: The application-specific secret key used for hashing. This is required.
$KEY_LENGTH : int = API_KEY_DEFAULT_LENGTH: The length of the generated random keys in bytes. Defaults to API_KEY_DEFAULT_LENGTH.
$HASH_ALGO : string = API_KEY_DEFAULT_ALGO: The hashing algorithm to use for HMAC. Defaults to API_KEY_DEFAULT_ALGO. Must be a supported algorithm by hash_hmac_algos().
$hashed_public_key : string = '': An optional pre-computed hashed public key.
$data : string = '': Optional pre-existing data associated with the key.
$created : int = 0: Optional pre-existing creation timestamp. If not provided.
$ttl : int = 0: The time-to-live (in seconds) for this key. After this duration, the key is considered expired. A value of 0 indicates that the key never expires. Defaults to 0.

anatomy()

Analyzes a token and provides its anatomy in relation to a given Key object.


    public
            static        anatomy(string $token, Key $key) : array<string|int, mixed>

Parameters

$token : string: The token to analyze.
$key : Key: The Key object to compare against.

Return values

array<string|int, mixed> —

An associative array containing the token, extracted public key, shared key, the Key object's public key and hashed public key, the Key object's data, and a boolean indicating if the token is valid for the given Key object.

create()

Creates a new Key object with pre-defined hashed public key and data.


    public
            static        create(string $hashed_public_key, string $data, string $APP_KEY[, string $label = '' ][, string $ip = '' ][, int $ttl = 0 ][, int $created = 0 ][, int $KEY_LENGTH = API_KEY_DEFAULT_LENGTH ][, string $HASH_ALGO = API_KEY_DEFAULT_ALGO ]) : self

This static method is useful for reconstructing a Key object from stored data.

Parameters

$hashed_public_key : string: The pre-computed hashed public key.
$data : string: The pre-existing data associated with the key.
$APP_KEY : string: The application-specific secret key used for hashing.
$label : string = '': An optional label for this key. Defaults to an empty string.
$ip : string = '': The IP address associated with this key. Defaults to an empty string.
$ttl : int = 0: The time-to-live (in seconds) for this key. After this duration, the key is considered expired. A value of 0 indicates that the key never expires. Defaults to 0.
$created : int = 0: Optional pre-existing creation timestamp. If not provided.
$KEY_LENGTH : int = API_KEY_DEFAULT_LENGTH: The length of the original random keys in bytes. Defaults to API_KEY_DEFAULT_LENGTH.
$HASH_ALGO : string = API_KEY_DEFAULT_ALGO: The hashing algorithm used for HMAC. Defaults to API_KEY_DEFAULT_ALGO.

Return values

self —

A new Key object initialized with the provided data.

dict()

Returns an associative array representing the Key object's label, IP address, and data.


    public
                    dict() : array<string|int, mixed>

Return values

array<string|int, mixed> —

An associative array with keys 'label', 'ip', and 'data'.

file()

Constructs a file path based on a given timestamp and an optional filename.


    public
            static        file(int $created[, string $file = '' ]) : string

This static method generates a directory structure using the year, month, and day extracted from the provided timestamp. The resulting path can optionally include a filename at the end.

Parameters

$created : int: A timestamp representing the creation date. This timestamp is expected to be an integer with a length of 8 digits (YYYYMMDD format). An assertion will fail if this condition is not met.
$file : string = '': An optional filename to append to the generated directory path. Defaults to an empty string.

Return values

string —

The generated file path, with directory separators appropriate for the operating system. The path will be in the format: YYYY/MM/DD[/filename].

file_path()

Generates the specific file path for this instance's data storage.


    public
                    file_path() : string

This method leverages the file() static method to create a structured file path. The path is determined by the instance's creation timestamp and a unique identifier derived from its hashed public key. This strategy ensures a well-organized and distributed storage system.

Return values

string —

The generated file path. The path is composed of subdirectories representing the year, month, and day of creation, followed by the instance's hashed public key as the filename. The directory separators are platform-specific.

hmac()

Computes the HMAC (Hash-based Message Authentication Code) of a given text.


    public
            static        hmac(string $text, string $APP_KEY[, string $HASH_ALGO = API_KEY_DEFAULT_ALGO ]) : string

Parameters

$text : string: The input string to hash.
$APP_KEY : string: The secret key to use for the HMAC.
$HASH_ALGO : string = API_KEY_DEFAULT_ALGO: The hashing algorithm to use. Defaults to API_KEY_DEFAULT_ALGO.

Return values

string —

The hexadecimal representation of the HMAC.

parse()

Parses a token to extract the public key and the shared key (HMAC of the private key).


    public
            static        parse(string $token[, int $KEY_LENGTH = API_KEY_DEFAULT_LENGTH ][, string $HASH_ALGO = API_KEY_DEFAULT_ALGO ]) : array<string|int, mixed>

Parameters

$token : string: The token to parse.
$KEY_LENGTH : int = API_KEY_DEFAULT_LENGTH: The expected length of the public key in bytes. Defaults to API_KEY_DEFAULT_LENGTH.
$HASH_ALGO : string = API_KEY_DEFAULT_ALGO: The hashing algorithm that was used to generate the HMAC. Defaults to API_KEY_DEFAULT_ALGO.

Return values

array<string|int, mixed> —

An array containing the public key (at index 0) and the shared key (at index 1), or an empty array if the token format is invalid or the hash algorithm is unsupported.

test()

Performs a series of tests to verify the functionality of the Key class.


    public
            static        test([bool $debug = false ]) : void

Parameters

$debug : bool = false: If true, enables verbose output during the tests. Defaults to false.

token()

Generates a token by concatenating the public key and the HMAC of the private key.


    public
                    token() : string

Return values

string —

The generated token.

valid()

Validates a given token against the current Key object's private key and application key.


    public
                    valid(string $token[, string $ip = '' ]) : bool

Parameters

$token : string: The token to validate.
$ip : string = '': The IP address associated with this key. Defaults to an empty string.

Return values

bool —

True if the token is valid, false otherwise.

data()

Manages the internal data of the object, allowing retrieval in hexadecimal format or setting it from a hexadecimal string.


    private
                    data([string $data_hex = '' ]) : string

When called without any arguments, this method decodes the internal base64 encoded data and returns its hexadecimal representation.

When called with a hexadecimal string as an argument, it encodes this string into base64 and updates the internal data of the object. In this case, the method returns an empty string.

Parameters

$data_hex : string = '': Optional. A hexadecimal string to set as the internal data. Defaults to an empty string, in which case the current data is returned in hexadecimal format.

Return values

string —

The hexadecimal representation of the internal data if no argument is provided. An empty string if a hexadecimal string is provided as an argument.

private_key()

Extracts the private key from the `$data` property.


    private
                    private_key() : array<string|int, mixed>

This function assumes that the $data property has a specific structure: random bytes (1 to KEY_LENGTH) + hashed public key + private key + random bytes (1 to KEY_LENGTH). It extracts the private key based on the position of the $hashed_public_key.

Return values

array<string|int, mixed> —

The extracted private key with IP.

random_key()

Generates a random key of the specified length.


    private
                    random_key() : string

Return values

string —

A hexadecimal representation of the random key.

Key in package Application

Tags

Table of Contents

Properties

Methods

Properties

$created

$data

$debug

Tags

$hashed_public_key

$ip

$label

$public_key

Tags

$ttl

$APP_KEY

$HASH_ALGO

$KEY_LENGTH

Methods

__construct()

Parameters

Tags

anatomy()

Parameters

Tags

Return values

create()

Parameters

Tags

Return values

dict()

Tags

Return values

file()

Parameters

Tags

Return values

file_path()

Tags

Return values

hmac()

Parameters

Tags

Return values

parse()

Parameters

Tags

Return values

test()

Parameters

Tags

token()

Tags

Return values

valid()

Parameters

Tags

Return values

data()

Parameters

Tags

Return values

private_key()

Tags

Return values

random_key()

Tags

Return values

Key
in package

Application