php-encryption
===============

This is a class for doing symmetric encryption in PHP. **Requires PHP 5.4 or newer.**

[![Build Status](https://travis-ci.org/defuse/php-encryption.svg?branch=master)](https://travis-ci.org/defuse/php-encryption)

Implementation
--------------

Messages are encrypted with AES-128 in CBC mode and are authenticated with
HMAC-SHA256 (Encrypt-then-Mac). PKCS7 padding is used to pad the message to
a multiple of the block size. HKDF is used to split the user-provided key into
two keys: one for encryption, and the other for authentication. It is
implemented using the `openssl_` and `hash_hmac` functions.

Warning
--------

This is new code, and it hasn't received much review by experts. I have spent
many hours making it as secure as possible (extensive runtime tests, secure
coding practices), and auditing it for problems, but I may have missed some
issues. So be careful. Don't trust it with your life. Check out the open GitHub
issues for a list of known issues. If you find a problem with this library,
please report it by opening a GitHub issue.

That said, you're probably much better off using this library than any other
encryption library written in PHP. 

Philosophy
-----------

This library was created after noticing how much insecure PHP encryption code
there is. I once did a Google search for "php encryption" and found insecure
code or advice on 9 of the top 10 results.

Encryption is becoming an essential component of modern websites. This library
aims to fulfil a subset of that need: Authenticated symmetric encryption of
short strings, given a random key.

This library is developed around several core values:

- Rule #1: Security is prioritized over everything else.

    > Whenever there is a conflict between security and some other property,
    > security will be favored. For example, the library has runtime tests,
    > which make it slower, but will hopefully stop it from encrypting stuff
    > if the platform it's running on is broken.

- Rule #2: It should be difficult to misuse the library.

    > We assume the developers using this library have no experience with
    > cryptography. We only assume that they know that the "key" is something
    > you need to encrypt and decrypt the messages, and that it must be
    > protected. Whenever possible, the library should refuse to encrypt or
    > decrypt messages when it is not being used correctly.

- Rule #3: The library aims only to be compatible with itself.

    > Other PHP encryption libraries try to support every possible type of
    > encryption, even the insecure ones (e.g. ECB mode). Because there are so
    > many options, inexperienced developers must make decisions between
    > things like "CBC" mode and "ECB" mode, knowing nothing about either one,
    > which inevitably creates vulnerabilities.

    > This library will only support one secure mode. A developer using this
    > library will call "encrypt" and "decrypt" not caring about how they are
    > implemented.

- Rule #4: The library should consist of a single PHP file and nothing more.

    > Some PHP encryption libraries, like libsodium-php [1], are not
    > straightforward to install and cannot packaged with "just download and
    > extract" applications. This library will always be just one PHP file
    > that you can put in your source tree and require().

References:

    [1] https://github.com/jedisct1/libsodium-php