Merge branch 'v2.0'

Author: defuse

.gitattributes

@@ -0,0 +1,2 @@
+/.gitattributes export-ignore
+/.travis.yml export-ignore

.gitignore

@@ -0,0 +1,11 @@
+*~
+/test/unit/File/big-generated-file
+/composer.lock
+/vendor
+defuse-crypto.phar
+defuse-crypto.phar.sig
+composer.phar
+box.phar
+phpunit.phar
+phpunit.phar.asc
+test/unit/File/tmp

.php_cs

@@ -0,0 +1,65 @@
+<?php
+
+$config = Symfony\CS\Config\Config::create()
+    ->level(Symfony\CS\FixerInterface::PSR2_LEVEL)
+    ->fixers([
+        'blankline_after_open_tag',
+        'empty_return',
+        'extra_empty_lines',
+        'function_typehint_space',
+        'join_function',
+        'method_argument_default_value',
+        'multiline_array_trailing_comma',
+        'no_blank_lines_after_class_opening',
+        'no_empty_lines_after_phpdocs',
+        'phpdoc_indent',
+        'phpdoc_no_access',
+        'phpdoc_no_empty_return',
+        'phpdoc_no_package',
+        'phpdoc_params',
+        'phpdoc_scalar',
+        'phpdoc_separation',
+        'phpdoc_trim',
+        'phpdoc_type_to_var',
+        'phpdoc_types',
+        'phpdoc_var_without_name',
+        'remove_leading_slash_use',
+        'remove_lines_between_uses',
+        'short_bool_cast',
+        'single_quote',
+        'spaces_after_semicolon',
+        'spaces_before_semicolon',
+        'spaces_cast',
+        'standardize_not_equal',
+        'ternary_spaces',
+        'trim_array_spaces',
+        'unneeded_control_parentheses',
+        'unused_use',
+        'whitespacy_lines',
+        'align_double_arrow',
+        'concat_with_spaces',
+        'logical_not_operators_with_successor_space',
+        'multiline_spaces_before_semicolon',
+        'newline_after_open_tag',
+        'ordered_use',
+        'php_unit_construct',
+        'phpdoc_order',
+        'short_array_syntax',
+    ]);
+
+if (null === $input->getArgument('path')) {
+    $config
+        ->finder(
+            Symfony\CS\Finder\DefaultFinder::create()
+                ->in('src/')
+                ->in('other/')
+                ->in('test/')
+                ->filter(
+                  function (\SplFileInfo $file) {
+                    return strpos($file->getRelativePathname(), 'random_compat') === FALSE;
+                  }
+                )
+        );
+}
+
+return $config;

.travis.yml

@@ -9,7 +9,14 @@ sudo: false
 
 matrix:
     fast_finish: true
-    allow_failures:
-      - php: "7.0"
 
-script: ./test.sh
+install:
+    - composer install
+    - curl -LSs https://box-project.github.io/box2/installer.php | php
+    - mkdir ~/box
+    - mv box.phar ~/box/box
+
+script:
+    - ./test.sh
+    - PATH=$PATH:~/box/ make -C dist/ build-phar
+    - ./test.sh dist/defuse-crypto.phar

LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Taylor Hornby <https://defuse.ca> and Paragon Initiative
+Enterprises <https://paragonie.com>.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -3,88 +3,85 @@ php-encryption
 
 [![Build Status](https://travis-ci.org/defuse/php-encryption.svg?branch=master)](https://travis-ci.org/defuse/php-encryption)
 
-This is a class for doing symmetric encryption in PHP. **Requires PHP 5.4 or newer.**
+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.
 
-Implementation
---------------
+The library is a joint effort between [Taylor Hornby](https://defuse.ca/) and
+[Scott Arciszewski](https://paragonie.com/blog/author/scott-arcizewski) as well
+as numerous open-source contributors.
 
-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.
+What separates this library from other PHP encryption libraries is, firstly,
+that it is secure. The authors used to encounter insecure PHP encryption code on
+a daily basis, so they created this library to bring more security to the
+ecosystem. Secondly, this library is "difficult to misuse." Like
+[libsodium](https://github.com/jedisct1/libsodium), its API is designed to be
+easy to use in a secure way and hard to use in an insecure way.
 
-Audit Status
--------------
+Dependencies
+------------
 
-This code has not been subjected to a formal, paid, security audit. However, it
-has received some informal review from members of the PHP security community.
-
-As the author of this library, I take security very seriously and always opt to
-not implement a feature unless I am confident that I can do so without
-introducing security bugs. I take particular care to ensure the library is hard
-to use in an insecure way, even by someone who is not experienced in
-cryptography.
-
-This library considers many edge cases that most PHP encryption libraries do not
-handle correctly. In all likelihood, you are safer using this library than
-almost any other encryption library for PHP.
-
-If you use this library as a part of your business and would like to fund (or
-help fund) a formal audit, I would be very grateful.
+This library requres 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.
 
-Philosophy
------------
+Getting Started
+----------------
 
-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.
+Start with the [**Tutorial**](docs/Tutorial.md). You can find instructions for
+obtaining this library's code securely in the [Installing and
+Verifying](docs/InstallingAndVerifying.md) documentation.
 
-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.
+After you've read the tutorial and got the code, refer to the formal
+documentation for each of the classes this library provides:
 
-This library is developed around several core values:
+- [Crypto](docs/classes/Crypto.md)
+- [File](docs/classes/File.md)
+- [Key](docs/classes/Key.md)
+- [KeyProtectedByPassword](docs/classes/KeyProtectedByPassword.md)
 
-- Rule #1: Security is prioritized over everything else.
+If you encounter difficulties, see the [FAQ](docs/FAQ.md) answers. The fixes to
+the most commonly-reported problems are explained there.
 
-    > 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.
+If you're a cryptographer and want to understand the nitty-gritty details of how
+this library works, look at the [Cryptography Details](docs/CryptoDetails.md)
+documentation.
 
-- Rule #2: It should be difficult to misuse the library.
+If you're interested in contributing to this library, see the [Internal
+Developer Documentation](docs/InternalDeveloperDocs.md).
 
-    > 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.
+Examples
+---------
 
-- Rule #3: The library aims only to be compatible with itself.
+If the documentation is not enough for you to understand how to use this
+library, then you can look at an example project that uses this library:
 
-    > 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.
+- [encutil](https://github.com/defuse/encutil)
 
-    > 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.
+Security Audit Status
+---------------------
 
-- Rule #4: The library should require no special installation.
+This code has not been subjected to a formal, paid, security audit. However, it
+has received lots of review from members of the PHP security community, and the
+authors are experienced with cryptography. In all likelihood, you are safer
+using this library than almost any other encryption library for PHP.
 
-    > 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().
+If you use this library as a part of your business and would like to help fund
+a formal audit, please [contact Taylor Hornby](https://defuse.ca/contact.htm).
 
-References:
+Public Keys
+------------
 
-    [1] https://github.com/jedisct1/libsodium-php
+The GnuPG public key used to sign releases is available in
+[other/signingkey.asc](other/signingkey.asc). Its fingerprint is:
 
-Authors
----------
+```
+2FA6 1D8D 99B9 2658 6BAC  3D53 385E E055 A129 1538
+```
 
-This library is authored by Taylor Hornby and Scott Arciszewski.
+You can verify it against the Taylor Hornby's [contact
+page](https://defuse.ca/contact.htm) and
+[twitter](https://twitter.com/DefuseSec/status/723741424253059074).

autoload.php

@@ -7,14 +7,24 @@
     "authors": [
         {
             "name": "Taylor Hornby",
-            "email": "[email protected]"
+            "email": "[email protected]",
+            "homepage": "https://defuse.ca/"
+        },
+        {
+            "name": "Scott Arciszewski",
+            "email": "[email protected]",
+            "homepage": "https://paragonie.com"
         }
     ],
     "autoload": {
-        "files": ["autoload.php"]
+        "classmap": ["src"]
     },
     "require": {
-        "php":  ">=5.4.0",
-        "ext-openssl": "*"
+        "paragonie/random_compat": "~2.0",
+        "ext-openssl": "*",
+        "php":  ">=5.4.0"
+    },
+    "require-dev": {
+        "nikic/php-parser": "^2.0"
     }
 }