DEV Community: Scott Arciszewski

Message Encryption in JavaScript and PHP

Scott Arciszewski — Sun, 20 Oct 2019 21:34:26 +0000

Just for fun, let's encrypt some stuff in client-side JavaScript and have a PHP server decrypt it. Note that this will never replace TLS (HTTPS).

JavaScript Encryption with Sodium-Plus

You'll want the latest release of sodium-plus for this. (As of this writing, it's version 0.4.0.)

<script
  src="/static/js/sodium-plus.min.js"
  integrity="sha384-lv7SVE0eb0bXA3fgK6PwlhViiUwG6tBuMAhS8XX7RvBvyRcdEdJ8HKtFgs4vHTUh"
></script>

Next, you'll want to write some JavaScript code to encrypt a message and send it to a server. I'll be using jQuery for this example, but you can easily adapt it to use a XMLHttpRequest object instead.

Let's define two functions. One loads a CryptographyKey object from a hard-coded string (n.b. you never want to actually do this, but for the sake of an easy, working example, we're using a hard-coded secret). The other actually encrypts a message.

/**
 * Get the example key. In the real world, you want to generate these randomly.
 */
async function getExampleKey() {
    if (!window.sodium) window.sodium = await SodiumPlus.auto();
    return CryptographyKey.from(
        'e9897cea109576c2f8088c277125d553e4f83afbc0abbb92cfb1f7b776b4fee0',
        'hex'
    );
    // return await sodium.crypto_secretbox_keygen();
}

/**
 * Encrypt a message under a given key.
 */
async function encryptMessage(message, key) {
    if (!window.sodium) window.sodium = await SodiumPlus.auto();

    let nonce = await sodium.randombytes_buf(24);
    let encrypted = await sodium.crypto_secretbox(message, nonce, key);
    return nonce.toString('hex') + encrypted.toString('hex');
}

Next, you'll want to write a function that gathers user input, encrypts it, and sends it to a server.

async function sendEncryptedMessage() {
    let key = await getExampleKey();
    let message = $("#user-input").val();
    let encrypted = await encryptMessage(message, key);
    $.post("/send-message", {"message": encrypted}, function (response) {
        console.log(response);
        $("#output").append("<li><pre>" + response.message + "</pre></li>");
    });
}

...and some supporting HTML:

<label for="user-input">Type a message to encrypt and send:</label>
<textarea id="user-input"></textarea>
<button id="send-it" type="button">Send Encrypted Message</button>
<hr />
<ol id="output"></ol>

<script type="text/javascript">
$("#send-it").on('click', sendEncryptedMessage);
</script>

PHP Decryption with Sodium

You're going to want paragonie/sodium_compat.

If you're using PHP 7.2, with overwhelming probability you can just use the built in sodium_* functions. However, some distros may incorrectly disable the sodium extension by default. So to play it safe, install sodium_compat anyway.

If you're using a framework (Symfony, Laravel), your code will look a lot cleaner, but for the sake of illustration, the decryption code will look like this:

<?php
declare(strict_types=1);

require 'vendor/autoload.php'; // Composer

header('Content-Type: application/json');

$key = sodium_hex2bin('e9897cea109576c2f8088c277125d553e4f83afbc0abbb92cfb1f7b776b4fee0');

$encrypted = $_POST['message'] ?? null;
if (!$encrypted) {
    echo json_encode(
        ['message' => null, 'error' => 'no message provided'],
        JSON_PRETTY_PRINT
    );
    exit(1);
}

$nonce = sodium_hex2bin(substr($encrypted, 0, 48));
$ciphertext = sodium_hex2bin(substr($encrypted, 48));
$plaintext = sodium_crypto_secretbox_open($ciphertext, $nonce, $key);

echo json_encode(
    ['message' => $plaintext, 'original' => $encrypted],
    JSON_PRETTY_PRINT
);

Putting it Together

When you type in a message and press the button, it will encrypt it and send a hex-encoded string to the server.

The PHP code will then decrypt the message and return the plaintext in a JSON response.

The JavaScript code will then grab the plaintext from the JSON response and append it to the output field below the form.

Security Considerations

This is just a toy example to illustrate how to use sodium-plus (JavaScript) and libsodium (PHP) to encrypt/decrypt messages.

We took a lot of shortcuts that you won't want to take in a real system (for example: hard-coding the encryption keys, and eschewing error-checking in favor of brevity).

If you'd like to do something more advanced (public-key encryption in JavaScript and the congruent PHP functions), the documentation is available for free online.

Shameless plug: If you're looking for security experts to review your JavaScript or PHP code, check out why you may want to hire Paragon Initiative Enterprises for code audits.

Sodium-Plus: A Positive Cryptography Experience for JavaScript Developers

Scott Arciszewski — Mon, 07 Oct 2019 11:20:51 +0000

Update (2019-10-11): I also published a follow-up to this article that's a bit broader in scope.

If you ask around about implementing encryption or signatures in your apps, chances are someone will tell you to just use libsodium. And this is, truthfully, the correct answer for most people's problems.

However, the incumbent options for libsodium in the JavaScript ecosystem leave a lot to be desired.

In particular, there are two back-end libraries that implement libsodium in JavaScript that I'll be discussing:

sodium-native, which is an unopinionated low-level binding of the C API
libsodium-wrappers (and the other packages in the libsodium.js repository) which is cross-platform but slightly slower than sodium-native

Encrypting a String in Sodium-Native

I bet you think you could just do this and call it a day?

const sodium = require('sodium-native');

// Initialize with random bytes:
let key = sodium.randombytes_buf(32);
let nonce = sodium.randombytes_buf(24);
let message = "This is just an example string. Hello dev.to readers!";

// Encrypt:
let encrypted = sodium.crypto_secretbox_easy(message, nonce, key);

// Decrypt:
let decrypted = sodium.crypto_secretbox_open_easy(encrypted, nonce, key);
console.log(message === decrypted.toString());

Short, sweet, and to the point, right? Nope. That code doesn't work at all.

That snippet of code needs to be written like this:

const sodium = require('sodium-native');

// Initialize with random bytes:
let key = sodium.randombytes_buf(32);
let nonce = sodium.randombytes_buf(24);
let message = Buffer.from("This is just an example string. Hello dev.to readers!");

// Encrypt:
let encrypted = Buffer.alloc(message.length + 16);
sodium.crypto_secretbox_easy(encrypted, message, nonce, key);

// Decrypt:
let decrypted = Buffer.alloc(encrypted.length - 16);
sodium.crypto_secretbox_open_easy(decrypted, encrypted, nonce, key);
console.log(message.toString() === decrypted.toString());

This API is terrible for JavaScript developers: Instead of returning a value, sodium-native overwrites one of the buffers you pass with the return value. Which means you have to allocate (and correctly size) buffers yourself.

Manual buffer allocation, especially to Node.js devs who learned before Buffer.alloc() and Buffer.from() became the norm, almost begs developers to write memory unsafe code. It also breaks if the user provides a string input instead of a Buffer.

Encrypting a String in Libsodium.js

Fortunately, libsodium-wrappers does a fairly good job of exposing a usable in most cases. Except one caveat:

const _sodium = require('libsodium-wrappers');
await _sodium.ready; // You can't use the library until it's ready
const sodium = _sodium;

Henceforth, the API consists entirely of synchronous functions.

const _sodium = require('libsodium-wrappers');

(async function() {
  await _sodium.ready;
  const sodium = _sodium;

  // Initialize with random bytes:
  let key = sodium.randombytes_buf(32);
  let nonce = sodium.randombytes_buf(24);
  let message = "This is just an example string. Hello dev.to readers!";

  // Encrypt:
  let encrypted = sodium.crypto_secretbox_easy(message, nonce, key);

  // Decrypt:
  let decrypted = sodium.crypto_secretbox_open_easy(encrypted, nonce, key);
  console.log(message === decrypted.toString());
})();

Other Differences and Design Warts

Compared with sodium-native, libsodium-wrappers is slightly slower (sodium-native calls a C library, where as libsodium-wrappers compiles the library with emscripten), but it runs in more places (i.e. in web browsers) and doesn't need a C compiler to get running.

Both libraries suffer from a subtle risk with X25519 keypairs: It's easy to accidentally get the public and secret key arguments mixed up and make your protocol insecure (although the unit tests will still pass).

Neither library works well with IDE code completion.

Neither library is particularly well-documented, either.

Because of these grievances, if a developer asked me today which of the two to use in a greenfield development project, I wouldn't be able to recommend either. Which is really sad because the first two sentences of the official libsodium documentation state:

Sodium is a modern, easy-to-use software library for encryption, decryption, signatures, password hashing and more.

It is a portable, cross-compilable, installable, packageable fork of NaCl, with a compatible API, and an extended API to improve usability even further.

So, with that in mind, I'd like to introduce Sodium-Plus to the world.

Introducing Sodium-Plus (Na+)

You can find sodium-plus on Github and install it from NPM.

Sodium-Plus is the libsodium API that JavaScript developers deserve.

const { SodiumPlus } = require('sodium-plus');

(async function() {
    // Select a backend automatically
    let sodium = await SodiumPlus.auto();

    let key = await sodium.crypto_secretbox_keygen();
    let nonce = await sodium.randombytes_buf(24);
    let message = 'This is just a test message';
    // Message can be a string, buffer, array, etc.

    let ciphertext = await sodium.crypto_secretbox(message, nonce, key);
    console.log(ciphertext);
    try {
        let decrypted = await sodium.crypto_secretbox_open(ciphertext, nonce, key);
        console.log(decrypted.toString('utf-8'));
    } catch (e) {
        console.error("Invalid ciphertext throws instead of returning false.");
    }
})();

It's pluggable. You can power it with either sodium-native if you're strictly a Node shop and need the performance, or libsodium-wrappers if you need cross-platform support. You can even install sodium-native on some builds and Sodium-Plus will automatically use it in the default configuration.

It's asynchronous where ever possible.

It's fully type-safe. You'll never accidentally get your public and secret keys mixed up with Sodium-Plus.

const { SodiumPlus } = require('sodium-plus');

(async function() {
    // Select a backend automatically
    let sodium = await SodiumPlus.auto();
    console.log("Selected backend: " + sodium.getBackendName());

    let aliceKeypair = await sodium.crypto_box_keypair();
        let aliceSecret = await sodium.crypto_box_secretkey(aliceKeypair);
        let alicePublic = await sodium.crypto_box_publickey(aliceKeypair);

    // This works:
    let ciphertext = await sodium.crypto_box_seal(plaintext, alicePublic);
    let decrypted = await sodium.crypto_box_seal_open(ciphertext, alicePublic, aliceSecret);

    // These do not:
    try {
        ciphertext = await sodium.crypto_box_seal(plaintext, aliceSecret);
    } catch (e) {
        decrypted = await sodium.crypto_box_seal_open(ciphertext, aliceSecret, alicePublic);
        console.log(e); // TypeError { ... }
    }
})();

Feel free to run this code yourself, both with and without sodium-native.

In virtually every way, we want Sodium-Plus to be an significant usability improvement over the existing libsodium implementations.

Additionally, we want to make sure it's easier to use Sodium-Plus than any other JavaScript cryptography libraries.

What's the Project Status?

As of 2019-10-07:

Version 0.1.0 (the first alpha) has been released, which only contains the most common features of libsodium.
Many APIs (generichash, secretstream, etc.) have not yet been implemented in our library. The documentation has not been completed yet for what is implemented.
However, your IDE will autocomplete correctly (due to our use of docblocks).

Our development roadmap is as follows:

Initial release. We are here.
Collect feedback from developers. (This is where I'd love your help!)
API completeness. (a.k.a. Finish wrapping the other libraries)
Complete the documentation.
Ensure 100% unit test coverage.
Ensure a @types bundle is available for TypeScript users.
Maybe get a security audit? (Not sure if the funding exists for this yet.)
Version 1.0.0. (Expected late 2019.)

Where can I get Sodium-Plus?

Github: https://github.com/paragonie/sodium-plus
NPM: https://www.npmjs.com/package/sodium-plus

The Case for Automatic Updates

Scott Arciszewski — Wed, 31 Jan 2018 15:21:51 +0000

Once a security bug exists in your customer's networks, preventing a security breach involves a lot of moving parts, but most importantly:

Identifying the security bugs before criminals do.
Fixing the security bugs you've identified.
Getting the patch deployed in all of your customer's networks.

Consider the timeline below:

The time between point 0 and point 1 might be years. For the Linux kernel, it's about 5 years on average. There are a lot of ways to reduce this number, and most of them involve automated testing and manual code review from security experts.

The time between point 1 and point 2 might be weeks or months. Our average vulnerability identified-to-fixed time window is less than 24 hours. Most organizations do not enjoy the same agility or expertise.

Most development teams have no control over the time between points 2 and 3 -- the amount of time it take for the fix to be applied (and the vulnerability to be neutralized) after the update is available.

By making updates manual rather than automatic, you're forcing your customers to take all the responsibility for making sure that your mistakes don't hurt their business. Only a very small minority of your customers might prefer the responsibility of verifying and applying each update themselves.

By and large, most people do not have the security awareness, time management, and discipline to undertake this responsibility 24/7/365.

Automatic security updates reduce the interval between points 2 and 3 from possibly infinite to nearly zero. That's clearly a meaningful improvement over manual patch management.

What's the Practical Risk in Outdated Software?

The problem of outdated software is well-studied by the information security industry. According to Verizon's 2015 Data Breach Investigations Report (PDF), for example, when a software vulnerability was used...

99.9% of the exploited vulnerabilities were compromised more than a year after the CVE was published.

In 2016, Wombat Security reflected on similar studies in an article titled Out-of-Date Software and Plug-ins Compound End-User Risk. An article on Help Net Security examines findings from F-Secure and echoes the problem of companies relying on out-dated software and putting their users at risk.

The danger of outdated software is supported by both the data and by simple logic: If criminals are aware of a specific vulnerability in a software product, it doesn't matter that the vendor published a security patch if most of the companies that use their product will remain vulnerable when criminals want to exploit it.

It Seems So Obvious, But...

If 99.9% of real-world software exploits are preventable by keeping software up-to-date, and the danger of unpatched vulnerabilities is well-known among security professionals, the obvious question is, "Why doesn't everything update itself automatically?"

Implementing a secure automatic update mechanism is a nontrivial engineering feat that most programmers don't even know where to begin addressing. And often the ones that think they do are uninformed about the risks and complexity.

Simple and Secure Automatic Software Updates

First, make sure your deliverables are reproducible from the source code. If you're working with scripting languages that are never compiled into binary code, this merely requires your software be open source.

Second, use an update framework (i.e The Update Framework) that enforces code signing. This means that your update files must be signed by a private key controlled only by you, but can be verified by anyone with your public key.

If you don't understand what "private key" or "public key" means, our other dev.to article is an approachable introduction to cryptography terms and concepts and will shed some light on the matter.

Finally, run a Chronicle instance. Every time you release an update, publish the new release information to your Chronicle. Make your code that interfaces with The Update Framework verify that the release you're seeing is also published in the Chronicle (or, especially for enterprise customers, their own replica of your Chronicle that resides on the corporate network).

That's it. The Update Framework (or a similar implementation relevant to your stack) and Chronicle are all you need (as far as tooling goes). Make your software open source, and your builds reproducible, and you'll drastically reduce your customer's attack surface in terms of both space and time.

Secure Automatic Software Updates in PHP

There isn't currently a PHP implementation of The Update Framework. If there's enough community interest, we may commit to building one in the future. However, that might not be necessary.

If you're developing modern PHP, you're almost certainly using Composer and Packagist. If not, it's highly recommended that you learn it ASAP.

In 2017, I opened a proposal to the Packagist team to run their own Chronicle instance, which would be used to publish information about software releases in real time. We're working on other proposals to enforce signature validation and solve the Public Key Infrastructure (PKI) problems.

In other words: If you're using Composer, then in the near future this may already be a solved problem for you.

Secure Automatic Updates for Embedded Devices and the Internet of Things (IoT)

Embedded development faces unique challenges and there hasn't been a lot of guidance on implementing secure automatic update protocols, especially for so-called "smart devices". Due to low memory or power usage requirements, it's often not feasible to just staple cryptography onto your product design without using up your entire power or memory budget.

For extremely constrained devices, libhydrogen is an attractive option. It's very lightweight, and the current implementation uses only two primitives to provide a full-featured cryptography library: the Gimli permutation and Curve25519.

This post merged the important parts of several posts about automatic updates on the Paragon Initiative Enterprises blog. Check our website out if you're interested in building secure PHP software.

Supply Chain Attacks and Secure Software Updates

Scott Arciszewski — Thu, 28 Sep 2017 13:26:08 +0000

I generally don't like writing about current events, because the inherent ephemeral nature of the news means that your words become less meaningful with each passing day. As a professional, I find wasting other people's time in poor taste.

However, the topic of supply chain attacks has come up repeatedly in the recent months, so I'd like to take a moment to reflect on these incidents, as well as the work I've done through Paragon Initiative Enterprises (PIE for short) to be able to solve this problem at scale.

What's a Supply Chain Attack?

In general, a supply chain attack involves first hacking a trusted third party who provides a product or service to your target, and then using your newly acquired, privileged position to compromise your intended target.

More narrowly, we're only interested in supply chain attacks which involve compromising the companies that produce software used by other companies. Hardware based supply chain attacks have been demonstrated by leaked documents concerning nation state actors.

A Recent History of Supply Chain Attacks

Rather than rehash the long history of supply-chain attacks (both theoretical and actual) and the motivation for virtually every Linux distro to PGP-sign their update information, let's just look at what's happened in the year 2017.

The industry's first wake-up call in recent months was a ransomware called NotPetya that was spread throughout Ukraine through the auto-update mechanism for M.E.Doc, one of the few government-approved accounting softwares.

Last month, Kaspersky Lab's research teams published a write-up about a malware campaign called ShadowPad, which infected a software update for an unspecified product by a company called NetSarang. The product in question is reportedly used by hundreds of large firms, especially in the energy sector, so the long-term impact of such an infection (if undetected) is best left to the imagination.

Most recently, but certainly not finally, we learned that the most recent updates for a common Windows utility called CCleaner had also been infected with malware.

The Common Denominator in Recent Supply-Chain Attacks

In each of these recent cases, malicious actors had compromised a software company and infected the "legitimate" copy of the software that users would download and install.

In some of these cases, an automatic update mechanism was used to deliver the payloads. However, it is erroneous to call out auto-update features as the reason for infection. If a malicious and signed binary was uploaded to a company website, the fact that updates have to be performed manually would not have helped the victims. They would just happily install it, none the wiser.

In all of these cases, the malicious software update was spread to everyone who installed it, rather than a targeted attack against only networks of interest. I'd wager that there are some of these going on in the wild as I type this, but they're inherently much more difficult to detect.

The real security problem here has very little to do with automation.

The Fundamental Problem with Software Update Security

The reason that supply chain attacks are viable, effective, and often difficult to detect is that very little (if any) industry attention is given towards guaranteeing Software Authenticity.

This is a topic we have covered extensively:

If you read only one of the above links, read the one from August 2017.

Our company has done a lot of work in between client engagements to make it easier for developers to make their software updates signed, auditable, and reproducible. This does several things:

Signed: If the signing key is kept offline, even if the webserver or update server is compromised, the malware will not be accepted by the end user's computer. This is a nontrivial impediment to supply chain attacks, provided the company in question has adequate discipline to keep their signing key secret.
Auditable: Even with a pilfered signing key, with this guarantee in place, attacks will be unavoidably detectable due to each update being committed to an append-only data structure (e.g. a Merkle tree or hash chain). This also ensures that everyone gets the same update and prevents targeted attacks (which, as mentioned above, haven't yet been detected, but cannot be ruled out).
Reproducible: With open source software and reproducible builds, users can verify that the binary they received corresponds to the expected version of the software they intended to install. Combined with the auditability guarantee, if even one power user or security expert inspects the source code for backdoors, that's sufficient to ensure that all other copies of the same update are authentic.

If all three guarantees are provided, it's even generally safer to deploy your updates automatically (by default; power users should be allowed to disable this mechanism).

Furthermore, because of these guarantees, most attackers will be dis-incentivized to even attempt such an attack: The success of their campaign hinges on their ability to steal a cryptography key, they can't target networks or persons of interest, the likelihood of being caught very early is extraordinarily high.

If we can make all software updates come with authenticity guarantees, I believe we will all-but-eliminate supply chain attacks in the real world.

Does This Really Matter?

We've consistently focused on the problem of ensuring software updates are secure enough to automate since our company's inception.

We strongly believe that solving this problem at scale will have a more profound impact on the security of the Internet than almost any other problem in all of information security and applied cryptography.

"Wait, I Think I Can Solve This Using [Buzzword]"

If you're looking for a killer app cybersecurity solution to these sort of attacks, the answer involves a lot of inglorious janitorial work cleaning up the software ecosystem and assisting open source software projects to get on board with scalable and trustworthy solutions.

This is not a problem that necessarily needs a blockchain to solve.

It's not a problem that traditional endpoint security (read: anti-virus software) is even in the correct genre to a solution.

No, we're going to need to solve this as a community, not an industry. That means a lot of dedicated security experts and developers working together. That means a lot of short-term developer hours expended to improve the long-term health of your companies.

I fully anticipate that charlatans and snake-oil salesmen will come out of the woodwork to pitch their poorly thought-out solutions to supply chain attacks as increasing number of computer criminals find them to be an effective way to infect victims. Even more hours will likely be expended on debunking their fraudulent claims and alerting the uninformed of their deception.

But in the end? If we, as a community—as a society—can work together to solve the problem of secure software updates for the Internet at large? It will all be worth it.

This was originally published on the PIE blog

Libsodium Quick Reference

Scott Arciszewski — Mon, 19 Jun 2017 07:44:53 +0000

If you're not familiar with cryptography terminology, read this page first. It covers everything from terms (e.g. nonce) to concepts (e.g. public-key encryption).

At Day Camp 4 Developers, I presented a talk titled Cooking with Sodium in PHP 7.2, which was largely live-demoing the various cryptography features provided by libsodium. One of the questions I was asked by attendees was about knowing which feature to use to solve specific problems. This is the sort of problem that I suspect many people run into, so here's a quick reference table followed by a detailed explanation.

In the table below, all encryption modes utilize authenticated encryption.

Libsodium Function	Type	Notes / Use Case
Libsodium Function	Type	Notes / Use Case
crypto_pwhash	Password hashing	Secure password storage, key derivation from user input
crypto_generichash	Cryptographic hash function	Collision- and preimage-resistant; replace MD5/SHA1/etc.
crypto_shorthash	Short-input hash function	Hash tables, bloom filters, cache lookup keys
crypto_auth	Symmetric authentication	Both parties can verify and/or forge messages
crypto_sign	Asymmetric authentication	Digital signature (anyone can verify, only sender can sign)
crypto_aead_*	Symmetric encryption	Shared-secret encryption with additional data
crypto_secretbox	Symmetric encryption	Compatibility with NaCl, TweetNaCl, etc.
crypto_box	Asymmetric encryption	Both sender and receiver can decrypt
crypto_box_seal	Asymmetric encryption	Only receiver can decrypt; sender is anonymous

Solving Common Tasks with Libsodium

I need to store an encrypted or hashed password (actually never encrypted, only hashed)

Use crypto_pwhash_str() and crypto_pwhash_str_verify().

I need to encrypt a string and then decrypt it later (on the same machine)

For simplicity: use crypto_secretbox() and crypto_secretbox_open().

It's actually better to use crypto_aead_* (especially if you use the sample code, but the secretbox API is simple and secure.

I need to encrypt a string and then decrypt it later (on a different machine)

It depends!

Do you have a two-way data flow (A <=> B) or a one-way data flow (A -> B)?

If you're only ever encrypting on Node A, and only ever decrypting on Node B, you'll want crypto_box_seal() and crypto_box_seal_open(). This prevents the sender (Node A) from decrypting messages after they've been sent to recipient (Node B).

Otherwise, you'll simply want to use crypto_box() and crypto_box_open().

I previously used mcrypt_encrypt() or openssl_encrypt() and need to migrate my data

First, decrypt your data as usual, then re-encrypt using crypto_secretbox() and crypto_secretbox_open().

I previously used openssl_public_encrypt() / openssl_private_decrypt() and need to migrate my data

First, decrypt your data as usual, then re-encrypt using crypto_box or crypto_box_seal (see previous answer about encryption between different machines for guidance on which one you want).

Libsodium Function Analysis

PHP Developers: In PHP before 7.2 with libsodium from PECL, the functions below were defined in the Sodium name space. In PHP 7.2, the namespaces were dropped in favor of a sodium_ prefix (to conform to the PHP internal development standards).

For example, in PHP 7.1 and below with ext/sodium from PECL, an example snippet for crypto_secretbox() might look like this:

<?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);

When PHP 7.2 is released, the interface will look like this instead:

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

For sodium_compat users, your code will look like this:

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

In the examples below, when we define a libsodium function, the actual function name will be either namespaced, prefixed, or a static method on ParagonIE_Sodium_Compat. For simplicity, we're using the bare libsodium name since that part remains constant.

Hash Functions

crypto_pwhash()

Choose your own adventure:

Key derivation: crypto_pwhash()
Password hashing/verification: crypto_pwhash_str() and crypto_pwhash_str_verify()

Libsodium uses Argon2, the Password Hashing Competition winner. More specifically, it uses Argon2i (the side-channel resistant variant) in all current versions, but a future version may switch the default to Argon2id, which is more resistant to GPU attacks.

You want to use one of the crypto_pwhash functions whenever you are taking a user-provided input (i.e a password) and your goal is to either:

turn their password into a cryptography key, or
store it for secure verification at a later date

Make sure you check the official libsodium documentation covering crypto_pwhash for details on how to use it.

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($password, $storeInDatabase)) {
    /* Logged in! */
} else {
    /* Incorrect password. */
}

crypto_generichash()

For PHP developers: This is sort of like hash(), except it can also be hash_hmac() if you pass a key, and it only allows BLAKE2b (so you don't have to select the algorithm).

You want to use crypto_generichash() anywhere you'd normally use hash(), md5(), or sha1() (unless "normally" implies something that would cause a cryptographer would look at you funny). crypto_generichash() is attractive because it is all of the following:

Collision-resistant
Preimage-resistant
Immune to length-extension attacks
More secure than SHA256
Faster than MD5

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()

SipHash, the algorithm powering crypto_shorthash(), is a secure keyed pseudo-random function. Or, in other words, it's a hash function like BLAKE2b, except it's only meant to be used with a key and its output size of 64 bits is too small to be collision-resistant or immune to brute-force searches.

Don't use crypto_shorthash() in places where crypto_generichash() would be appropriate. SipHash is better suited for building hash tables with a per-request key to resist hash-collision denial-of-service attacks. You can also use it for Bloom filters and cache lookups where micro-benchmarks matter. But generally, crypto_generichash() and crypto_pwhash() are probably better tools for the job.

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() is from NaCl, and serves to provide symmetric-key authentication. If you know about HMAC, you know what this does. PHP developers will only really only need crypto_auth() and its counterpart crypto_auth_verify() if you're aiming to interoperate with other NaCl/libsodium projects. Otherwise, hash_hmac() and hash_equals() accomplish the same thing.

crypto_auth() is, in fact, HMAC-SHA512 truncated to 32 bytes.

It is important to note that, with HMAC, any party capable of verifying messages is also capable of signing them. That's what symmetric-key authentication means. If you need one entity to be able to sign, but everyone else in the universe to be able to only verify, then you want crypto_sign() instead.

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()

The crypto_sign functions come in two flavors:

crypto_sign() and crypto_sign_open(), which are useful for sending signed messages in one go.
crypto_sign_detached() and crypto_sign_verify_detached(), which are more generally useful.

Generally, you'll find yourself reaching for the latter two more in PHP land, but the original two are useful too.

Unlike crypto_auth, crypto_sign utilizes asymmetric (a.k.a. public-key) cryptography. You sign a message with your secret key, and anyone with your public key can verify the message.

Once again, the libsodium documentation for crypto_sign is worth a read.

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()

AEAD is a cryptographer acronym that stands for Authenticated Encryption with Associated Data. The general idea is that you have:

Your plaintext, which gets encrypted into the ciphertext.
Some other data, which doesn't touch the ciphertext.
An authentication tag, which covers both the ciphertext and the other data.

You want to use crypto_aead when you have either a pre-shared key or a negotiated one (e.g. via Elliptic Curve Diffie-Hellman).

AEAD modes are the preferred way to encrypt in 2017. Libsodium offers several options for its AEAD interface, all of which implement symmetric encryption. You will probably want to use, in order of preference:

(One day): crypto_aead_encrypt() and crypto_aead_decrypt()
- Not available yet.
- Will be available after the selection of CAESAR finalists.
crypto_aead_xchacha20poly1305_ietf_*()
- Allows you to use very large nonces, which can safely be generated randomly with no practical risk of accidental nonce reuse.
crypto_aead_chacha20poly1305_ietf_*()
- The standardized ChaCha20-Poly1305 variant.
crypto_aead_aes256gcm_*()
- Required specialized hardware support. Only use this if every device is guaranteed to have modern processors.
crypto_aead_chacha20poly1305_*()
- Implemented before the IETF standardized their nonce/counter sizes for use in TLS. Less widely supported.

The AEAD section of the libsodium documentation has more details about key/nonce sizes, etc.

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() is from NaCl and implements symmetric (shared-key) authenticated encryption. secretbox accepts a large nonce, which is safe to generate randomly (random_bytes() in PHP, randombytes_buf() in libsodium) and virtually never worry about reusing a nonce.

You want to use crypto_secretbox() when you have either a pre-shared key or a negotiated one (e.g. via Elliptic Curve Diffie-Hellman).

If you have to choose between secretbox and aead_xchacha20poly1305, go for the AEAD mode. Otherwise, use secretbox.

The relevant section of the libsodium documentation for crypto_secretbox can be found here.

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 is from NaCl and implements authenticated asymmetric (a.k.a. public-key) encryption. With crypto_box(), both the sender and recipient can read messages and verify the other party sent them. However, it allows each party to negotiate their own private keys and share distinct secrets with each other, so talking with one person doesn't allow you to eavesdrop on another's conversations with them.

You want to use crypto_box() where you'd normally implement RSA encryption. It's more commonly found in interactive protocols (e.g. messaging applications).

To learn more, see the libsodium documentation for 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() is a libsodium exclusive, which allows the sender to encrypt a message that only the recipient can decrypt. Sealing APIs are sometimes referred to as anonymous public-key encryption, because although it provides ciphertext integrity, the sender is not authenticated like with crypto_box.

You want to use crypto_box_seal whenever you're encrypting information that you don't want the sender to be able to decrypt. For example, storing encrypted data in an online database that can only be decrypted with key that is kept offline in an air-gapped machine.

If you're trying to decide between crypto_box() versus crypto_box_seal(), ask yourself if the system that performed the encryption should be capable of decrypting the messages they sent. If the answer is no, you want crypto_box_seal(). If you still need the sender to be authenticated, use crypto_sign() before crypto_box_seal() on the sending side and crypto_sign_open() after crypto_box_seal_open() on the receiving side.

As always, the documentation for crypto_box_seal explains its usage in-depth.

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);

Other Functions

If you're confused about any of the libsodium functions not listed here, refer to the official libsodium documentation.

This was originally published on our company website. All of our blog posts are released under a Creative Commons License.

PHP 7.2: The First Programming Language to Add Modern Cryptography to its Standard Library

Scott Arciszewski — Sun, 12 Feb 2017 22:36:34 +0000

You Wouldn't Base64 a Password! Cryptography Terms and Concepts for Developers

Scott Arciszewski — Tue, 13 Dec 2016 21:57:50 +0000

Originally published at: You Wouldn't Base64 a Password! on the Paragon Initiative Enterprises blog

There's a ton of bad programming and security advice on the Internet. Some of the advice is bad because the author is misinformed, some because it emphasizes precision over clarity and most people wind up lost in the jargon.

If you feel that cryptography is a weird, complicated, and slightly intimidating subject for which your feelings might be best described as lukewarm (on a good day), we hope that by the time you finish reading this page, you will have a clear understanding of the terms and concepts people use when this topic comes up.

Warning: The example snippets on this page are for illustrative purposes. Don't use them in your projects. If you want a real-world example to reference, check out the snippets in our Chief Development Officer's StackOverflow answer instead.

Basic Cryptography Concepts for Developers

Let's start with a basic question: What exactly is a cryptographic feature? In the simplest terms we can muster: Cryptographic features use math to secure an application.

Digging a little deeper: there are a plethora of cryptography algorithms and they can generally be grouped together based on two criteria:

How much information must be supplied by the developer?
What is the intended goal?
- Confidentiality?
- Integrity?
- Authenticity?
- Non-repudiation? Deniability? (These two are opposites.)

Overview of Cryptography Concepts

Keyless Cryptography (0 keys)
- Hash Functions
Secret-Key Cryptography (1 key)
- Secret-Key Message Authentication
- Secret-Key Encryption
- Authenticated Secret-Key Encryption
Public-Key Cryptography (2 keys)
- Shared Secret Key Agreement
- Digital Signatures

The First Rule of Cryptography: Don't Implement it Yourself

Developing cryptography features is best left to the experts. By all means, do feel free to tinker, but don't deploy your experiments in production or share them with other developers who might deploy them in production.

Instead, use a high-level cryptography library that experts have already vetted. Follow the link to read our PHP cryptography library recommendations.

Keyless Cryptography

The simplest algorithm to consider is the cryptographic hash function, which accepts one input and returns a single deterministic fixed-size output.

hash("sha256", "");
// e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

hash("sha256", "The quick brown fox jumps over the lazy dog");
// d7a8fbb307d7809469ca9abcb0082e4f8d5651e46d3cdb762d02d0bf37c9e592

When using a well-designed cryptographic hash function, such as BLAKE2 or SHA256, any change you make to the message will result in a drastically different hash output.

hash("sha256", "The quick brown fox jumps over the lazy cog");
// e4c4d8f3bf76b692de791a173e05321150f7a345b46484fe427f6acc7ecc81be

Simple hash functions are fast and deterministic; if you have any arbitrary message, you can calculate the hash output for that particular message. By themselves, they are mostly useful for error checking or as a building block for other cryptographic primitives, which most developers will not need to develop.

Cryptographic hash functions are one-way data transformations. Although you can easily calculate the hash output (often referred to as a message digest) for any arbitrary message, you cannot easily go from the hash output to the original message.

Some hash functions (such as MD5) have weaker security guarantees and smaller output sizes. As a result, it's almost trivial to calculate two different messages that will produce the same MD5 hash.

Secret Key Cryptography

Most cryptography algorithms aren't as simple as hash functions. As a consequence, they are a lot more useful and can provide security guarantees beyond, "Yes, this output can be reproduced from this input."

Consequently, they typically require two pieces of input: The message and a secret key. A secret key should be a unique string of random bytes that both the sender and intended recipient should know, and nobody else.

Keyed Hash Functions - Message Authentication

A keyed hash function, such as HMAC, is a special implementation of a hash function that accepts a message and a secret key and produces a Message Authentication Code (MAC).

hash_hmac("sha256", "The quick brown fox jumps over the lazy dog", "secret key");
// 4a513ac60b4f0253d95c2687fa104691c77c9ed77e884453c6a822b7b010d36f

hash_hmac("sha256", "The quick brown fox jumps over the lazy cog", "secret key");
// ed6b9bc9d64e4c923b2cc19c15fff329f343f30884935c10e617e0fe067adef1

hash_hmac("sha256", "The quick brown fox jumps over the lazy dog", "secret kez");
// 291579f3123c3126df04a57f78768b6290df93f979b86af25fecd98a9811da5a

hash_hmac("sha256", "The quick brown fox jumps over the lazy cog", "secret kez");
// 298bb0244ebc987810de3892384bb4663742a540db2b3a875f66b09d068d1f64

Keyed hash functions are more useful than hash functions; only someone with the secret key can calculate a MAC for a given message. Therefore, if you transmit a message and a MAC for a given message, and never transmit the secret key, you can be reasonably sure that the message is authentic.

Secret Key Encryption

Warning: Encryption without message authentication is vulnerable to chosen ciphertext attacks. Please read our whitepaper on Secure Data Encryption in PHP.

Formally, encryption is the reversible process of transforming of a message (called the plaintext) and a secret key into a seemingly random string of bytes (called the ciphertext). i.e. encrypt($message, $key) should return a unique string of random bytes for a given pair of $message and $key.

Unfortunately, simple secret-key encryption (also known as ECB mode) is not secure. If you encrypt the same (16-byte, for the popular AES encryption algorithm) block within a message with the same key in ECB mode, the ciphertext will repeat.

Modern secret-key encryption, therefore, actually accepts more than two pieces of information. Beyond the plaintext message and a secret key, they also require a unique Initialization Vector (IV, for CBC mode) or nonce (number to be used once, for CTR mode). The difference between a nonce and IV is subtle.

None of the code on this page is secure; neither are any of the encryption keys.

/**
 * This code is for example purposes only. DO NOT USE IT.
 * Use https://github.com/defuse/php-encryption instead
 * 
 * Demo: http://3v4l.org/ih8om
 */
bin2hex(
    openssl_encrypt(
      /* Message: */
        "The quick brown fox jumps over the lazy dog",
      /* Cipher algorithm and block mode: */
        'aes-128-ctr',
      /* Encryption key: (don't use weak keys like this ever, it's just an example!): */
        "\x01\x02\x03\x04" . "\x05\x06\x07\x08" . "\x09\x0a\x0b\x0c" . "\x0d\x0e\x0f\x10",
      /* Constant that means "don't encode": */
        OPENSSL_RAW_DATA,
      /* Initialization Vector or Nonce -- don't ever actually use all NULL bytes: */
        str_repeat("\0", 16) // This is a really bad way to generate a nonce or IV. 
    )
);
// 8f99e1315fcc7875325149dda085c504fc157e39c0b7f31c6c0b333136a7a8877c4971a5ce5688f94ae650

/**
 * This code is for example purposes only. DO NOT USE IT.
 * Use https://github.com/defuse/php-encryption instead
 * 
 * Demo: http://3v4l.org/ZgW38
 */
openssl_decrypt(
  /* Message: */
    hex2bin(
        "8f99e1315fcc7875325149dda085c504fc157e39c0b7f31c6c0b333136a7a8877c4971a5ce5688f94ae650"
    ),
  /* Cipher algorithm and block mode: */
    'aes-128-ctr',
  /* Encryption key: (don't use weak keys like this ever, it's just an example!): */
    "\x01\x02\x03\x04" . "\x05\x06\x07\x08" . "\x09\x0a\x0b\x0c" . "\x0d\x0e\x0f\x10",
  /* Constant that means "don't encode": */
    OPENSSL_RAW_DATA,
  /* Initialization Vector or Nonce -- don't ever actually use all NULL bytes: */
    str_repeat("\0", 16) // This is a really bad way to generate a nonce or IV.
);
// The quick brown fox jumps over the lazy dog

A more in-depth and less illustrative example (which properly generates IVs) is available here.

For a closer examination at symmetric-key encryption with OpenSSL, read our white paper.

Decryption is only successful if the same IV/nonce and secret key are used. However, only the key must be kept secret; the IV and nonce can even be broadcast with your encrypted message.

Authenticated Secret-Key Encryption

If you recall from our earlier blog post, Using Encryption and Authentication Correctly, secret-key encryption itself is vulnerable to tampering unless you combine it with authentication.

The only strategies proven to be secure are to use an AEAD mode or to always encrypt first then authenticate the encrypted data with a MAC.

If you are following an Encrypt-Then-MAC construction, you want to use two separate secret keys: One for the encryption, the other for the MAC. In other words, apply the previous two sections together:

/**
 * This code is for example purposes only. DO NOT USE IT.
 * Use https://github.com/defuse/php-encryption instead
 */
$nonce = random_bytes(16);
$ciphertext = openssl_encrypt(
  /* Message: */
    "The quick brown fox jumps over the lazy dog",
  /* Cipher algorithm and block mode: */
    'aes-128-ctr',
  /* Encryption key: (don't use weak keys like this ever, it's just an example!)
   *    Instead, you want to generate 16, 24, or 32 random bytes (i.e. random_bytes(16))
   *    on your own. It's generally a bad idea to copy and paste security code.
   */
    "\x01\x02\x03\x04" . "\x05\x06\x07\x08" . "\x09\x0a\x0b\x0c" . "\x0d\x0e\x0f\x10",
  /* Constants that mean "don't encode" and "we have no padding" to the OpenSSL API: */
    OPENSSL_RAW_DATA + OPENSSL_ZERO_PADDING,
  /* Initialization Vector or Nonce: */
    $nonce
);
// You should choose a better HMAC key than we did for this article:
$mac = hash_hmac("sha256", $nonce.$ciphertext, "\xff\xfe\xfd\xfc" . "\xfb\xfa\xf9\xf8" . "\xf7\xf6\xf5\xf4" . "\xf3\xf2\xf1\xf0", true);
echo bin2hex($nonce.$ciphertext.$mac);
/*
   71b5546f 6cb857cd 0d8f8be3 f9312c74 <- Nonce (randomly chosen)
   356146df 274552c2 e98d3008 b1dfa35c <- Ciphertext
   60d6130d 9c9ca525 6c2f2f25 0b321176
   06563174 c3b073a0 5ab263
   4d1c7416 b086a316 a0474a05 84e3793c <- MAC
   a32fde09 0d82a5ef 213cb329 da3b5b06 
 */

It is important to exercise caution when combining cryptographic features. Our basic protocol as written above has no redundant features:

Secret key encryption provides confidentiality such that it can only be read with the correct secret key.
Keyed hash functions provide authentication (and consequently, message integrity) such that anyone possessing the correct secret key can recalculate the same MAC.
A random IV/nonce is used to make each encrypted message unique, even if the unencrypted message is the same.

It should go without saying, but double-encrypting or double-authenticating when you need authenticated encryption would just be silly.

Public Key Cryptography

Public key cryptography is challenging for nontechnical people to understand, and even more challenging for technical people to explain correctly without burying the reader in mathematics or missing critical points. The end result is usually a lot of confusion and occasionally a false sense of understanding. (A fauxreka moment, if you will.)

Here's all you need to know right now: Unlike secret key encryption, which involves a single secret key that is held by both parties, in public key cryptography, each participant has two keys:

Each participant has a private key, which they never share.
Each participant also has a public key, which is mathematically related to their private key, which they share with everyone.

It is unfortunate that the "key" terminology from secret key cryptography stuck when public key cryptography was discovered, as there aren't very many physical systems that are intuitively similar to what's going on here. Some people have attempted to explain public key cryptography using colors or detailed explanations. If you're interested in the intimate details, we recommend both of the links in the previous sentence.

For everyone else, if you can accept these premises, understanding the rest isn't hard:

To use public key cryptography, you generate a key-pair and share the public key, but keep the private key to yourself. (In most cases, every participant does this.)
There is only one private key for any given public key.
Both of the keys in a given key-pair are related to each other, mathematically.
Given a public key, it is almost impossible to figure out what the private key is.
Given a private key, you can near-instantly calculate the related public key.

Got it? Let's build something with this understanding.

Shared Secret Key Agreement

Let's say you want to talk to a friend over the Internet using secret key cryptography (which is much faster than public key cryptography), but you don't want anyone else to read it. You and her haven't already agreed upon a secret key. How do you do it?

Glossing over the finer details (the color video above explains it fairly well), this is what you do:

You send her your public key (yellow).
She sends you her public key (light blue).
Combine your private key (green) and her public key (blue) to form a shared secret key.
She will combine her private key (red) with your public key (yellow) to form the same exact shared key.

How? Modular arithmetic (classic Diffie Hellman) or multiplication along elliptic curves over finite fields (modern Elliptic Curve Diffie Hellman).

Digital Signatures

Digital signature algorithms, such as EdDSA (Edwards-curve Digital Signature Algorithm), are one of the most useful innovations to result from public key cryptography.

A digital signature is calculated from a message and a private key. Earlier algorithms (such as ECDSA) also required you to generate a unique random nonce for each message, but this was proven to be error-prone in the real world.

Anyone else with a copy of your public key can verify that a particular message was signed by your private key. Unlike keyed hash functions, this verification takes place without requiring you to reveal your private key.

Common Misconceptions and Pitfalls

Password Storage

Quick answer: Just use bcrypt. For PHP developers, this means password_hash() and password_verify() rather than crypt().

Many developers think passwords should be encrypted, but this is false. Passwords should be *hashed*, not encrypted. Furthermore, don't confuse password hashing algorithms with simple cryptographic hash functions. They're not the same thing:

Cryptographic Hashes	Password Hashes
Fast Only one input: The message	Intentionally slow At least three inputs: The password A per-user salt A cost factor (how expensive to make the computation)

Unlike cryptographic hashes, password hashes require more than one input parameter. But unlike encryption algorithms, password hashes are one-way deterministic trap door calculations. Also unlike secret-key encryption, the salt does not need to remain secret; it merely needs to be unique per user. The purpose of a unique salt per user is to thwart pre-computation and to make brute-force guessing passwords from a list of hashes more expensive.

Can I encrypt my (bcrypt) password hashes?

Yes. If you run your web application and your database on separate hardware servers, this actually provides a substantial defense in depth. That's the reasoning behind our password_lock library.

File Verification

Digital signatures can prove authenticity, cryptographic hash functions can not.

There is a nontrivial portion of technical users that will, upon downloading an executable from a website, recalculate the MD5 or SHA1 hash of the file and compare it to one displayed on the web page they downloaded the file from. If it matches, they will execute the file, fully trusting its contents to be genuine.

If both the file and the hash value are stored on the same server, this is a completely ludicrous waste of time: Any attacker who can alter your download can replace the hashes on the web page too. (If the file and hash are on separate servers, the situation is a little different, but the improvement is not significant enough to warrant eschewing a better solution.)

After all, as we said above, hash functions like MD5 and SHA1 produce a deterministic fixed-size output for a given input. There are no secrets involved. When a solution does not increase security but makes people feel more secure, we call them security theater.

Cryptographic hash functions are security theater in this situation. You want digital signatures instead.

To improve security, instead of posting MD5/SHA1 hashes, the software vendor can instead sign their package with their EdDSA private key and share their EdDSA public key far and wide. When you download the file, you should also download the signature and, using the verified public key, check that it is authentic.

For example: Minisign.

A keyed hash function won't work here either, as you would need to distribute the secret key in order for anyone to be able to verify the signature. If they have the secret key, they can forge their own signatures for maliciously altered message (in this case, executable file).

Digital signatures are the best way to achieve assurance about the authenticity of a download. MD5/SHA1 hashes are almost always useless here.

Encoding and Compression Aren't Cryptographic

A common beginner's mistake is to use an encoding function, such as base64_encode(), to attempt to obfuscate information. Consider the following code, which was offered in a LinkedIn discussion about how to properly store passwords in a PHP web application:

This may very well be the worst password storage function ever written.

A lot of developers will either encode or compress information and assume their solution provides the same level of security as actual cryptographic features simply because the output is not human readable. It doesn't.

Encoding and compression algorithms are both reversible, keyless transformations of information. Encoding specifies how information should be represented in human-readable text. Compression attempts to reduce an input to as little space as possible. Both are useful, but they are not cryptographic features.

Recap

Cryptographic hash algorithms (e.g. SHA256) are deterministic one-way algorithms that require zero keys.
Keyed hashing algorithms (e.g. HMAC) are used for authentication in secret-key cryptography; requires one key.
Secret-key encryption algorithms (e.g. AES-CTR) are used to transform messages so only someone possessing the secret key can reverse; requires one key.
Shared secret agreement algorithms (e.g. ECDH) are used to negotiate a shared secret key while only requiring the public transmission of both party's public keys. Requires four keys (two pairs of private/public) to generate a fifth.
Digital signature algorithms (e.g. Ed25519) are used to sign messages (with one's private key) that anyone possessing the corresponding public key can validate. Requires two keys.
Password hashing algorithms (e.g. bcrypt) are slow hashing algorithms designed specifically for being difficult to efficiently attack with a brute force search. Requires one secret input and a per-user salt.
Encoding algorithms (e.g. Base64) are not cryptographic.
Compression algorithms (e.g. gzip) are not cryptographic.

Keep in Mind

Don't encrypt passwords. Instead, hash them with a password hashing algorithm. (You may encrypt the hashes.) Hash functions like MD5, SHA1, and SHA256 are not encryption. Anyone who uses the phrase "password encryption" probably needs to read this entire page carefully, because they are deeply mistaken.
Secret-key encryption without message authentication is insecure (it's vulnerable to chosen ciphertext attacks).
For downloads: digital signatures prove authenticity, hashes do not. You want a Minsign or GPG signature, not an MD5 hash.

We hope that this post serves as a good introduction to cryptography concepts. Our team publishes new posts about cryptography, application security, and web development in PHP anywhere from 2 to 5 times per month (usually on Friday). We also offer code review and technology consulting services.