12.0.2

.circleci/config.yml

@@ -14,6 +14,7 @@ jobs:
       - run: mkdir -p coverage
       - run: php vendor/phpunit/phpunit/phpunit --coverage-html coverage --coverage-clover=coverage.clover
       - run: php vendor/infection/infection/bin/infection
+      - run: php vendor/squizlabs/php_codesniffer/bin/phpcs src | tee codesniff.log
       - run: php examples/support.php
       - run: wget https://scrutinizer-ci.com/ocular.phar
       - run: php ocular.phar code-coverage:upload --format=php-clover coverage.clover
@@ -25,6 +26,8 @@ jobs:
           path: coverage
       - store_artifacts:
           path: infection.log
+      - store_artifacts:
+          path: codesniff.log
 
   build-72:
     docker:

docs/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changes in Dcrypt
 
+## 12.0.2
+- More clarity and unity in internal API
+- Add codesniffer to circle ci testing
+- Lots of cs fixes
+
 ## 12.0.1
 - Much more efficient testing config
 - Fix spelling mistakes

docs/KEYS.md

@@ -1,30 +1,29 @@
 # Guide to dcrypt keys
 
 Dcrypt likes __BIG__ keys.
-This document explains some of the reasoning behind these design decisions and some tips on handling keys.
+This document explains the reasoning behind this design decision and some tips on key management.
 
 ## Why 2048 bytes though?
 
+The large size of key size of 2048 bytes enables dcrypt to forgo any computationally wasteful (at best) and potentially dangerous (at worst) password derivation while still providing very strong security and brute force resistance.
+
 At 2048 bytes the probability of every byte in the 0x00 to 0xFF range being used at least once in a pseudo-random string approaches 1.
-This statistical truth is exploited to prevent, with a high degree of confidence, entire classes of implementation errors like double encoding of keys.
+This statistical curiosity can be leveraged to differentiate between strong and weak entropy sources.
+Particularly, implementation mistakes like double encoding of the key can be rejected by ensuring that the byte stream uses most of the 2^8 keyspace.
 
-A basic test is performed at run time to indicate whether the key is likely to be pseudo-random.
-An exception is raised if the key does not pass this test.
-This test is not perfect but it is simple and fast.
-It may become conditional in the future.
+Before encryption a basic key entropy test is performed which rejects keys that are not likely to be pseudo-random.
+This test is not perfect but it is simple and fast, and it may become conditional in the future.
 
-A generic of the randomness test is this as follows:
+A generic of the randomness test is as follows:
 
 ```php
 <?php
 
-if (\count(\array_unique(\str_split($key))) < 250) {
+if (count(array_unique(str_split($key))) < 250) {
     // throw InvalidKeyException
 }
 ```
 
-The large size of 2048 bytes safely allows us to forgo computationally wasteful and potentially dangerous password derivation while still providing strong security.
-
 ## Create a new key
 
 Command line to screen:
@@ -36,7 +35,7 @@ head -c 2048 /dev/urandom | base64 -w 0 | xargs echo
 Command line to file:
 
 ```bash
-head -c 2048 /dev/urandom | base64 -w 0 > ~/secret.key
+head -c 2048 /dev/urandom | base64 -w 0 > /path/to/secret.key
 ```
 
 PHP static function:

docs/PHILOSOPHY.md

@@ -1,7 +1,9 @@
 # Philosophy
+
 - Use PHP's native functions instead of polyfills
 - Require no external dependencies
-- Use strong typing and strict type enforcement
+- Use strong typing and strict type enforcement over type-checking conditional code
 - Make source as simple as possible to audit
 - Prefer clarity over backwards compatibility
+- Lowest possible SLOC to achieve goals
 - Iterate often to obtain perfection

src/Aes256Ecb.php

@@ -1,34 +1,34 @@
-<?php declare(strict_types=1);
-
-/**
- * Aes256Ecb.php
- *
- * PHP version 7
- *
- * @category Dcrypt
- * @package  Dcrypt
- * @author   Michael Meyer (mmeyer2k) <m.meyer2k@gmail.com>
- * @license  http://opensource.org/licenses/MIT The MIT License (MIT)
- * @link     https://github.com/mmeyer2k/dcrypt
- */
-
-namespace Dcrypt;
-
-/**
- * Symmetric AES-256-ECB encryption functions powered by OpenSSL.
- *
- * @category Dcrypt
- * @package  Dcrypt
- * @author   Michael Meyer (mmeyer2k) <m.meyer2k@gmail.com>
- * @license  http://opensource.org/licenses/MIT The MIT License (MIT)
- * @link     https://github.com/mmeyer2k/dcrypt
- */
-class Aes256Ecb extends Aes256Gcm
-{
-    /**
-     * AES-256 cipher identifier that will be passed to openssl
-     *
-     * @var string
-     */
-    const CIPHER = 'aes-256-ecb';
+<?php declare(strict_types=1);
+
+/**
+ * Aes256Ecb.php
+ *
+ * PHP version 7
+ *
+ * @category Dcrypt
+ * @package  Dcrypt
+ * @author   Michael Meyer (mmeyer2k) <m.meyer2k@gmail.com>
+ * @license  http://opensource.org/licenses/MIT The MIT License (MIT)
+ * @link     https://github.com/mmeyer2k/dcrypt
+ */
+
+namespace Dcrypt;
+
+/**
+ * Symmetric AES-256-ECB encryption functions powered by OpenSSL.
+ *
+ * @category Dcrypt
+ * @package  Dcrypt
+ * @author   Michael Meyer (mmeyer2k) <m.meyer2k@gmail.com>
+ * @license  http://opensource.org/licenses/MIT The MIT License (MIT)
+ * @link     https://github.com/mmeyer2k/dcrypt
+ */
+class Aes256Ecb extends Aes256Gcm
+{
+    /**
+     * AES-256 cipher identifier that will be passed to openssl
+     *
+     * @var string
+     */
+    const CIPHER = 'aes-256-ecb';
 }

src/Aes256Ofb.php

@@ -1,34 +1,34 @@
-<?php declare(strict_types=1);
-
-/**
- * Aes256Ofb.php
- *
- * PHP version 7
- *
- * @category Dcrypt
- * @package  Dcrypt
- * @author   Michael Meyer (mmeyer2k) <m.meyer2k@gmail.com>
- * @license  http://opensource.org/licenses/MIT The MIT License (MIT)
- * @link     https://github.com/mmeyer2k/dcrypt
- */
-
-namespace Dcrypt;
-
-/**
- * Symmetric AES-256-GCM encryption functions powered by OpenSSL.
- *
- * @category Dcrypt
- * @package  Dcrypt
- * @author   Michael Meyer (mmeyer2k) <m.meyer2k@gmail.com>
- * @license  http://opensource.org/licenses/MIT The MIT License (MIT)
- * @link     https://github.com/mmeyer2k/dcrypt
- */
-class Aes256Ofb extends Aes256Gcm
-{
-    /**
-     * AES-256 cipher identifier that will be passed to openssl
-     *
-     * @var string
-     */
-    const CIPHER = 'aes-256-ofb';
-}
+<?php declare(strict_types=1);
+
+/**
+ * Aes256Ofb.php
+ *
+ * PHP version 7
+ *
+ * @category Dcrypt
+ * @package  Dcrypt
+ * @author   Michael Meyer (mmeyer2k) <m.meyer2k@gmail.com>
+ * @license  http://opensource.org/licenses/MIT The MIT License (MIT)
+ * @link     https://github.com/mmeyer2k/dcrypt
+ */
+
+namespace Dcrypt;
+
+/**
+ * Symmetric AES-256-GCM encryption functions powered by OpenSSL.
+ *
+ * @category Dcrypt
+ * @package  Dcrypt
+ * @author   Michael Meyer (mmeyer2k) <m.meyer2k@gmail.com>
+ * @license  http://opensource.org/licenses/MIT The MIT License (MIT)
+ * @link     https://github.com/mmeyer2k/dcrypt
+ */
+class Aes256Ofb extends Aes256Gcm
+{
+    /**
+     * AES-256 cipher identifier that will be passed to openssl
+     *
+     * @var string
+     */
+    const CIPHER = 'aes-256-ofb';
+}

src/Exceptions/InvalidChecksumException.php

@@ -1,20 +1,29 @@
-<?php declare(strict_types=1);
-
-/**
- * InvalidChecksumException.php
- *
- * PHP version 7
- *
- * @category Dcrypt
- * @package  Dcrypt
- * @author   Michael Meyer (mmeyer2k) <m.meyer2k@gmail.com>
- * @license  http://opensource.org/licenses/MIT The MIT License (MIT)
- * @link     https://github.com/mmeyer2k/dcrypt
- */
-
-namespace Dcrypt\Exceptions;
-
-class InvalidChecksumException extends \Exception
-{
-
+<?php declare(strict_types=1);
+
+/**
+ * InvalidChecksumException.php
+ *
+ * PHP version 7
+ *
+ * @category Dcrypt
+ * @package  Dcrypt
+ * @author   Michael Meyer (mmeyer2k) <m.meyer2k@gmail.com>
+ * @license  http://opensource.org/licenses/MIT The MIT License (MIT)
+ * @link     https://github.com/mmeyer2k/dcrypt
+ */
+
+namespace Dcrypt\Exceptions;
+
+/**
+ * A handler for checksum exceptions
+ *
+ * @category Dcrypt
+ * @package  Dcrypt
+ * @author   Michael Meyer (mmeyer2k) <m.meyer2k@gmail.com>
+ * @license  http://opensource.org/licenses/MIT The MIT License (MIT)
+ * @link     https://github.com/mmeyer2k/dcrypt
+ */
+class InvalidChecksumException extends \Exception
+{
+    const MESSAGE = 'Invalid ciphertext checksum';
 }

src/Exceptions/InvalidKeyException.php

@@ -1,20 +1,30 @@
-<?php declare(strict_types=1);
-
-/**
- * InvalidKeyException.php
- *
- * PHP version 7
- *
- * @category Dcrypt
- * @package  Dcrypt
- * @author   Michael Meyer (mmeyer2k) <m.meyer2k@gmail.com>
- * @license  http://opensource.org/licenses/MIT The MIT License (MIT)
- * @link     https://github.com/mmeyer2k/dcrypt
- */
-
-namespace Dcrypt\Exceptions;
-
-class InvalidKeyException extends \Exception
-{
-
+<?php declare(strict_types=1);
+
+/**
+ * InvalidKeyException.php
+ *
+ * PHP version 7
+ *
+ * @category Dcrypt
+ * @package  Dcrypt
+ * @author   Michael Meyer (mmeyer2k) <m.meyer2k@gmail.com>
+ * @license  http://opensource.org/licenses/MIT The MIT License (MIT)
+ * @link     https://github.com/mmeyer2k/dcrypt
+ */
+
+namespace Dcrypt\Exceptions;
+
+/**
+ * A handler for key exceptions
+ *
+ * @category Dcrypt
+ * @package  Dcrypt
+ * @author   Michael Meyer (mmeyer2k) <m.meyer2k@gmail.com>
+ * @license  http://opensource.org/licenses/MIT The MIT License (MIT)
+ * @link     https://github.com/mmeyer2k/dcrypt
+ */
+class InvalidKeyException extends \Exception
+{
+    const KEYLENGTH = 'Key must be at least 2048 bytes and base64 encoded';
+    const KEYRANDOM = 'Key does not contain the minimum amount of entropy';
 }

src/OneTimePad.php

@@ -29,17 +29,24 @@ class OneTimePad
     /**
      * Encrypt or decrypt a binary input string.
      * 
-     * @param  string $input Input data to encrypt
-     * @param  string $key   Encryption/decryption key to use on input
-     * @param  string $algo  Hashing algo to generate keystream
+     * @param string $input Input data to encrypt
+     * @param string $key   Encryption/decryption key to use on input
+     * @param string $algo  Hashing algo to generate keystream
+     *
      * @return string
      */
-    public static function crypt(string $input, string $key, string $algo = 'sha3-512'): string
-    {
+    public static function crypt(
+        string $input,
+        string $key,
+        string $algo = 'sha3-512'
+    ): string {
+        // Split the input into chunks sized the same as the hash size
         $chunks = \str_split($input, Str::hashSize($algo));
 
+        // Determine total input length
         $length = Str::strlen($input);
 
+        // Create a new key object
         $key = new OpensslKey($algo, $key, '');
 
         foreach ($chunks as $i => &$chunk) {

src/OpensslBridge.php

@@ -15,7 +15,8 @@
 namespace Dcrypt;
 
 /**
- * Provides functionality common to the dcrypt AES block ciphers. Extend this class to customize your cipher suite.
+ * Provides functionality common to the dcrypt AES block ciphers.
+ * Extend this class to customize your cipher suite.
  *
  * @category Dcrypt
  * @package  Dcrypt