From f51ba3fbbe8a70a49aff7509d2f6f92761f5509a Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Mon, 6 Jul 2026 08:27:41 +0200 Subject: [PATCH 1/2] Standardize README landing page --- README.md | 105 ++++-------------------------------------------------- 1 file changed, 6 insertions(+), 99 deletions(-) diff --git a/README.md b/README.md index 0fd16d5..34a4784 100644 --- a/README.md +++ b/README.md @@ -1,120 +1,27 @@ # Sodium -A PowerShell module that provides direct bindings to the [`libsodium`](https://github.com/jedisct1/libsodium) cryptographic library. - -This module was initially created to serve the needs of the [GitHub PowerShell module](https://github.com/PSModule/GitHub). -GitHub's method for creating or updating [secrets via the REST API](https://docs.github.com/en/rest/guides/encrypting-secrets-for-the-rest-api?apiVersion=2022-11-28#example-encrypting-a-secret-using-c) -requires that secrets be encrypted using the [libsodium](https://github.com/jedisct1/libsodium) library. - -## Prerequisites - -This module relies on the following external resources: - -- The [PSModule framework](https://github.com/PSModule) for building, testing, and publishing the module. -- The [libsodium](https://github.com/jedisct1/libsodium) library for cryptographic operations. +Sodium is a PowerShell module for handling Sodium-encrypted secrets. ## Installation -To install the module from the PowerShell Gallery, use the following command: +Install the module from the PowerShell Gallery: ```powershell Install-PSResource -Name Sodium Import-Module -Name Sodium ``` -## Examples +## Documentation -### Example 1: Generate a new key pair +Documentation is published at [psmodule.io/Sodium](https://psmodule.io/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 - -PublicKey PrivateKey ---------- ---------- -9fv51aqi00MYN4UR7Ew/DLXMS9t1NapLs7yyo+vegz4= MiJAFUZxZ1UCbQTwKfH7HY6AhIFYQlnok5fBD2K+y/g= -``` - -### 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. - -```powershell -$params = @{ - Message = "mymessage" - PublicKey = "9fv51aqi00MYN4UR7Ew/DLXMS9t1NapLs7yyo+vegz4=" -} -ConvertTo-SodiumSealedBox @params - -905j4S/JyP9XBBmOIdHSOXiDu7fUtZo9TFIMnAfBMESgcVBwttLnEyxJn4xPEX5OMKQ+Bc4P6Hg= -``` - -### 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. - -```powershell -$params = @{ - SealedBox = '905j4S/JyP9XBBmOIdHSOXiDu7fUtZo9TFIMnAfBMESgcVBwttLnEyxJn4xPEX5OMKQ+Bc4P6Hg=' - PublicKey = '9fv51aqi00MYN4UR7Ew/DLXMS9t1NapLs7yyo+vegz4=' - PrivateKey = 'MiJAFUZxZ1UCbQTwKfH7HY6AhIFYQlnok5fBD2K+y/g=' #gitleaks:allow -} -ConvertFrom-SodiumSealedBox @params - -mymessage -``` - -### Finding More Examples - -For additional examples, refer to the [examples](examples) folder. - -Alternatively, you can use the following command to list all available commands in this module: +Use PowerShell help and command discovery for module details: ```powershell Get-Command -Module Sodium -``` - -To view examples for a specific command, use: - -```powershell Get-Help -Examples ``` ## Contributing -Coder or not, you can contribute to this project! We welcome all contributions. - -### For Users - -If you don't code, you still have valuable insights that can improve this project. -If the module behaves unexpectedly, throws errors, or lacks functionality, you can help by submitting bug reports and feature requests. -Please check the [issues](https://github.com/PSModule/Sodium/issues) tab and submit a new issue if needed. - -### For Developers - -If you are a developer, we welcome your contributions. -Please read the [Contribution Guidelines](CONTRIBUTING.md) for more information. - -You can help by picking up an existing issue or submitting a new one if you have an idea for a feature or improvement. - -## Acknowledgements - -This module would not be possible without the following resources: - -- **libsodium** | [Docs](https://doc.libsodium.org/) | [GitHub](https://github.com/jedisct1/libsodium) +Issues and pull requests are welcome. Please use the repository issue tracker to report bugs, request features, or discuss improvements. From f76cbbd8394239e9fc3d4b3bf35e1fda568c05b2 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Mon, 6 Jul 2026 10:32:08 +0200 Subject: [PATCH 2/2] Address Copilot README review --- README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 34a4784..2805767 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Sodium -Sodium is a PowerShell module for handling Sodium-encrypted secrets. +Sodium is a PowerShell module for handling libsodium-based encryption and decryption. ## Installation @@ -11,6 +11,8 @@ Install-PSResource -Name Sodium Import-Module -Name Sodium ``` +On Windows, the module requires the Microsoft Visual C++ Redistributable for Visual Studio 2015 or later. + ## Documentation Documentation is published at [psmodule.io/Sodium](https://psmodule.io/Sodium/). @@ -19,7 +21,7 @@ Use PowerShell help and command discovery for module details: ```powershell Get-Command -Module Sodium -Get-Help -Examples +Get-Help ConvertTo-SodiumSealedBox -Examples ``` ## Contributing