🚀 [Feature]: Add function to create deterministic key pairs (#21)

## Description

- Fixes #19

This pull request introduces a new feature to generate deterministic key
pairs using a seed in the `New-SodiumKeyPair` PowerShell function. The
changes include updates to both the `Sodium` class and the
`New-SodiumKeyPair` function to support this new functionality.

### New Feature: Deterministic Key Pair Generation

* **`Sodium` class update**: Added a new P/Invoke method
`crypto_box_seed_keypair` to generate key pairs using a seed.
* **Documentation updates**: Enhanced the comments and examples in
`New-SodiumKeyPair.ps1` to include usage information for the new seed
parameter.
* **Parameter addition**: Added a new `Seed` parameter to the
`New-SodiumKeyPair` function to allow for deterministic key pair
generation.
* **Key pair generation logic**: Updated the key pair generation logic
to handle both seeded and non-seeded key pair creation based on the
provided parameters.

## Type of change

<!-- Use the check-boxes [x] on the options that are relevant. -->

- [ ] 📖 [Docs]
- [ ] 🪲 [Fix]
- [ ] 🩹 [Patch]
- [ ] ⚠️ [Security fix]
- [x] 🚀 [Feature]
- [ ] 🌟 [Breaking change]

## Checklist

<!-- Use the check-boxes [x] on the options that are relevant. -->

- [x] I have performed a self-review of my own code
- [x] I have commented my code, particularly in hard-to-understand areas

Author: MariusStorhaug

PSModule/Sodium/Sodium.cs

@@ -11,6 +11,9 @@ public static class Sodium
         [DllImport("libsodium", CallingConvention = CallingConvention.Cdecl)]
         public static extern int crypto_box_keypair(byte[] pk, byte[] sk);
 
+        [DllImport("libsodium", CallingConvention = CallingConvention.Cdecl)]
+        public static extern int crypto_box_seed_keypair(byte[] pk, byte[] sk, byte[] seed);
+
         [DllImport("libsodium", CallingConvention = CallingConvention.Cdecl)]
         public static extern int crypto_box_seal(byte[] ciphertext, byte[] message, ulong mlen, byte[] pk);
 

README.md

@@ -38,7 +38,21 @@ PublicKey                                    PrivateKey
 9fv51aqi00MYN4UR7Ew/DLXMS9t1NapLs7yyo+vegz4= MiJAFUZxZ1UCbQTwKfH7HY6AhIFYQlnok5fBD2K+y/g=
 ```
 
-## Example 2: Encrypt a message using a public key (Sealed Boxes encryption)
+### Example 2: Deterministic Key Pair Generation
+
+Generate a key pair deterministically using a seed. The same seed will always produce the same key pair.
+
+```powershell
+New-SodiumKeyPair -Seed 'MySecureSeed'
+
+PublicKey PrivateKey
+-------- - ----------
+WQakMx2mIAQMwLqiZteHUTwmMP6mUdK2FL0WEybWgB8= ci5/7eZ0IbGXtqQMaNvxhJ2d9qwFxA8Kjx+vivSTXqU=
+```
+
+
+
+### Example 3: Encrypt a message using a public key (Sealed Boxes encryption)
 
 After generating a key pair, a message can be encrypted using the associated public key with [Sealed Boxes encryption](https://doc.libsodium.org/public-key_cryptography/sealed_boxes).
 Below, a message is encrypted using the public key from the previous example.
@@ -53,7 +67,7 @@ ConvertTo-SodiumSealedBox @params
 905j4S/JyP9XBBmOIdHSOXiDu7fUtZo9TFIMnAfBMESgcVBwttLnEyxJn4xPEX5OMKQ+Bc4P6Hg=
 ```
 
-## Example 3: Decrypt a Sodium-encrypted sealed box string
+### Example 4: Decrypt a Sodium-encrypted sealed box string
 
 To decrypt a string that was encrypted using [Sealed Boxes encryption](https://doc.libsodium.org/public-key_cryptography/sealed_boxes), both the private and public keys are required.
 

src/functions/public/New-SodiumKeyPair.ps1

@@ -8,12 +8,35 @@
         The keys are returned as a PowerShell custom object, with both the public and private keys
         encoded in base64 format.
 
+        If a seed is provided, the key pair is deterministically generated using a SHA-256 derived seed.
+        This ensures that the same input seed will always produce the same key pair.
+
         .EXAMPLE
         New-SodiumKeyPair
 
+        Output:
+        ```powershell
+        PublicKey                                    PrivateKey
+        ---------                                    ----------
+        Ac0wdsq6lqLGktckJrasPcTbVRuUCU+OKzVpMno+v0g= PVXI64v00+aT2b2O6Q4l+SfMBUY2R/Nogsl2mp/hXAs=
+        ```
+
         Generates a new key pair and returns a custom object containing the base64-encoded
         public and private keys.
 
+        .EXAMPLE
+        New-SodiumKeyPair -Seed "MySecureSeed"
+
+        Output:
+        ```powershell
+        PublicKey                                    PrivateKey
+        ---------                                    ----------
+        WQakMx2mIAQMwLqiZteHUTwmMP6mUdK2FL0WEybWgB8= ci5/7eZ0IbGXtqQMaNvxhJ2d9qwFxA8Kjx+vivSTXqU=
+        ```
+
+        Generates a deterministic key pair using the given seed string. The same seed will produce
+        the same key pair every time.
+
         .LINK
         https://psmodule.io/Sodium/Functions/New-SodiumKeyPair/
 
@@ -26,8 +49,12 @@
         Justification = 'Does not change state'
     )]
     [OutputType([pscustomobject])]
-    [CmdletBinding()]
-    param()
+    [CmdletBinding(DefaultParameterSetName = 'NewKeyPair')]
+    param(
+        # A seed value to use for key generation.
+        [Parameter(Mandatory, ParameterSetName = 'SeededKeyPair')]
+        [string] $Seed
+    )
 
     begin {
         $null = [PSModule.Sodium]::sodium_init()
@@ -36,14 +63,26 @@
     process {
         $pkSize = [PSModule.Sodium]::crypto_box_publickeybytes().ToUInt32()
         $skSize = [PSModule.Sodium]::crypto_box_secretkeybytes().ToUInt32()
-
         $publicKey = New-Object byte[] $pkSize
         $privateKey = New-Object byte[] $skSize
 
-        # Generate key pair
-        $null = [PSModule.Sodium]::crypto_box_keypair($publicKey, $privateKey)
+        switch ($PSCmdlet.ParameterSetName) {
+            'SeededKeyPair' {
+                # Derive a 32-byte seed from the provided string seed (using SHA-256)
+                $seedBytes = [System.Text.Encoding]::UTF8.GetBytes($Seed)
+                $derivedSeed = [System.Security.Cryptography.SHA256]::Create().ComputeHash($seedBytes)
+                $result = [PSModule.Sodium]::crypto_box_seed_keypair($publicKey, $privateKey, $derivedSeed)
+                break
+            }
+            default {
+                $result = [PSModule.Sodium]::crypto_box_keypair($publicKey, $privateKey)
+            }
+        }
+
+        if ($result -ne 0) {
+            throw 'Key pair generation failed.'
+        }
 
-        # Convert to Base64 for easy storage/transfer
         return [pscustomobject]@{
             PublicKey  = [Convert]::ToBase64String($publicKey)
             PrivateKey = [Convert]::ToBase64String($privateKey)

tests/Sodium.Tests.ps1

@@ -74,5 +74,24 @@
             $publicKeyBytes.Length | Should -Be 32
             $privateKeyBytes.Length | Should -Be 32
         }
+
+        It 'Generates deterministic keys when a seed is provided' {
+            $seed = 'DeterministicSeed'
+            $keyPair1 = New-SodiumKeyPair -Seed $seed
+            $keyPair2 = New-SodiumKeyPair -Seed $seed
+
+            $keyPair1.PublicKey | Should -Be $keyPair2.PublicKey
+            $keyPair1.PrivateKey | Should -Be $keyPair2.PrivateKey
+        }
+
+        It 'Generates different keys for different seeds' {
+            $seed1 = 'SeedOne'
+            $seed2 = 'SeedTwo'
+            $keyPair1 = New-SodiumKeyPair -Seed $seed1
+            $keyPair2 = New-SodiumKeyPair -Seed $seed2
+
+            $keyPair1.PublicKey | Should -Not -Be $keyPair2.PublicKey
+            $keyPair1.PrivateKey | Should -Not -Be $keyPair2.PrivateKey
+        }
     }
 }