Minor Boyscouting for v2.0

src/Core.php

@@ -2,7 +2,6 @@
 namespace Defuse\Crypto;
 
 use \Defuse\Crypto\Exception as Ex;
-use \Defuse\Crypto\Crypto;
 
 final class Core
 {

src/Key.php

@@ -127,13 +127,25 @@ final class Key
     private $key_bytes = null;
     private $config = null;
 
+    /**
+     * Creates a new random Key object for use with this library.
+     * 
+     * @return \Defuse\Crypto\Key
+     */
     public static function CreateNewRandomKey()
     {
         $config = self::GetKeyVersionConfigFromKeyHeader(self::KEY_CURRENT_VERSION);
         $bytes = Core::secureRandom($config->keyByteSize());
         return new Key(self::KEY_CURRENT_VERSION, $bytes);
     }
 
+    /**
+     * Loads a Key object from an ASCII-safe string
+     * 
+     * @param string $savedKeyString
+     * @return \Defuse\Crypto\Key
+     * @throws Ex\CannotPerformOperationException
+     */
     public static function LoadFromAsciiSafeString($savedKeyString)
     {
         try {
@@ -195,13 +207,26 @@ public static function LoadFromAsciiSafeString($savedKeyString)
         return new Key($version_header, $key_bytes);
     }
 
+    /**
+     * Private constructor -> cannot be instantiated directly:
+     * 
+     *    $key = new Key("\xDE\xF0\x02\x00", "some_key_string"); // errors
+     * 
+     * @param string $version_header
+     * @param string $bytes
+     */
     private function __construct($version_header, $bytes)
     {
         $this->key_version_header = $version_header;
         $this->key_bytes = $bytes;
         $this->config = self::GetKeyVersionConfigFromKeyHeader($this->key_version_header);
     }
 
+    /**
+     * Encodes the key as an ASCII string, with a checksum, for storing.
+     * 
+     * @return string
+     */
     public function saveToAsciiSafeString()
     {
         return Encoding::binToHex(
@@ -221,6 +246,12 @@ public function isSafeForCipherTextVersion($major, $minor)
         return $major == 2 && $minor == 0;
     }
 
+    /**
+     * Get the raw bytes of the encryption key
+     * 
+     * @return string
+     * @throws CannotPerformOperationException
+     */
     public function getRawBytes()
     {
         if (is_null($this->key_bytes) || Core::ourStrlen($this->key_bytes) < self::MIN_SAFE_KEY_BYTE_SIZE) {
@@ -231,6 +262,13 @@ public function getRawBytes()
         return $this->key_bytes;
     }
 
+    /**
+     * Parse a key header, get the configuration
+     * 
+     * @param string $key_header
+     * @return \Defuse\Crypto\KeyConfig
+     * @throws Ex\CannotPerformOperationException
+     */
     private static function GetKeyVersionConfigFromKeyHeader($key_header) {
         if ($key_header === self::KEY_CURRENT_VERSION) {
             return new KeyConfig([
@@ -244,8 +282,11 @@ private static function GetKeyVersionConfigFromKeyHeader($key_header) {
         );
     }
 
-    /*
-     * NEVER use this, exept for testing.
+    /**
+     * NEVER use this, except for testing.
+     * 
+     * @param string $bytes
+     * @return \Defuse\Crypto\Key
      */
     public static function LoadFromRawBytesForTestingPurposesOnlyInsecure($bytes)
     {

src/RuntimeTests.php

@@ -14,7 +14,7 @@
 
 class RuntimeTests extends Crypto
 {
-    /*
+    /**
      * Runs tests.
      * Raises Ex\CannotPerformOperationException or Ex\CryptoTestFailedException if
      * one of the tests fail. If any tests fails, your system is not capable of
@@ -74,6 +74,13 @@ public static function runtimeTest()
         $test_state = 1;
     }
 
+    /**
+     * Run-time test: string encryption and decryption
+     *
+     * @param \Defuse\Crypto\Config $config
+     *
+     * @throws Ex\CryptoTestFailedException
+     */
     private static function testEncryptDecrypt($config)
     {
         $key = Crypto::createNewRandomKey();
@@ -129,7 +136,9 @@ private static function testEncryptDecrypt($config)
     }
 
     /**
-     * Run-time testing
+     * Run-time testing: HKDF
+     *
+     * @param \Defuse\Crypto\Config $config
      *
      * @throws Ex\CryptoTestFailedException
      */
@@ -171,7 +180,7 @@ private static function HKDFTestVector($config)
     }
 
     /**
-     * Run-Time tests
+     * Run-Time testing: HMAC
      *
      * @throws Ex\CryptoTestFailedException
      */
@@ -190,7 +199,9 @@ private static function HMACTestVector($config)
     }
 
     /**
-     * Run-time tests
+     * Run-time testing: AES-256-CTR
+     * 
+     * @param \Defuse\Crypto\Config $config
      *
      * @throws Ex\CryptoTestFailedException
      */
@@ -219,12 +230,14 @@ private static function AESTestVector($config)
 
         $computed_ciphertext = Crypto::plainEncrypt($plaintext, $key, $iv, $config);
         if ($computed_ciphertext !== $ciphertext) {
+            /*
             echo str_repeat("\n", 30);
             var_dump($config);
             echo \bin2hex($computed_ciphertext);
             echo "\n---\n";
             echo \bin2hex($ciphertext);
             echo str_repeat("\n", 30);
+            */
             throw new Ex\CryptoTestFailedException();
         }
 
@@ -233,5 +246,4 @@ private static function AESTestVector($config)
             throw new Ex\CryptoTestFailedException();
         }
     }
-
 }