Merge pull request #3 from paragonie/suite-id-human-readable

Add human-readable ciphersuite names

Author: paragonie-security

src/AEAD/AES128GCM.php

@@ -16,6 +16,11 @@ public function getAeadId(): string
         return self::AEAD_ID;
     }
 
+    public function getSuiteName(): string
+    {
+        return 'AES-128-GCM';
+    }
+
     public function keyLength(): int
     {
         return 16;

src/AEAD/AES256GCM.php

@@ -14,6 +14,10 @@ public function getAeadId(): string
     {
         return self::AEAD_ID;
     }
+    public function getSuiteName(): string
+    {
+        return 'AES-256-GCM';
+    }
 
     public function keyLength(): int
     {

src/AEAD/ChaCha20Poly1305.php

@@ -16,6 +16,11 @@ public function getAeadId(): string
         return self::AEAD_ID;
     }
 
+    public function getSuiteName(): string
+    {
+        return 'ChaCha20Poly1305';
+    }
+
     public function keyLength(): int
     {
         return 32;

src/AEAD/ExportOnly.php

@@ -18,6 +18,11 @@ public function getAeadId(): string
         return self::AEAD_ID;
     }
 
+    public function getSuiteName(): string
+    {
+        return 'Export-Only AEAD';
+    }
+
     /**
      * @throws HPKEException
      */

src/HPKE.php

@@ -30,6 +30,20 @@ public function __construct(
         public AEADInterface $aead
     ) {}
 
+    /**
+     * Human-readable suite name.
+     *
+     * @return string
+     */
+    public function getSuiteName(): string
+    {
+        return implode(', ', [
+            $this->kem->getSuiteName(),
+            $this->kdf->getSuiteName(),
+            $this->aead->getSuiteName(),
+        ]);
+    }
+
     /**
      * @return string
      */

src/Hash.php

@@ -7,4 +7,13 @@ enum Hash: string
     case Sha256 = 'sha256';
     case Sha384 = 'sha384';
     case Sha512 = 'sha512';
+
+    public function getSuiteName(): string
+    {
+        return match ($this) {
+            self::Sha256 => 'SHA256',
+            self::Sha384 => 'SHA384',
+            self::Sha512 => 'SHA512',
+        };
+    }
 }

src/Interfaces/AEADInterface.php

@@ -7,6 +7,7 @@
 interface AEADInterface
 {
     public function getAeadId(): string;
+    public function getSuiteName(): string;
     public function keyLength(): int;
     public function nonceLength(): int;
     public function tagLength(): int;

src/Interfaces/KDFInterface.php

@@ -5,6 +5,7 @@
 interface KDFInterface
 {
     public function getKdfId(): string;
+    public function getSuiteName(): string;
     public function getHashLength(): int;
 
     public function deriveBytes(

src/Interfaces/KemInterface.php

@@ -9,6 +9,7 @@ public function generateKeys(): array;
     public function getHeaderLength(): int;
 
     public function getKemId(): string;
+    public function getSuiteName(): string;
 
     public function getPublicKeyLength(): int;
 

src/KDF/HKDF.php

@@ -37,6 +37,11 @@ public function getKdfId(): string
         };
     }
 
+    public function getSuiteName(): string
+    {
+        return 'HKDF-' . $this->hash->getSuiteName();
+    }
+
     public function deriveBytes(
         #[\SensitiveParameter]
         string|SymmetricKeyInterface $ikm,