Skip to content
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
107 changes: 8 additions & 99 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,120 +1,29 @@
# 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 libsodium-based encryption and decryption.

## Installation

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

Comment thread
MariusStorhaug marked this conversation as resolved.
```powershell
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](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
```
On Windows, the module requires the Microsoft Visual C++ Redistributable for Visual Studio 2015 or later.

### Finding More Examples
## Documentation

For additional examples, refer to the [examples](examples) folder.
Documentation is published at [psmodule.io/Sodium](https://psmodule.io/Sodium/).

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 <CommandName> -Examples
Get-Help ConvertTo-SodiumSealedBox -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.
Loading