4 This is a class for doing symmetric encryption in PHP. **Requires PHP 5.4 or newer.**
6 [![Build Status](https://travis-ci.org/defuse/php-encryption.svg?branch=master)](https://travis-ci.org/defuse/php-encryption)
11 Messages are encrypted with AES-128 in CBC mode and are authenticated with
12 HMAC-SHA256 (Encrypt-then-Mac). PKCS7 padding is used to pad the message to
13 a multiple of the block size. HKDF is used to split the user-provided key into
14 two keys: one for encryption, and the other for authentication. It is
15 implemented using the `openssl_` and `hash_hmac` functions.
20 This is new code, and it hasn't received much review by experts. I have spent
21 many hours making it as secure as possible (extensive runtime tests, secure
22 coding practices), and auditing it for problems, but I may have missed some
23 issues. So be careful. Don't trust it with your life. Check out the open GitHub
24 issues for a list of known issues. If you find a problem with this library,
25 please report it by opening a GitHub issue.
27 That said, you're probably much better off using this library than any other
28 encryption library written in PHP.
33 This library was created after noticing how much insecure PHP encryption code
34 there is. I once did a Google search for "php encryption" and found insecure
35 code or advice on 9 of the top 10 results.
37 Encryption is becoming an essential component of modern websites. This library
38 aims to fulfil a subset of that need: Authenticated symmetric encryption of
39 short strings, given a random key.
41 This library is developed around several core values:
43 - Rule #1: Security is prioritized over everything else.
45 > Whenever there is a conflict between security and some other property,
46 > security will be favored. For example, the library has runtime tests,
47 > which make it slower, but will hopefully stop it from encrypting stuff
48 > if the platform it's running on is broken.
50 - Rule #2: It should be difficult to misuse the library.
52 > We assume the developers using this library have no experience with
53 > cryptography. We only assume that they know that the "key" is something
54 > you need to encrypt and decrypt the messages, and that it must be
55 > protected. Whenever possible, the library should refuse to encrypt or
56 > decrypt messages when it is not being used correctly.
58 - Rule #3: The library aims only to be compatible with itself.
60 > Other PHP encryption libraries try to support every possible type of
61 > encryption, even the insecure ones (e.g. ECB mode). Because there are so
62 > many options, inexperienced developers must make decisions between
63 > things like "CBC" mode and "ECB" mode, knowing nothing about either one,
64 > which inevitably creates vulnerabilities.
66 > This library will only support one secure mode. A developer using this
67 > library will call "encrypt" and "decrypt" not caring about how they are
70 - Rule #4: The library should consist of a single PHP file and nothing more.
72 > Some PHP encryption libraries, like libsodium-php [1], are not
73 > straightforward to install and cannot packaged with "just download and
74 > extract" applications. This library will always be just one PHP file
75 > that you can put in your source tree and require().
79 [1] https://github.com/jedisct1/libsodium-php