80 lines
3.4 KiB
Markdown
80 lines
3.4 KiB
Markdown
php-encryption
|
|
===============
|
|
|
|
This is a class for doing symmetric encryption in PHP. **Requires PHP 5.4 or newer.**
|
|
|
|
[](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
|