The X509Crypto PowerShell Module
The X509Crypto class library is now more accessible than ever! The X509Crypto PowerShell Module exposes all of the core features of the X509Crypto class library through PowerShell cmdlets. The module can be used in lieu of the commandline utility for X509Alias setup and maintenance, or for protection of sensitive data that must be accessed in your PowerShell scripts (passwords, database connection strings, API keys, etc)
The X509Crypto Powershell module may be imported from the standard Powershell gallery using the Install-Module cmdlet:
# If you are an administrator:
> Install-Module -Name X509Crypto
# Otherwise:
> Install-Module -Name X509Crypto -Scope CurrentUser
Summary of cmdlets
The X509Crypto PowerShell module exports the following cmdlets:
| Cmdlet Name | Description |
|---|---|
| New-X509Alias | Establishes a new X509Alias to use for cryptographic operations |
| Mount-X509Alias | Mounts an existing X509Alias |
| Dismount-X509Alias | Disposes an existing X509Alias (including cryptographic key material) from the current PowerShell session |
| Import-X509Alias | Imports an X509Alias (including certificate, private key and all encrypted secrets) from a password-protected backup file |
| Export-X509Alias | Exports an X509Alias (including certificate, private key and all encrypted secrets) to a password-protected backup file |
| Remove-X509Alias | Removes an X509Alias (including all encrypted secrets and optionally the associated certificate & private key) from the system |
| Protect-X509CryptoSecret | Accepts an identifier and a text expression to encrypt (such as a password or API key) and stores it in the specified X509Alias as a key/value pair |
| Read-X509CryptoSecret | Decrypts an identified text expression that is stored in the specified X509Alias |
| Protect-File | Encrypts a file at the specified path using the identified X509Alias |
| Unprotect-File | Decrypts a file at the specified path using the identified X509Alias, which was originally used to encrypt it |
| Unprotect-X509Alias | Returns all the identifiers and associated decrypted secrets contained within the specified X509Alias |
| Update-X509Alias | Modifies the specified X509Alias to use a different certificate and associated private key (also re-encrypts all secrets contained within the specified X509Alias) |
| Update-X509CryptoFileEncryption | Re-encrypts a file at the specified path such that it is encrypted using a different X509Alias (and associated certificate & private key) |
| Read-X509Context | Lists the X509Alias' and/or encryption certificates available in the specified X509Context (current user or system) |
| Install-X509CryptoCertificate | Installs a certificate and associated private key in the specified X509Context from a PKCS#12 (.pfx or .p12) file |
| Export-X509CryptoCertificate | Exports a certificate and associated private key to a password-protected PKCS#12 (.pfx) file |
Cmdlet Details
Please find, below, detailed descriptions for each of the X509Crypto Cmdlets.
New-X509Alias
Establishes a new X509Alias to use for cryptographic operations
Parameters:
| Name | Type | Description | Required? | Value From Pipeline? | Aliases |
|---|---|---|---|---|---|
| -Location | string | The X509Context in which to create the alias. Acceptable values are "user" and "system" | Yes | No | Context, X509Context, StoreLocation, CertStore, CertStoreLocation, Store |
| -Name | string | The desired name for the X509Alias | Yes | No | Alias, X509Alias |
| -Thumbprint | string | The thumbprint of the encryption certificate. If not specified, a new self-signed encryption certificate will be automatically generated within the specified X509Context. | No | No |
Output Type:
X509Alias
Example:
> New-X509Alias -Location user -Name sample -Thumbprint 349A5332D998DFC0A30C330FE443B2F8449C94BF
New alias "sample" committed to "user" X509Context
Thumbprint: 349A5332D998DFC0A30C330FE443B2F8449C94BF
Name : sample
Thumbprint : 349A5332D998DFC0A30C330FE443B2F8449C94BF
Context : Org.X509Crypto.X509Context
FullName : user\sample
Certificate : [Subject]
CN=Sample
[Issuer]
CN=Sample
[Serial Number]
78A8EF2EC152DEBA41E98FB8774E763D
[Not Before]
11/24/2020 9:05:24 PM
[Not After]
11/24/2021 9:25:24 PM
[Thumbprint]
349A5332D998DFC0A30C330FE443B2F8449C94BF
Mount-X509Alias
Mounts an existing X509Alias
Parameters:
| Name | Type | Description | Required? | Value From Pipeline? | Aliases |
|---|---|---|---|---|---|
| -Location | string | The name of X509Context where the X509Alias exists. Acceptable values are "user" and "system" | Yes | No | Context, X509Context, StoreLocation, CertStore, CertStoreLocation, Store |
| -Name | string | The name for the X509Alias to retrieve | Yes | No | Alias, X509Alias |
Output Type:
X509Alias
Example:
> $Alias = Mount-X509Alias -Name sample -Location user Alias "sample" has been loaded from the "user" X509Context
> $Alias
Name : sample
Thumbprint : 349A5332D998DFC0A30C330FE443B2F8449C94BF
Context : Org.X509Crypto.X509Context
FullName : user\sample
Certificate : [Subject]
CN=Sample
[Issuer]
CN=Sample
[Serial Number]
78A8EF2EC152DEBA41E98FB8774E763D
[Not Before]
11/24/2020 9:05:24 PM
[Not After]
11/24/2021 9:25:24 PM
[Thumbprint]
349A5332D998DFC0A30C330FE443B2F8449C94BF
Dismount-X509Alias
Disposes an existing X509Alias (including cryptographic key material) from the current PowerShell session
Parameters:
| Name | Type | Description | Required? | Value From Pipeline? | Aliases |
|---|---|---|---|---|---|
| -Alias | X509Alias | The X509Alias to dismount | Yes | Yes | X509Alias |
Output Type:
boolean
Example:
> $Alias | Dismount-X509Alias
X509Alias "sample" has been dismounted.
True
Import-X509Alias
Imports an X509Alias (including certificate, private key and all encrypted secrets) from a password-protected backup file
Parameters:
| Name | Type | Description | Required? | Value From Pipeline? | Aliases |
|---|---|---|---|---|---|
| -Location | string | The X509Context in which to import the X509Alias. Acceptable values are "user" and "system" | Yes | No | Context, X509Context, StoreLocation, CertStore, CertStoreLocation, Store |
| -Name | string | The name under which to register this X509Alias (if not specified, the X509Alias name found in the import file will be used) | No | No | Alias, X509Alias |
| -Overwrite | switch | If enabled and an existing X509Alias with the same name already exists in the X509Context specified for "Location", it will be overwritten | No | No | |
| -Path | string | The path to the file where the X509Alias is stored | Yes | No |
Output Type:
X509Alias
Example:
> $Alias = Import-X509Alias -Path p:\_temp\sample.xca -Location user
Enter the password to unlock this X509Alias file: ********
X509Alias "exporttest" has been successfully imported into the user X509Context from the file "p:\_temp\sample.xca"
Export-X509Alias
Exports an X509Alias (including certificate, private key and all encrypted secrets) to a password-protected backup file
Parameters:
| Name | Type | Description | Required? | Value From Pipeline? | Aliases |
|---|---|---|---|---|---|
| -Alias | X509Alias | The X509Alias to export | Yes | Yes | X509Alias |
| -Path | string | The path in which to write the exported X509Alias file | Yes | No | |
| -Overwrite | switch | If enabled and a file already exists in the indicated location for "Path" it will be overwritten. | No | No | |
| -Quiet | switch | If enabled, and a file already exists in the indicated location for "Path" it will be overwritten. Only applicable if "-Overwrite" switch is enabled. | No | No |
Output Type:
Example:
> $Alias | Export-X509Alias -Path p:\_temp\sample
Enter a strong password to protect the X509Alias file: ********
Confirm: ********
X509Alias aliasName was successfully exported to file "p:\_temp\sample.xca"
Remove-X509Alias
Removes an X509Alias (including all encrypted secrets and optionally the associated certificate & private key) from the system
Parameters:
| Name | Type | Description | Required? | Value From Pipeline? | Aliases |
|---|---|---|---|---|---|
| -Alias | X509Alias | The X509Alias to remove from the system | Yes | Yes | X509Alias |
| -DeleteCert | switch | If enabled, the X509Crypto encryption certificate associated with this X509Alias will also be deleted from the X509Context where it presently exists | No | No | |
| -Quiet | switch | If enabled, no confirmation message will be displayed before X509Alias deletion. | No | No |
Output Type:
boolean
Example:
> $Alias | Remove-X509Alias
WARNING! The X509Alias "sample" will be removed from the "user" X509Context. Any secrets contained in this X509Alias will be unrecoverable. Enter "YES" if you wish to proceed
Your entry: YES
Alias "sample" has been removed from the "user" X509Context
True
Protect-X509CryptoSecret
Accepts an identifier and a text expression to encrypt (such as a password or API key) and stores it in the specified X509Alias as a key/value pair
Parameters:
| Name | Type | Description | Required? | Value From Pipeline? | Aliases |
|---|---|---|---|---|---|
| -Alias | X509Alias | The X509Alias with which to protect the text. Use New-Alias or Get-Alias cmdlet to create. | Yes | Yes | X509Alias |
| -Id | string | The identifier under which to store the encrypted secret (used for retrieval) | Yes | No | Secret, SecretName, Identifier |
| -Input | string | The text expression to be encrypted | Yes | No | Text, Expression |
| -Overwrite | switch | If enabled and there is already a secret contained in the specified X509Alias stored under the name specified for "-Id" the existing secret will be overwritten. | No | No |
Output Type:
boolean
Example:
> $Alias | Protect-X509CryptoSecret -Id APIKey -Input '8f3b4cae962ea7f' Secret "APIKey" added to X509Alias "exporttest" in the user X509Context
True
Read-X509CryptoSecret
Decrypts an identified text expression that is stored in the specified X509Alias
Parameters:
| Name | Type | Description | Required? | Value From Pipeline? | Aliases |
|---|---|---|---|---|---|
| -Alias | X509Alias | The X509Alias with which to protect the text. Use New-Alias or Get-Alias cmdlet to create. | Yes | Yes | X509Alias |
| -Id | string | The identifier under which the encrypted secret is stored within the X509Alias. May not be combined with "-Expression" | No | No | Secret, SecretName, Identifier |
| -Input | string | The ciphertext expression to be decrypted. May not be combined with "-Id" | No | No | Ciphertext, Expression |
Output Type:
string
Example:
> $APIKey = $($Alias | Read-X509CryptoSecret -Id APIKey)
> $APIKey
8f3b4cae962ea7f
Protect-File
Encrypts a file at the specified path using the identified X509Alias
Parameters:
| Name | Type | Description | Required? | Value From Pipeline? | Aliases |
|---|---|---|---|---|---|
| -Alias | X509Alias | The X509Alias to use for encryption | Yes | Yes | X509Alias |
| -Path | string | The path of the file to encrypt | Yes | No | |
| -Output | string | The path to which to write the encrypted file. If not specified, the name of the file indicated for "-Path" will be appended with a ".ctx" extension | No | No | |
| -Overwrite | switch | If enabled, should a file already exist under the same path as specified/inferred for "Output", it will be replaced. | No | No | |
| -Erase | int | The number of times to write over the disk sectors where the plaintext file exists. If not specified, the plaintext file will not be deleted or erased. | No | No | Wipe |
| -Quiet | switch | If enabled, no warning will be displayed before the plaintext file specified for "-Path" is wiped from disk. Not appliable if "-Erase" is not enabled | No | No |
Output Type:
Example:
> $Alias | Protect-File -Path P:\_temp\Capture.PNG
The file "P:\_temp\Capture.PNG" was successfully encrypted. The ciphertext file name is "P:\_temp\Capture.PNG.ctx"
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 12/1/2020 1:24 PM 8344 Capture.PNG.ctx
Unprotect-File
Decrypts a file at the specified path using the identified X509Alias, which was originally used to encrypt it
Parameters:
| Name | Type | Description | Required? | Value From Pipeline? | Aliases |
|---|---|---|---|---|---|
| -Alias | X509Alias | The X509Alias that was used to encrypt the file | Yes | Yes | X509Alias |
| -Path | string | The path of the file to decrypt | Yes | No | |
| -Output | string | The path to which to write the decrypted file. If not specified, the original plaintext file name will be restored | No | No | |
| -Overwrite | switch | If included, should a file already exist under the same path as specified/inferred for "Output", it will be replaced. | No | No | |
| -Erase | int | The number of times to write over the disk sectors where the ciphertext file exists. If not specified, the ciphertext file will not be deleted or erased. | No | No | Wipe |
| -Quiet | switch | If enabled, no warning will be displayed before the plaintext file specified for "-Path" is wiped from disk. Not appliable if "-Erase" is not defined | No | No |
Output Type:
Example:
> $Alias | Unprotect-File -Path P:\_temp\Capture.PNG.ctx -Overwrite
The file "P:\_temp\Capture.PNG.ctx" was successfully decrypted. The recovered file name is "P:\_temp\Capture.PNG"
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 12/1/2020 1:38 PM 8061 Capture.PNG
Unprotect-X509Alias
Returns all the identifiers and associated decrypted secrets contained within the specified X509Alias
Parameters:
| Name | Type | Description | Required? | Value From Pipeline? | Aliases |
|---|---|---|---|---|---|
| -Alias | X509Alias | The X509Alias from which to list secrets | Yes | Yes | X509Alias |
Output Type:
Key/Value string Pairs
Example:
> $Alias | Unprotect-X509Alias
Identifier Value
---------- -----
APIKey 8f3b4cae962ea7f
badpassword Jets1972
SSN 123-45-6789
Update-X509Alias
Modifies the specified X509Alias to use a different certificate and associated private key (also re-encrypts all secrets contained within the specified X509Alias)
Parameters:
| Name | Type | Description | Required? | Value From Pipeline? | Aliases |
|---|---|---|---|---|---|
| -Alias | X509Alias | The source X509Alias from which to move all protected secrets | Yes | Yes | X509Alias |
| -Location | string | The X509Context where the new encryption certificate exists. If not specified, the X509Context of the entry for "Alias" will be used. Acceptable entries are "user" and "system". | No | No | Context, X509Context, StoreLocation, CertStore, CertStoreLocation, Store |
| -Thumbprint | string | The thumbprint of the new encryption certificate | Yes | No |
Output Type:
X509Alias
Example:
> $Alias | Update-X509Alias -Location user -thumbprint 30C1120243EC8782AB08CB17274C0A847C46304F
X509Alias Sample successfully updated. Now using encryption certificate with thumbprint 30C1120243EC8782AB08CB17274C0A847C46304F from the user X509Context
Name : Sample
Thumbprint : 30C1120243EC8782AB08CB17274C0A847C46304F
Context : Org.X509Crypto.X509Context
FullName : user\Sample
Certificate : [Subject]
CN=mikeb
[Issuer]
CN=mikeb
[Serial Number]
01
[Not Before]
9/23/2020 11:13:32 PM
[Not After]
9/23/2030 11:13:32 PM
[Thumbprint]
30C1120243EC8782AB08CB17274C0A847C46304F
Update-X509CryptoFileEncryption
Re-encrypts a file at the specified path such that it is encrypted using a different X509Alias (and associated certificate & private key)
Parameters:
| Name | Type | Description | Required? | Value From Pipeline? | Aliases |
|---|---|---|---|---|---|
| -CurrentAlias | X509Alias | The X509Alias that was previously used to encrypt the file | Yes | No | OldAlias, OldX509Alias, CurrentX509Alias |
| -Path | string | The path of the encrytped file which needs to be re-encrypted using a different X509Alias | Yes | No | |
| -TargetAlias | X509Alias | The X509Alias that will re-encrypt the file | Yes | No | NewAlias, NewX509Alias, TargetX509Alias |
Output Type:
Example:
> $NewAlias = New-X509Alias -Name newTest -Context user
New alias "newTest" committed to "user" X509Context
Thumbprint: E4A03C52B06973EF6217F5AB843C3A94C22889A5
> Update-X509CryptoFileEncryption -Path P:\_temp\example.docx.ctx -CurrentAlias $Alias -TargetAlias $NewAlias
The file P:\_temp\example.docx.ctx was successfully re-encrypted using the X509Crypto alias newTest located in the "user" X509Context
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 12/1/2020 2:24 PM 16184 example.docx.ctx
Read-X509Context
Lists the X509Alias' and/or encryption certificates available in the specified X509Context (current user or system)
Parameters:
| Name | Type | Description | Required? | Value From Pipeline? | Aliases |
|---|---|---|---|---|---|
| -Location | string | The X509Context from which to list existing X509Aliases and/or encryption certificates. Acceptable values are "user" and "system" | Yes | No | Context, X509Context, StoreLocation, CertStore, CertStoreLocation, Store |
| -All | switch | If enabled, certificates that are not currently assigned to an X509Alias will also be included in the output | No | No |
Output Type:
X509AliasDescription
Example:
> Read-X509Context user -All
AliasName Thumbprint Subject Expires
---- ---------- ------- -------
CNGTest 007EBE7ECCC97F82A7C269FFE3A12CEB10B07D45 CN=mikeb 11/30/2030 10:16:03 PM
exporttest 30C1120243EC8782AB08CB17274C0A847C46304F CN=mikeb 9/23/2030 11:13:32 PM
myvault 8FD265E90D7FA0B1AAF72260D759B4AEF121C083 CN=Import Test 2 11/24/2021 9:14:44 PM
myvault3 1149C6D8C7EE13582E1DFB5B772CB834FB5C35B0 CN=mikeb 6/24/2030 9:38:40 AM
Non Assigned E536B6568A6FCD41B4BF66409E03C75705F40067 CN=mikeb 12/1/2030 11:32:46 AM
Non Assigned D6F985F4A05344DCE3926B95C46B33084F32D676 CN=mikeb 9/23/2030 11:11:34 PM
Non Assigned B6B1AD77CB33AFB478E5939189C381B2609622DE CN=mikeb 11/21/2030 9:54:04 PM
Install-X509CryptoCertificate
Installs a certificate and associated private key in the specified X509Context from a PKCS#12 (.pfx or .p12) file
Parameters:
| Name | Type | Description | Required? | Value From Pipeline? | Aliases |
|---|---|---|---|---|---|
| -Path | string | The path to the PKCS#12 file conaining the encryption certificate and private key | Yes | No | |
| -Location | string | The X509Context in which to install the encryption certificate. Acceptable values are "user" and "system" | Yes | No | Context, X509Context, StoreLocation, CertStore, CertStoreLocation, Store |
| -Name | string | The name of a new X509Alias in which to associate this encryption certificate | Yes | No | Alias, X509Alias |
| -Overwrite | switch | If enabled and an existing X509Alias with the name indicated for "-Name" is found, it will be overwritten | No | No |
Output Type:
X509Alias
Example:
> Install-X509CryptoCertificate -Path P:\_temp\example.pfx -Location user -name installExample
Path: P:\_temp\example.pfx
Enter the password to unlock "example.pfx": ********
Added encryption certificate to the user X509Context.
Certificate Thumbprint: B31FE7E7AE5229F8186782742CF579197FA859FD
X509Alias: installExample
Name : installExample
Thumbprint : B31FE7E7AE5229F8186782742CF579197FA859FD
Context : Org.X509Crypto.X509Context
FullName : user\installExample
Certificate : [Subject]
CN=mikeb
[Issuer]
CN=mikeb
[Not Before]
6/20/2020 9:36:10 PM
[Not After]
6/20/2030 9:36:10 PM
[Thumbprint]
B31FE7E7AE5229F8186782742CF579197FA859FD
Export-X509CryptoCertificate
Exports a certificate and associated private key to a password-protected PKCS#12 (.pfx) file
Parameters:
| Name | Type | Description | Required? | Value From Pipeline? | Aliases |
|---|---|---|---|---|---|
| -Alias | X509Alias | The source X509Alias from which to export the encryption certificate. Not to be used with the "-Location" and "-Thumbprint" parameters | No | Yes | X509Alias |
| -Location | string | The X509Context from which to export the certificate. Acceptable values are "user" and "system". Must be paired with the "-Thumbprint" parameter. Not to be used with the "-Alias" parameter | No | No | Context, X509Context, StoreLocation, CertStore, CertStoreLocation, Store |
| -Thumbprint | string | The thumbprint of the encryption certificate to export. Must be paired with the "-Location" parameter. Not to be used with the "Alias" parameter | No | No | |
| -Path | The path in which to write the PKCS#12 cert/key bundle file. | Yes | No |
Output Type:
Example:
> $Alias | Export-X509CryptoCertificate -Path p:\_temp\certExpSample
Enter a strong password (needed to unlock the .pfx file): ********
Confirm: ********
Encryption certificate with thumbprint E4A03C52B06973EF6217F5AB843C3A94C22889A5 from the user X509Context has been exported to the file "p:\_temp\certExpSample.pfx"
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 12/1/2020 2:59 PM 2522 certExpSample.pfx