See #41

paragonie · Aug 22, 2016 · 8980974 · 8980974
1 parent a72ccd6
commit 8980974
Show file tree

Hide file tree

Showing 3 changed files with 210 additions and 1 deletion.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,14 @@
 # Changelog
 
+# Version 3.1.0 (2016-08-22)
+
+* Added an `export()` method to `KeyFactory`, and congruent `import*()`
+  methods. For example:
+  * `export($key)` returns a `HiddenString` with a versioned and
+     checksummed, hex-encoded string representing the key material.
+  * `importEncryptionKey($hiddenString)` expects an `EncryptionKey`
+     object or throws a `TypeError`
+
 # Version 3.0.0 (2016-07-30)
 
 * Use [paragonie/constant_time_encoding](https://github.com/paragonie/constant_time_encoding) 

diff --git a/src/KeyFactory.php b/src/KeyFactory.php
@@ -285,6 +285,162 @@ public static function getSecurityLevels(string $level = self::INTERACTIVE): arr
                 );
         }
     }
+
+    /**
+     * Load a symmetric authentication key from a string
+     *
+     * @param HiddenString $keyData
+     * @return AuthenticationKey
+     *
+     * @throws Alerts\CannotPerformOperation
+     */
+    public static function importAuthenticationKey(HiddenString $keyData): AuthenticationKey
+    {
+        return new AuthenticationKey(
+            new HiddenString(
+                self::getKeyDataFromString(
+                    \Sodium\hex2bin($keyData->getString())
+                )
+            )
+        );
+    }
+
+    /**
+     * Load a symmetric encryption key from a string
+     *
+     * @param HiddenString $keyData
+     * @return EncryptionKey
+     *
+     * @throws Alerts\CannotPerformOperation
+     */
+    public static function importEncryptionKey(HiddenString $keyData): EncryptionKey
+    {
+        return new EncryptionKey(
+            new HiddenString(
+                self::getKeyDataFromString(
+                    \Sodium\hex2bin($keyData->getString())
+                )
+            )
+        );
+    }
+
+    /**
+     * Load, specifically, an encryption public key from a string
+     *
+     * @param HiddenString $keyData
+     * @return EncryptionPublicKey
+     *
+     * @throws Alerts\CannotPerformOperation
+     */
+    public static function importEncryptionPublicKey(HiddenString $keyData): EncryptionPublicKey
+    {
+        return new EncryptionPublicKey(
+            new HiddenString(
+                self::getKeyDataFromString(
+                    \Sodium\hex2bin($keyData->getString())
+                )
+            )
+        );
+    }
+
+    /**
+     * Load, specifically, an encryption secret key from a string
+     *
+     * @param HiddenString $keyData
+     * @return EncryptionSecretKey
+     *
+     * @throws Alerts\CannotPerformOperation
+     */
+    public static function importEncryptionSecretKey(HiddenString $keyData): EncryptionSecretKey
+    {
+        return new EncryptionSecretKey(
+            new HiddenString(
+                self::getKeyDataFromString(
+                    \Sodium\hex2bin($keyData->getString())
+                )
+            )
+        );
+    }
+
+    /**
+     * Load, specifically, a signature public key from a string
+     *
+     * @param HiddenString $keyData
+     * @return SignaturePublicKey
+     *
+     * @throws Alerts\CannotPerformOperation
+     */
+    public static function importSignaturePublicKey(HiddenString $keyData): SignaturePublicKey
+    {
+        return new SignaturePublicKey(
+            new HiddenString(
+                self::getKeyDataFromString(
+                    \Sodium\hex2bin($keyData->getString())
+                )
+            )
+        );
+    }
+
+    /**
+     * Load, specifically, a signature secret key from a string
+     *
+     * @param HiddenString $keyData
+     * @return SignatureSecretKey
+     *
+     * @throws Alerts\CannotPerformOperation
+     */
+    public static function importSignatureSecretKey(HiddenString $keyData): SignatureSecretKey
+    {
+        return new SignatureSecretKey(
+            new HiddenString(
+                self::getKeyDataFromString(
+                    \Sodium\hex2bin($keyData->getString())
+                )
+            )
+        );
+    }
+
+    /**
+     * Load an asymmetric encryption key pair from a string
+     *
+     * @param HiddenString $keyData
+     * @return EncryptionKeyPair
+     *
+     * @throws Alerts\CannotPerformOperation
+     */
+    public static function importEncryptionKeyPair(HiddenString $keyData): EncryptionKeyPair
+    {
+        return new EncryptionKeyPair(
+            new EncryptionSecretKey(
+                new HiddenString(
+                    self::getKeyDataFromString(
+                        \Sodium\hex2bin($keyData->getString())
+                    )
+                )
+            )
+        );
+    }
+
+    /**
+     * Load an asymmetric signature key pair from a string
+     *
+     * @param HiddenString $keyData
+     * @return SignatureKeyPair
+     *
+     * @throws Alerts\CannotPerformOperation
+     */
+    public static function importSignatureKeyPair(HiddenString $keyData): SignatureKeyPair
+    {
+        return new SignatureKeyPair(
+            new SignatureSecretKey(
+                new HiddenString(
+                    self::getKeyDataFromString(
+                        \Sodium\hex2bin($keyData->getString())
+                    )
+                )
+            )
+        );
+    }
 
     /**
      * Load a symmetric authentication key from a file
@@ -449,6 +605,35 @@ public static function loadSignatureKeyPair(string $filePath): SignatureKeyPair
             )
         );
     }
+
+    /**
+     * Export a cryptography key to a string (with a checksum)
+     *
+     * @param $key
+     * @return HiddenString
+     * @throws \TypeError
+     */
+    public static function export($key): HiddenString
+    {
+        if ($key instanceof KeyPair) {
+            return self::export(
+                $key->getSecretKey()
+            );
+        }
+        if ($key instanceof Key) {
+            return new HiddenString(
+                \Sodium\bin2hex(
+                    Halite::HALITE_VERSION_KEYS . $key->getRawKeyMaterial() .
+                    \Sodium\crypto_generichash(
+                        Halite::HALITE_VERSION_KEYS . $key->getRawKeyMaterial(),
+                        '',
+                        \Sodium\CRYPTO_GENERICHASH_BYTES_MAX
+                    )
+                )
+            );
+        }
+        throw new \TypeError('Expected a Key.');
+    }
 
     /**
      * Save a key to a file

diff --git a/test/unit/KeyTest.php b/test/unit/KeyTest.php
@@ -69,7 +69,6 @@ public function testDeriveSigningKey()
         );
     }
 
-
     public function testKeyTypes()
     {
         $key = KeyFactory::generateAuthenticationKey();
@@ -143,6 +142,14 @@ public function testEncKeyStorage()
         $this->assertTrue(
             \hash_equals($enc_public->getRawKeyMaterial(), $load_public->getRawKeyMaterial())
         );
+
+        $encoded = KeyFactory::export($enc_secret);
+        $imported = KeyFactory::importEncryptionSecretKey($encoded);
+
+        $this->assertSame(
+            $enc_secret->getRawKeyMaterial(),
+            $imported->getRawKeyMaterial()
+        );
 
         \unlink($file_secret);
         \unlink($file_public);
@@ -174,6 +181,14 @@ public function testSignKeyStorage()
         $this->assertTrue(
             \hash_equals($sign_public->getRawKeyMaterial(), $load_public->getRawKeyMaterial())
         );
+
+        $encoded = KeyFactory::export($sign_secret);
+        $imported = KeyFactory::importSignatureSecretKey($encoded);
+
+        $this->assertSame(
+            $sign_secret->getRawKeyMaterial(),
+            $imported->getRawKeyMaterial()
+        );
 
         \unlink($file_secret);
         \unlink($file_public);