🌟 [Major]: Align function naming with libsodium (#22)

## Description

This pull request attempts to align naming of functions, parameters and
outputs to be closer with `libsodiium` terminology. This includes
significant changes to the encryption and decryption functions,
transitioning from using the term "SodiumEncryptedString" to
"SodiumSealedBox".

- Fixes #20 

### Changes to function names and parameters

* `ConvertFrom-SodiumEncryptedString` renamed to
`ConvertFrom-SodiumSealedBoxString`, with updates to function name,
parameters, and documentation to use "SealedBox" instead of
"EncryptedString". Also updates the parameter from `Secret` to
`SealedBox` to better align with `libsodium`.
* `ConvertTo-SodiumEncryptedString` renamed to
`ConvertTo-SodiumSealedBoxString`, with updates to function name,
parameters, and documentation to use "SealedBox" instead of
"EncryptedString". Also uipdates the parameter from `Secret` to
`Message` to better align with `libsodium`.

### Updates to examples

*
[`examples/CreateGitHubSecret.ps1`](diffhunk://#diff-b7943e4c6e438d9b3c4c861bdc8fe422a1d5e5df32be6f6aab3e34edb699a149L4-R4):
Updated the encryption function call to use `ConvertTo-SodiumSealedBox`
instead of `ConvertTo-SodiumEncryptedString`.
*
[`examples/GitHubSecretService.ps1`](diffhunk://#diff-fe6c0fb0a8d439a5e6ed90bbaa6394857934aaf8c8771ef862546e69ca9437a6L25-R25):
Updated encryption and decryption function calls to use
`ConvertTo-SodiumSealedBox` and `ConvertFrom-SodiumSealedBox`
respectively.
[[1]](diffhunk://#diff-fe6c0fb0a8d439a5e6ed90bbaa6394857934aaf8c8771ef862546e69ca9437a6L25-R25)
[[2]](diffhunk://#diff-fe6c0fb0a8d439a5e6ed90bbaa6394857934aaf8c8771ef862546e69ca9437a6L46-R50)

### Documentation updates

*
[`README.md`](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L40-R67):
Updated examples to use "Sealed Boxes encryption" and changed function
calls to `ConvertTo-SodiumSealedBox` and `ConvertFrom-SodiumSealedBox`.

### Test updates:
*
[`tests/Module.Tests.ps1`](diffhunk://#diff-a94f0e90abaaff044e3cb0327ce3a63a10cd61551269a414e4dc40ad2af8a951L2-R75):
Added new tests for encryption and decryption using
`ConvertTo-SodiumSealedBox` and `ConvertFrom-SodiumSealedBox`, including
error cases for invalid keys.

## Type of change

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

- [ ] 📖 [Docs]
- [ ] 🪲 [Fix]
- [ ] 🩹 [Patch]
- [ ] ⚠️ [Security fix]
- [ ] 🚀 [Feature]
- [x] 🌟 [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

README.md

@@ -28,6 +28,7 @@ Import-Module -Name Sodium
 
 The module provides functionality to create a new cryptographic key pair.
 The keys are returned as a PowerShell custom object with `PublicKey` and `PrivateKey` properties, encoded in base64 format.
+For more info on the key pair generation, refer to the [Public-key signatures documentation](https://doc.libsodium.org/public-key_cryptography/public-key_signatures).
 
 ```powershell
 New-SodiumKeyPair
@@ -37,30 +38,34 @@ PublicKey                                    PrivateKey
 9fv51aqi00MYN4UR7Ew/DLXMS9t1NapLs7yyo+vegz4= MiJAFUZxZ1UCbQTwKfH7HY6AhIFYQlnok5fBD2K+y/g=
 ```
 
-### Example 2: Encrypt a secret using a public key
+## Example 2: Encrypt a message using a public key (Sealed Boxes encryption)
 
-After generating a key pair, a secret can be encrypted using the associated public key.
-Below, a secret is encrypted using the public key from the previous example.
+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.
 
 ```powershell
-ConvertTo-SodiumEncryptedString -Secret "mysecret" -PublicKey "9fv51aqi00MYN4UR7Ew/DLXMS9t1NapLs7yyo+vegz4="
+$params = @{
+    Message   = "mymessage"
+    PublicKey = "9fv51aqi00MYN4UR7Ew/DLXMS9t1NapLs7yyo+vegz4="
+}
+ConvertTo-SodiumSealedBox @params
 
 905j4S/JyP9XBBmOIdHSOXiDu7fUtZo9TFIMnAfBMESgcVBwttLnEyxJn4xPEX5OMKQ+Bc4P6Hg=
 ```
 
-### Example 3: Decrypt a Sodium-encrypted string
+## Example 3: Decrypt a Sodium-encrypted sealed box string
 
-To decrypt an encrypted string, both the private and public keys are required.
+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.
 
 ```powershell
 $params = @{
-    EncryptedSecret = '905j4S/JyP9XBBmOIdHSOXiDu7fUtZo9TFIMnAfBMESgcVBwttLnEyxJn4xPEX5OMKQ+Bc4P6Hg='
-    PublicKey       = '9fv51aqi00MYN4UR7Ew/DLXMS9t1NapLs7yyo+vegz4='
-    PrivateKey      = 'MiJAFUZxZ1UCbQTwKfH7HY6AhIFYQlnok5fBD2K+y/g='
+    SealedBox  = '905j4S/JyP9XBBmOIdHSOXiDu7fUtZo9TFIMnAfBMESgcVBwttLnEyxJn4xPEX5OMKQ+Bc4P6Hg='
+    PublicKey  = '9fv51aqi00MYN4UR7Ew/DLXMS9t1NapLs7yyo+vegz4='
+    PrivateKey = 'MiJAFUZxZ1UCbQTwKfH7HY6AhIFYQlnok5fBD2K+y/g='
 }
-ConvertFrom-SodiumEncryptedString @params
+ConvertFrom-SodiumSealedBox @params
 
-mysecret
+mymessage
 ```
 
 ### Finding More Examples

examples/CreateGitHubSecret.ps1

@@ -1,7 +1,7 @@
 #Requires -Module GitHub
 
 $response = Invoke-GitHubAPI -ApiEndpoint '/orgs/PSModule/actions/secrets/public-key' | Select-Object -ExpandProperty response
-$sealedPublicKeyBox = ConvertTo-SodiumEncryptedString -Secret 'mysecret' -PublicKey $response.key
+$sealedPublicKeyBox = ConvertTo-SodiumSealedBox -Secret 'mysecret' -PublicKey $response.key
 Invoke-GitHubAPI -ApiEndpoint '/orgs/PSModule/actions/secrets/mysecret' -Method PUT -Body @{
     encrypted_value = $sealedPublicKeyBox
     key_id          = $response.key_id

examples/GitHubSecretService.ps1

@@ -22,7 +22,7 @@ $userInfo = @{
 }
 
 # 3a) You encrypt the secret with the public key.
-$encryptedSecret = ConvertTo-SodiumEncryptedString -Secret $secret -PublicKey $userInfo.PublicKey
+$encryptedSecret = ConvertTo-SodiumSealedBox -Message $secret -PublicKey $userInfo.PublicKey
 
 # 3b) You send the encrypted secret to GitHub with the name of the secret and the ID GitHub sent you.
 $secretInfo = @{
@@ -43,11 +43,11 @@ $GitHubSecretStore[$secretInfo.SecretName] = [pscustomobject]@{
 # 5) When used in GitHub Actions, the GitHub Secret Service likely ONLY trusts the 'GitHub Actions' App,
 #    and retrieves the secret by its name.
 $actionParams = @{
-    Secret     = $GitHubSecretStore[$secretName].Secret
+    SealedBox  = $GitHubSecretStore[$secretName].Secret
     PublicKey  = $GitHubSecretStore[$secretName].PublicKey
     PrivateKey = $GitHubSecretStore[$secretName].PrivateKey
 }
-$decryptedString = ConvertFrom-SodiumEncryptedString @actionParams
+$decryptedString = ConvertFrom-SodiumSealedBox @actionParams
 
 # 6) The decrypted secret is now available for use in the GitHub Action.
 Write-Warning $decryptedString

src/functions/private/ConvertTo-ByteArray.ps1

@@ -1,31 +1,35 @@
-function ConvertFrom-SodiumEncryptedString {
+function ConvertFrom-SodiumSealedBox {
     <#
         .SYNOPSIS
-        Decrypts a base64-encoded, Sodium-encrypted string.
+        Decrypts a base64-encoded, Sodium SealedBox-encrypted string.
 
         .DESCRIPTION
-        Converts a base64-encoded, Sodium-encrypted string into its original plaintext form.
+        Converts a base64-encoded, Sodium SealedBox-encrypted string into its original plaintext form.
         Uses the provided public and private keys to decrypt the sealed message.
 
         .EXAMPLE
         $params = @{
-            EncryptedSecret = $encryptedSecret
+            SealedBox       = $encryptedMessage
             PublicKey       = $publicKey
             PrivateKey      = $privateKey
         }
-        ConvertFrom-SodiumEncryptedString @params
+        ConvertFrom-SodiumSealedBox @params
 
-        Decrypts the given encrypted secret using the specified public and private keys and returns the original string.
+        Decrypts the given encrypted message using the specified public and private keys and returns the original string.
 
         .LINK
-        https://psmodule.io/Sodium/Functions/ConvertFrom-SodiumEncryptedString/
+        https://psmodule.io/Sodium/Functions/ConvertFrom-SodiumSealedBox/
+
+        .LINK
+        https://doc.libsodium.org/public-key_cryptography/sealed_boxes
     #>
     [OutputType([string])]
     [CmdletBinding()]
     param(
         # The base64-encoded encrypted secret string to decrypt.
         [Parameter(Mandatory)]
-        [string] $Secret,
+        [Alias('CipherText')]
+        [string] $SealedBox,
 
         # The base64-encoded public key used for decryption.
         [Parameter(Mandatory)]
@@ -37,13 +41,13 @@
     )
 
     begin {
-        Initialize-Sodium
+        $null = [PSModule.Sodium]::sodium_init()
     }
 
     process {
-        $ciphertext = [Convert]::FromBase64String($Secret)
-        $publicKeyByteArray = ConvertTo-ByteArray $PublicKey
-        $privateKeyByteArray = ConvertTo-ByteArray $PrivateKey
+        $ciphertext = [Convert]::FromBase64String($SealedBox)
+        $publicKeyByteArray = [Convert]::FromBase64String($PublicKey)
+        $privateKeyByteArray = [Convert]::FromBase64String($PrivateKey)
 
         if ($publicKeyByteArray.Length -ne 32) { throw 'Invalid public key.' }
         if ($privateKeyByteArray.Length -ne 32) { throw 'Invalid private key.' }

src/functions/private/Initialize-Sodium.ps1

@@ -0,0 +1,61 @@
+function ConvertTo-SodiumSealedBox {
+    <#
+        .SYNOPSIS
+        Encrypts a message using a sealed public key box.
+
+        .DESCRIPTION
+        This function encrypts a given message using a public key with the SealedPublicKeyBox method from the Sodium library.
+        The result is a base64-encoded sealed box that can only be decrypted by the corresponding private key.
+
+        .EXAMPLE
+        ConvertTo-SodiumSealedBox -Message "Hello world!" -PublicKey "BASE64_PUBLIC_KEY"
+
+        Encrypts the message "Hello world!" using the provided base64-encoded public key and returns a base64-encoded sealed box.
+
+        .LINK
+        https://psmodule.io/Sodium/Functions/ConvertTo-SodiumSealedBox/
+
+        .LINK
+        https://doc.libsodium.org/public-key_cryptography/sealed_boxes
+    #>
+    [OutputType([string])]
+    [CmdletBinding()]
+    param(
+        # The message string to be encrypted.
+        [Parameter(Mandatory)]
+        [string] $Message,
+
+        # The base64-encoded public key used for encryption.
+        [Parameter(Mandatory)]
+        [string] $PublicKey
+    )
+    begin {
+        $null = [PSModule.Sodium]::sodium_init()
+    }
+
+    process {
+        # Convert public key from Base64 or space-separated string
+        try {
+            $publicKeyByteArray = [Convert]::FromBase64String($PublicKey)
+        } catch {
+            $PSCmdlet.ThrowTerminatingError($_)
+        }
+        if ($publicKeyByteArray.Length -ne 32) {
+            throw "Invalid public key. Expected 32 bytes but got $($publicKeyByteArray.Length)."
+        }
+
+        $messageBytes = [System.Text.Encoding]::UTF8.GetBytes($Message)
+        $overhead = [PSModule.Sodium]::crypto_box_sealbytes().ToUInt32()
+        $cipherLength = $messageBytes.Length + $overhead
+        $ciphertext = New-Object byte[] $cipherLength
+
+        # Encrypt message
+        $result = [PSModule.Sodium]::crypto_box_seal($ciphertext, $messageBytes, [uint64]$messageBytes.Length, $publicKeyByteArray)
+
+        if ($result -ne 0) {
+            throw 'Encryption failed.'
+        }
+
+        return [Convert]::ToBase64String($ciphertext)
+    }
+}

…ic/ConvertFrom-SodiumEncryptedString.ps1 …s/public/ConvertFrom-SodiumSealedBox.ps1src/functions/public/ConvertFrom-SodiumEncryptedString.ps1 renamed to src/functions/public/ConvertFrom-SodiumSealedBox.ps1 src/functions/public/ConvertFrom-SodiumEncryptedString.ps1 renamed to src/functions/public/ConvertFrom-SodiumSealedBox.ps1

@@ -16,6 +16,9 @@
 
         .LINK
         https://psmodule.io/Sodium/Functions/New-SodiumKeyPair/
+
+        .LINK
+        https://doc.libsodium.org/public-key_cryptography/public-key_signatures
     #>
     [Diagnostics.CodeAnalysis.SuppressMessageAttribute(
         'PSUseShouldProcessForStateChangingFunctions', '',
@@ -27,7 +30,7 @@
     param()
 
     begin {
-        Initialize-Sodium
+        $null = [PSModule.Sodium]::sodium_init()
     }
 
     process {