Phalcon Encryption

Encryption\Crypt

Provides encryption capabilities to Phalcon applications.

use Phalcon\Crypt;

$crypt = new Crypt();

$crypt->setCipher("aes-256-ctr");

$key  =
"T4\xb1\x8d\xa9\x98\x05\\\x8c\xbe\x1d\x07&[\x99\x18\xa4~Lc1\xbeW\xb3";
$input = "The message to be encrypted";

$encrypted = $crypt->encrypt($input, $key);

echo $crypt->decrypt($encrypted, $key);

Uses Phalcon\Encryption\Crypt\CryptInterface · Phalcon\Encryption\Crypt\Exception\DecryptionFailed · Phalcon\Encryption\Crypt\Exception\EmptyDecryptionKey · Phalcon\Encryption\Crypt\Exception\EmptyEncryptionKey · Phalcon\Encryption\Crypt\Exception\EncryptionFailed · Phalcon\Encryption\Crypt\Exception\Exception · Phalcon\Encryption\Crypt\Exception\InvalidAuthTagLength · Phalcon\Encryption\Crypt\Exception\InvalidDecryptLength · Phalcon\Encryption\Crypt\Exception\InvalidPaddingSize · Phalcon\Encryption\Crypt\Exception\IvLengthCalculationFailed · Phalcon\Encryption\Crypt\Exception\Mismatch · Phalcon\Encryption\Crypt\Exception\MissingAuthData · Phalcon\Encryption\Crypt\Exception\MissingOpensslExtension · Phalcon\Encryption\Crypt\Exception\RandomBytesGenerationFailed · Phalcon\Encryption\Crypt\Exception\UnsupportedAlgorithm · Phalcon\Encryption\Crypt\PadFactory · Phalcon\Traits\Php\Base64Trait · Phalcon\Traits\Php\HashTrait · Phalcon\Traits\Php\InfoTrait · Phalcon\Traits\Php\OpensslTrait

Method Summary

Constants

Properties

Methods

__construct()

public function __construct(
    string $cipher = self::DEFAULT_CIPHER,
    bool $useSigning = true,
    PadFactory $padFactory = null
);

Crypt constructor.

decrypt()

public function decrypt(
    string $input,
    string $key = null
): string;

Decrypts an encrypted text.

$encrypted = $crypt->decrypt(
    $encrypted,
    "T4\xb1\x8d\xa9\x98\x05\\\x8c\xbe\x1d\x07&[\x99\x18\xa4~Lc1\xbeW\xb3"
);

decryptBase64()

public function decryptBase64(
    string $input,
    string $key = null,
    bool $safe = false
): string;

Decrypt a text that is coded as a base64 string.

encrypt()

public function encrypt(
    string $input,
    string $key = null
): string;

Encrypts a text.

$encrypted = $crypt->encrypt(
    "Top secret",
    "T4\xb1\x8d\xa9\x98\x05\\\x8c\xbe\x1d\x07&[\x99\x18\xa4~Lc1\xbeW\xb3"
);

encryptBase64()

public function encryptBase64(
    string $input,
    string $key = null,
    bool $safe = false
): string;

Encrypts a text returning the result as a base64 string.

getAuthData()

public function getAuthData(): string;

Returns the auth data

getAuthTag()

public function getAuthTag(): string;

Returns the auth tag

getAuthTagLength()

public function getAuthTagLength(): int;

Returns the auth tag length

getAvailableCiphers()

public function getAvailableCiphers(): array;

Returns a list of available ciphers.

getAvailableHashAlgorithms()

public function getAvailableHashAlgorithms(): array;

Return a list of registered hashing algorithms suitable for hash_hmac.

getCipher()

public function getCipher(): string;

Returns the current cipher

getHashAlgorithm()

public function getHashAlgorithm(): string;

Get the name of hashing algorithm.

getKey()

public function getKey(): string;

Returns the encryption key

isValidDecryptLength()

public function isValidDecryptLength( string $input ): bool;

Returns if the input length for decryption is valid or not (number of bytes required by the cipher).

setAuthData()

public function setAuthData( string $data ): CryptInterface;

setAuthTag()

public function setAuthTag( string $tag ): CryptInterface;

setAuthTagLength()

public function setAuthTagLength( int $length ): CryptInterface;

setCipher()

public function setCipher( string $cipher ): CryptInterface;

Sets the cipher algorithm for data encryption and decryption.

setHashAlgorithm()

public function setHashAlgorithm( string $hashAlgorithm ): static;

Set the name of hashing algorithm.

setKey()

public function setKey( string $key ): CryptInterface;

Sets the encryption key.

The $key should have been previously generated in a cryptographically safe way.

Bad key: “le password”

Better (but still unsafe) -> “#1dj8$=dp?.ak//j1V$~%*0X”

Good key: “T4\xb1\x8d\xa9\x98\x05\\x8c\xbe\x1d\x07&[\x99\x18\xa4~Lc1\xbeW\xb3”

setPadding()

public function setPadding( int $scheme ): CryptInterface;

Changes the padding scheme used.

useSigning()

public function useSigning( bool $useSigning ): CryptInterface;

Sets if the calculating message digest must used.

checkCipherHashIsAvailable()

protected function checkCipherHashIsAvailable(
    string $cipher,
    string $type
): void;

Checks if a cipher or a hash algorithm is available

cryptPadText()

protected function cryptPadText(
    string $input,
    string $mode,
    int $blockSize,
    int $paddingType
): string;

Pads texts before encryption. See cryptopad

cryptUnpadText()

protected function cryptUnpadText(
    string $input,
    string $mode,
    int $blockSize,
    int $paddingType
): string;

Removes a padding from a text.

If the function detects that the text was not padded, it will return it unmodified.

decryptGcmCcmAuth()

protected function decryptGcmCcmAuth(
    string $mode,
    string $cipherText,
    string $decryptKey,
    string $iv
): string;

decryptGetUnpadded()

protected function decryptGetUnpadded(
    string $mode,
    int $blockSize,
    string $decrypted
): string;

encryptGcmCcm()

protected function encryptGcmCcm(
    string $mode,
    string $padded,
    string $encryptKey,
    string $iv
): string;

encryptGetPadded()

protected function encryptGetPadded(
    string $mode,
    string $input,
    int $blockSize
): string;

initializeAvailableCiphers()

protected function initializeAvailableCiphers(): static;

Initialize available cipher algorithms.

Encryption\Crypt\CryptInterface

Interface for Phalcon\Crypt

Uses Phalcon\Contracts\Encryption\Crypt\Crypt

Encryption\Crypt\Exception\DecryptionFailed

Method Summary

Methods

__construct()

public function __construct();

Encryption\Crypt\Exception\EmptyDecryptionKey

Method Summary

Methods

__construct()

public function __construct();

Encryption\Crypt\Exception\EmptyEncryptionKey

Method Summary

Methods

__construct()

public function __construct();

Encryption\Crypt\Exception\EncryptionFailed

Method Summary

Methods

__construct()

public function __construct();

Encryption\Crypt\Exception\Exception

Exceptions thrown in Phalcon\Crypt use this class

Encryption\Crypt\Exception\InvalidAuthTagLength

Method Summary

Methods

__construct()

public function __construct();

Encryption\Crypt\Exception\InvalidDecryptLength

Method Summary

Methods

__construct()

public function __construct();

Encryption\Crypt\Exception\InvalidPaddingSize

Method Summary

Methods

__construct()

public function __construct();

Encryption\Crypt\Exception\IvLengthCalculationFailed

Method Summary

Methods

__construct()

public function __construct();

Encryption\Crypt\Exception\Mismatch

Exceptions thrown in Phalcon\Crypt will use this class.

Encryption\Crypt\Exception\MissingAuthData

Method Summary

Methods

__construct()

public function __construct();

Encryption\Crypt\Exception\MissingOpensslExtension

Method Summary

Methods

__construct()

public function __construct();

Encryption\Crypt\Exception\RandomBytesGenerationFailed

Method Summary

Methods

__construct()

public function __construct();

Encryption\Crypt\Exception\UnsupportedAlgorithm

Method Summary

Methods

__construct()

public function __construct(
    string $type,
    string $cipher
);

Encryption\Crypt\PadFactory

Factory for creating pad classes

Uses Phalcon\Encryption\Crypt · Phalcon\Encryption\Crypt\Padding\PadInterface · Phalcon\Factory\AbstractFactory

Method Summary

Properties

Methods

__construct()

public function __construct( array $services = [] );

AdapterFactory constructor.

newInstance()

public function newInstance( string $name ): PadInterface;

Create a new instance of the adapter

padNumberToService()

public function padNumberToService( int $number ): string;

Gets a Crypt pad constant and returns the unique service name for the padding class

getServices()

protected function getServices(): array;

Encryption\Crypt\Padding\Ansi

Class Ansi

@package Phalcon\Encryption\Crypt\Padding

Method Summary

Methods

pad()

public function pad( int $paddingSize ): string;

unpad()

public function unpad(
    string $input,
    int $blockSize
): int;

Encryption\Crypt\Padding\Iso10126

Class Iso10126

@package Phalcon\Encryption\Crypt\Padding

Method Summary

Methods

pad()

public function pad( int $paddingSize ): string;

unpad()

public function unpad(
    string $input,
    int $blockSize
): int;

Encryption\Crypt\Padding\IsoIek

Class IsoIek

@package Phalcon\Encryption\Crypt\Padding

Method Summary

Methods

pad()

public function pad( int $paddingSize ): string;

unpad()

public function unpad(
    string $input,
    int $blockSize
): int;

Encryption\Crypt\Padding\Noop

Class Noop

@package Phalcon\Encryption\Crypt\Padding

Method Summary

Methods

pad()

public function pad( int $paddingSize ): string;

unpad()

public function unpad(
    string $input,
    int $blockSize
): int;

Encryption\Crypt\Padding\PadInterface

Interface for Phalcon\Encryption\Crypt\Padding

Uses Phalcon\Contracts\Encryption\Crypt\Padding\Pad

Encryption\Crypt\Padding\Pkcs7

Class Pkcs7

@package Phalcon\Encryption\Crypt\Padding

Method Summary

Methods

pad()

public function pad( int $paddingSize ): string;

unpad()

public function unpad(
    string $input,
    int $blockSize
): int;

Encryption\Crypt\Padding\Space

Class Space

@package Phalcon\Encryption\Crypt\Padding

Method Summary

Methods

pad()

public function pad( int $paddingSize ): string;

unpad()

public function unpad(
    string $input,
    int $blockSize
): int;

Encryption\Crypt\Padding\Zero

Class Zero

@package Phalcon\Encryption\Crypt\Padding

Method Summary

Methods

pad()

public function pad( int $paddingSize ): string;

unpad()

public function unpad(
    string $input,
    int $blockSize
): int;

Encryption\Security

This component provides a set of functions to improve the security in Phalcon applications

$login    = $this->request->getPost("login");
$password = $this->request->getPost("password");

$user = Users::findFirstByLogin($login);

if ($user) {
    if ($this->security->checkHash($password, $user->password)) {
        // The password is valid
    }
}

Uses Phalcon\Contracts\Encryption\Security\Security · Phalcon\Di\AbstractInjectionAware · Phalcon\Di\DiInterface · Phalcon\Encryption\Security\Exception · Phalcon\Encryption\Security\Exceptions\UnknownHashAlgorithm · Phalcon\Encryption\Security\Random · Phalcon\Http\RequestInterface · Phalcon\Session\ManagerInterface · Phalcon\Traits\Php\HashTrait

Method Summary

Constants

Properties

Methods

__construct()

public function __construct(
    SessionInterface $session = null,
    RequestInterface $request = null
);

Security constructor.

checkHash()

public function checkHash(
    string $password,
    string $passwordHash,
    int $maxPassLength = 0
): bool;

Checks a plain text password and its hash version to check if the password matches

checkToken()

public function checkToken(
    string $tokenKey = null,
    mixed $tokenValue = null,
    bool $destroyIfValid = true
): bool;

Check if the CSRF token sent in the request is the same that the current in session

computeHmac()

public function computeHmac(
    string $data,
    string $key,
    string $algorithm,
    bool $raw = false
): string;

Computes a HMAC

destroyToken()

public function destroyToken(): static;

Removes the value of the CSRF token and key from session

getDefaultHash()

public function getDefaultHash(): int;

Returns the default hash

getHashInformation()

public function getHashInformation( string $hash ): array;

Returns information regarding a hash

getRandom()

public function getRandom(): Random;

Returns a secure random number generator instance

getRandomBytes()

public function getRandomBytes(): int;

Returns a number of bytes to be generated by the openssl pseudo random generator

getRequestToken()

public function getRequestToken(): string|null;

Returns the value of the CSRF token for the current request.

getSaltBytes()

public function getSaltBytes( int $numberBytes = 0 ): string;

Generate a >22-length pseudo random string to be used as salt for passwords

getSessionToken()

public function getSessionToken(): string|null;

Returns the value of the CSRF token in session

getToken()

public function getToken(): string|null;

Generates a pseudo random token value to be used as input’s value in a CSRF check

getTokenKey()

public function getTokenKey(): string|null;

Generates a pseudo random token key to be used as input’s name in a CSRF check

getWorkFactor()

public function getWorkFactor(): int;

hash()

public function hash(
    string $password,
    array $options = []
): string;

Creates a password hash using bcrypt with a pseudo random salt

Any defaultHash value that is not explicitly handled (including the deprecated, unimplemented constants) resolves to bcrypt.

isLegacyHash()

public function isLegacyHash( string $passwordHash ): bool;

Checks if a password hash is a valid bcrypt’s hash

refreshToken()

public function refreshToken(): static;

Forces the regeneration of the CSRF token and key, writing the new values to the session even when auto-refresh has been disabled. Useful after a successful login or any other state change where rotating the token is appropriate.

setAutoRefresh()

public function setAutoRefresh( bool $autoRefresh ): static;

Toggles automatic regeneration of the CSRF token on every call to getToken() / getTokenKey(). When set to false, existing session values are reused (no session write), and a new token is only minted when none is present or refreshToken() is called explicitly.

setDefaultHash()

public function setDefaultHash( int $defaultHash ): static;

Sets the default hash

setRandomBytes()

public function setRandomBytes( int $randomBytes ): static;

Sets a number of bytes to be generated by the openssl pseudo random generator

setWorkFactor()

public function setWorkFactor( int $workFactor ): static;

Sets the work factor

getLocalService()

protected function getLocalService(
    string $name,
    string $property
);

Encryption\Security\Exception

Phalcon\Encryption\Security\Exception

Exceptions thrown in Phalcon\Security will use this class

Encryption\Security\Exceptions\InvalidRandomInput

Uses Phalcon\Encryption\Security\Exception

Method Summary

Methods

__construct()

public function __construct();

Encryption\Security\Exceptions\UnknownHashAlgorithm

Uses Phalcon\Encryption\Security\Exception

Method Summary

Methods

__construct()

public function __construct( string $algo );

Encryption\Security\JWT\Builder

JWT Builder

@link https://tools.ietf.org/html/rfc7519

Uses Phalcon\Encryption\Security\JWT\Exceptions\EmptyPassphrase · Phalcon\Encryption\Security\JWT\Exceptions\InvalidAudience · Phalcon\Encryption\Security\JWT\Exceptions\InvalidExpirationTime · Phalcon\Encryption\Security\JWT\Exceptions\InvalidNotBefore · Phalcon\Encryption\Security\JWT\Exceptions\ValidatorException · Phalcon\Encryption\Security\JWT\Exceptions\WeakPassphrase · Phalcon\Encryption\Security\JWT\Signer\SignerInterface · Phalcon\Encryption\Security\JWT\Token\Enum · Phalcon\Encryption\Security\JWT\Token\Item · Phalcon\Encryption\Security\JWT\Token\Signature · Phalcon\Encryption\Security\JWT\Token\Token · Phalcon\Support\Collection · Phalcon\Support\Collection\CollectionInterface · Phalcon\Support\Helper\Json\Encode · Phalcon\Traits\Php\Base64Trait

Method Summary

Methods

__construct()

public function __construct( SignerInterface $signer );

Builder constructor.

addClaim()

public function addClaim(
    string $name,
    mixed $value
): static;

Adds a custom claim

addHeader()

public function addHeader(
    string $name,
    mixed $value
): static;

Adds a custom claim

getAudience()

public function getAudience();

getClaims()

public function getClaims(): array;

getContentType()

public function getContentType(): string|null;

getExpirationTime()

public function getExpirationTime(): int|null;

getHeaders()

public function getHeaders(): array;

getId()

public function getId(): string|null;

getIssuedAt()

public function getIssuedAt(): int|null;

getIssuer()

public function getIssuer(): string|null;

getNotBefore()

public function getNotBefore(): int|null;

getPassphrase()

public function getPassphrase(): string;

getSubject()

public function getSubject(): string|null;

getToken()

public function getToken(): Token;

init()

public function init(): static;

setAudience()

public function setAudience( mixed $audience ): static;

The “aud” (audience) claim identifies the recipients that the JWT is intended for. Each principal intended to process the JWT MUST identify itself with a value in the audience claim. If the principal processing the claim does not identify itself with a value in the “aud” claim when this claim is present, then the JWT MUST be rejected. In the general case, the “aud” value is an array of case- sensitive strings, each containing a StringOrURI value. In the special case when the JWT has one audience, the “aud” value MAY be a single case-sensitive string containing a StringOrURI value. The interpretation of audience values is generally application specific. Use of this claim is OPTIONAL.

setContentType()

public function setContentType( string $contentType ): static;

Sets the content type header ‘cty’

setExpirationTime()

public function setExpirationTime( int $timestamp ): static;

The “exp” (expiration time) claim identifies the expiration time on or after which the JWT MUST NOT be accepted for processing. The processing of the “exp” claim requires that the current date/time MUST be before the expiration date/time listed in the “exp” claim. Implementers MAY provide for some small leeway, usually no more than a few minutes, to account for clock skew. Its value MUST be a number containing a NumericDate value. Use of this claim is OPTIONAL.

setId()

public function setId( string $jwtId ): static;

The “jti” (JWT ID) claim provides a unique identifier for the JWT. The identifier value MUST be assigned in a manner that ensures that there is a negligible probability that the same value will be accidentally assigned to a different data object; if the application uses multiple issuers, collisions MUST be prevented among values produced by different issuers as well. The “jti” claim can be used to prevent the JWT from being replayed. The “jti” value is a case- sensitive string. Use of this claim is OPTIONAL.

setIssuedAt()

public function setIssuedAt( int $timestamp ): static;

The “iat” (issued at) claim identifies the time at which the JWT was issued. This claim can be used to determine the age of the JWT. Its value MUST be a number containing a NumericDate value. Use of this claim is OPTIONAL.

setIssuer()

public function setIssuer( string $issuer ): static;

The “iss” (issuer) claim identifies the principal that issued the JWT. The processing of this claim is generally application specific. The “iss” value is a case-sensitive string containing a StringOrURI value. Use of this claim is OPTIONAL.

setNotBefore()

public function setNotBefore( int $timestamp ): static;

The “nbf” (not before) claim identifies the time before which the JWT MUST NOT be accepted for processing. The processing of the “nbf” claim requires that the current date/time MUST be after or equal to the not-before date/time listed in the “nbf” claim. Implementers MAY provide for some small leeway, usually no more than a few minutes, to account for clock skew. Its value MUST be a number containing a NumericDate value. Use of this claim is OPTIONAL.

setPassphrase()

public function setPassphrase( string $passphrase ): static;

setSubject()

public function setSubject( string $subject ): static;

The “sub” (subject) claim identifies the principal that is the subject of the JWT. The claims in a JWT are normally statements about the subject. The subject value MUST either be scoped to be locally unique in the context of the issuer or be globally unique. The processing of this claim is generally application specific. The “sub” value is a case-sensitive string containing a StringOrURI value. Use of this claim is OPTIONAL.

setClaim()

protected function setClaim(
    string $name,
    mixed $value
): Builder;

Sets a registered claim

Encryption\Security\JWT\Exceptions\EmptyPassphrase

Method Summary

Methods

__construct()

public function __construct();

Encryption\Security\JWT\Exceptions\InvalidAudience

Method Summary

Methods

__construct()

public function __construct();

Encryption\Security\JWT\Exceptions\InvalidAudienceType

Method Summary

Methods

__construct()

public function __construct();

Encryption\Security\JWT\Exceptions\InvalidClaims

Uses InvalidArgumentException

Method Summary

Methods

__construct()

public function __construct();

Encryption\Security\JWT\Exceptions\InvalidExpirationTime

Method Summary

Methods

__construct()

public function __construct();

Encryption\Security\JWT\Exceptions\InvalidHeader

Uses InvalidArgumentException

Method Summary

Methods

__construct()

public function __construct();

Encryption\Security\JWT\Exceptions\InvalidNotBefore

Method Summary

Methods

__construct()

public function __construct();

Encryption\Security\JWT\Exceptions\MalformedJwtString

Uses InvalidArgumentException

Method Summary

Methods

__construct()

public function __construct();

Encryption\Security\JWT\Exceptions\MissingJwtTypHeader

Uses InvalidArgumentException

Method Summary

Methods

__construct()

public function __construct();

Encryption\Security\JWT\Exceptions\UnsupportedAlgorithmException

Exception thrown when the algorithm is not supported for JWT

Uses Exception

Encryption\Security\JWT\Exceptions\UnsupportedHmacAlgorithm

Method Summary

Methods

__construct()

public function __construct();

Encryption\Security\JWT\Exceptions\ValidatorException

Exception thrown when the validation does not pass for JWT

Uses Exception

Encryption\Security\JWT\Exceptions\WeakPassphrase

Method Summary

Methods

__construct()

public function __construct();

Encryption\Security\JWT\Signer\AbstractSigner

Abstract class helping with the signer classes

Method Summary

Properties

Methods

getAlgorithm()

public function getAlgorithm(): string;

Encryption\Security\JWT\Signer\Hmac

HMAC signing class

Uses Phalcon\Encryption\Security\JWT\Exceptions\UnsupportedAlgorithmException · Phalcon\Encryption\Security\JWT\Exceptions\UnsupportedHmacAlgorithm · Phalcon\Traits\Php\HashTrait

Method Summary

Methods

__construct()

public function __construct( string $algo = "sha512" );

Hmac constructor.

getAlgHeader()

public function getAlgHeader(): string;

Return the value that is used for the “alg” header

sign()

public function sign(
    string $payload,
    string $passphrase
): string;

Sign a payload using the passphrase

verify()

public function verify(
    string $source,
    string $payload,
    string $passphrase
): bool;

Verify a passed source with a payload and passphrase

Encryption\Security\JWT\Signer\None

No signing class

Method Summary

Methods

getAlgHeader()

public function getAlgHeader(): string;

Return the value that is used for the “alg” header

getAlgorithm()

public function getAlgorithm(): string;

Return the algorithm used

sign()

public function sign(
    string $payload,
    string $passphrase
): string;

Sign a payload using the passphrase

verify()

public function verify(
    string $source,
    string $payload,
    string $passphrase
): bool;

Verify a passed source with a payload and passphrase

Encryption\Security\JWT\Signer\SignerInterface

Interface for JWT Signer classes

Uses Phalcon\Contracts\Encryption\Security\JWT\Signer\Signer

Encryption\Security\JWT\Token\AbstractItem

Abstract helper class for Tokens

Method Summary

Properties

Methods

getEncoded()

public function getEncoded(): string;

Encryption\Security\JWT\Token\Enum

Constants for Tokens. It offers constants for Headers as well as Claims

@link https://tools.ietf.org/html/rfc7519

Constants

Encryption\Security\JWT\Token\Item

Storage class for a Token Item

Method Summary

Methods

__construct()

public function __construct(
    array $payload,
    string $encoded
);

Item constructor.

get()

public function get(
    string $name,
    mixed $defaultValue = null
): mixed|null;

getPayload()

public function getPayload(): array;

has()

public function has( string $name ): bool;

Encryption\Security\JWT\Token\Parser

Token Parser class.

It parses a token by validating if it is formed properly and splits it into three parts. The headers are decoded, then the claims and finally the signature. It returns a token object populated with the decoded information.

Uses InvalidArgumentException · Phalcon\Encryption\Security\JWT\Exceptions\InvalidClaims · Phalcon\Encryption\Security\JWT\Exceptions\InvalidHeader · Phalcon\Encryption\Security\JWT\Exceptions\MalformedJwtString · Phalcon\Encryption\Security\JWT\Exceptions\MissingJwtTypHeader · Phalcon\Support\Helper\Json\Decode · Phalcon\Traits\Php\Base64Trait

Method Summary

Methods

__construct()

public function __construct( Decode $decode = null );

parse()

public function parse( string $token ): Token;

Parse a token and return it

Encryption\Security\JWT\Token\Signature

Signature class containing the encoded data and the hash.

Method Summary

Methods

__construct()

public function __construct(
    string $hash = "",
    string $encoded = ""
);

Signature constructor.

getHash()

public function getHash(): string;

Encryption\Security\JWT\Token\Token

Token Class.

A container for Token related data. It stores the claims, headers, signature and payload. It also calculates and returns the token string.

@property Item $claims @property Item $headers @property Signature $signature

@link https://tools.ietf.org/html/rfc7519

Uses Phalcon\Encryption\Security\JWT\Signer\SignerInterface · Phalcon\Encryption\Security\JWT\Validator

Method Summary

Methods

__construct()

public function __construct(
    Item $headers,
    Item $claims,
    Signature $signature
);

Token constructor.

getClaims()

public function getClaims(): Item;

Return the registered claims

getHeaders()

public function getHeaders(): Item;

Return the registered headers

getPayload()

public function getPayload(): string;

Return the payload

getSignature()

public function getSignature(): Signature;

Return the signature

getToken()

public function getToken(): string;

Return the token

validate()

public function validate( Validator $validator ): array;

Validate the token against the claims registered in the validator.

Only claims that have a value in the validator are checked. A claim left as null expresses no expectation and is skipped.

verify()

public function verify(
    SignerInterface $signer,
    string $key
): bool;

Verify the signature

Encryption\Security\JWT\Validator

Class Validator

Uses DateTimeImmutable · Phalcon\Encryption\Security\JWT\Exceptions\InvalidAudienceType · Phalcon\Encryption\Security\JWT\Exceptions\ValidatorException · Phalcon\Encryption\Security\JWT\Signer\SignerInterface · Phalcon\Encryption\Security\JWT\Token\Enum · Phalcon\Encryption\Security\JWT\Token\Token · Phalcon\Time\Clock\ClockInterface

Method Summary

Methods

__construct()

public function __construct(
    Token $token,
    int $timeShift = 0,
    ClockInterface $clock = null
);

Validator constructor.

get()

public function get( string $claim ): mixed|null;

Return the value of a claim

getErrors()

public function getErrors(): array;

Return an array with validation errors (if any)

set()

public function set(
    string $claim,
    mixed $value
): static;

Set the value of a claim, for comparison with the token values

setToken()

public function setToken( Token $token ): static;

Set the token to be validated

validateAudience()

public function validateAudience( mixed $audience ): static;

Validate the audience

validateClaim()

public function validateClaim(
    string $name,
    mixed $value
): static;

Validate a claim

validateExpiration()

public function validateExpiration( int $timestamp ): static;

Validate the expiration time of the token

validateId()

public function validateId( string $id = null ): static;

Validate the id of the token

A null id expresses no expectation and is skipped.

validateIssuedAt()

public function validateIssuedAt( int $timestamp ): static;

Validate the issued at (iat) of the token

A token issued at exactly $timestamp is valid. Only a token issued after it, i.e. in the future, is rejected.

validateIssuer()

public function validateIssuer( string $issuer = null ): static;

Validate the issuer of the token

A null issuer expresses no expectation and is skipped.

validateNotBefore()

public function validateNotBefore( int $timestamp ): static;

Validate the notbefore (nbf) of the token

A token is valid at exactly $timestamp. Only a timestamp before the “nbf” claim is rejected.

validateSignature()

public function validateSignature(
    SignerInterface $signer,
    string $passphrase
): static;

Validate the signature of the token

validateSubject()

public function validateSubject( string $subject = null ): static;

Validate the subject of the token

A null subject expresses no expectation and is skipped.

Encryption\Security\Random

Phalcon\Encryption\Security\Random

Secure random number generator class.

Provides secure random number generator which is suitable for generating session key in HTTP cookies, etc.

Phalcon\Encryption\Security\Random could be mainly useful for:

• Key generation (e.g. generation of complicated keys)
• Generating random passwords for new user accounts
• Encryption systems

$random = new \Phalcon\Encryption\Security\Random();

// Random binary string
$bytes = $random->bytes();

// Random hex string
echo $random->hex(10); // a29f470508d5ccb8e289
echo $random->hex(10); // 533c2f08d5eee750e64a
echo $random->hex(11); // f362ef96cb9ffef150c9cd
echo $random->hex(12); // 95469d667475125208be45c4
echo $random->hex(13); // 05475e8af4a34f8f743ab48761

// Random base62 string
echo $random->base62(); // z0RkwHfh8ErDM1xw

// Random base64 string
echo $random->base64(12); // XfIN81jGGuKkcE1E
echo $random->base64(12); // 3rcq39QzGK9fUqh8
echo $random->base64();   // DRcfbngL/iOo9hGGvy1TcQ==
echo $random->base64(16); // SvdhPcIHDZFad838Bb0Swg==

// Random URL-safe base64 string
echo $random->base64Safe();           // PcV6jGbJ6vfVw7hfKIFDGA
echo $random->base64Safe();           // GD8JojhzSTrqX7Q8J6uug
echo $random->base64Safe(8);          // mGyy0evy3ok
echo $random->base64Safe(null, true); // DRrAgOFkS4rvRiVHFefcQ==

// Random UUID (version 4) - returns a string
echo $random->uuid(); // db082997-2572-4e2c-a046-5eefe97b1235
echo $random->uuid(); // da2aa0e2-b4d0-4e3c-99f5-f5ef62c57fe2

// For other UUID versions (1, 3, 5, 6, 7) or object-based access use the
// Phalcon\Encryption\Security\Uuid factory instead:
//
// $uuid = new \Phalcon\Encryption\Security\Uuid();
// echo $uuid->v1(); // time-based
// echo $uuid->v6(); // reordered time-based (sortable)
// echo $uuid->v7(); // Unix-timestamp based (sortable)

// Random number between 0 and $len
echo $random->number(256); // 84
echo $random->number(256); // 79
echo $random->number(100); // 29
echo $random->number(300); // 40

// Random base58 string
echo $random->base58();   // 4kUgL2pdQMSCQtjE
echo $random->base58();   // Umjxqf7ZPwh765yR
echo $random->base58(24); // qoXcgmw4A9dys26HaNEdCRj9
echo $random->base58(7);  // 774SJD3vgP

This class partially borrows SecureRandom library from Ruby

@link https://ruby-doc.org/stdlib-2.2.2/libdoc/securerandom/rdoc/SecureRandom.html

Uses Phalcon\Encryption\Security\Exceptions\InvalidRandomInput

Method Summary

Methods

base58()

public function base58( int $len = 16 ): string;

Generates a random base58 string

The result may contain alphanumeric characters except 0, O, I and l.

It is similar to Phalcon\Encryption\Security\Random::base64() but has been modified to avoid both non-alphanumeric characters and letters which might look ambiguous when printed.

$random = new \Phalcon\Encryption\Security\Random();

echo $random->base58(); // 4kUgL2pdQMSCQtjE

@see \Phalcon\Encryption\Security\Random:base64 @link https://en.wikipedia.org/wiki/Base58

base62()

public function base62( int $len = 16 ): string;

Generates a random base62 string

It is similar to Phalcon\Encryption\Security\Random::base58() but has been modified to provide the largest value that can safely be used in URLs without needing to take extra characters into consideration because it is [A-Za-z0-9].

$random = new \Phalcon\Encryption\Security\Random();

echo $random->base62(); // z0RkwHfh8ErDM1xw

@see \Phalcon\Encryption\Security\Random:base58

base64()

public function base64( int $len = 16 ): string;

Generates a random base64 string

The length of the result string is usually greater of $len. Size formula: 4 * ($len / 3) rounded up to a multiple of 4.

$random = new \Phalcon\Encryption\Security\Random();

echo $random->base64(12); // 3rcq39QzGK9fUqh8

base64Safe()

public function base64Safe(
    int $len = 16,
    bool $padding = false
): string;

Generates a random URL-safe base64 string

The length of the result string is usually greater of $len.

By default, padding is not generated because “=” may be used as a URL delimiter. The result may contain A-Z, a-z, 0-9, “-” and “_”. “=” is also used if $padding is true. See RFC 3548 for the definition of URL-safe base64.

$random = new \Phalcon\Encryption\Security\Random();

echo $random->base64Safe(); // GD8JojhzSTrqX7Q8J6uug

@link https://www.ietf.org/rfc/rfc3548.txt

bytes()

public function bytes( int $len = 16 ): string;

Generates a random binary string

The Random::bytes method returns a string and accepts as input an int representing the length in bytes to be returned.

If $len is not specified, 16 is assumed. It may be larger in future. The result may contain any byte: “x00” - “xFF”.

$random = new \Phalcon\Encryption\Security\Random();

$bytes = $random->bytes();
var_dump(bin2hex($bytes));
// Possible output: string(32) "00f6c04b144b41fad6a59111c126e1ee"

hex()

public function hex( int $len = 16 ): string;

Generates a random hex string

The length of the result string is usually greater of $len.

$random = new \Phalcon\Encryption\Security\Random();

echo $random->hex(10); // a29f470508d5ccb8e289

number()

public function number( int $len ): int;

Generates a random number between 0 and $len

Returns an integer: 0 <= result <= $len.

$random = new \Phalcon\Encryption\Security\Random();

echo $random->number(16); // 8

uuid()

public function uuid(): string;

Generates a v4 random UUID (Universally Unique IDentifier)

The version 4 UUID is purely random (except the version). It does not contain meaningful information such as MAC address, time, etc. See RFC 4122 for details of UUID.

Delegates to Phalcon\Encryption\Security\Uuid::v4(). For other UUID versions or object-based access use that class directly.

$random = new \Phalcon\Encryption\Security\Random();

echo $random->uuid(); // 1378c906-64bb-4f81-a8d6-4ae1bfcdec22

@link https://www.ietf.org/rfc/rfc4122.txt

base()

protected function base(
    string $alphabet,
    int $base,
    mixed $number = 16
): string;

Generates a random string based on the number ($base) of characters ($alphabet).

Encryption\Security\Uuid

Factory that generates UUIDs of versions 1 through 7.

Each call creates a new immutable version object. Cast to string for the UUID value; use the returned object for additional methods such as getDateTime() or getNode().

Uses Phalcon\Encryption\Security\Uuid\Version1 · Phalcon\Encryption\Security\Uuid\Version3 · Phalcon\Encryption\Security\Uuid\Version4 · Phalcon\Encryption\Security\Uuid\Version5 · Phalcon\Encryption\Security\Uuid\Version6 · Phalcon\Encryption\Security\Uuid\Version7

Method Summary

Methods

v1()

public function v1(): Version1;

Generates a version 1 (time-based) UUID.

v3()

public function v3(
    string $namespaceName,
    string $name
): Version3;

Generates a version 3 (name-based MD5) UUID.

v4()

public function v4(): Version4;

Generates a version 4 (random) UUID.

v5()

public function v5(
    string $namespaceName,
    string $name
): Version5;

Generates a version 5 (name-based SHA-1) UUID.

v6()

public function v6(): Version6;

Generates a version 6 (reordered time-based) UUID.

v7()

public function v7(): Version7;

Generates a version 7 (Unix timestamp) UUID.

Encryption\Security\Uuid\AbstractUuid

Shared base for all UUID version objects.

Method Summary

Constants

Properties

Methods

__toString()

public function __toString(): string;

Returns the UUID string.

jsonSerialize()

public function jsonSerialize(): string;

Returns the UUID string for JSON serialisation.

format()

protected function format( string $hex ): string;

Formats a 32-character hex string as a canonical UUID string.

getNodeProvider()

protected function getNodeProvider(): NodeProviderInterface;

Returns the shared SysNodeProvider instance, creating it on first call. The static property means one discovery per request regardless of how many VersionN objects are constructed.

namespaceToBytes()

protected function namespaceToBytes( string $uuid ): string;

Converts a canonical UUID string to its 16-byte binary representation.

uuidTimestampToDateTime()

protected function uuidTimestampToDateTime( mixed $timestamp ): \DateTimeImmutable;

Converts a 60-bit UUID timestamp (100-ns intervals since UUID epoch) to a DateTimeImmutable. Used by Version1 and Version6.

Encryption\Security\Uuid\NodeProviderInterface

Uses Phalcon\Contracts\Encryption\Security\Uuid\NodeProvider

Encryption\Security\Uuid\RandomNodeProvider

Generates a random 48-bit node with the multicast bit set.

Used as a fallback when no hardware MAC address is available.

@link https://www.ietf.org/rfc/rfc4122.txt Section 4.5

Method Summary

Methods

getNode()

public function getNode(): string;

Returns a random 12-character hex node with the multicast bit set.

Encryption\Security\Uuid\SysNodeProvider

Discovers the hardware MAC address and returns it as a 12-character hex node.

Two-layer cache:

1. Instance property - free on all calls after the first within this instance.
2. APCu - cross-request within the same PHP-FPM worker (optional).

Falls back to RandomNodeProvider if no valid MAC address is found.

Platform support: Linux - reads /sys/class/net/*/address macOS - passthru(“ifconfig 2>&1”) Windows - passthru(“ipconfig /all 2>&1”) FreeBSD - passthru(“netstat -i -f link 2>&1”)

Uses Phalcon\Traits\Php\FileTrait · Phalcon\Traits\Php\InfoTrait

Method Summary

Methods

getNode()

public function getNode(): string;

Returns the hardware MAC address as a 12-character hex string. Result is cached in the instance property and optionally in APCu.

Encryption\Security\Uuid\TimeBasedUuidInterface

Uses Phalcon\Contracts\Encryption\Security\Uuid\TimeBasedUuid

Encryption\Security\Uuid\UuidInterface

Marker interface for UUID version adapters.

Also carries the standard RFC 4122 namespace UUIDs as constants.

Uses Phalcon\Contracts\Encryption\Security\Uuid\Uuid

Encryption\Security\Uuid\Version1

Generates a version 1 (time-based) UUID.

The timestamp is the number of 100-nanosecond intervals since October 15, 1582 00:00:00.00 UTC (the UUID epoch). The node is resolved via SysNodeProvider (hardware MAC, APCu-cached) with RandomNodeProvider as fallback.

@link https://www.ietf.org/rfc/rfc4122.txt

Method Summary

Methods

__construct()

public function __construct(
    \DateTimeInterface $dateTime = null,
    mixed $node = null
);

getDateTime()

public function getDateTime(): \DateTimeImmutable;

Returns a DateTimeImmutable built from the UUID’s embedded timestamp.

getNode()

public function getNode(): string;

Returns the 12-character hex node embedded in the UUID.

Encryption\Security\Uuid\Version3

Generates a version 3 (name-based MD5) UUID.

Given a namespace UUID and a name string, produces a deterministic UUID by hashing namespace bytes + name with MD5, then stamping version/variant.

@link https://www.ietf.org/rfc/rfc4122.txt

Method Summary

Methods

__construct()

public function __construct(
    string $namespaceName,
    string $name
);

Encryption\Security\Uuid\Version4

Generates a version 4 (random) UUID.

All 122 non-fixed bits are random. Identical algorithm to Phalcon\Encryption\Security\Random::uuid().

@link https://www.ietf.org/rfc/rfc4122.txt

Method Summary

Methods

__construct()

public function __construct();

Encryption\Security\Uuid\Version5

Generates a version 5 (name-based SHA-1) UUID.

Given a namespace UUID and a name string, produces a deterministic UUID by hashing namespace bytes + name with SHA-1 (first 16 bytes used), then stamping version/variant bits.

@link https://www.ietf.org/rfc/rfc4122.txt

Method Summary

Methods

__construct()

public function __construct(
    string $namespaceName,
    string $name
);

Encryption\Security\Uuid\Version6

Generates a version 6 (reordered time-based) UUID.

Uses the same 60-bit UUID timestamp as version 1 but rearranges the fields so the most-significant time bits come first, producing UUIDs that sort lexicographically in chronological order.

@link https://www.rfc-editor.org/rfc/rfc9562

Method Summary

Methods

__construct()

public function __construct();

getDateTime()

public function getDateTime(): \DateTimeImmutable;

Returns a DateTimeImmutable built from the UUID’s embedded timestamp.

getNode()

public function getNode(): string;

Returns the 12-character hex node embedded in the UUID.

Encryption\Security\Uuid\Version7

Generates a version 7 (Unix timestamp) UUID per RFC 9562.

Layout (128 bits): unix_ts_ms (48) | ver=7 (4) | rand_a (12) | var=10 (2) | rand_b (62)

@link https://www.rfc-editor.org/rfc/rfc9562

Method Summary

Methods

__construct()

public function __construct();