Sodium

A PowerShell module that provides direct bindings to the libsodium cryptographic library.

This module was initially created to serve the needs of the GitHub PowerShell module. GitHub's method for creating or updating secrets via the REST API requires that secrets be encrypted using the libsodium library.

Prerequisites

This module relies on the following external resources:

• The PSModule framework for building, testing, and publishing the module.
• The libsodium library for cryptographic operations.

Installation

To install the module from the PowerShell Gallery, use the following command:

Install-PSResource -Name Sodium
Import-Module -Name Sodium

Examples

Example 1: Generate a new key pair

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.

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.

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. Below, a message is encrypted using the public key from the previous example.

$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, both the private and public keys are required.

$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 folder.

Alternatively, you can use the following command to list all available commands in this module:

Get-Command -Module Sodium

To view examples for a specific command, use:

Get-Help <CommandName> -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 tab and submit a new issue if needed.

For Developers

If you are a developer, we welcome your contributions. Please read the Contribution Guidelines 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 | GitHub