Update pwsh style to latest community standards #52
347
README.md
347
README.md
|
|
@ -1,166 +1,181 @@
|
||||||
[](https://ci.appveyor.com/project/OCram85/pscredentialstore/branch/master)
|
<p align="right">
|
||||||
[](https://ci.appveyor.com/project/OCram85/pscredentialstore/branch/master/tests)
|
<img src="http://forthebadge.com/images/badges/built-with-love.svg">
|
||||||
[](https://coveralls.io/github/OCram85/PSCredentialStore?branch=master)
|
<img src="http://forthebadge.com/images/badges/for-you.svg">
|
||||||
[](https://codecov.io/gh/OCram85/PSCredentialStore)
|
</p>
|
||||||
[](https://www.powershellgallery.com/packages/PSCredentialStore)
|
|
||||||
[](https://www.powershellgallery.com/packages/PSCredentialStore)
|
<p align="center">
|
||||||
[](https://www.powershellgallery.com/packages/PSCredentialStore)
|
<a href="https://github.com/OCram85/PSCredentialStore/">
|
||||||
|
<img src="https://raw.githubusercontent.com/OCram85/PSCredentialStore/master/assets/social-logo.png" alt="PSCredentialStore" />
|
||||||
|
</a>
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<h1 align="center">
|
||||||
|
PSCredentialStore
|
||||||
:key: General
|
</h1>
|
||||||
=======
|
|
||||||
|
<p align="center">
|
||||||
The PSCredentialStore is a simple credential manager for `PSCredential` objects. It stores PSCredentials in a simple json
|
🔐 A simple credential manager to store and reuse multiple PSCredential objects.
|
||||||
file. You can choose between a private and shared credential store. The private one exists in your profile and can
|
</p>
|
||||||
ony accessed by your account on the same machine. The shared store enables you to use different credentials for your
|
|
||||||
scripts without exposing them as plain text.
|
<p align="center">
|
||||||
|
<a href="https://cloud.drone.io/OCram85/PSCredentialStore">
|
||||||
PSCredentialStore was developed to simplify the delegation of complex powershell scripts. In this case you often
|
<img src="https://cloud.drone.io/api/badges/OCram85/PSCredentialStore/status.svg" alt="Master Branch Build Status">
|
||||||
need to store credentials for non interactive usage like in scheduled tasks.
|
</a>
|
||||||
|
<a href="https://codecov.io/gh/OCram85/PSCredentialStore">
|
||||||
Starting with version `1.0.0` PSCredential uses Pfx certificates fo encryption. You can use Pfx certificate files
|
<img src="https://codecov.io/gh/OCram85/PSCredentialStore/branch/master/graph/badge.svg" alt="CodeCov">
|
||||||
or certificates stored in the certificate store.
|
</a>
|
||||||
|
<a href="https://www.powershellgallery.com/packages/PSCredentialStore">
|
||||||
For more details read the [about_PSCredentialStore](/docs/about_PSCredentialStore.md) page on github or via CLI with
|
<img src="https://img.shields.io/powershellgallery/v/PSCredentialStore.svg?style=plastic" alt="PowershellGallery Published Version">
|
||||||
`Get-Help about_PSCredentialStore`.
|
</a>
|
||||||
|
<a href="https://www.powershellgallery.com/packages/PSCredentialStore">
|
||||||
You can find the [reference](/docs/PSCredentialStore.md) in the /docs/ path as well.
|
<img src="https://img.shields.io/powershellgallery/vpre/PSCredentialStore.svg?label=latest%20preview&style=plastic" />
|
||||||
|
</a>
|
||||||
:vulcan_salute: Requirements
|
<a href="https://www.powershellgallery.com/packages/PSCredentialStore">
|
||||||
============
|
<img src="https://img.shields.io/powershellgallery/dt/PSCredentialStore.svg?style=plastic" />
|
||||||
|
</a>
|
||||||
- PowerShell >= `5.1`
|
</p>
|
||||||
- .NET Framework >= `4.6` or .NET Core >= `1.0`
|
|
||||||
|
|
||||||
:bomb: About Security
|
## :key: General
|
||||||
============
|
|
||||||
|
The PSCredentialStore is a simple credential manager for `PSCredential` objects. It stores PSCredentials in a simple json
|
||||||
>This section explains some security topics and the the design decisions we made to balance the usage and security needs.
|
file. You can choose between a private and shared credential store. The private one exists in your profile and can
|
||||||
|
ony accessed by your account on the same machine. The shared store enables you to use different credentials for your
|
||||||
To be able to delegate `PSCredentials` objects we can't exclusively rely on the `SecureString` cmdlets. You can't
|
scripts without exposing them as plain text.
|
||||||
decrypt and reuse such credentials from a different user account or even machine. This is caused by automatically
|
|
||||||
generated encryption key which, is used create a `Secure String` based encrypted string.
|
PSCredentialStore was developed to simplify the delegation of complex powershell scripts. In this case you often
|
||||||
|
need to store credentials for non interactive usage like in scheduled tasks.
|
||||||
In order to delegate a password, while still using the underlying security framework, we have to provide a custom
|
|
||||||
encryption key. This leads to the fact, that everyone who has access to the key could encrypt or decrypt your data.
|
Starting with version `1.0.0` PSCredential uses Pfx certificates fo encryption. You can use Pfx certificate files
|
||||||
|
or certificates stored in the certificate store.
|
||||||
So we decided to use the public and private keys from valid certificates as part of the custom encryption keys to encrypt your data.
|
|
||||||
|
For more details read the [about_PSCredentialStore](/docs/about_PSCredentialStore.md) page on github or via CLI with
|
||||||
This means clearly: Everyone who has access to the `CredentialStore` needs also access to the certificate file to work with it.
|
`Get-Help about_PSCredentialStore`.
|
||||||
|
|
||||||
Keep in mind you need to secure the access with your NTFS file permissions to avoid unwanted usage. Another option is
|
You can find the [reference](/docs/PSCredentialStore.md) in the /docs/ path as well.
|
||||||
to import the certificate into your certification vaults of you operating system. In this case you can grand the
|
|
||||||
permission to the certificates itself.
|
## :vulcan_salute: Requirements
|
||||||
|
|
||||||
Here is s brief hierarchy description of the certificate location: *(First match wins)*
|
- PowerShell >= `5.1`
|
||||||
|
- .NET Framework >= `4.6` or .NET Core >= `1.0`
|
||||||
| CredentialStore Type | Certificate Location |
|
|
||||||
| -------------------- | ---------------------- |
|
## :bomb: About Security
|
||||||
| Private | `CurrentUser`\\`My` |
|
|
||||||
| Shared (Windows) | `CurrentUser`\\`My` |
|
>This section explains some security topics and the the design decisions we made to balance the usage and security needs.
|
||||||
| | `LocalMachine`\\`Root` |
|
|
||||||
| Shared (Linux) | `LocalMachine`\\`My` |
|
To be able to delegate `PSCredentials` objects we can't exclusively rely on the `SecureString` cmdlets. You can't
|
||||||
| | `LocalMachine`\\`Root` |
|
decrypt and reuse such credentials from a different user account or even machine. This is caused by automatically
|
||||||
|
generated encryption key which, is used create a `Secure String` based encrypted string.
|
||||||
|
|
||||||
|
In order to delegate a password, while still using the underlying security framework, we have to provide a custom
|
||||||
:hammer_and_wrench: Installation
|
encryption key. This leads to the fact, that everyone who has access to the key could encrypt or decrypt your data.
|
||||||
============
|
|
||||||
|
So we decided to use the public and private keys from valid certificates as part of the custom encryption keys to encrypt your data.
|
||||||
:artificial_satellite: PowerShellGallery.com (Recommended Way)
|
|
||||||
---------------------------------------
|
This means clearly: Everyone who has access to the `CredentialStore` needs also access to the certificate file to work with it.
|
||||||
|
|
||||||
* Make sure you use PowerShell 5.1 or higher with `$PSVersionTable`.
|
Keep in mind you need to secure the access with your NTFS file permissions to avoid unwanted usage. Another option is
|
||||||
* Use the builtin PackageManagement and install with: `Import-Module PowerShellGet; Install-Module 'PSCredentialStore' -Repository 'PSGallery'`
|
to import the certificate into your certification vaults of you operating system. In this case you can grand the
|
||||||
* Additionally use the `-AllowPrerelease` switch until we publish the final release!
|
permission to the certificates itself.
|
||||||
* Done. Start exploring the Module with `Import-Module PSCredentialStore ; Get-Command -Module PSCredentialStore`
|
|
||||||
|
Here is s brief hierarchy description of the certificate location: *(First match wins)*
|
||||||
:building_construction: Manual Way
|
|
||||||
----------
|
| CredentialStore Type | Certificate Location |
|
||||||
|
| -------------------- | ---------------------- |
|
||||||
* Take a look at the [Latest Release](https://github.com/OCram85/PSCredentialStore/releases/latest) page.
|
| Private | `CurrentUser`\\`My` |
|
||||||
* Download the `PSCredentialStore.zip`.
|
| Shared (Windows) | `CurrentUser`\\`My` |
|
||||||
* Unpack the zip file and put it in your Powershell module path.
|
| | `LocalMachine`\\`Root` |
|
||||||
* Don't forget to change the NTFS permission flag in the context menu.
|
| Shared (Linux) | `LocalMachine`\\`My` |
|
||||||
* Start with `Import-Module PSCredentialStore`
|
| | `LocalMachine`\\`Root` |
|
||||||
|
|
||||||
:sparkles: Quick Start
|
## :hammer_and_wrench: Installation
|
||||||
-----------
|
|
||||||
|
### :artificial_satellite: PowerShellGallery.com (Recommended Way)
|
||||||
**1.** First we need a blank credential store. You can decide between a *private* or *shared* store. The private
|
|
||||||
Credential Store can only be accessed with your profile on the machine you created it.
|
* Make sure you use PowerShell 5.1 or higher with `$PSVersionTable`.
|
||||||
|
* Use the builtin PackageManagement and install with: `Import-Module PowerShellGet; Install-Module 'PSCredentialStore' -Repository 'PSGallery'`
|
||||||
Starting with version `1.0.0` you can decide the storage type of your fresh created certificate. As default
|
* Additionally use the `-AllowPrerelease` switch until we publish the final release!
|
||||||
PSCredentialStore creates a new pfx certificate file beside the credential store itself. Optionally you can provide
|
* Done. Start exploring the Module with `Import-Module PSCredentialStore ; Get-Command -Module PSCredentialStore`
|
||||||
the parameter `-UseCertStore`. This imports the new certificate in the user or machine certificate store as well.
|
|
||||||
|
### :building_construction: Manual Way
|
||||||
```powershell
|
|
||||||
# Private credential store
|
* Take a look at the [Latest Release](https://github.com/OCram85/PSCredentialStore/releases/latest) page.
|
||||||
New-CredentialStore
|
* Download the `PSCredentialStore.zip`.
|
||||||
|
* Unpack the zip file and put it in your Powershell module path.
|
||||||
# Private credential store with certificate store usage
|
* Don't forget to change the NTFS permission flag in the context menu.
|
||||||
New-CredentialStore -UseCertStore
|
* Start with `Import-Module PSCredentialStore`
|
||||||
|
|
||||||
# Shared credential store
|
### :sparkles: Quick Start
|
||||||
New-CredentialStore -Shared
|
|
||||||
|
**1.** First we need a blank credential store. You can decide between a *private* or *shared* store. The private
|
||||||
#Shared credential store in custom location
|
Credential Store can only be accessed with your profile on the machine you created it.
|
||||||
New-CredentialStore -Shared -Path 'C:\CredentialStore.json'
|
|
||||||
```
|
Starting with version `1.0.0` you can decide the storage type of your fresh created certificate. As default
|
||||||
|
PSCredentialStore creates a new pfx certificate file beside the credential store itself. Optionally you can provide
|
||||||
**2.** Now you can manage your credential store items:
|
the parameter `-UseCertStore`. This imports the new certificate in the user or machine certificate store as well.
|
||||||
```powershell
|
|
||||||
# This will prompt for credentials and stores it in a private store
|
```powershell
|
||||||
New-CredentialStoreItem -RemoteHost 'dc01.myside.local' -Identifier 'AD'
|
# Private credential store
|
||||||
|
New-CredentialStore
|
||||||
# You can now use it in other scripts like this:
|
|
||||||
$DCCreds = Get-CredentialStoreItem -RemoteHost 'dc01.myside.local' -Identifier 'AD'
|
# Private credential store with certificate store usage
|
||||||
Invoke-Command -ComputerName 'dc01.myside.local' -Credential $DCCreds -ScripBlock {Get-Process}
|
New-CredentialStore -UseCertStore
|
||||||
```
|
|
||||||
|
# Shared credential store
|
||||||
The credential store contains also a simple function to establish a connection with several systems or protocols.
|
New-CredentialStore -Shared
|
||||||
If you have already installed the underlying framework / modules, you can connect these endpoints:
|
|
||||||
|
#Shared credential store in custom location
|
||||||
* **CiscoUcs** - Establish a connection to a Cisco UCS fabric interconnect.
|
New-CredentialStore -Shared -Path 'C:\CredentialStore.json'
|
||||||
* Required Modules: [`Cisco.UCS.Core`, `Cisco.UCSManager`](https://software.cisco.com/download/release.html?i=!y&mdfid=286305108&softwareid=284574017&release=2.1.1)
|
```
|
||||||
* **FTP** - Establish a connection to a FTP host.
|
|
||||||
* Required Modules: [`WinSCP`](https://www.powershellgallery.com/packages/WinSCP)
|
**2.** Now you can manage your credential store items:
|
||||||
* **NetAppFAS** - Establish a connection to a NetApp Clustered ONTAP filer.
|
```powershell
|
||||||
* Required Modules: [`DataONTAP`](http://mysupport.netapp.com/tools/info/ECMLP2310788I.html?productID=61926)
|
# This will prompt for credentials and stores it in a private store
|
||||||
* **VMware** - Establish a connection to a VMware vCenter or ESXi host.
|
New-CredentialStoreItem -RemoteHost 'dc01.myside.local' -Identifier 'AD'
|
||||||
* Required Modules: [`VMware.VimAutomation.Core`](https://www.powershellgallery.com/packages/VMware.PowerCLI)
|
|
||||||
* **CisServer** - Establish a connection to the CisServer Service on vCenter Host.
|
# You can now use it in other scripts like this:
|
||||||
* Required Modules: [`VMware.VimAutomation.Cis.Core`](https://www.powershellgallery.com/packages/VMware.PowerCLI)
|
$DCCreds = Get-CredentialStoreItem -RemoteHost 'dc01.myside.local' -Identifier 'AD'
|
||||||
* **ExchangeHTTP** - Establish a remote connection with an Exchange endpoint via http.
|
Invoke-Command -ComputerName 'dc01.myside.local' -Credential $DCCreds -ScripBlock {Get-Process}
|
||||||
* Requires PowerShell remoting
|
```
|
||||||
* **ExchangeHTTPS** - Establish a remote connection with an Exchange endpoint via https.
|
|
||||||
* Requires PowerShell remoting
|
The credential store contains also a simple function to establish a connection with several systems or protocols.
|
||||||
* **SCP** - Establish a SCP connection.
|
If you have already installed the underlying framework / modules, you can connect these endpoints:
|
||||||
* Required Modules: [`WinSCP`](https://www.powershellgallery.com/packages/WinSCP)
|
|
||||||
|
* **CiscoUcs** - Establish a connection to a Cisco UCS fabric interconnect.
|
||||||
Here are some basic examples:
|
* Required Modules: [`Cisco.UCS.Core`, `Cisco.UCSManager`](https://software.cisco.com/download/release.html?i=!y&mdfid=286305108&softwareid=284574017&release=2.1.1)
|
||||||
|
* **FTP** - Establish a connection to a FTP host.
|
||||||
```powershell
|
* Required Modules: [`WinSCP`](https://www.powershellgallery.com/packages/WinSCP)
|
||||||
Connect-To -RemoteHost "ucs.myside.local" -Type CiscoUcs
|
* **NetAppFAS** - Establish a connection to a NetApp Clustered ONTAP filer.
|
||||||
Connect-To -RemoteHost "ftp.myside.local" -Type FTP
|
* Required Modules: [`DataONTAP`](http://mysupport.netapp.com/tools/info/ECMLP2310788I.html?productID=61926)
|
||||||
Connect-To -RemoteHost "fas.myside.local" -Type NetAppFAS
|
* **VMware** - Establish a connection to a VMware vCenter or ESXi host.
|
||||||
Connect-To -RemoteHost "esx01.myside.local" -Type VMware
|
* Required Modules: [`VMware.VimAutomation.Core`](https://www.powershellgallery.com/packages/VMware.PowerCLI)
|
||||||
Connect-To -RemoteHost "vcr.myside.local" -Type CisServer
|
* **CisServer** - Establish a connection to the CisServer Service on vCenter Host.
|
||||||
Connect-To -RemoteHost "exchange1.myside.local" -Type ExchangeHTTP
|
* Required Modules: [`VMware.VimAutomation.Cis.Core`](https://www.powershellgallery.com/packages/VMware.PowerCLI)
|
||||||
Connect-To -RemoteHost "exchange1.myside.local" -Type ExchangeHTTPS
|
* **ExchangeHTTP** - Establish a remote connection with an Exchange endpoint via http.
|
||||||
Connect-To -RemoteHost "ubuntu.myside.local" -Type SCP
|
* Requires PowerShell remoting
|
||||||
```
|
* **ExchangeHTTPS** - Establish a remote connection with an Exchange endpoint via https.
|
||||||
|
* Requires PowerShell remoting
|
||||||
:pushpin: Credits
|
* **SCP** - Establish a SCP connection.
|
||||||
-------
|
* Required Modules: [`WinSCP`](https://www.powershellgallery.com/packages/WinSCP)
|
||||||
|
|
||||||
A huge thanks to all the people who helped with their projects and indirect contributions which made this possible!
|
Here are some basic examples:
|
||||||
|
|
||||||
- This module is inspired by the awesome work of Dave Wyatt ([@dlwyatt](https://github.com/dlwyatt)) with articles like these:
|
```powershell
|
||||||
- https://powershell.org/2013/11/24/saving-passwords-and-preventing-other-processes-from-decrypting-them/
|
Connect-To -RemoteHost "ucs.myside.local" -Type CiscoUcs
|
||||||
- https://powershell.org/2014/02/01/revisited-powershell-and-encryption/
|
Connect-To -RemoteHost "ftp.myside.local" -Type FTP
|
||||||
- The awesome people from [LibreSSL](http://www.libressl.org/) which publishes the [portable openssl/libressl binaries](https://github.com/libressl-portable/portable)!
|
Connect-To -RemoteHost "fas.myside.local" -Type NetAppFAS
|
||||||
|
Connect-To -RemoteHost "esx01.myside.local" -Type VMware
|
||||||
|
Connect-To -RemoteHost "vcr.myside.local" -Type CisServer
|
||||||
|
Connect-To -RemoteHost "exchange1.myside.local" -Type ExchangeHTTP
|
||||||
|
Connect-To -RemoteHost "exchange1.myside.local" -Type ExchangeHTTPS
|
||||||
|
Connect-To -RemoteHost "ubuntu.myside.local" -Type SCP
|
||||||
|
```
|
||||||
|
|
||||||
|
### :pushpin: Credits
|
||||||
|
|
||||||
|
A huge thanks to all the people who helped with their projects and indirect contributions which made this possible!
|
||||||
|
|
||||||
|
- This module is inspired by the awesome work of Dave Wyatt ([@dlwyatt](https://github.com/dlwyatt)) with articles like these:
|
||||||
|
- https://powershell.org/2013/11/24/saving-passwords-and-preventing-other-processes-from-decrypting-them/
|
||||||
|
- https://powershell.org/2014/02/01/revisited-powershell-and-encryption/
|
||||||
|
- The awesome people from [LibreSSL](http://www.libressl.org/) which publishes the [portable openssl/libressl binaries](https://github.com/libressl-portable/portable)!
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue