Version 2.0.0 Documentation (and other things)

README.md

@@ -3,88 +3,84 @@ 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 Jan
+01, 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 contributotrs.
 
-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.
+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 a version of PHP 5.4 or
+newer with the OpenSSL extensions enabled (the default). It comes bundled with
+[random\_compat](https://github.com/paragonie/random_compat) 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.
-
-- Rule #3: The library aims only to be compatible with itself.
+Examples
+---------
 
-    > 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.
+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:
 
-    > 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.
+- [encutil](https://github.com/defuse/encutil)
 
-- Rule #4: The library should require no special installation.
+Security Audit Status
+---------------------
 
-    > 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().
+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. In all
+likelihood, you are safer using this library than almost any other encryption
+library for PHP.
 
-References:
+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).
 
-    [1] https://github.com/jedisct1/libsodium-php
+Public Keys
+------------
 
-Authors
----------
+The GnuPG public key used to sign releases is available in
+[other/signingkey.asc](other/signingkey.asc). Its fingerprint is:
 
-This library is authored by Taylor Hornby and Scott Arciszewski.
+```
+2FA6 1D8D 99B9 2658 6BAC  3D53 385E E055 A129 1538
+```
 
+You can verify it against the Taylor Hornby's [contact
+page](https://defuse.ca/contact.htm) and
+[twitter](https://twitter.com/DefuseSec/status/723741424253059074).

dist/defuse-crypto.phar.sig

@@ -0,0 +1,17 @@
+-----BEGIN PGP SIGNATURE-----
+Version: GnuPG v2
+
+iQIcBAABCAAGBQJXHEa0AAoJEDhe4FWhKRU4ZS8QAJzo8p9K7UqGyiRMHd4rsV7f
+e3fUlr9YHnvrxHKtxBeY/817+lng8d8yc3PdLQHnmUDB04zEbeh+U95ZYZT3Jm9W
+6fU8y8n5EzzxZBbkDGeDM+ds/BZZeGjNfl9HUz2huERwNueiASOmpUYLFaWiGziw
+ivDiVWISfFnxU9IIeWUUX8wbRO3kL23AuNsRHXnjaL8OWLdZHg+562QaBP8l/vGp
+JXSGdknIzb0hHTQgrk/fqMl8S2eHzgl/ZK6xI15RUPWQ85L4wIno5rkeD0jSdPuu
+5EoQoBkcdC5H88dBcd6zhnAcBgBRl715jvLbZU+Jr3CQEGWD41MRRSwa7sAPYR1l
+MjUdwvU4MVK/VHBbRD2JlgCrR/HXchfWpYwdSIx+2UcF8wEH5nqqRPAi3LTCN+bu
+qA6CD9/rQh2dlYEZgq60VoDiXKHPM6kPcpyyIC/iaYgfif4M4reBDu9aVCCmYmwk
+33oQ0S+nu0+q7IaQrIY8ohD7lguVloYTqhdysUrWQaEYo+uKaCz6WlZuhJz3RrhX
+u5lNTeajWKXhPGhBfE0prQ6kdGfMGEb5iV9JxzM1f/9nq2ow5fg1QtBmKcegNP52
+FKU29BM6DU82dOUckJY+KICgQ2XWka+Laqj1x26a2Hml+xx3eiSmHQjO+v6CvZfo
+Am8gGvNnyc6DgDKXVXzN
+=BZoQ
+-----END PGP SIGNATURE-----