0 follower

Final Class Yiisoft\Security\Mac

All Classes | Methods

Inheritance	Yiisoft\Security\Mac

Provides ability to sign a message with a MAC (message authentication). Signed message contains both original message and a MAC hash. When obtaining original message from signed message using a key an exception is thrown if message was altered.

Public Methods

Hide inherited methods

Method	Description	Defined By
__construct()		Yiisoft\Security\Mac
getMessage()	Get original message from signed message.	Yiisoft\Security\Mac
sign()	Prefixes data with a keyed sign value so that it can later be detected if it is tampered.	Yiisoft\Security\Mac

Method Details

Hide inherited methods

__construct() public method

public __construct( string $algorithm = 'sha256' ): mixed
$algorithm	string	Hash algorithm for message authentication. Recommend sha256, sha384 or sha512.

Source code

                public function __construct(
    private readonly string $algorithm = 'sha256'
) {
}

getMessage() public method

Get original message from signed message.

See also \Yiisoft\Security\hash().

public getMessage( string $data, string $key, boolean $rawHash = false ): string
$data	string	The data to be validated. The data must be previously generated by sign().
$key	string	The secret key that was previously used to generate the sign for the data in sign(). function to see the supported hashing algorithms on your system. This must be the same as the value passed to sign() when generating the hash signature for the data.
$rawHash	boolean	This should take the same value as when you generate the data using sign(). It indicates whether the sign value in the data is in binary format. If false, it means the hash value consists of lowercase hex digits only.
return	string	The real data with the signature stripped off.
throws	RuntimeException	When HMAC generation fails.
throws	Yiisoft\Security\DataIsTamperedException	If the given data is tampered.

Source code

                public function getMessage(
    string $data,
    #[SensitiveParameter]
    string $key,
    bool $rawHash = false
): string {
    $test = hash_hmac($this->algorithm, '', '', $rawHash);
    if (!$test) {
        throw new \RuntimeException("Failed to generate HMAC with hash algorithm: {$this->algorithm}.");
    }
    $hashLength = StringHelper::byteLength($test);
    if (StringHelper::byteLength($data) >= $hashLength) {
        $hash = StringHelper::byteSubstring($data, 0, $hashLength);
        $pureData = StringHelper::byteSubstring($data, $hashLength, null);
        $calculatedHash = hash_hmac($this->algorithm, $pureData, $key, $rawHash);
        if (hash_equals($hash, $calculatedHash)) {
            return $pureData;
        }
    }
    throw new DataIsTamperedException();
}

sign() public method

Prefixes data with a keyed sign value so that it can later be detected if it is tampered.

There is no need to sign inputs or outputs of Yiisoft\Security\Crypt::encryptByKey() or Yiisoft\Security\Crypt::encryptByPassword() as those methods perform the task.

See also:

\Yiisoft\Security\validate()
\Yiisoft\Security\generateBytes()
\Yiisoft\Security\hkdf()
\Yiisoft\Security\pbkdf2()

public sign( string $data, string $key, boolean $rawHash = false ): string
$data	string	The data to be protected.
$key	string	The secret key to be used for generating sign. Should be a secure cryptographic key.
$rawHash	boolean	Whether the generated sign value is in raw binary format. If false, lowercase hex digits will be generated.
return	string	The data prefixed with the keyed sign.
throws	RuntimeException	When HMAC generation fails.

Source code

                public function sign(
    string $data,
    #[SensitiveParameter]
    string $key,
    bool $rawHash = false
): string {
    $hash = hash_hmac($this->algorithm, $data, $key, $rawHash);
    if (!$hash) {
        throw new \RuntimeException("Failed to generate HMAC with hash algorithm: {$this->algorithm}.");
    }
    return $hash . $data;
}