|
1 | 1 | # Sodium |
2 | 2 |
|
3 | | -A PowerShell module that provides direct bindings to the [`libsodium`](https://github.com/jedisct1/libsodium) cryptographic library. |
4 | | - |
5 | | -This module was initially created to serve the needs of the [GitHub PowerShell module](https://github.com/PSModule/GitHub). |
6 | | -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) |
7 | | -requires that secrets be encrypted using the [libsodium](https://github.com/jedisct1/libsodium) library. |
8 | | - |
9 | | -## Prerequisites |
10 | | - |
11 | | -This module relies on the following external resources: |
12 | | - |
13 | | -- The [PSModule framework](https://github.com/PSModule) for building, testing, and publishing the module. |
14 | | -- The [libsodium](https://github.com/jedisct1/libsodium) library for cryptographic operations. |
| 3 | +Sodium is a PowerShell module for handling Sodium-encrypted secrets. |
15 | 4 |
|
16 | 5 | ## Installation |
17 | 6 |
|
18 | | -To install the module from the PowerShell Gallery, use the following command: |
| 7 | +Install the module from the PowerShell Gallery: |
19 | 8 |
|
20 | 9 | ```powershell |
21 | 10 | Install-PSResource -Name Sodium |
22 | 11 | Import-Module -Name Sodium |
23 | 12 | ``` |
24 | 13 |
|
25 | | -## Examples |
| 14 | +## Documentation |
26 | 15 |
|
27 | | -### Example 1: Generate a new key pair |
| 16 | +Documentation is published at [psmodule.io/Sodium](https://psmodule.io/Sodium/). |
28 | 17 |
|
29 | | -The module provides functionality to create a new cryptographic key pair. |
30 | | -The keys are returned as a PowerShell custom object with `PublicKey` and `PrivateKey` properties, encoded in base64 format. |
31 | | -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). |
32 | | - |
33 | | -```powershell |
34 | | -New-SodiumKeyPair |
35 | | -
|
36 | | -PublicKey PrivateKey |
37 | | ---------- ---------- |
38 | | -9fv51aqi00MYN4UR7Ew/DLXMS9t1NapLs7yyo+vegz4= MiJAFUZxZ1UCbQTwKfH7HY6AhIFYQlnok5fBD2K+y/g= |
39 | | -``` |
40 | | - |
41 | | -### Example 2: Deterministic Key Pair Generation |
42 | | - |
43 | | -Generate a key pair deterministically using a seed. The same seed will always produce the same key pair. |
44 | | - |
45 | | -```powershell |
46 | | -New-SodiumKeyPair -Seed 'MySecureSeed' |
47 | | -
|
48 | | -PublicKey PrivateKey |
49 | | --------- - ---------- |
50 | | -WQakMx2mIAQMwLqiZteHUTwmMP6mUdK2FL0WEybWgB8= ci5/7eZ0IbGXtqQMaNvxhJ2d9qwFxA8Kjx+vivSTXqU= |
51 | | -``` |
52 | | - |
53 | | -### Example 3: Encrypt a message using a public key (Sealed Boxes encryption) |
54 | | - |
55 | | -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). |
56 | | -Below, a message is encrypted using the public key from the previous example. |
57 | | - |
58 | | -```powershell |
59 | | -$params = @{ |
60 | | - Message = "mymessage" |
61 | | - PublicKey = "9fv51aqi00MYN4UR7Ew/DLXMS9t1NapLs7yyo+vegz4=" |
62 | | -} |
63 | | -ConvertTo-SodiumSealedBox @params |
64 | | -
|
65 | | -905j4S/JyP9XBBmOIdHSOXiDu7fUtZo9TFIMnAfBMESgcVBwttLnEyxJn4xPEX5OMKQ+Bc4P6Hg= |
66 | | -``` |
67 | | - |
68 | | -### Example 4: Decrypt a Sodium-encrypted sealed box string |
69 | | - |
70 | | -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. |
71 | | - |
72 | | -```powershell |
73 | | -$params = @{ |
74 | | - SealedBox = '905j4S/JyP9XBBmOIdHSOXiDu7fUtZo9TFIMnAfBMESgcVBwttLnEyxJn4xPEX5OMKQ+Bc4P6Hg=' |
75 | | - PublicKey = '9fv51aqi00MYN4UR7Ew/DLXMS9t1NapLs7yyo+vegz4=' |
76 | | - PrivateKey = 'MiJAFUZxZ1UCbQTwKfH7HY6AhIFYQlnok5fBD2K+y/g=' #gitleaks:allow |
77 | | -} |
78 | | -ConvertFrom-SodiumSealedBox @params |
79 | | -
|
80 | | -mymessage |
81 | | -``` |
82 | | - |
83 | | -### Finding More Examples |
84 | | - |
85 | | -For additional examples, refer to the [examples](examples) folder. |
86 | | - |
87 | | -Alternatively, you can use the following command to list all available commands in this module: |
| 18 | +Use PowerShell help and command discovery for module details: |
88 | 19 |
|
89 | 20 | ```powershell |
90 | 21 | Get-Command -Module Sodium |
91 | | -``` |
92 | | - |
93 | | -To view examples for a specific command, use: |
94 | | - |
95 | | -```powershell |
96 | 22 | Get-Help <CommandName> -Examples |
97 | 23 | ``` |
98 | 24 |
|
99 | 25 | ## Contributing |
100 | 26 |
|
101 | | -Coder or not, you can contribute to this project! We welcome all contributions. |
102 | | - |
103 | | -### For Users |
104 | | - |
105 | | -If you don't code, you still have valuable insights that can improve this project. |
106 | | -If the module behaves unexpectedly, throws errors, or lacks functionality, you can help by submitting bug reports and feature requests. |
107 | | -Please check the [issues](https://github.com/PSModule/Sodium/issues) tab and submit a new issue if needed. |
108 | | - |
109 | | -### For Developers |
110 | | - |
111 | | -If you are a developer, we welcome your contributions. |
112 | | -Please read the [Contribution Guidelines](CONTRIBUTING.md) for more information. |
113 | | - |
114 | | -You can help by picking up an existing issue or submitting a new one if you have an idea for a feature or improvement. |
115 | | - |
116 | | -## Acknowledgements |
117 | | - |
118 | | -This module would not be possible without the following resources: |
119 | | - |
120 | | -- **libsodium** | [Docs](https://doc.libsodium.org/) | [GitHub](https://github.com/jedisct1/libsodium) |
| 27 | +Issues and pull requests are welcome. Please use the repository issue tracker to report bugs, request features, or discuss improvements. |
0 commit comments