PHP sodium_crypto_auth() Function: Usage and Examples

sodium_crypto_auth computes a fixed-size keyed authenticator for a message using the libsodium secret-key MAC primitive.

The examples explain the data format, expected results and the difference between this API and nearby cryptographic operations.

What It Does

The operation is intended for: sodium_crypto_auth computes a fixed-size keyed authenticator for a message using the libsodium secret-key MAC primitive.

The sodium extension must be enabled.

Syntax and Return Value

sodium_crypto_auth(string $message, string $key): string

Parameter	Purpose
$message (string)	The plaintext or input message bytes; content is not automatically character-normalized.
$key (string)	Raw key bytes in the required algorithm-specific length; protect them from disclosure.

The declared return type is shown above. Errors can include false results or exceptions depending on this API: Both parties must share the same secret. A MAC is not a public-key digital signature.

Example 1: Basic Operation

A keyed MAC authenticates a message; the tag is not encrypted data.

<?php
$message = "Account update";
$key = sodium_crypto_auth_keygen();
$tag = sodium_crypto_auth($message, $key);
echo strlen($tag) . " authentication bytes";

Example 2: A Different Use Case

Check the MAC using the same message and secret key.

<?php
// Check the alternative case.
$message = "New order: 42";
$key = sodium_crypto_auth_keygen();
$tag = sodium_crypto_auth($message, $key);
var_dump(sodium_crypto_auth_verify($tag, $message, $key));

Practical Example: Checking the Result

Show that modifying a message invalidates the authentication tag.

<?php
// Verify the expected behavior before using results.
$message = "Export completed";
$key = sodium_crypto_auth_keygen();
$tag = sodium_crypto_auth($message, $key);
var_dump(sodium_crypto_auth_verify($tag, $message . "!", $key) === false);

Important Behavior and Edge Cases

Both parties must share the same secret. A MAC is not a public-key digital signature.

Comparison with Related Functions

Approach	Key distinction
sodium_crypto_auth	sodium_crypto_auth computes a fixed-size keyed authenticator for a message using the libsodium secret-key MAC primitive.
Related technique	sodium_crypto_sign_detached instead uses public-key signatures.

Common Beginner Mistakes

Mistake	Correct approach
Confusing this operation with a neighboring cryptographic or security mechanism	sodium_crypto_sign_detached instead uses public-key signatures.
Ignoring a security prerequisite or failure case	Both parties must share the same secret. A MAC is not a public-key digital signature.

Key Takeaways

sodium_crypto_auth computes a fixed-size keyed authenticator for a message using the libsodium secret-key MAC primitive.
Both parties must share the same secret. A MAC is not a public-key digital signature.
sodium_crypto_sign_detached instead uses public-key signatures.

Apply this behavior to a real application only after confirming the required extension, configuration and failure handling on the deployment runtime.