<?php
// PHP < 7.2 with `pecl install libsodium`
$key = str_repeat("\x80", 32);
$nonce = random_bytes(24);
$data = $nonce . \Sodium\crypto_secretbox("Test", $nonce, $key);

<?php
// PHP >= 7.2
$key = str_repeat("\x80", 32);
$nonce = random_bytes(24);
$data = $nonce . sodium_crypto_secretbox("Test", $nonce, $key);

<?php
// PHP >= 7.2
$key = str_repeat("\x80", 32);
$nonce = random_bytes(24);
$data = $nonce . ParagonIE_Sodium_Compat::crypto_secretbox("Test", $nonce, $key);

Hash Functions

crypto_pwhash()

crypto_pwhash() Sample Code (PHP 7.2+)

<?php

/* This uses Argon2i with two numeric constants that correspond to
 * the number of passes (OPSLIMIT) and the amount of memory to use
 * (MEMLIMIT). A higher OPSLIMIT helps against CPU attacks, while a
 * higher MEMLIMIT helps against GPU attacks.
 */
$storeInDatabase = sodium_crypto_pwhash_str(
    $password, 
    SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE,
    SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE
);

/* Once that's stored, you can just test against the hash like so: */
if (sodium_crypto_pwhash_str_verify($storeInDatabase, $password)) {
    /* Logged in! */
} else {
    /* Incorrect password. */
}

crypto_generichash()

crypto_generichash() Sample Code (PHP 7.2+)

<?php

$someData = 'This is a test message';
$someSecretKey = random_bytes(32);

$hash      = sodium_crypto_generichash($someData);
var_dump(mb_strlen($hash, '8bit')); /* int(32) */

$blake2mac = sodium_crypto_generichash($someData, $someSecretKey);
var_dump(mb_strlen($blake2mac, '8bit')); /* int(32) */

$truncated = sodium_crypto_generichash($someData, '', 16);
var_dump(mb_strlen($truncated, '8bit')); /* int(16) */

crypto_shorthash()

crypto_shorthash() Sample Code (PHP 7.2+)

<?php
$key = random_bytes(16);
$input = ['apple', 'boy', 'cat', 'dog', 'echo'];
$mapped = [];
foreach ($input as $item) {
    $hash = sodium_crypto_shorthash($item, $key);
    $mapped[bin2hex($hash)] = $item;
}
var_dump($mapped);

Authentication

crypto_auth()

crypto_auth() Sample Code (PHP 7.2+)

<?php
$key = random_bytes(32);
$message = 'authenticate me';

/* Get the message authentication code (MAC): */
$mac = sodium_crypto_auth($message, $key);

/* Verify a message: */
if (sodium_crypto_auth_verify($mac, $message, $key)) {
    /* Verified */
} else {
    /* Message has been tampered with; discard */
}

crypto_sign()

crypto_sign() Sample Code (PHP 7.2+)

<?php
$mySigningKeypair = sodium_crypto_sign_keypair();
$secretKey = sodium_crypto_sign_secretkey($mySigningKeypair);
$publicKey = sodium_crypto_sign_publickey($mySigningKeypair);

$message = 'authenticate me';

/* Sign the message, using your secret key (which is NOT given out): */
$signature = sodium_crypto_sign_detached($message, $secretKey);

/* Now validate the signature with your public key (which IS given out): */
if (sodium_crypto_sign_verify_detached($signature, $message, $publicKey)) {
    /* Message was signed by me. */
} else {
    throw new Exception('Invalid signature. Do not trust the message.');
}

Encryption

crypto_aead()

crypto_aead_*() Sample Code (PHP with sodium_compat)

<?php
/**
 * Wrap crypto_aead_*_encrypt() in a drop-dead-simple encryption interface
 *
 * @link https://paragonie.com/b/kIqqEWlp3VUOpRD7
 * @param string $message
 * @param string $key
 * @return string
 */
function simpleEncrypt($message, $key)
{
    $nonce = random_bytes(24); // NONCE = Number to be used ONCE, for each message
    $encrypted = ParagonIE_Sodium_Compat::crypto_aead_xchacha20poly1305_ietf_encrypt(
        $message,
        $nonce,
        $nonce,
        $key
    );
    return $nonce . $encrypted;
}

/**
 * Wrap crypto_aead_*_decrypt() in a drop-dead-simple decryption interface
 *
 * @link https://paragonie.com/b/kIqqEWlp3VUOpRD7
 * @param string $message - Encrypted message
 * @param string $key     - Encryption key
 * @return string
 * @throws Exception
 */
function simpleDecrypt($message, $key)
{
    $nonce = mb_substr($message, 0, 24, '8bit');
    $ciphertext = mb_substr($message, 24, null, '8bit');
    $plaintext = ParagonIE_Sodium_Compat::crypto_aead_xchacha20poly1305_ietf_decrypt(
        $ciphertext,
        $nonce,
        $nonce,
        $key
    );
    if (!is_string($plaintext)) {
        throw new Exception('Invalid message');
    }
    return $plaintext;
}

$secretKey = random_bytes(32);
$message = 'Test message';

/* Encrypt the message: */
$ciphertext = simpleEncrypt($message, $secretKey);

/* Decrypt the message: */
try {
    $decrypted = simpleDecrypt($ciphertext, $secretKey);
    var_dump(hash_equals($decrypted, $message));
    /* bool(true) */
} catch (Exception $ex) {
    /* Someone is up to no good */
    exit(255);
}

crypto_secretbox()

crypto_secretbox_*() Sample Code (PHP 7.2+)

<?php
$key = random_bytes(32);
$message = 'Yellow submarine';

/* For each encryption: */
    $nonce = random_bytes(24); /* Never repeat this! */
    $ciphertext = sodium_crypto_secretbox($message, $nonce, $key);
    $plaintext = sodium_crypto_secretbox_open($ciphertext, $nonce, $key);

crypto_box()

crypto_box() Sample Code (PHP 7.2+)

<?php
# Setup:

/* On Node A */
$aliceKeypair = sodium_crypto_box_keypair();
    $aliceSecretKey = sodium_crypto_box_secretkey($aliceKeypair);
    $alicePublicKey = sodium_crypto_box_publickey($aliceKeypair);
    // Then share $alicePublicKey with Node B

/* On Node B: */
$bobKeypair = sodium_crypto_box_keypair();
    $bobSecretKey = sodium_crypto_box_secretkey($bobKeypair);
    $bobPublicKey = sodium_crypto_box_publickey($bobKeypair);
    // Then share $bobPublicKey with Node A

# Transmission:

/* Sending from Node A to Node B */
    $message 'Hi there! :)';
    $aliceToBob = $aliceSecretKey . $bobPublicKey;
    $nonce = random_bytes(24); /* Never repeat this! */
    $ciphertext = $nonce . sodium_crypto_box($message, $nonce, $aliceToBob);

/* On Node B, receiving an encrypted message from Node A */
    $bobToAlice = $bobSecretKey . $alicePublicKey;
    $nonce = mb_substr($ciphertext, 0, 24, '8bit');
    $encrypted = mb_substr($ciphertext, 24, null, '8bit');
    $decrypted = sodium_crypto_box_open($encrypted, $nonce, $bobToAlice);

# Alternatively:

/* Sending from Node B to Node A */
    $message 'Hello yourself.';
    $bobToAlice = $bobSecretKey . $alicePublicKey;
    $nonce = random_bytes(24); /* Never repeat this! */
    $ciphertext = $nonce . sodium_crypto_box($message, $nonce, $bobToAlice);

/* On Node A, receiving an encrypted message from Node B */
    $aliceToBob = $aliceSecretKey . $bobPublicKey;
    $nonce = mb_substr($ciphertext, 0, 24, '8bit');
    $encrypted = mb_substr($ciphertext, 24, null, '8bit');
    $decrypted = sodium_crypto_box_open($encrypted, $nonce, $aliceToBob);

crypto_box_seal()

crypto_box_seal() Sample Code (PHP 7.2+)

<?php
# Setup:

/* On Node B: */
$bobKeypair = sodium_crypto_box_keypair();
    $bobPublicKey = sodium_crypto_box_publickey($bobKeypair);
    // Then share $bobPublicKey with Node A

# Transmission:

/* Sending from Node A to Node B */
    $message 'Hi there! :)';
    $ciphertext = sodium_crypto_box_seal($message, $bobPublicKey);

/* On Node B, receiving an encrypted message from Node A */
    $decrypted = sodium_crypto_box_seal_open($ciphertext, $bobKeypair);