Prepare for v1.5.1 upon Suhosin fix confirmation.

README.md

@@ -1,6 +1,11 @@
 # Halite
 
 [![Build Status](https://travis-ci.org/paragonie/halite.svg?branch=stable)](https://travis-ci.org/paragonie/halite)
+[![Latest Stable Version](https://poser.pugx.org/paragonie/halite/v/stable)](https://packagist.org/packages/paragonie/halite)
+[![Latest Unstable Version](https://poser.pugx.org/paragonie/halite/v/unstable)](https://packagist.org/packages/paragonie/halite)
+[![License](https://poser.pugx.org/paragonie/halite/license)](https://packagist.org/packages/paragonie/halite)
+
+> **Note**: This is the version 1 branch. Please upgrade to a newer version as soon as possible.
 
 Halite is a high-level cryptography interface that relies on [libsodium](https://pecl.php.net/package/libsodium)
 for all of its underlying cryptography operations.
@@ -15,8 +20,43 @@ without making your source code available under a GPL-compatible license.
 
 ## Using Halite in Your Applications
 
-1. [Install Libsodium and the PHP Extension](https://paragonie.com/book/pecl-libsodium/read/00-intro.md#installing-libsodium)
-2. `composer require paragonie/halite`
+### Step 1: Installing libsodium
+
+Before you can use Halite, you must choose a version that fits the requirements 
+of your project. The differences between the requirements for the available 
+versions of Halite are briefly highlighted below.
+
+|           | PHP   | libsodium | PECL libsodium |
+|-----------|-------|-----------|----------------|
+| Halite 2+ | 7.0.0 | 1.0.9     | 1.0.6          |
+| Halite 1  | 5.6.0 | 1.0.6     | 1.0.2          |
+
+If you plan to use Halite 1, or your distribution has the necessary version already,
+then you should be able to
+[install a precompiled libsodium](https://paragonie.com/book/pecl-libsodium/read/00-intro.md#installing-libsodium)
+package.
+
+### Step 2: Installing the PECL libsodium extension
+
+**Important Note**: It is important that this step is repeated every time that a
+different version of libsodium is installed. The resulting PECL libsodium extension
+is version dependent of the currently installed libsodium.
+
+Installation instructions for the PECL libsodium extension can be found in the
+[PECL libsodium book](https://paragonie.com/book/pecl-libsodium/read/00-intro.md#installing-extension)
+on the Paragon Initiative Enterprises website.
+
+### Step 3: Use Composer to install Halite
+
+The last step required to use Halite is to install it using Composer.
+
+For the latest version of Halite:
+
+    composer require paragonie/halite
+
+Or for older versions of Halite, specify the version number:
+
+    composer require paragonie/halite:^v1
 
 ## Using Halite in Your Project
 
@@ -40,3 +80,68 @@ Check out the [documentation](doc). The basic Halite API is designed for simplic
     * Asymmetric
        * `Asymmetric\Crypto::sign`(`string`, [`SignatureSecretKey`](doc/Classes/Asymmetric/SignatureSecretKey.md), `bool?`): `string`
        * `Asymmetric\Crypto::verify`(`string`, [`SignaturePublicKey`](doc/Classes/Asymmetric/SignaturePublicKey.md), `string`, `bool?`): `bool`
+
+### Example: Encrypting and Decrypting a message
+
+First, generate and persist a key exactly once:
+
+```php
+<?php
+use ParagonIE\Halite\KeyFactory;
+
+$encKey = KeyFactory::generateEncryptionKey();
+KeyFactory::save($encKey, '/path/outside/webroot/encryption.key');
+```
+
+And then you can encrypt/decrypt messages like so:
+
+```php
+<?php
+use ParagonIE\Halite\KeyFactory;
+use ParagonIE\Halite\Symmetric\Crypto as Symmetric;
+
+$encryptionKey = KeyFactory::loadEncryptionKey('/path/outside/webroot/encryption.key');
+
+$message = 'This is a confidential message for your eyes only.';
+$ciphertext = Symmetric::encrypt($message, $encryptionKey);
+
+$decrypted = Symmetric::decrypt($ciphertext, $encryptionKey);
+
+var_dump($decrypted === $message); // bool(true)
+```
+
+This should produce something similar to:
+
+    314202017d893cb20eeab4ef51f6861d55a60797c6de0453f11e464ce210091b914b1c40470869d3d390986eeebe2d34e393efe986fc52de7464f30d8d38df5c6b629c019c454a2eec03ca618f9e2ba34f20c81614d63988f0f845911cafbeee7e79893e1f7c33e298da3b3474ac3ea9181298a2ce7e468914c329b35f50ac32b01136dc87e7f7881d31909227273817ac01c3b8f19dc6db881ad962d5b3e4c95d61494747028114f15a2e718c19
+
+### Example: Generating a key from a password
+
+```php
+<?php
+use ParagonIE\Halite\KeyFactory;
+use ParagonIE\Halite\Symmetric\Crypto as Symmetric;
+
+$passwd = 'correct horse battery staple';
+// Use random_bytes(32); to generate the salt:
+$salt = "\xdd\x7b\x1e\x38\x75\x9f\x72\x86\x0a\xe9\xc8\x58\xf6\x16\x0d\x3b\xdd\x7b\x1e\x38\x75\x9f\x72\x86\x0a\xe9\xc8\x58\xf6\x16\x0d\x3b";
+
+$encryptionKey = KeyFactory::deriveEncryptionKey($passwd, $salt);
+```
+
+A key derived from a password can be used in place of one randomly generated.
+
+### Example: Encrypting a large file on a system with low memory
+
+Halite includes a file cryptography class that utilizes a streaming API to
+allow large files (e.g. gigabytes) be encrypted on a system with very little
+available memory (i.e. less than 8 MB).
+
+```php
+<?php
+use ParagonIE\Halite\File;
+use ParagonIE\Halite\KeyFactory;
+
+$encryptionKey = KeyFactory::loadEncryptionKey('/path/outside/webroot/encryption.key');
+
+File::encrypt('input.txt', 'output.txt', $encryptionKey);
+```