🎃👻 13.1.2 spooky update

.circleci/config.yml

@@ -13,7 +13,6 @@ jobs:
       - run: ./vendor/bin/phpunit --coverage-html coverage --coverage-clover=coverage.clover
       - run: ./vendor/bin/infection
       - run: ./vendor/bin/phpmetrics --report-html=phpmetrics ./src
-      - 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
       - save_cache:

README.md

@@ -36,18 +36,28 @@ composer require "mmeyer2k/dcrypt=^13.0"
 
 ## Block Ciphers
 
-The dcrypt library helps application developers avoid common mistakes in crypto implementations that leave data at risk while still providing flexibility in its options for crypto enthusiasts.
-Dcrypt's block cipher functions require the use of a high entropy 256 bit (minimum), base64-encoded key.
+The dcrypt library helps application developers avoid common mistakes in crypto implementations that leave data at risk.
 
-To generate a new key, execute this on the command line:
+[Specification document](https://github.com/mmeyer2k/dcrypt/blob/master/docs/CRYPTO.md)
+
+### Keys
+
+Safe usage of dcrypt's block cipher functions requires the use of a high entropy 256 bit (minimum) key.
+Keys should be passed into dcrypt in *base64* encoded format.
+
+**You are responsible for the randomness of your key!**
+
+Generate a new key on the linux CLI:
 
 ```bash
 head -c 32 /dev/urandom | base64 -w 0 | xargs echo
 ```
 
-_You are responsible for the randomness of your key!_
-
-[Specification document](https://github.com/mmeyer2k/dcrypt/blob/master/docs/CRYPTO.md)
+Or with PHP...
+```php
+<?php
+$key = \Dcrypt\OpensslKey::create(32);
+```
 
 ### AES-256 GCM Encryption
 
@@ -56,7 +66,8 @@ Dcrypt will handle the AEAD authentication tag, [SHA3](https://en.wikipedia.org/
 
 ```php
 <?php
-$key = "..............................";
+// Create a new random 32 byte key
+$key = \Dcrypt\OpensslKey::create(32);
 
 $encrypted = \Dcrypt\Aes::encrypt('a secret', $key);
 
@@ -84,7 +95,7 @@ Several AES-256 encryption modes are supported out of the box via hardcoded clas
 ### Custom Encryption Suites
 
 Dcrypt is compatible with _most_ OpenSSL ciphers and hashing algorithms supported by PHP.
-Run `php examples/support.php` to view supported options.
+Run `openssl_get_cipher_methods()` and `hash_algos()` to view supported options on your platform.
 
 #### Static Wrapper
 
@@ -158,7 +169,7 @@ try {
 Be sure you understand the risks and inherent issues of using a stream cipher before proceeding.
 
 - Each key should only be used once
-- No checksums mean data can be forged or altered
+- Data integrity can not be guaranteed
 - [https://en.wikipedia.org/wiki/Stream_cipher_attacks](https://en.wikipedia.org/wiki/Stream_cipher_attacks)
 - [https://jameshfisher.com/2018/01/01/making-a-stream-cipher/](https://jameshfisher.com/2018/01/01/making-a-stream-cipher/)
 

composer.json

@@ -1,27 +1,33 @@
 {
-    "name": "mmeyer2k/dcrypt",
-    "description": "A petite library of encryption functionality for PHP",
-    "keywords": ["encryption", "hashing", "pbkdf", "aes", "openssl"],
-    "license": "MIT",
-    "authors": [
-        {
-            "name": "Michael Meyer",
-            "email": "m.meyer2k@gmail.com"
-        }
-    ],
-    "require": {
-        "php": ">=7.1.0"
-    },
-    "autoload": {
-        "psr-4": {
-            "Dcrypt\\": "src/"
-        }
-    },
-    "autoload-dev": {
-        "classmap": [
-            "examples/",
-            "tests/"
-        ]
-    },
-    "minimum-stability": "dev"
+  "name": "mmeyer2k/dcrypt",
+  "description": "A petite library of encryption functionality for PHP",
+  "keywords": [
+    "encryption",
+    "aes",
+    "gcm",
+    "openssl"
+  ],
+  "license": "MIT",
+  "authors": [
+    {
+      "name": "Michael Meyer",
+      "email": "m.meyer2k@gmail.com"
+    }
+  ],
+  "require": {
+    "php": ">=7.1.0",
+    "ext-openssl": "*",
+    "ext-mbstring": "*"
+  },
+  "autoload": {
+    "psr-4": {
+      "Dcrypt\\": "src/"
+    }
+  },
+  "autoload-dev": {
+    "classmap": [
+      "tests/"
+    ]
+  },
+  "minimum-stability": "dev"
 }

docs/CHANGELOG.md

@@ -1,4 +1,14 @@
-# Changes in Dcrypt
+# Changelog for `dcrypt`
+
+## 13.1.2
+- Offload some functionality into OpensslKey object for readability
+- OpensslKey throws exception if non-allowed properties are accessed
+- Add ext-openssl and ext-mbstring to the requirements (makes IDE happy)
+- Remove examples directory in favor of a more robust `docs/` option
+- Improved exception handling that sheds some legacy crust
+- Removed superfluous root namespace backslashes throughout project
+- Modified ciphertext unpacking algorithm
+- More complete docblocks
 
 ## 13.1.1
 - Add test class for `Aes` static helper object

src/Exceptions/InvalidChecksumException.php

@@ -17,6 +17,8 @@
 
 namespace Dcrypt\Exceptions;
 
+use Exception;
+
 /**
  * A handler for checksum exceptions.
  *
@@ -27,7 +29,7 @@
  *
  * @link     https://github.com/mmeyer2k/dcrypt
  */
-class InvalidChecksumException extends \Exception
+class InvalidChecksumException extends Exception
 {
-    const MESSAGE = 'Invalid ciphertext checksum';
+    protected $message = 'Invalid ciphertext checksum';
 }

src/Exceptions/InvalidKeyException.php → src/Exceptions/InvalidKeyEncodingException.php

@@ -17,6 +17,8 @@
 
 namespace Dcrypt\Exceptions;
 
+use Exception;
+
 /**
  * A handler for key exceptions.
  *
@@ -27,8 +29,7 @@
  *
  * @link     https://github.com/mmeyer2k/dcrypt
  */
-class InvalidKeyException extends \Exception
+class InvalidKeyEncodingException extends Exception
 {
-    const KEYLENGTH = 'Key must be at least 32 bytes';
-    const BASE64ENC = 'Key must be properly formatted base64';
+    protected $message = 'Key must be base64 encoded';
 }

src/Exceptions/InvalidKeyLengthException.php

@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * InvalidKeyException.php.
+ *
+ * PHP version 7
+ *
+ * @category 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;
+
+use Exception;
+
+/**
+ * A handler for key exceptions.
+ *
+ * @category 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 InvalidKeyLengthException extends Exception
+{
+    protected $message = 'Key must be at least 32 bytes';
+}

src/OneTimePad.php

@@ -37,6 +37,8 @@ class OneTimePad
      * @param string $key   Encryption/decryption key to use on input
      * @param string $algo  Hashing algo to generate keystream
      *
+     * @throws Exceptions\InvalidKeyLengthException
+     *
      * @return string
      */
     public static function crypt(
@@ -45,13 +47,13 @@ public static function crypt(
         string $algo = 'sha3-512'
     ): string {
         // Split the input into chunks sized the same as the hash size
-        $chunks = \str_split($input, Str::hashSize($algo));
+        $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);
+        $key = new OpensslKey($key, $algo);
 
         foreach ($chunks as $i => &$chunk) {
             // Create the info key based on counter
@@ -61,6 +63,6 @@ public static function crypt(
             $chunk = $chunk ^ $key->deriveKey($info);
         }
 
-        return \implode($chunks);
+        return implode($chunks);
     }
 }

src/OpensslBridge.php

@@ -17,6 +17,8 @@
 
 namespace Dcrypt;
 
+use Exception;
+
 /**
  * Provides functionality common to the dcrypt AES block ciphers.
  * Extend this class to customize your cipher suite.
@@ -36,6 +38,8 @@ class OpensslBridge
      * @param string $data Ciphertext to decrypt
      * @param string $key  Key which will be used to decrypt data
      *
+     * @throws Exception
+     *
      * @return string
      */
     public static function decrypt(string $data, string $key): string
@@ -49,6 +53,8 @@ public static function decrypt(string $data, string $key): string
      * @param string $data Plaintext string to encrypt.
      * @param string $key  Key which will be used to encrypt data
      *
+     * @throws Exception
+     *
      * @return string
      */
     public static function encrypt(string $data, string $key): string