Hashing and encryption

Three jobs every application with users meets: keeping passwords so that nobody - the database's reader included - can read them back; handing a value to the browser that it cannot read or change; and sending a link that works for the one who got it, until it expires. PHP has the building blocks - password_hash, sodium, hash_hmac - and these helpers put them together the safe way.

Passwords

A password is never stored, only its hash. padHash makes one with a new random salt each time, so two users with the same password get different hashes; padHashCheck tells whether a password typed at login matches the stored hash.

<?php

  $phrase = 'correct horse battery staple';
  $hash   = padHash ( $phrase );

  $right  = padHashCheck ( $phrase, $hash ) ? 'yes' : 'no';
  $wrong  = padHashCheck ( 'Tr0ub4dor&3', $hash ) ? 'yes' : 'no';
  $rehash = padHashNeedsRehash ( $hash ) ? 'yes' : 'no';
  $shape  = substr ( $hash, 0, 4 ) . '... '
          . strlen ( $hash ) . ' characters';

?>

<p>Stored: {$shape}</p>
<p>The right password matches: {$right}</p>
<p>Another password matches: {$wrong}</p>
<p>Needs a new hash: {$rehash}</p>

• After a successful login, padHashNeedsRehash says whether the stored hash was made with older settings - a lower cost, an older algorithm. The password is at hand right then, so the hash can be made again and stored.
• A password that is no text, or a hash that is none - the NULL of a user that does not exist - simply does not match: padHashCheck answers FALSE, never an error.

Sealed values

padEncrypt seals a value - text, a number, an array: whatever JSON holds - so it can travel through the browser in a cookie, a hidden field or a link, and come back unread and unchanged. Anyone can carry the payload; only the application can open it.

<?php

  $payload = padEncrypt ( [ 'order' => 1042,
                            'step'  => 'payment' ] );

  $length  = strlen ( $payload );
  $back    = padDecrypt ( $payload );
  $changed = substr ( $payload, 0, -1 ) . 'x';
  $forged  = padDecrypt ( $changed, 'refused' );

?>

<p>Sealed: {$length} URL-safe characters</p>
<p>Opened: order {$back.order}, step {$back.step}</p>
<p>One character changed: {$forged}</p>

• The value is JSON-encoded and sealed with sodium's secretbox and a random nonce, so the same value sealed twice gives two different payloads.
• A payload that was changed in a single character, cut short, or sealed with another key opens to the default - NULL unless one is given. An object comes back as an array.

Signed links

A link in a mail - confirm your address, download your invoice - has to work without a login, for the one who got it, and stop working after a while. padSignedUrl adds the time it expires and a signature over the application, the page and every value; padSignatureValid (), in the page the link leads to, says whether the request came by such a link.

<?php

  $link = padSignedUrl ( 'invoice', [ 'id' => 1042 ], 3600 );

  $shown = preg_replace (
    [ '/padExpires=\d+/', '/padSignature=\w+/' ],
    [ 'padExpires=...',   'padSignature=...'   ],
    $link
  );

  $here  = padSignatureValid () ? 'yes' : 'no';

?>

<p><code>{$shown}</code></p>
<p>This page came by a signed link: {$here}</p>

The page the link leads to checks it before anything else:

// invoice.php
if ( ! padSignatureValid () )
  padRedirect ( 'link_expired' );

$invoice = db ( "RECORD * FROM invoices WHERE id = {0}", [ $id ] );

• The expiry is a number of seconds, a DateInterval or a moment such as '+2 days'; without one the link never expires.
• A value changed, added or removed, another page, an expiry moved or passed - each makes the signature invalid. The order of the values does not count, and the link holds in the clean form too.
• The link is absolute, since it is mostly mailed; the values are visible in it - sign what must not change, seal what must not be read.

The key

Sealing and signing use the application key. Without a setting it is the file DATA/keys/<application>.key, made the first time it is needed - 32 random bytes, readable by its owner only, under DATA/ where no URL reaches. Set $padAppKey in _config/config.php - 32 bytes, or 'base64:' and 32 bytes in base64, the form the key file holds - when several servers must read each other's values, and keep it out of version control. A new key makes every value sealed and every link signed before it unreadable. The error reports never show it.