Add more instructions to the README

README.md

@@ -8,11 +8,149 @@ This is a class for doing symmetric encryption in PHP. **Requires PHP 5.4 or new
 Implementation
 --------------
 
-Messages are encrypted with AES-128 in CTR mode and are authenticated with
+Messages are encrypted with AES-256 in CTR mode and are authenticated with
 HMAC-SHA256 (Encrypt-then-Mac). 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.
 
+## Installing this Library
+
+### Using Composer
+
+```sh
+composer require defuse/php-encryption
+```
+
+### Direct Installation (Phar)
+
+Download the PHP Archive and public key. Extract 
+
+### Direct Installation (Manual)
+
+Download the [latest release](https://github.com/defuse/php-encryption/releases). Extract all of the files into a directory on your webserver (e.g. `/var/www/lib/defuse/php-encryption`).
+
+Then add this to your PHP scripts:
+
+```php
+require '/var/www/lib/defuse/php-encryption/autoload.php';
+```
+
+## Using this Library
+
+1. Generate and store an encryption key.
+2. Encrypt plaintext strings with your key to obtain ciphertext, using `Crypto`.
+3. Decrypt ciphertext strings with your key to obtain plaintext, using `Crypto`.
+4. Encrypt/decrypt files with your key, using `File`.
+
+### Generate and Store an Encryption Key
+
+Generate a new key:
+
+```php
+$key = \Defuse\Crypto\Key::createNewRandomKey();
+````
+
+The above command will generate a random encryption key, using a 
+cryptographically secure pseudorandom number generator. This will generally only
+need to be done *once* if you need to reuse this key for multiple messages.
+
+```php
+$encryptionKeyDataForStorage = $key->saveToAsciiSafeString()
+```
+
+This returns an encoded string that you can use to persist a key across multiple
+runs of the application. You might decide to copy it to a configuration file
+not tracked by Git, for example. To load it again on the next script execution,
+just do this:
+
+```php
+$key = \Defuse\Crypto\Key::LoadFromAsciiSafeString($storedKeyData);
+```
+
+### Encrypting Strings
+
+Once you have a `Key` object, you're ready to encrypt data. All you have to do
+is pass your desired string and the `Key` object to `Crypto::encrypt()`.
+
+```php
+try {
+    $ciphertext = \Defuse\Crypto\Crypto::encrypt("Test message", $key);
+} catch (\Defuse\Crypto\Exception\CryptoTestFailedException $ex) {
+    die("Our platform is not secure enough to use this cryptography library.");
+}
+```
+
+### Decrypting Strings
+
+If encryption made sense, then the decryption API should be intuitive and
+precisely what you expect it to be:
+
+
+### Interlude: A Complete Example
+
+First, generate a key and store it:
+
+```php
+<?php
+require_once "/path/to/defuse/php-encryption/autoload.php';
+$key = \Defuse\Crypto\Key::createNewRandomKey();
+file_put_contents('shared_key.txt', $key->saveToAsciiSafeString());
+```
+
+The two scripts below, `encrypt_msg.php` and `decrypt_msg.php` are command-line
+PHP scripts meant to encrypt/decrypt messages using a pre-shared-key.
+
+Sender:
+
+```php
+<?php
+use \Defuse\Crypto\Crypto;
+use \Defuse\Crypto\Key;
+require_once "/path/to/defuse/php-encryption/autoload.php';
+
+$keyData = file_get_contents('shared_key.txt');
+$key = Key::LoadFromAsciiSafeString($keyData);
+
+$encrypted = Crypto::encrypt($argv[1], $key);
+echo $encrypted, "\n";
+```
+
+Receiver:
+
+```php
+<?php
+use \Defuse\Crypto\Crypto;
+use \Defuse\Crypto\Key;
+require_once "/path/to/defuse/php-encryption/autoload.php';
+
+$keyData = file_get_contents('shared_key.txt');
+$key = Key::LoadFromAsciiSafeString();
+
+$decrypted = Crypto::decrypt($argv[1], $key);
+echo $decrypted, "\n";
+```
+
+If you run this command:
+
+    php decrypt_msg.php `php encrypt_msg.php It\ Works\!`
+
+It will print "It works!" into your console. Now, assuming you and your 
+recipient have the same `shared-key.txt`, you can send messages to/from them and
+only they should be able to decrypt them.
+
+### Encrypting and Decrypting Files
+
+In addition to our standard `Crypto::encrypt()` and `Crypto::decrypt()` 
+interface, this library has a separate class for encrypting/decrypting files.
+
+This is mostly useful for encrypting large files (say, 1.5 GB) on a machine with
+very low memory usage (say, a maximum of 64 MB of RAM).
+
+```php
+\Defuse\Crypto\File::encryptFile($inputFilename, $outputFilename, $key);
+\Defuse\Crypto\File::decryptFile($encryptedFile, $plaintextFile, $key);
+```
+
 Audit Status
 -------------
 
@@ -74,16 +212,12 @@ This library is developed around several core values:
 
 - Rule #4: The library should require no special installation.
 
-    > 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 a handful of PHP
-    > files that you can copy to your source tree and require().
-
-References:
-
-    [1] https://github.com/jedisct1/libsodium-php
+    > Some PHP encryption libraries, like [libsodium-php](https://github.com/jedisct1/libsodium-php),
+    > are not straightforward to install and cannot packaged with "just download
+    > and extract" applications. This library will always be just a handful of
+    > PHP files that you can copy to your source tree and require().
 
 Authors
 ---------
 
-This library is authored by Taylor Hornby and Scott Arciszewski.
+This library is authored by [Taylor Hornby](https://bqp.io) and [Scott Arciszewski](https://paragonie.com/blog/author/scott-arciszewski).

autoload.php

@@ -4,7 +4,7 @@
  */
 \spl_autoload_register(function ($class) {
     // Project-specific namespace prefix
-    $prefix = 'Defuse\\Crypto';
+    $prefix = 'Defuse\\Crypto\\';
 
     // Base directory for the namespace prefix
     $base_dir = __DIR__.'/src/';
@@ -18,19 +18,46 @@
 
     // Get the relative class name
     $relative_class = \substr($class, $len);
-
-    // Replace the namespace prefix with the base directory, replace namespace
-    // separators with directory separators in the relative class name, append
-    // with .php
-    $file = $base_dir.
-        \str_replace(
-            ['\\', '_'],
-            '/',
-            $relative_class
-        ).'.php';
-
-    // If the file exists, require it
-    if (\file_exists($file)) {
-        require $file;
+
+    /**
+     * unserialize() -> autoloader -> LFI hardening
+     */
+    $classmap = array(
+        'Config' =>
+            'Config.php',
+        'Core' =>
+            'Core.php',
+        'Crypto' =>
+            'Crypto.php',
+        'Encoding' =>
+            'Encoding.php',
+        'ExceptionHandler' =>
+            'ExceptionHandler.php',
+        'File' =>
+            'File.php',
+        'FileConfig' =>
+            'FileConfig.php',
+        'Key' =>
+            'Key.php',
+        'KeyConfig' =>
+            'KeyConfig.php',
+        'RuntimeTests' =>
+            'RuntimeTests.php',
+        'StreamInterface' =>
+            'StreamInterface.php',
+        // Exceptions:
+        'Exception\\CannotPerformOperationException' =>
+            'Exception/CannotPerformOperationException.php',
+        'Exception\\CryptoException' =>
+            'Exception/CryptoException.php',
+        'Exception\\CryptoTestFailedException' =>
+            'Exception/CryptoTestFailedException.php',
+        'Exception\\InvalidCiphertextException' =>
+            'Exception/InvalidCiphertextException.php',
+    );
+    foreach ($classmap as $classname => $file) {
+        if ($classname === $relative_class) {
+            require $base_dir.$file;
+        }
     }
 });

src/Core.php

@@ -2,7 +2,6 @@
 namespace Defuse\Crypto;
 
 use \Defuse\Crypto\Exception as Ex;
-use \Defuse\Crypto\Crypto;
 
 final class Core
 {
@@ -27,12 +26,7 @@ public static function incrementCounter($ctr, $inc, &$config)
     {
         static $ivsize = null;
         if ($ivsize === null) {
-            $ivsize = \openssl_cipher_iv_length($config->cipherMethod());
-            if ($ivsize === false) {
-                throw new Ex\CannotPerformOperationException(
-                    "Problem obtaining the correct nonce length."
-                );
-            }
+            $ivsize = self::cipherIvLength($config->cipherMethod());
         }
 
         if (self::ourStrlen($ctr) !== $ivsize) {
@@ -73,6 +67,27 @@ public static function incrementCounter($ctr, $inc, &$config)
         return $ctr;
     }
 
+    /**
+     * Returns the cipher initialization vector (iv) length.
+     *
+     * @param string $method
+     * @return int
+     * @throws Ex\CannotPerformOperationException
+     */
+    public static function cipherIvLength($method)
+    {
+        self::ensureFunctionExists('openssl_cipher_iv_length');
+        $ivsize = \openssl_cipher_iv_length($method);
+
+        if ($ivsize === false || $ivsize <= 0) {
+            throw new Ex\CannotPerformOperationException(
+                'Could not get the IV length from OpenSSL'
+            );
+        }
+
+        return $ivsize;
+    }
+
     /**
      * Returns a random binary string of length $octets bytes.
      *

src/Crypto.php

@@ -105,13 +105,7 @@ public static function encrypt($plaintext, $key, $raw_binary = false)
         );
 
         // Generate a random initialization vector.
-        Core::ensureFunctionExists("openssl_cipher_iv_length");
-        $ivsize = \openssl_cipher_iv_length($config->cipherMethod());
-        if ($ivsize === false || $ivsize <= 0) {
-            throw new Ex\CannotPerformOperationException(
-                "Could not get the IV length from OpenSSL"
-            );
-        }
+        $ivsize = Core::cipherIvLength($config->cipherMethod());
         $iv = Core::secureRandom($ivsize);
 
         $ciphertext = $salt . $iv . self::plainEncrypt($plaintext, $ekey, $iv, $config);
@@ -210,13 +204,7 @@ public static function decrypt($ciphertext, $key, $raw_binary = false)
             $ekey = Core::HKDF($config->hashFunctionName(), $key, $config->keyByteSize(), $config->encryptionInfoString(), $salt, $config);
 
             // Extract the initialization vector from the ciphertext.
-            Core::EnsureFunctionExists("openssl_cipher_iv_length");
-            $ivsize = \openssl_cipher_iv_length($config->cipherMethod());
-            if ($ivsize === false || $ivsize <= 0) {
-                throw new Ex\CannotPerformOperationException(
-                    "Could not get the IV length from OpenSSL"
-                );
-            }
+            $ivsize = Core::cipherIvLength($config->cipherMethod());
             if (Core::ourStrlen($ciphertext) <= $ivsize) {
                 throw new Ex\InvalidCiphertextException(
                     "Ciphertext is too short."
@@ -302,13 +290,7 @@ public static function legacyDecrypt($ciphertext, $key)
             );
 
             // Extract the initialization vector from the ciphertext.
-            Core::EnsureFunctionExists("openssl_cipher_iv_length");
-            $ivsize = \openssl_cipher_iv_length($config->cipherMethod());
-            if ($ivsize === false || $ivsize <= 0) {
-                throw new Ex\CannotPerformOperationException(
-                    "Could not get the IV length from OpenSSL"
-                );
-            }
+            $ivsize = Core::cipherIvLength($config->cipherMethod());
             if (Core::ourStrlen($ciphertext) <= $ivsize) {
                 throw new Ex\InvalidCiphertextException(
                     "Ciphertext is too short."
@@ -467,7 +449,7 @@ protected static function getVersionConfigFromMajorMinor($major, $minor)
                         'cipher_method' => 'aes-256-ctr',
                         'block_byte_size' => 16,
                         'key_byte_size' => 32,
-                        'salt_byte_size' => 16,
+                        'salt_byte_size' => 32,
                         'hash_function_name' => 'sha256',
                         'mac_byte_size' => 32,
                         'encryption_info_string' => 'DefusePHP|V2|KeyForEncryption',