library/defuse/php-encryption-1.2.1/README.md

   1 php-encryption
   2 ===============
   3
   4 This is a class for doing symmetric encryption in PHP. **Requires PHP 5.4 or newer.**
   5
   6 [![Build Status](https://travis-ci.org/defuse/php-encryption.svg?branch=master)](https://travis-ci.org/defuse/php-encryption)
   7
   8 Implementation
   9 --------------
  10
  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.
  16
  17 Warning
  18 --------
  19
  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.
  26
  27 That said, you're probably much better off using this library than any other
  28 encryption library written in PHP.
  29
  30 Philosophy
  31 -----------
  32
  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.
  36
  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.
  40
  41 This library is developed around several core values:
  42
  43 - Rule #1: Security is prioritized over everything else.
  44
  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.
  49
  50 - Rule #2: It should be difficult to misuse the library.
  51
  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.
  57
  58 - Rule #3: The library aims only to be compatible with itself.
  59
  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.
  65
  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
  68     > implemented.
  69
  70 - Rule #4: The library should consist of a single PHP file and nothing more.
  71
  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().
  76
  77 References:
  78
  79     [1] https://github.com/jedisct1/libsodium-php