Update version number to 2.2, docs to warn encryption doesn't hide length, version number check in release instructions, and specify a minimum OpenSSL version

Author: defuse

README.md

@@ -8,9 +8,9 @@ php-encryption
 [![Downloads](https://img.shields.io/packagist/dt/defuse/php-encryption.svg)](https://packagist.org/packages/defuse/php-encryption)
 
 This is a library for encrypting data with a key or password in PHP. **It
-requires PHP 5.4 or newer.** The current version is v2.0.0, which is expected to
-remain stable and supported by its authors with security and bugfixes until at
-least January 1st, 2019.
+requires PHP 5.6 or newer and OpenSSL 1.0.1 or newer.** The current version is
+v2.2.0, which is expected to remain stable and supported by its authors with
+security and bugfixes until at least January 1st, 2020.
 
 The library is a joint effort between [Taylor Hornby](https://defuse.ca/) and
 [Scott Arciszewski](https://paragonie.com/blog/author/scott-arcizewski) as well
@@ -27,11 +27,11 @@ easy to use in a secure way and hard to use in an insecure way.
 Dependencies
 ------------
 
-This library requires no special dependencies except for PHP 5.4 or newer with
-the OpenSSL extensions enabled (this is the default). It uses
-[random\_compat](https://github.com/paragonie/random_compat), which is bundled
-in with this library so that your users will not need to follow any special
-installation steps.
+This library requires no special dependencies except for PHP 5.6 or newer with
+the OpenSSL extensions (version 1.0.1 or later) enabled (this is the default).
+It uses [random\_compat](https://github.com/paragonie/random_compat), which is
+bundled in with this library so that your users will not need to follow any
+special installation steps.
 
 Getting Started
 ----------------

composer.json

@@ -23,7 +23,7 @@
     "require": {
         "paragonie/random_compat": "~2.0",
         "ext-openssl": "*",
-        "php":  ">=5.4.0"
+        "php":  ">=5.6.0"
     },
     "require-dev": {
         "phpunit/phpunit": "^4|^5",

docs/FAQ.md

@@ -37,3 +37,15 @@ If you're getting this exception, then the string you're giving to
 `loadFromAsciiSafeString()` is *not* the same as the string you got from
 `saveToAsciiSafeString()`. Perhaps your database column isn't wide enough and
 it's truncating the string as you insert it?
+
+Does encrypting hide the length of the plaintext?
+--------------------------------------------------
+
+Encryption does not, and is not intended to, hide the length of the data being
+encrypted. For example, it is not safe to encrypt a field in which only a small
+number of different-length values are possible (e.g. "male" or "female") since
+it would be possible to tell what the plaintext is by looking at the length of
+the ciphertext. In order to do this safely, it is your responsibility to, before
+encrypting, pad the data out to the length of the longest string that will ever
+be encrypted. This way, all plaintexts are the same length, and no information
+about the plaintext can be gleaned from the length of the ciphertext.

docs/InternalDeveloperDocs.md

@@ -117,6 +117,12 @@ Check that the version number in composer.json is correct:
 cat composer.json
 ```
 
+Check that the version number in README.md is correct:
+
+```
+cat README.md
+```
+
 Run the tests:
 
 ```

docs/Tutorial.md

@@ -46,6 +46,16 @@ What this library provides is symmetric encryption for "data at rest." This
 means it is not suitable for use in building protocols where "data is in motion"
 (i.e. moving over a network) except in limited set of cases.
 
+Please note that **encryption does not, and is not intended to, hide the
+*length* of the data being encrypted.** For example, it is not safe to encrypt
+a field in which only a small number of different-length values are possible
+(e.g. "male" or "female") since it would be possible to tell what the plaintext
+is by looking at the length of the ciphertext. In order to do this safely, it is
+your responsibility to, before encrypting, pad the data out to the length of the
+longest string that will ever be encrypted. This way, all plaintexts are the
+same length, and no information about the plaintext can be gleaned from the
+length of the ciphertext.
+
 Getting the Code
 -----------------
 

docs/classes/Crypto.md

@@ -56,6 +56,16 @@ model the caller is designing their application under. If you are unsure where
 to store `$key`, consult with a professional cryptographer to get help designing
 your application.
 
+Please note that **encryption does not, and is not intended to, hide the
+*length* of the data being encrypted.** For example, it is not safe to encrypt
+a field in which only a small number of different-length values are possible
+(e.g. "male" or "female") since it would be possible to tell what the plaintext
+is by looking at the length of the ciphertext. In order to do this safely, it is
+your responsibility to, before encrypting, pad the data out to the length of the
+longest string that will ever be encrypted. This way, all plaintexts are the
+same length, and no information about the plaintext can be gleaned from the
+length of the ciphertext.
+
 ### Crypto::decrypt($ciphertext, Key $key, $raw\_binary = false)
 
 **Description:**

docs/classes/File.md

@@ -52,6 +52,16 @@ caller is designing their application under. If you are unsure where to store
 `$key`, consult with a professional cryptographer to get help designing your
 application.
 
+Please note that **encryption does not, and is not intended to, hide the
+*length* of the data being encrypted.** For example, it is not safe to encrypt
+a field in which only a small number of different-length values are possible
+(e.g. "male" or "female") since it would be possible to tell what the plaintext
+is by looking at the length of the ciphertext. In order to do this safely, it is
+your responsibility to, before encrypting, pad the data out to the length of the
+longest string that will ever be encrypted. This way, all plaintexts are the
+same length, and no information about the plaintext can be gleaned from the
+length of the ciphertext.
+
 ### File::decryptFile($inputFilename, $outputFilename, Key $key)
 
 **Description:**
@@ -155,6 +165,16 @@ value of `$password` may be leaked out to an attacker through the stack trace.
 We recommend configuring PHP to never output stack traces (either displaying
 them to the user or saving them to log files).
 
+Please note that **encryption does not, and is not intended to, hide the
+*length* of the data being encrypted.** For example, it is not safe to encrypt
+a field in which only a small number of different-length values are possible
+(e.g. "male" or "female") since it would be possible to tell what the plaintext
+is by looking at the length of the ciphertext. In order to do this safely, it is
+your responsibility to, before encrypting, pad the data out to the length of the
+longest string that will ever be encrypted. This way, all plaintexts are the
+same length, and no information about the plaintext can be gleaned from the
+length of the ciphertext.
+
 ### File::decryptFileWithPassword($inputFilename, $outputFilename, $password)
 
 **Description:**
@@ -268,6 +288,16 @@ caller is designing their application under. If you are unsure where to store
 `$key`, consult with a professional cryptographer to get help designing your
 application.
 
+Please note that **encryption does not, and is not intended to, hide the
+*length* of the data being encrypted.** For example, it is not safe to encrypt
+a field in which only a small number of different-length values are possible
+(e.g. "male" or "female") since it would be possible to tell what the plaintext
+is by looking at the length of the ciphertext. In order to do this safely, it is
+your responsibility to, before encrypting, pad the data out to the length of the
+longest string that will ever be encrypted. This way, all plaintexts are the
+same length, and no information about the plaintext can be gleaned from the
+length of the ciphertext.
+
 ### File::decryptResource($inputHandle, $outputHandle, Key $key)
 
 **Description:**
@@ -374,6 +404,16 @@ value of `$password` may be leaked out to an attacker through the stack trace.
 We recommend configuring PHP to never output stack traces (either displaying
 them to the user or saving them to log files).
 
+Please note that **encryption does not, and is not intended to, hide the
+*length* of the data being encrypted.** For example, it is not safe to encrypt
+a field in which only a small number of different-length values are possible
+(e.g. "male" or "female") since it would be possible to tell what the plaintext
+is by looking at the length of the ciphertext. In order to do this safely, it is
+your responsibility to, before encrypting, pad the data out to the length of the
+longest string that will ever be encrypted. This way, all plaintexts are the
+same length, and no information about the plaintext can be gleaned from the
+length of the ciphertext.
+
 ### File::decryptResourceWithPassword($inputHandle, $outputHandle, $password)
 
 **Description:**