The Sodium crypto library of PHP 7.2

by Enrico Zimuel
Senior Software Engineer
Rogue Wave Software, Inc.

ZendCon & OpenEnterprise 2018, Las Vegas (NV), October 16

Overview

• NaCl/Sodium libraries
• Elliptic Curve Cryptography
• Sodium in PHP 7.2:
  1. Encrypt/Authenticate with a shared-key
  2. Sending secret messages
  3. Digital signature
  4. AEAD AES-GCM
  5. Store passwords safely
  6. Derive a key from a user's password

Cryptography

Cryptography is hard. Hard to design, hard to implement, hard to use, and hard to get right.

NaCl

• NaCl: Networking and Cryptography library
• High-speed software library for network communication, encryption, decryption, signatures, etc
• by Prof. Daniel J. Bernstein, and others
• Highly-secure primitives and constructions, implemented with extreme care to avoid side-channel attacks

Side-channel attack

Attack based on information gained from the implementation of a computer system, rather than weaknesses in the implemented algorithm itself

Decode RSA key using power analysis

Source: Protecting Against Side-Channel Attacks with an Ultra-Low Power Processor

Timing attack

An attacker measures the CPU time to perform some procedures involving a secret (e.g. encryption key). If this time depends on the secret, the attacker may be able to deduce information about the secret.

Example in PHP

function compare(string $expected, string $actual): bool
{
    $lenExpected = strlen($expected);
    $lenActual   = strlen($actual);
    if ($lenExpected !== $lenActual) {
        return false;
    }
    for($i=0; $i < $lenActual; $i++) {
        if ($expected[$i] !== $actual[$i]) {
            return false;
        }
    }
    return true;
}

Prevent timing attack

We need a constant-time string comparision function

• PHP 5.6+: hash_equals(string $a, string $b)
• Sodium: sodium_compare(string $a, string $b)
• Pure PHP: Utils::compareStrings(string $a, string $b) in zend-crypt

Best timing attack

In 2006 Adi Shamir, Eran Tromer, and Dag Arne Osvik used a timing attack to discover, in 65 milliseconds, the secret key used in widely deployed software for hard-disk encryption.

Source: Cache Attacks and Countermeasures: the Case of AES

Sodium crypto library

Sodium

• Sodium (libsodium) is a fork of NaCl
• A portable, cross-compilable, installable, packageable, API-compatible version of NaCl
• Same implementations of crypto primitives as NaCl
• Shared library and a standard set of headers (portable implementation)
• Official web site: libsodium.org

Features

• Authenticated public-key and authenticated shared-key encryption
• Public-key and shared-key signatures
• Hashing
• Keyed hashes for short messages
• Secure pseudo-random numbers generation

Algorithms in Sodium

• Curve25519 Diffie–Hellman key-exchange function
• Salsa20, ChaCha20 stream ciphers
• Poly1305 message-authentication code
• Ed25519 public-key signature system
• Argon2, Scrypt password hashing
• AES-GCM authenticated encryption algorithm

Elliptic curves

Elliptic curves

Add 2 points

A + B = C, A + C = D, A + D = E

Scalar multiplication

P + P = 2P

Given P and Q find k such that Q = kP is hard!

Sodium in PHP

• Available (as standard library) from PHP 7.2
• PECL extension (libsodium) for PHP 7.0/7.1
• 85 functions with prefix sodium_
  e.g. sodium_crypto_box_keypair()

Example 1:

encrypt with a shared-key

Symmetric encryption

$msg = 'This is a super secret message!';

// Generating an encryption key and a nonce
$key   = random_bytes(SODIUM_CRYPTO_SECRETBOX_KEYBYTES); // 256 bit
$nonce = random_bytes(SODIUM_CRYPTO_SECRETBOX_NONCEBYTES); // 24 bytes

// Encrypt
$ciphertext = sodium_crypto_secretbox($msg, $nonce, $key);
// Decrypt
$plaintext = sodium_crypto_secretbox_open($ciphertext, $nonce, $key);

echo $plaintext === $msg ? 'Success' : 'Error';

Example 2:

authenticate with a shared-key

Symmetric authentication

$msg = 'This is the message to authenticate!';
$key = random_bytes(SODIUM_CRYPTO_SECRETBOX_KEYBYTES); // 256 bit

// Generate the Message Authentication Code
$mac = sodium_crypto_auth($msg, $key);

// Altering $mac or $msg, verification will fail
echo sodium_crypto_auth_verify($mac, $msg, $key) ? 'Success' : 'Error';

Example 3:

sending secret messages

Public-key encryption

$aliceKeypair = sodium_crypto_box_keypair();
$alicePublicKey = sodium_crypto_box_publickey($aliceKeypair);
$aliceSecretKey = sodium_crypto_box_secretkey($aliceKeypair);

$bobKeypair = sodium_crypto_box_keypair();
$bobPublicKey = sodium_crypto_box_publickey($bobKeypair); // 32 bytes
$bobSecretKey = sodium_crypto_box_secretkey($bobKeypair); // 32 bytes

$msg = 'Hi Bob, this is Alice!';
$nonce = random_bytes(SODIUM_CRYPTO_BOX_NONCEBYTES); // 24 bytes

$keyEncrypt = $aliceSecretKey . $bobPublicKey;
$ciphertext = sodium_crypto_box($msg, $nonce, $keyEncrypt);

$keyDecrypt = $bobSecretKey . $alicePublicKey;
$plaintext = sodium_crypto_box_open($ciphertext, $nonce, $keyDecrypt);
echo $plaintext === $msg ? 'Success' : 'Error';

Example 4:

Digital signature

Digital signature

$keypair = sodium_crypto_sign_keypair();
$publicKey = sodium_crypto_sign_publickey($keypair); // 32 bytes
$secretKey = sodium_crypto_sign_secretkey($keypair); // 64 bytes

$msg = 'This message is from Alice';
// Sign a message
$signedMsg = sodium_crypto_sign($msg, $secretKey);
// Or generate only the signature (detached mode)
$signature = sodium_crypto_sign_detached($msg, $secretKey); // 64 bytes

// Verify the signed message
$original = sodium_crypto_sign_open($signedMsg, $publicKey);
echo $original === $msg ? 'Signed msg ok' : 'Error signed msg';
// Verify the signature
echo sodium_crypto_sign_verify_detached($signature, $msg, $publicKey) ?
     'Signature ok' : 'Error signature';

Example 5:

AES-GCM

AEAD AES-256-GCM

if (! sodium_crypto_aead_aes256gcm_is_available()) {
    throw new \Exception("AES-GCM is not supported on this platform");
}
$msg = 'Super secret message!';
$key = random_bytes(SODIUM_CRYPTO_AEAD_AES256GCM_KEYBYTES);
$nonce = random_bytes(SODIUM_CRYPTO_AEAD_AES256GCM_NPUBBYTES);

// AEAD encryption
$ad = 'Additional public data';
$ciphertext = sodium_crypto_aead_aes256gcm_encrypt(
    $msg,
    $ad,
    $nonce,
    $key
);
// AEAD decryption
$decrypted = sodium_crypto_aead_aes256gcm_decrypt(
    $ciphertext,
    $ad,
    $nonce,
    $key
);
if ($decrypted === false) {
    throw new \Exception("Decryption failed");
}
echo $decrypted === $msg ? 'OK' : 'Error';

Note: you need to store also ad and nonce + ciphertext

Example 6:

store passwords safely

Argon2i

$password = 'password';

$hash = sodium_crypto_pwhash_str(
    $password,
    SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE,
    SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE
); // 97 bytes

echo sodium_crypto_pwhash_str_verify($hash, $password) ?
     'OK' : 'Error';

An example of Argon2i hash:

$argon2id$v=19$m=65536,t=2,p=1$EF1BpShRmCYHN7ryxlhtBg$zLZO4IWjx3E...

Argon2 in PHP 7.2

$password = 'password';

// Argon2i without Sodium
$hash = password_hash($password, PASSWORD_ARGON2I); // 95 bytes

echo password_verify($password, $hash) ? 'OK' : 'Error';

Comparing with Sodium:

$argon2id$v=19$m=65536,t=2,p=1$EF1BpShRmCYH... // 97 bytes, Sodium
$argon2i$v=19$m=1024,t=2,p=2$Y3pweEtMdS82SG... // 95 bytes, PHP

Note: password_hash() is not compatible with sodium_crypto_pwhash_str()

Example 7:

Derive a key from a user's password

Password are bad

• Not random
• Predictable (most of the time)
• Only a subset of ASCII codes (typically 68 vs 256)
• Never use it as encryption/authentication key!
• Use KDF to derive a key from a password

Derive a key using Argon2i

Example: generating a binary key of 32 bytes

$password = 'password';
$salt = random_bytes(SODIUM_CRYPTO_PWHASH_SALTBYTES);

$key = sodium_crypto_pwhash(
    32,
    $password,
    $salt,
    SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE,
    SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE
);

Note: you need to store also the salt to generate the same key from password

References

Thanks!

Contact me: enrico.zimuel [at] roguewave.com

Follow me: @ezimuel