diff --git a/README.md b/README.md index dfb10b7..d8dd59b 100644 --- a/README.md +++ b/README.md @@ -1,45 +1,42 @@ -[![AppVeyor branch](https://img.shields.io/appveyor/ci/OCram85/PSCredentialStore/master.svg?style=plastic "Master Banch Build Status")](https://ci.appveyor.com/project/OCram85/pscredentialstore/branch/master) +[![AppVeyor branch](https://img.shields.io/appveyor/ci/OCram85/PSCredentialStore/master.svg?style=plastic "Master Branch Build Status")](https://ci.appveyor.com/project/OCram85/pscredentialstore/branch/master) [![AppVeyor tests branch](https://img.shields.io/appveyor/tests/OCram85/PSCredentialStore/master.svg?style=plastic "Pester Tests Results")](https://ci.appveyor.com/project/OCram85/pscredentialstore/branch/master/tests) [![Coveralls github](https://img.shields.io/coveralls/github/OCram85/PSCredentialStore.svg?style=plastic "Coveralls.io Coverage Report")](https://coveralls.io/github/OCram85/PSCredentialStore?branch=master) [![PowerShell Gallery](https://img.shields.io/powershellgallery/v/PSCredentialStore.svg?style=plastic "PowershellGallery Published Version")](https://www.powershellgallery.com/packages/PSCredentialStore) +[![PowerShell Gallery](https://img.shields.io/powershellgallery/vpre/PSCredentialStore.svg?label=latest%20preview&style=plastic "PowershellGallery Latest Preview Version")](https://www.powershellgallery.com/packages/PSCredentialStore) [![PowerShell Gallery](https://img.shields.io/powershellgallery/dt/PSCredentialStore.svg?style=plastic "PowershellGallery Downloads")](https://www.powershellgallery.com/packages/PSCredentialStore) ![forthebadge](http://forthebadge.com/images/badges/built-with-love.svg) ![forthebadge](http://forthebadge.com/images/badges/for-you.svg) -General +:key: General ======= -The PSCredentialStore is a simple credential manager for PSCredentials. It stores PSCredentials in a simple json +The PSCredentialStore is a simple credential manager for `PSCredential` objects. It stores PSCredentials in a simple json 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 scripts without exposing them as plain text. -**The shared store isn't 100% secure and I don't recommend using it in production!** - 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. +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. + For more details read the [about_PSCredentialStore](/docs/about_PSCredentialStore.md) page on github or via CLI with `Get-Help about_PSCredentialStore`. -:exclamation: Upcoming Changes :exclamation: -================ +You can find the [reference](/docs/PSCredentialStore.md) in the /docs/ path as well. -The will be some breaking changes starting with the `0.5.0.xxx`: - -- **PSCredentialStore will use PFX certificates to encrypt your credentials.** - - This replaces the the current encryption methods and you need to recreate or upgrade your pre existing stores. -- The changes allows the PSCredentialStore module to support the PowerShell `Core` editions. - - Yes this means, you can use the module on any PowerShell 6 supported linux distribution. -- It's also possible to create a shared credential store and transfer it onto a another platform like: -`Windows -- to --> Linux` and vice versa. -- Automatically creates self signed certificate with 2048 bits RSA keys for encryption. - -Installation +:vulcan_salute: Requirements ============ -PowerShellGallery.com (Recommended Way) +- PowerShell >= `5.1` +- .NET Framework >= `4.6` or .NET Core >= `1.0` + +:hammer_and_wrench: Installation +============ + +:artificial_satellite: PowerShellGallery.com (Recommended Way) --------------------------------------- * Make sure you use PowerShell 5.1 or higher with `$PSVersionTable`. @@ -47,7 +44,7 @@ PowerShellGallery.com (Recommended Way) * Additionally use the `-AllowPrerelease` switch until we publish the final release! * Done. Start exploring the Module with `Import-Module PSCredentialStore ; Get-Command -Module PSCredentialStore` -Manual Way +:building_construction: Manual Way ---------- * Take a look at the [Latest Release](https://github.com/OCram85/PSCredentialStore/releases/latest) page. @@ -56,19 +53,27 @@ Manual Way * Don't forget to change the NTFS permission flag in the context menu. * Start with `Import-Module PSCredentialStore` -Quick Start +:sparkles: Quick Start ----------- **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. + +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 +the parameter `-UseCertStore`. This imports the new certificate in the user or machine certificate store as well. + ```powershell # Private credential store New-CredentialStore -# Shared credential rtore +# Private credential store with certificate store usage +New-CredentialStore -UseCertStore + +# Shared credential store New-CredentialStore -Shared -#Shared credential store in custom Location +#Shared credential store in custom location New-CredentialStore -Shared -Path 'C:\CredentialStore.json' ``` @@ -110,14 +115,17 @@ Connect-To -RemoteHost "ftp.myside.local" -Type FTP 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 ``` -Credits +: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 @dlwyatt with articles like these: +- 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)! diff --git a/appveyor.yml b/appveyor.yml index b51512b..6f3197b 100644 --- a/appveyor.yml +++ b/appveyor.yml @@ -1,8 +1,5 @@ -# release version: -#version: 0.5.0.{build} - # pre release version: -version: 0.5.{build} +version: 1.0.{build} #branches: # only: diff --git a/docs/Connect-To.md b/docs/Connect-To.md index 96c0a5a..f0fb164 100644 --- a/docs/Connect-To.md +++ b/docs/Connect-To.md @@ -1,10 +1,3 @@ ---- -external help file: PSCredentialStore-help.xml -Module Name: PSCredentialStore -online version: https://github.com/OCram85/PSCredentialStore -schema: 2.0.0 ---- - # Connect-To ## SYNOPSIS @@ -14,14 +7,14 @@ Connects to the given host using the stored CredentialStoreItem. ### Private (Default) ``` -Connect-To -RemoteHost [-Identifier ] -Type [-Credentials ] +Connect-To -RemoteHost [-Identifier ] -Type [-Credentials ] [-PassThru] [] ``` ### Shared ``` -Connect-To -RemoteHost [-Identifier ] -Type [-Credentials ] - [-Path ] [-Shared] [] +Connect-To -RemoteHost [-Identifier ] -Type [-Credentials ] [-Shared] + [-Path ] [-PassThru] [] ``` ## DESCRIPTION @@ -29,37 +22,37 @@ Establish a connection to the selected host using a stored CredentialStoreItem. ## EXAMPLES -### EXAMPLE 1 +### BEISPIEL 1 ``` Connect-To -RemoteHost "ucs.myside.local" -Type CiscoUcs ``` -### EXAMPLE 2 +### BEISPIEL 2 ``` Connect-To -RemoteHost "ftp.myside.local" -Type FTP ``` -### EXAMPLE 3 +### BEISPIEL 3 ``` Connect-To -RemoteHost "fas.myside.local" -Type NetAppFAS ``` -### EXAMPLE 4 +### BEISPIEL 4 ``` Connect-To -RemoteHost "esx01.myside.local" -Type VMware ``` -### EXAMPLE 5 +### BEISPIEL 5 ``` Connect-To -RemoteHost "vCenter.myside.local" -Type CisServer ``` -### EXAMPLE 6 +### BEISPIEL 6 ``` Connect-To -RemoteHost "exchange01.myside.local" -Type ExchangeHTTP ``` -### EXAMPLE 7 +### BEISPIEL 7 ``` Connect-To -RemoteHost "exchange01.myside.local" -Type ExchangeHTTPS ``` @@ -102,6 +95,21 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -PassThru +Returns the value from the underlying connection type function. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -Path Define a custom path to a shared CredentialStore. @@ -112,7 +120,7 @@ Aliases: Required: False Position: Named -Default value: "{0}\PSCredentialStore\CredentialStore.json" -f $env:ProgramData +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` @@ -142,7 +150,7 @@ Type: SwitchParameter Parameter Sets: Shared Aliases: -Required: False +Required: True Position: Named Default value: False Accept pipeline input: False @@ -167,20 +175,18 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS ### [None] - ## OUTPUTS ### [None] - ## NOTES -File Name : Connect-To.ps1 -Author : Marco Blessing - marco.blessing@googlemail.com -Requires : +- File Name : Connect-To.ps1 +- Author : Marco Blessing - marco.blessing@googlemail.com +- Requires : ## RELATED LINKS diff --git a/docs/Disconnect-From.md b/docs/Disconnect-From.md index 9d2d322..5d0d6df 100644 --- a/docs/Disconnect-From.md +++ b/docs/Disconnect-From.md @@ -1,10 +1,3 @@ ---- -external help file: PSCredentialStore-help.xml -Module Name: PSCredentialStore -online version: https://github.com/OCram85/PSCredentialStore -schema: 2.0.0 ---- - # Disconnect-From ## SYNOPSIS @@ -21,42 +14,42 @@ Terminates a session established with Connect-To using a CredentialStoreItem. ## EXAMPLES -### EXAMPLE 1 +### BEISPIEL 1 ``` Disconnect-From -RemoteHost "ucs.myside.local" -Type CiscoUcs ``` -### EXAMPLE 2 +### BEISPIEL 2 ``` Disconnect-From -RemoteHost "ftp.myside.local" -Type FTP ``` -### EXAMPLE 3 +### BEISPIEL 3 ``` Disconnect-From -RemoteHost "fas.myside.local" -Type NetAppFAS ``` -### EXAMPLE 4 +### BEISPIEL 4 ``` Disconnect-From -RemoteHost "esx01.myside.local" -Type VMware ``` -### EXAMPLE 5 +### BEISPIEL 5 ``` Disconnect-From -RemoteHost "esx01.myside.local" -Type VMware -Force:$True ``` -### EXAMPLE 6 +### BEISPIEL 6 ``` Disconnect-From -RemoteHost "vcenter.myside.local" -Type CisServer ``` -### EXAMPLE 7 +### BEISPIEL 7 ``` Disconnect-From -RemoteHost "exchange01.myside.local" -Type ExchangeHTTP ``` -### EXAMPLE 8 +### BEISPIEL 8 ``` Disconnect-From -RemoteHost "exchange01.myside.local" -Type ExchangeHTTPS ``` @@ -111,20 +104,18 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS ### [None] - ## OUTPUTS ### [None] - ## NOTES -File Name : Disconnect-From.ps1 -Author : Marco Blessing - marco.blessing@googlemail.com -Requires : +- File Name : Disconnect-From.ps1 +- Author : Marco Blessing - marco.blessing@googlemail.com +- Requires : ## RELATED LINKS diff --git a/docs/Get-CSCertificate.md b/docs/Get-CSCertificate.md new file mode 100644 index 0000000..266e8e7 --- /dev/null +++ b/docs/Get-CSCertificate.md @@ -0,0 +1,71 @@ +# Get-CSCertificate + +## SYNOPSIS +Returns the current used valid PfX certificate. + +## SYNTAX + +``` +Get-CSCertificate [-Type] [-Thumbprint] [] +``` + +## DESCRIPTION +Use this function to get the available pfx certificate respecting the config hierarchy. + +## EXAMPLES + +### BEISPIEL 1 +``` +Get-CSCertificate -Type 'Shared' -Thumbprint '12334456' +``` + +## PARAMETERS + +### -Thumbprint +Provide the credentials thumbprint for the search. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 2 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Type +Select the current credential store type. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### [None] +## OUTPUTS + +### [System.Security.Cryptography.X509Certificates.X509Certificate2] +## NOTES +- File Name : Get-CSCertificate.ps1 +- Author : Marco Blessing - marco.blessing@googlemail.com +- Requires : + +## RELATED LINKS + +[https://github.com/OCram85/PSCredentialStore](https://github.com/OCram85/PSCredentialStore) + diff --git a/docs/Get-CredentialStore.md b/docs/Get-CredentialStore.md index 718c9af..24b83e3 100644 --- a/docs/Get-CredentialStore.md +++ b/docs/Get-CredentialStore.md @@ -1,10 +1,3 @@ ---- -external help file: PSCredentialStore-help.xml -Module Name: PSCredentialStore -online version: https://github.com/OCram85/PSCredentialStore -schema: 2.0.0 ---- - # Get-CredentialStore ## SYNOPSIS @@ -31,7 +24,7 @@ Get-CredentialStoreItem. ## EXAMPLES -### EXAMPLE 1 +### BEISPIEL 1 ``` $CSContent = Get-CredentialStore -Path "C:\TMP\mystore.json" ``` @@ -48,7 +41,7 @@ Aliases: Required: False Position: Named -Default value: "{0}\PSCredentialStore\CredentialStore.json" -f $env:ProgramData +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` @@ -71,22 +64,18 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS ### [None] - ## OUTPUTS ### [PSObject] Returns the credential store content as PSObject. - ## NOTES -\`\`\` -File Name : Get-CredentialStore.ps1 -Author : Marco Blessing - marco.blessing@googlemail.com -Requires : -\`\`\` +- File Name : Get-CredentialStore.ps1 +- Author : Marco Blessing - marco.blessing@googlemail.com +- Requires : ## RELATED LINKS diff --git a/docs/Get-CredentialStoreItem.md b/docs/Get-CredentialStoreItem.md index eba717e..6b0ab1c 100644 --- a/docs/Get-CredentialStoreItem.md +++ b/docs/Get-CredentialStoreItem.md @@ -1,10 +1,3 @@ ---- -external help file: PSCredentialStore-help.xml -Module Name: PSCredentialStore -online version: https://github.com/OCram85/PSCredentialStore -schema: 2.0.0 ---- - # Get-CredentialStoreItem ## SYNOPSIS @@ -28,7 +21,7 @@ Return the credential as PSCredential object. ## EXAMPLES -### EXAMPLE 1 +### BEISPIEL 1 ``` $myCreds = Get-CredentialStoreItem -Path "C:\TMP\mystore.json" -RemoteHost "esx01.myside.local" ``` @@ -63,7 +56,7 @@ Aliases: Required: False Position: Named -Default value: "{0}\PSCredentialStore\CredentialStore.json" -f $env:ProgramData +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` @@ -101,22 +94,18 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS ### [None] - ## OUTPUTS ### [System.Management.Automation.PSCredential] - ## NOTES -\`\`\` -File Name : Get-CredentialStoreItem.ps1 -Author : Marco Blessing - marco.blessing@googlemail.com -Requires : -\`\`\` +- File Name : Get-CredentialStoreItem.ps1 +- Author : Messing - marco.blessing@googlemail.com +- Requires : ## RELATED LINKS diff --git a/docs/Import-CSCertificate.md b/docs/Import-CSCertificate.md new file mode 100644 index 0000000..2211efa --- /dev/null +++ b/docs/Import-CSCertificate.md @@ -0,0 +1,72 @@ +# Import-CSCertificate + +## SYNOPSIS +Imports a linked certificate to the valid store location. + +## SYNTAX + +``` +Import-CSCertificate [-Type] [-Path] [] +``` + +## DESCRIPTION +Import-CSCertificate takes a pfx certificate file and imports it to the supposed certificate store for +private and shared credential stores. + +## EXAMPLES + +### BEISPIEL 1 +``` +Import-CSCertificate -Type 'Private' -Path (Join-Path -Path $Env:APPDATA -ChildItem 'PfxCertificate.pfx') +``` + +## PARAMETERS + +### -Path +Provide a valid path to pfx certificate file. + +```yaml +Type: FileInfo +Parameter Sets: (All) +Aliases: + +Required: True +Position: 2 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Type +Select between the a private and shared credential store. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### [None] +## OUTPUTS + +### [None] +## NOTES +- File Name : Import-CSCertificate.ps1 +- Author : Marco Blessing - marco.blessing@googlemail.com +- Requires : + +## RELATED LINKS + +[https://github.com/OCram85/PSCredentialStore](https://github.com/OCram85/PSCredentialStore) + diff --git a/docs/New-CSCertAttribute.md b/docs/New-CSCertAttribute.md new file mode 100644 index 0000000..8e778c5 --- /dev/null +++ b/docs/New-CSCertAttribute.md @@ -0,0 +1,147 @@ +# New-CSCertAttribute + +## SYNOPSIS +Creates required data for a certificate signing request. + +## SYNTAX + +``` +New-CSCertAttribute [-Country] [-State] [-City] [-Organization] + [-OrganizationalUnitName] [-CommonName] [[-Days] ] [] +``` + +## DESCRIPTION +Defines the certificate related properties for an upcoming New-PfxCertificate execution. + +## EXAMPLES + +### BEISPIEL 1 +``` +New-CSCertAttribute -Country 'DE' -State 'BW' -City 'Karlsruhe' -Organization 'AwesomeIT' -OrganizationalUnitName '' -CommonName 'MyPrivateCert' +``` + +## PARAMETERS + +### -City +Certificate city value. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 3 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -CommonName +The certificate common name. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 6 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Country +County code like EN, DE, IT, FR... + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Days +The validation time itself. + +```yaml +Type: Int32 +Parameter Sets: (All) +Aliases: + +Required: False +Position: 7 +Default value: 365 +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Organization +Certificate organization value. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 4 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -OrganizationalUnitName +Certificate OrganizationalUnitName value. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 5 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -State +Certificate state value. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 2 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### [None] +## OUTPUTS + +### [PSCredentialStore.Certificate.CSRDetails] +## NOTES +- File Name : New-CSCertAttribute.ps1 +- Author : Marco Blessing - marco.blessing@googlemail.com +- Requires : + +## RELATED LINKS + +[https://github.com/OCram85/PSCredentialStore](https://github.com/OCram85/PSCredentialStore) + diff --git a/docs/New-CSCertificate.md b/docs/New-CSCertificate.md new file mode 100644 index 0000000..163288c --- /dev/null +++ b/docs/New-CSCertificate.md @@ -0,0 +1,120 @@ +# New-CSCertificate + +## SYNOPSIS +Creates a new PFX certificate for the CredentialStore encryption. + +## SYNTAX + +``` +New-CSCertificate [-CRTAttribute] [[-KeyName] ] [[-CertName] ] [-WhatIf] [-Confirm] + [] +``` + +## DESCRIPTION +Use this function to create a custom self signed certificate used by the PSCredentialStore module. + +## EXAMPLES + +### BEISPIEL 1 +``` +New-CSCertificate -CRTAttribute $CRTAttribute -KeyName './myprivate.key' -CertName './mycert.pfx' +``` + +## PARAMETERS + +### -CertName +Provide a custom full path and name for the PFX certificate file. +The file extension has to be \`*.pfx\` + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 3 +Default value: ./certificate.pfx +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -CRTAttribute +Provide certificate related attributes provided by function New-CRTAttribute. + +```yaml +Type: Object +Parameter Sets: (All) +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -KeyName +Provide a custom full path and name for the private key. +The file extension has to be \`*.key\`. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 2 +Default value: ./private.key +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf +Shows what would happen if the cmdlet runs. +The cmdlet is not run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### [PSCredentialStore.Certificate.Attribute] +## OUTPUTS + +### [None] +## NOTES +- File Name : New-CSCertificate.ps1 +- Author : Marco Blessing - marco.blessing@googlemail.com +- Requires : + +## RELATED LINKS + +[https://github.com/OCram85/PSCredentialStore](https://github.com/OCram85/PSCredentialStore) + diff --git a/docs/New-CredentialStore.md b/docs/New-CredentialStore.md index eba717e..60a1172 100644 --- a/docs/New-CredentialStore.md +++ b/docs/New-CredentialStore.md @@ -1,92 +1,111 @@ ---- -external help file: PSCredentialStore-help.xml -Module Name: PSCredentialStore -online version: https://github.com/OCram85/PSCredentialStore -schema: 2.0.0 ---- - -# Get-CredentialStoreItem +# New-CredentialStore ## SYNOPSIS -Returns the Credential from a given remote host item. +Creates a new credential store File ## SYNTAX ### Private (Default) ``` -Get-CredentialStoreItem -RemoteHost [-Identifier ] [] +New-CredentialStore [-Force] [-PassThru] [-SkipPFXCertCreation] [-UseCertStore] [-WhatIf] [-Confirm] + [] ``` ### Shared ``` -Get-CredentialStoreItem -RemoteHost [-Identifier ] [-Shared] [-Path ] - [] +New-CredentialStore [-Shared] [-Path ] [-Force] [-PassThru] [-SkipPFXCertCreation] [-UseCertStore] + [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION -Return the credential as PSCredential object. +You need to run this script first to create a new credential store before you try to +save new credentials with New-CredentialStoreItem. ## EXAMPLES -### EXAMPLE 1 +### BEISPIEL 1 ``` -$myCreds = Get-CredentialStoreItem -Path "C:\TMP\mystore.json" -RemoteHost "esx01.myside.local" +New-CredentialStore ``` +# Creates a new private CredentialStore + +### BEISPIEL 2 +``` +New-CredentialStore -Force +``` + +# Resets an existing private CredentialStore + +### BEISPIEL 3 +``` +New-CredentialStore -Shared +``` + +# Creates a new shared CredentialStore + +### BEISPIEL 4 +``` +New-CredentialStore -Shared -Path "C:\TMP\CredentialStore.json" +``` + +# Creates a new shared CredentialStore in the given location. + ## PARAMETERS -### -Identifier -Provide a custom identifier to the given remote host key. -This enables you to store multiple credentials -for a single remote host entry. -For example ad/sys1, ftp/sys1, mssql/sys1 +### -Force +Use this switch to reset an existing store. +The complete content will be wiped. ```yaml -Type: String +Type: SwitchParameter Parameter Sets: (All) Aliases: Required: False Position: Named -Default value: None +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -PassThru +{{ Fill PassThru Description }} + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False Accept pipeline input: False Accept wildcard characters: False ``` ### -Path -Define a custom path to a shared CredentialStore. +Define a location for the new shared CredentialStore. +The default store will be created in +$Env:ProgramData\PSCredentialStore dir. ```yaml -Type: String +Type: FileInfo Parameter Sets: Shared Aliases: Required: False Position: Named -Default value: "{0}\PSCredentialStore\CredentialStore.json" -f $env:ProgramData -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -RemoteHost -Specify the host, for which you would like to change the credentials. - -```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: True -Position: Named Default value: None Accept pipeline input: False Accept wildcard characters: False ``` ### -Shared -Switch to shared mode with this param. -This enforces the command to work with a shared CredentialStore which -can be decrypted across systems. +Creates a CredentialStore in the Shared mode. +This enables you to read the CredentialStore Items on +different systems or profiles. +In addition you can optionally provide a custom path wit the -Path parameter. ```yaml Type: SwitchParameter @@ -100,23 +119,86 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -SkipPFXCertCreation +You can skip the pfx certificate creation process. +This makes sense if you have a previously created cert or want to +import a cert in cross-platform environments. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -UseCertStore +Instead of using a plain pfx file beside your CredentialStore file you can import it into the user or machine +certificate store. +In this case the system itself secures the cert and you don't hat to set custom NTFS +permissions so secure your shared certificate. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf +Shows what would happen if the cmdlet runs. +The cmdlet is not run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS ### [None] - ## OUTPUTS -### [System.Management.Automation.PSCredential] - +### ['PSCredentialStore.Store'] Returns the recently created CredentialStore object if the -PassThru parameter +### was given. ## NOTES -\`\`\` -File Name : Get-CredentialStoreItem.ps1 -Author : Marco Blessing - marco.blessing@googlemail.com -Requires : -\`\`\` +- File Name : New-CredentialStore.ps1 +- Author : Marco Blessing - marco.blessing@googlemail.com +- Requires : ## RELATED LINKS diff --git a/docs/New-CredentialStoreItem.md b/docs/New-CredentialStoreItem.md index 6b00dd3..dc185fe 100644 --- a/docs/New-CredentialStoreItem.md +++ b/docs/New-CredentialStoreItem.md @@ -1,10 +1,3 @@ ---- -external help file: PSCredentialStore-help.xml -Module Name: PSCredentialStore -online version: https://github.com/OCram85/PSCredentialStore -schema: 2.0.0 ---- - # New-CredentialStoreItem ## SYNOPSIS @@ -33,7 +26,7 @@ a VIConnection, NetApp FAS or UCS Fabric Interconnect. ## EXAMPLES -### EXAMPLE 1 +### BEISPIEL 1 ``` New-CredentialStoreItem -Path "C:\TMP\mystore.json" -RemoteHost "esx01.myside.local" ``` @@ -83,7 +76,7 @@ Aliases: Required: False Position: Named -Default value: "{0}\PSCredentialStore\CredentialStore.json" -f $env:ProgramData +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` @@ -104,7 +97,9 @@ Accept wildcard characters: False ``` ### -Shared -{{Fill Shared Description}} +Define the CredentialStore where you want to add the new item. +Default is always personal but can be +changed to shared, or even shared with custom path. ```yaml Type: SwitchParameter @@ -119,22 +114,18 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS ### [None] - ## OUTPUTS ### [None] - ## NOTES -\`\`\` -File Name : New-CredentialStoreItem.ps1 -Author : Marco Blessing - marco.blessing@googlemail.com -Requires : -\`\`\` +- File Name : New-CredentialStoreItem.ps1 +- Author : Marco Blessing - marco.blessing@googlemail.com +- Requires : ## RELATED LINKS diff --git a/docs/PSCredentialStore.md b/docs/PSCredentialStore.md index 6b840c0..7a67d83 100644 --- a/docs/PSCredentialStore.md +++ b/docs/PSCredentialStore.md @@ -1,14 +1,6 @@ ---- -Module Name: PSCredentialStore -Module Guid: 6800e192-9df8-4e30-b253-eb2c799bbe84 -Download Help Link: {{Please enter FwLink manually}} -Help Version: {{Please enter version of help manually (X.X.X.X) format}} -Locale: en-US ---- - # PSCredentialStore Module ## Description -{{Manually Enter Description Here}} +[about_PSCredentialStore](about_PSCredentialStore.md) ## PSCredentialStore Cmdlets ### [Connect-To](Connect-To.md) @@ -23,12 +15,24 @@ Reads the complete content of the credential store and returns it as a new objec ### [Get-CredentialStoreItem](Get-CredentialStoreItem.md) Returns the Credential from a given remote host item. -### [Get-CredentialStoreItem](Get-CredentialStoreItem.md) -Returns the Credential from a given remote host item. +### [Get-CSCertificate](Get-CSCertificate.md) +Returns the current used valid PfX certificate. + +### [Import-CSCertificate](Import-CSCertificate.md) +Imports a linked certificate to the valid store location. + +### [Import-CSCertificate](Import-CSCertificate.md) +Imports a linked certificate to the valid store location. ### [New-CredentialStoreItem](New-CredentialStoreItem.md) Adds a credential store item containing host, user and password to the given store. +### [New-CSCertAttribute](New-CSCertAttribute.md) +Creates required data for a certificate signing request. + +### [New-CSCertificate](New-CSCertificate.md) +Creates a new PFX certificate for the CredentialStore encryption. + ### [Remove-CredentialStoreItem](Remove-CredentialStoreItem.md) Remove the given credentials from the credential store. @@ -41,6 +45,12 @@ Returns the credential store state. ### [Test-CredentialStoreItem](Test-CredentialStoreItem.md) Checks if the given RemoteHost identifier combination exists in the credential store. +### [Test-CSCertificate](Test-CSCertificate.md) +Tests if the linked certificate is store ein the specified cert stores. + ### [Test-CSConnection](Test-CSConnection.md) Returns the connection state of a given type to the remote host. +### [Use-CSCertificate](Use-CSCertificate.md) +Links an existing PFX Certificate to a CredentialStore. + diff --git a/docs/Remove-CredentialStoreItem.md b/docs/Remove-CredentialStoreItem.md index 2fa9bfa..20ee2e9 100644 --- a/docs/Remove-CredentialStoreItem.md +++ b/docs/Remove-CredentialStoreItem.md @@ -1,10 +1,3 @@ ---- -external help file: PSCredentialStore-help.xml -Module Name: PSCredentialStore -online version: https://github.com/OCram85/PSCredentialStore -schema: 2.0.0 ---- - # Remove-CredentialStoreItem ## SYNOPSIS @@ -28,12 +21,25 @@ Use this CMDLet to completely remove an credential store item. ## EXAMPLES -### EXAMPLE 1 +### BEISPIEL 1 ``` -Remove-CredentialStoreItem -Path "C:\TMP\mystore.json" -RemoteHost "esx01.myside.local" +Remove-CredentialStoreItem -RemoteHost "esx01.myside.local" ``` -Remove-CredentialStoreItem -Path "C:\TMP\mystore.json" -RemoteHost "esx01.myside.local" -Identifier svc +### BEISPIEL 2 +``` +Remove-CredentialStoreItem -Shared -RemoteHost "esx01.myside.local" +``` + +### BEISPIEL 3 +``` +Remove-CredentialStoreItem -Shared -Path "C:\TMP\mystore.json" -RemoteHost "esx01.myside.local" +``` + +### BEISPIEL 4 +``` +Remove-CredentialStoreItem -RemoteHost "esx01.myside.local" -Identifier svc +``` ## PARAMETERS @@ -64,7 +70,7 @@ Aliases: Required: False Position: Named -Default value: "{0}\PSCredentialStore\CredentialStore.json" -f $env:ProgramData +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` @@ -102,22 +108,18 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS ### [None] - ## OUTPUTS ### [None] - ## NOTES -\`\`\` -File Name : Remove-CredentialStoreItem.ps1 -Author : Marco Blessing - marco.blessing@googlemail.com -Requires : -\`\`\` +- File Name : Remove-CredentialStoreItem.ps1 +- Author : Marco Blessing - marco.blessing@googlemail.com +- Requires : ## RELATED LINKS diff --git a/docs/Set-CredentialStoreItem.md b/docs/Set-CredentialStoreItem.md index da6d71e..ae8d989 100644 --- a/docs/Set-CredentialStoreItem.md +++ b/docs/Set-CredentialStoreItem.md @@ -1,10 +1,3 @@ ---- -external help file: PSCredentialStore-help.xml -Module Name: PSCredentialStore -online version: https://github.com/OCram85/PSCredentialStore -schema: 2.0.0 ---- - # Set-CredentialStoreItem ## SYNOPSIS @@ -25,21 +18,24 @@ Set-CredentialStoreItem -RemoteHost [-Identifier ] [-Credential ``` ## DESCRIPTION -{{Fill in the Description}} +Use this function to update your already stored RemoteHost items. ## EXAMPLES -### EXAMPLE 1 +### BEISPIEL 1 ``` Set-CredentialStoreItem -Path "C:\TMP\mystore.json" -RemoteHost "esx01.myside.local" ``` +### BEISPIEL 2 +``` Set-CredentialStoreItem -Path "C:\TMP\mystore.json" -RemoteHost "esx01.myside.local" -Identifier svc +``` ## PARAMETERS ### -Credential -{{Fill Credential Description}} +Provided the new credentials you want to update inside the RemoteHost item. ```yaml Type: PSCredential @@ -80,7 +76,7 @@ Aliases: Required: False Position: Named -Default value: "{0}\PSCredentialStore\CredentialStore.json" -f $env:ProgramData +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` @@ -118,22 +114,18 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS ### [None] - ## OUTPUTS ### [None] - ## NOTES -\`\`\` -File Name : Set-CredentialStoreItem.ps1 -Author : Marco Blessing - marco.blessing@googlemail.com -Requires : -\`\`\` +- File Name : Set-CredentialStoreItem.ps1 +- Author : Marco Blessing - marco.blessing@googlemail.com +- Requires : ## RELATED LINKS diff --git a/docs/Test-CSCertificate.md b/docs/Test-CSCertificate.md new file mode 100644 index 0000000..8234de1 --- /dev/null +++ b/docs/Test-CSCertificate.md @@ -0,0 +1,56 @@ +# Test-CSCertificate + +## SYNOPSIS +Tests if the linked certificate is store ein the specified cert stores. + +## SYNTAX + +``` +Test-CSCertificate [-Type] [] +``` + +## DESCRIPTION +Test-CSCertificate should be an easy high level test for the linked certificate. + +## EXAMPLES + +### BEISPIEL 1 +``` +Test-CSCertificate -Type 'Shared' +``` + +## PARAMETERS + +### -Type +Select between 'Private' or 'Shared'. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### [None] +## OUTPUTS + +### [bool] +## NOTES +- File Name : Test-CSCertificate.ps1 +- Author : Marco Blessing - marco.blessing@googlemail.com +- Requires : + +## RELATED LINKS + +[https://github.com/OCram85/PSCredentialStore](https://github.com/OCram85/PSCredentialStore) + diff --git a/docs/Test-CSConnection.md b/docs/Test-CSConnection.md index da6e927..ee3ee78 100644 --- a/docs/Test-CSConnection.md +++ b/docs/Test-CSConnection.md @@ -1,10 +1,3 @@ ---- -external help file: PSCredentialStore-help.xml -Module Name: PSCredentialStore -online version: https://github.com/OCram85/PSCredentialStore -schema: 2.0.0 ---- - # Test-CSConnection ## SYNOPSIS @@ -21,9 +14,9 @@ Use this script to check a connection which was established with the \`Connect-T ## EXAMPLES -### EXAMPLE 1 +### BEISPIEL 1 ``` -.\Test-CMConnection -RemoteHost "r0-i01-vcr01.p0r.kivbf-cloud.net" -Type VMware +Test-CMConnection -RemoteHost "vcr01.internal.net" -Type VMware ``` ## PARAMETERS @@ -61,20 +54,18 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS ### [None] - ## OUTPUTS -### [Boolean] - +### [bool] ## NOTES -File Name : Test-CSConnection.ps1 -Author : Marco Blessing - marco.blessing@googlemail.com -Requires : +- File Name : Test-CSConnection.ps1 +- Author : Marco Blessing - marco.blessing@googlemail.com +- Requires : ## RELATED LINKS diff --git a/docs/Test-CredentialStore.md b/docs/Test-CredentialStore.md index f3d1170..1b6768b 100644 --- a/docs/Test-CredentialStore.md +++ b/docs/Test-CredentialStore.md @@ -1,10 +1,3 @@ ---- -external help file: PSCredentialStore-help.xml -Module Name: PSCredentialStore -online version: https://github.com/OCram85/PSCredentialStore -schema: 2.0.0 ---- - # Test-CredentialStore ## SYNOPSIS @@ -29,12 +22,10 @@ the file exists. ## EXAMPLES -### Example 1 -```powershell -PS C:\> {{ Add example code here }} +### BEISPIEL 1 +``` +Test-CredentialStore -eq $true ``` - -{{ Add example description here }} ## PARAMETERS @@ -48,7 +39,7 @@ Aliases: Required: False Position: Named -Default value: "{0}\PSCredentialStore\CredentialStore.json" -f $env:ProgramData +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` @@ -71,18 +62,16 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS ## OUTPUTS ## NOTES -\`\`\` -File Name : Test-CredentialStore.ps1 -Author : Marco Blessing - marco.blessing@googlemail.com -Requires : -\`\`\` +- File Name : Test-CredentialStore.ps1 +- Author : Marco Blessing - marco.blessing@googlemail.com +- Requires : ## RELATED LINKS diff --git a/docs/Test-CredentialStoreItem.md b/docs/Test-CredentialStoreItem.md index abc9dff..229ee6c 100644 --- a/docs/Test-CredentialStoreItem.md +++ b/docs/Test-CredentialStoreItem.md @@ -1,10 +1,3 @@ ---- -external help file: PSCredentialStore-help.xml -Module Name: PSCredentialStore -online version: https://github.com/OCram85/PSCredentialStore -schema: 2.0.0 ---- - # Test-CredentialStoreItem ## SYNOPSIS @@ -30,7 +23,7 @@ you try to interact with it. ## EXAMPLES -### EXAMPLE 1 +### BEISPIEL 1 ``` If (Test-CredentialStoreItem -RemoteHost "Default") { ``` @@ -110,22 +103,18 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS ### [None] - ## OUTPUTS ### [None] - ## NOTES -\`\`\` -File Name : Test-CredentialStoreItem.ps1 -Author : Marco Blessing - marco.blessing@googlemail.com -Requires : -\`\`\` +- File Name : Test-CredentialStoreItem.ps1 +- Author : Marco Blessing - marco.blessing@googlemail.com +- Requires : ## RELATED LINKS diff --git a/docs/Use-CSCertificate.md b/docs/Use-CSCertificate.md new file mode 100644 index 0000000..90675d1 --- /dev/null +++ b/docs/Use-CSCertificate.md @@ -0,0 +1,107 @@ +# Use-CSCertificate + +## SYNOPSIS +Links an existing PFX Certificate to a CredentialStore. + +## SYNTAX + +### Private (Default) +``` +Use-CSCertificate -Path [-UseCertStore] [] +``` + +### Shared +``` +Use-CSCertificate -Path [-CredentialStore ] [-Shared] [-UseCertStore] [] +``` + +## DESCRIPTION +Linking a certificate is needed if you plan to use the same CredentialStore in cross platform scenarios. + +## EXAMPLES + +### BEISPIEL 1 +``` +Use-CSCertificate -Path 'C:\cert.pfx' +``` + +## PARAMETERS + +### -CredentialStore +Specify a custom path for a shared credential store. + +```yaml +Type: String +Parameter Sets: Shared +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Path +Specify the path to the PFX Certificate you want to link for usage. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Shared +Use the credential store in shared mode. + +```yaml +Type: SwitchParameter +Parameter Sets: Shared +Aliases: + +Required: True +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -UseCertStore +Use the given certificate and import it into the corresponding certificate store. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### [None] +## OUTPUTS + +### [None] +## NOTES +File Name : Use-CSCertificate.ps1 +Author : Marco Blessing - marco.blessing@googlemail.com +Requires : + +## RELATED LINKS + +[https://github.com/OCram85/PSCredentialStore](https://github.com/OCram85/PSCredentialStore) + diff --git a/docs/about_PSCredentialStore.md b/docs/about_PSCredentialStore.md index a4694ae..95db59b 100644 --- a/docs/about_PSCredentialStore.md +++ b/docs/about_PSCredentialStore.md @@ -1,4 +1,4 @@ -# PSCredentialStore +# PSCredentialStore ## about_PSCredentialStore @@ -7,24 +7,30 @@ PSCredentialStore enables managing multiple PSCredential objects. # LONG DESCRIPTION -The PSCredentialStore is an simple credential manager for PSCredentials. It stores multiple credential objects in a -simple json file. You can choose between a private and shared store. The private one exists in your profile and can +The PSCredentialStore is a simple credential manager for `PSCredential` objects. It stores PSCredentials in a simple json +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 -script without exposing them as plain text. - -**The shared store isn't 100% secure and I don't recommend using it in production!** +scripts without exposing them as plain text. 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. -To get started read the [about_PSCredentialStore](/src/en-US/about_PSCredential.help.txt) page. +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. +For more details read the [about_PSCredentialStore](/docs/about_PSCredentialStore.md) page on github or via CLI with +`Get-Help about_PSCredentialStore`. + +## Requirements + +- PowerShell >= `5.1` +- .NET Framework >= `4.6` or .NET Core >= `1.0` ## Installation ## PowerShellGallery.com (Recommended Way) -* Make sure you use PowerShell 4.0 or higher with `$PSVersionTable`. +* Make sure you use PowerShell 5.1 or higher with `$PSVersionTable`. * Use the builtin PackageManagement and install with: `Install-Module PSCredentialStore` * Done. Start exploring the Module with `Import-Module PSCredentialStore ; Get-Command -Module PSCredentialStore` @@ -36,19 +42,28 @@ To get started read the [about_PSCredentialStore](/src/en-US/about_PSCredential. * Don't forget to change the NTFS permission flag in the context menu. * Start with `Import-Module PSCredentialStore` -**1.** First we need a blank CredentialStore. You can decide between a *private* or *shared* store. The private +**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. + +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 +the parameter `-UseCertStore`. This imports the new certificate in the user or machine certificate store as well. + ```powershell -# Private Credential Store +# Private credential store New-CredentialStore -# Shared Credential Store +# Private credential store with certificate store usage +New-CredentialStore -UseCertStore + +# Shared credential rtore New-CredentialStore -Shared -#Shared CredentialStore in custom Location +#Shared credential store in custom Location New-CredentialStore -Shared -Path 'C:\CredentialStore.json' ``` + **2.** Now you can manage your CredentialStoreItems: ```powershell # This will prompt for credentials and stores it in a private store diff --git a/src/Certificate/Get-CSCertificate.ps1 b/src/Certificate/Get-CSCertificate.ps1 index 0e2cd6e..5bb654b 100644 --- a/src/Certificate/Get-CSCertificate.ps1 +++ b/src/Certificate/Get-CSCertificate.ps1 @@ -1,33 +1,30 @@ function Get-CSCertificate { <# .SYNOPSIS - Returns the certificate object given by thumbprint. + Returns the current used valid PfX certificate. .DESCRIPTION - You can use this function to get a stored certificate. Search for the object by its unique thumbprint. + Use this function to get the available pfx certificate respecting the config hierarchy. + + .PARAMETER Type + Select the current credential store type. .PARAMETER Thumbprint - Provide one or more thumprints. - - .PARAMETER StoreName - Select the store name in which you want to search the certificates. - - .PARAMETER StoreLocation - Select between the both available locations CurrentUser odr LocalMachine. + Provide the credentials thumbprint for the search. .INPUTS - [string] + [None] .OUTPUTS - [System.Security.Cryptography.X509Certificates.X509Certificate2[]] + [System.Security.Cryptography.X509Certificates.X509Certificate2] .EXAMPLE - Get-CSCertificate -Thumbprint '12345678' -StoreName 'My' -StoreLocation 'CurrentUser' + Get-CSCertificate -Type 'Shared' -Thumbprint '12334456' .NOTES - File Name : Get-CSCertificate.ps1 - Author : Marco Blessing - marco.blessing@googlemail.com - Requires : + - File Name : Get-CSCertificate.ps1 + - Author : Marco Blessing - marco.blessing@googlemail.com + - Requires : .LINK https://github.com/OCram85/PSCredentialStore @@ -35,47 +32,43 @@ function Get-CSCertificate { [CmdletBinding()] [OutputType([System.Security.Cryptography.X509Certificates.X509Certificate2])] param( - [Parameter(Mandatory = $true, ValueFromPipeline = $true)] + [Parameter(Mandatory = $true)] [ValidateNotNullOrEmpty()] - [string[]]$Thumbprint, + [ValidateSet('Private', 'Shared')] + [string]$Type, - [Parameter(Mandatory = $false)] - [ValidateSet( - 'AddressBook', - 'AuthRoot', - 'CertificateAuthority', - 'Disallowed', - 'My', - 'Root', - 'TrustedPeople', - 'TrustedPublisher' - )] - [string]$StoreName = 'My', - - [Parameter(Mandatory = $false)] - [ValidateSet( - 'CurrentUser', - 'LocalMachine' - )] - [string]$StoreLocation = 'CurrentUser' + [Parameter(Mandatory = $true)] + [ValidateNotNullOrEmpty()] + [string]$Thumbprint ) begin { - $Store = [System.Security.Cryptography.X509Certificates.X509Store]::New($StoreName, $StoreLocation) - try { - $Store.Open('ReadOnly') - } - catch { - $_.Exception.Message | Write-Error -ErrorAction Stop - } } - process { - foreach ($Thumb in $Thumbprint) { - Write-Output $Store.Certificates | Where-Object { $_.Thumbprint -eq $Thumb } + if ($Type -eq 'Private') { + Get-CSPfXCertificate -Thumbprint $Thumbprint -StoreName 'My' -StoreLocation 'CurrentUser' + } + elseif ($Type -eq 'Shared') { + if ( $isLinux) { + $cert = Get-CSPfxCertificate -Thumbprint $Thumbprint -StoreName 'My' -StoreLocation 'CurrentUser' + if ($null -eq $cert) { + Get-CSPfxCertificate -Thumbprint $Thumbprint -StoreName 'Root' -StoreLocation 'LocalMachine' + } + else { + Write-Output $cert + } + } + elseif ( (! $isLinux) -or ($isWindows) ) { + $cert = Get-CSPfxCertificate -Thumbprint $Thumbprint -StoreName 'My' -StoreLocation 'LocalMachine' + if ($null -eq $cert) { + Get-CSPfxCertificate -Thumbprint $Thumbprint -StoreName 'Root' -StoreLocation 'LocalMachine' + } + else { + Write-Output $cert + } + } } } end { - $Store.Close() } } diff --git a/src/Certificate/Import-CSCertificate.ps1 b/src/Certificate/Import-CSCertificate.ps1 index 6738036..244eb63 100644 --- a/src/Certificate/Import-CSCertificate.ps1 +++ b/src/Certificate/Import-CSCertificate.ps1 @@ -1,18 +1,17 @@ function Import-CSCertificate { <# .SYNOPSIS - adds a given pfx certificate file to current uerers personal certificate store. + Imports a linked certificate to the valid store location. .DESCRIPTION - This function is used to import existing pfx certificate files. The Import-PFXCertificate cmdle from the - PKI module imports the certficate into a deprecated store. Thus you can't read the private key afterwards or - using it for decrypting data. + Import-CSCertificate takes a pfx certificate file and imports it to the supposed certificate store for + private and shared credential stores. + + .PARAMETER Type + Select between the a private and shared credential store. .PARAMETER Path - Path to an existing *.pfx certificate file. - - .PARAMETER StoreName - Additionally you change change the store where you want the certificate into. + Provide a valid path to pfx certificate file. .INPUTS [None] @@ -21,12 +20,12 @@ function Import-CSCertificate { [None] .EXAMPLE - Import-CSCertificate -Path (Join-Path -Path $Env:APPDATA -ChildPath '/PSCredentialStore.pfx') + Import-CSCertificate -Type 'Private' -Path (Join-Path -Path $Env:APPDATA -ChildItem 'PfxCertificate.pfx') .NOTES - File Name : Import-CSCertificate.ps1 - Author : Marco Blessing - marco.blessing@googlemail.com - Requires : + - File Name : Import-CSCertificate.ps1 + - Author : Marco Blessing - marco.blessing@googlemail.com + - Requires : .LINK https://github.com/OCram85/PSCredentialStore @@ -36,77 +35,38 @@ function Import-CSCertificate { param( [Parameter(Mandatory = $true)] [ValidateNotNullOrEmpty()] - [string]$Path, + [ValidateSet('Private', 'Shared')] + [string]$Type, - [Parameter(Mandatory = $false)] - [ValidateSet( - 'AddressBook', - 'AuthRoot', - 'CertificateAuthority', - 'Disallowed', - 'My', - 'Root', - 'TrustedPeople', - 'TrustedPublisher' - )] - [string]$StoreName = 'My', + [Parameter(Mandatory = $true)] + [ValidateNotNullOrEmpty()] + [System.IO.FileInfo]$Path - [Parameter(Mandatory = $false)] - [ValidateSet( - 'CurrentUser', - 'LocalMachine' - )] - [string]$StoreLocation = 'CurrentUser', - - [Parameter(Mandatory = $false)] - [ValidateSet( - 'ReadOnly', - 'ReadWrite', - 'MaxAllowed', - 'OpenExistingOnly', - 'InclueArchived' - )] - [string]$OpenFlags = 'ReadWrite' ) begin { - $Store = [System.Security.Cryptography.X509Certificates.X509Store]::new($StoreName, $StoreLocation) - try { - $Store.Open($OpenFlags) - } - catch { - $_.Exception.Message | Write-Error -ErrorAction Stop - } - } - process { - try { - $cert = [System.Security.Cryptography.X509Certificates.X509Certificate2]::new( - $Path, - $null, - ( - [System.Security.Cryptography.X509Certificates.X509KeyStorageFlags]::Exportable -bor - [System.Security.Cryptography.X509Certificates.X509KeyStorageFlags]::PersistKeySet - ) - ) - - if (Test-CSCertificate -Thumbprint $cert.Thumbprint) { - Write-Warning -Message ('The certificate with thumbprint {0} is already present!' -f $cert.Thumbprint) - } - else { - $Store.Add($cert) - } - } - catch { - $_.Exception.Message | Write-Error -ErrorAction Stop + if (! (Test-Path -Path $Path)) { $ErrorParams = @{ ErrorAction = 'Stop' Exception = [System.Exception]::new( - 'Could not read or add the pfx certificate!' + ('File {0} not found!') -f $Path ) } Write-Error @ErrorParams } } + + process { + # Import to CurrentUser\My store for windows and linux + if ($Type -eq 'Private') { + Import-CSPfxCertificate -Path $Path -StoreName 'My' -StoreLocation 'CurrentUser' -OpenFlags 'ReadWrite' + } + elseif ( (! $isLinux ) -and ($Type -eq 'Shared') ) { + Import-CSPfxCertificate -Path $Path -StoreName 'My' -StoreLocation 'LocalMachine' -OpenFlags 'ReadWrite' + } + elseif ( ($isLinux) -and ($Type -eq 'Shared') ) { + Import-CSPfxCertificate -Path $Path -StoreName 'My' -StoreLocation 'CurrentUser' -OpenFlags 'ReadWrite' + } + } end { - $Store.Close() } } diff --git a/src/Certificate/New-CRTAttribute.ps1 b/src/Certificate/New-CSCertAttribute.ps1 similarity index 71% rename from src/Certificate/New-CRTAttribute.ps1 rename to src/Certificate/New-CSCertAttribute.ps1 index 30d76dc..e199a83 100644 --- a/src/Certificate/New-CRTAttribute.ps1 +++ b/src/Certificate/New-CSCertAttribute.ps1 @@ -1,13 +1,13 @@ -function New-CRTAttribute { +function New-CSCertAttribute { <# .SYNOPSIS - Create required data for a certificate signing request. + Creates required data for a certificate signing request. .DESCRIPTION Defines the certificate related properties for an upcoming New-PfxCertificate execution. .PARAMETER Country - Provide a two letter country code. + County code like EN, DE, IT, FR... .PARAMETER State Certificate state value. @@ -24,23 +24,22 @@ function New-CRTAttribute { .PARAMETER CommonName The certificate common name. - .PARAMETER CSRSubject - you can provide the needed certificate properties with in one hashtable. This hashtable has to contain the - following keys: 'Country', 'State', 'City', 'Organization', 'OrganizationalUnitName', 'CommonName'. + .PARAMETER Days + The validation time itself. .INPUTS [None] .OUTPUTS - ['PSCredentialStore.Certificate.CSRDetails'] + [PSCredentialStore.Certificate.CSRDetails] .EXAMPLE - New-CRTAttribute -CSRSubject @{Country = 'DE'; State = 'BW'; City = 'Karlsruhe'; Organization = 'AwesomeIT'; OrganizationalUnitName = '';CommonName = 'MyPrivateCert'} + New-CSCertAttribute -Country 'DE' -State 'BW' -City 'Karlsruhe' -Organization 'AwesomeIT' -OrganizationalUnitName '' -CommonName 'MyPrivateCert' .NOTES - File Name : New-CSRDetails.ps1 - Author : Marco Blessing - marco.blessing@googlemail.com - Requires : + - File Name : New-CSCertAttribute.ps1 + - Author : Marco Blessing - marco.blessing@googlemail.com + - Requires : .LINK https://github.com/OCram85/PSCredentialStore diff --git a/src/Certificate/New-PfxCertificate.ps1 b/src/Certificate/New-CSCertificate.ps1 similarity index 90% rename from src/Certificate/New-PfxCertificate.ps1 rename to src/Certificate/New-CSCertificate.ps1 index 4fb7a40..91d5554 100644 --- a/src/Certificate/New-PfxCertificate.ps1 +++ b/src/Certificate/New-CSCertificate.ps1 @@ -1,7 +1,7 @@ -function New-PfxCertificate { +function New-CSCertificate { <# .SYNOPSIS - Creates new PFX certificate for the CredentialStore encryption. + Creates a new PFX certificate for the CredentialStore encryption. .DESCRIPTION Use this function to create a custom self signed certificate used by the PSCredentialStore module. @@ -22,12 +22,12 @@ function New-PfxCertificate { [None] .EXAMPLE - New-PfxCertificate -CRTAttribute $CRTAttribute -KeyName './myprivate.key' -CertName './mycert.pfx' + New-CSCertificate -CRTAttribute $CRTAttribute -KeyName './myprivate.key' -CertName './mycert.pfx' .NOTES - File Name : New-PfxCertificate.ps1 - Author : Marco Blessing - marco.blessing@googlemail.com - Requires : + - File Name : New-CSCertificate.ps1 + - Author : Marco Blessing - marco.blessing@googlemail.com + - Requires : .LINK https://github.com/OCram85/PSCredentialStore diff --git a/src/Certificate/Test-CSCertificate.ps1 b/src/Certificate/Test-CSCertificate.ps1 index 7a6c97f..4ef34f6 100644 --- a/src/Certificate/Test-CSCertificate.ps1 +++ b/src/Certificate/Test-CSCertificate.ps1 @@ -1,19 +1,13 @@ function Test-CSCertificate { <# .SYNOPSIS - Tests if the given certificate exists in a store. + Tests if the linked certificate is store ein the specified cert stores. .DESCRIPTION - Use this function to ensure if a certificate is already imported into a given store. + Test-CSCertificate should be an easy high level test for the linked certificate. - .PARAMETER Thumbprint - Provide one or more thumprints. - - .PARAMETER StoreName - Select the store name in which you want to search the certificates. - - .PARAMETER StoreLocation - Select between the both available locations CurrentUser odr LocalMachine. + .PARAMETER Type + Select between 'Private' or 'Shared'. .INPUTS [None] @@ -22,12 +16,12 @@ function Test-CSCertificate { [bool] .EXAMPLE - Test-CSCertificate -Thumbprint '12345678' -StoreName 'My' -StoreLocation 'CurrentUser' + Test-CSCertificate -Type 'Shared' .NOTES - File Name : Test-CSCertificate.ps1 - Author : Marco Blessing - marco.blessing@googlemail.com - Requires : + - File Name : Test-CSCertificate.ps1 + - Author : Marco Blessing - marco.blessing@googlemail.com + - Requires : .LINK https://github.com/OCram85/PSCredentialStore @@ -35,45 +29,42 @@ function Test-CSCertificate { [CmdletBinding()] [OutputType([bool])] param( - [Parameter(Mandatory = $true, ValueFromPipeline = $true)] + [Parameter(Mandatory = $true)] [ValidateNotNullOrEmpty()] - [string]$Thumbprint, - - [Parameter(Mandatory = $false)] - [ValidateSet( - 'AddressBook', - 'AuthRoot', - 'CertificateAuthority', - 'Disallowed', - 'My', - 'Root', - 'TrustedPeople', - 'TrustedPublisher' - )] - [string]$StoreName = 'My', - - [Parameter(Mandatory = $false)] - [ValidateSet( - 'CurrentUser', - 'LocalMachine' - )] - [string]$StoreLocation = 'CurrentUser' + [ValidateSet('Private', 'Shared')] + [string]$Type ) - begin { - $Store = [System.Security.Cryptography.X509Certificates.X509Store]::New($StoreName, $StoreLocation) - try { - $Store.Open('ReadOnly') + if ($Type -eq 'Private') { + $CS = Get-CredentialStore } - catch { - $_.Exception.Message | Write-Error -ErrorAction Stop + elseif ($Type -eq 'Shared') { + $CS = Get-CredentialStore -Shared } + if ($null -ne $CS.PfxCertificate) { + Write-Warning 'There is a Pfx certificate file linked in the store. Certificates saved in the Cert store will be ignored!' + } + } - process { - $Cert = $Store.Certificates | Where-Object { $_.Thumbprint -eq $Thumbprint } - - if ($null -eq $Cert) { + if ($Type -eq 'Private') { + $cert = Get-CSPfXCertificate -Thumbprint $CS.Thumbprint -StoreName 'My' -StoreLocation 'CurrentUser' + } + elseif ($Type -eq 'Shared') { + if ( $isLinux) { + $cert = Get-CSPfxCertificate -Thumbprint $CS.Thumbprint -StoreName 'My' -StoreLocation 'CurrentUser' + if ($null -eq $cert) { + $cert = Get-CSPfxCertificate -Thumbprint $CS.Thumbprint -StoreName 'Root' -StoreLocation 'LocalMachine' + } + } + elseif ( (! $isLinux) -or ($isWindows) ) { + $cert = Get-CSPfxCertificate -Thumbprint $CS.Thumbprint -StoreName 'My' -StoreLocation 'LocalMachine' + if ($null -eq $cert) { + $cert = Get-CSPfxCertificate -Thumbprint $CS.Thumbprint -StoreName 'Root' -StoreLocation 'LocalMachine' + } + } + } + if ($null -eq $cert) { return $false } else { @@ -81,6 +72,5 @@ function Test-CSCertificate { } } end { - $Store.Close() } } diff --git a/src/Certificate/Use-PfxCertificate.ps1 b/src/Certificate/Use-CSCertificate.ps1 similarity index 73% rename from src/Certificate/Use-PfxCertificate.ps1 rename to src/Certificate/Use-CSCertificate.ps1 index e1802d7..76f0f40 100644 --- a/src/Certificate/Use-PfxCertificate.ps1 +++ b/src/Certificate/Use-CSCertificate.ps1 @@ -1,7 +1,7 @@ -function Use-PfxCertificate { +function Use-CSCertificate { <# .SYNOPSIS - Links an existing PFX Certifiacte to a CredentialStore. + Links an existing PFX Certificate to a CredentialStore. .DESCRIPTION Linking a certificate is needed if you plan to use the same CredentialStore in cross platform scenarios. @@ -9,6 +9,15 @@ function Use-PfxCertificate { .PARAMETER Path Specify the path to the PFX Certificate you want to link for usage. + .PARAMETER CredentialStore + Specify a custom path for a shared credential store. + + .PARAMETER Shared + Use the credential store in shared mode. + + .PARAMETER UseCertStore + Use the given certificate and import it into the corresponding certificate store. + .INPUTS [None] @@ -16,10 +25,10 @@ function Use-PfxCertificate { [None] .EXAMPLE - + Use-CSCertificate -Path 'C:\cert.pfx' .NOTES - File Name : Use-PfxCertificate.ps1 + File Name : Use-CSCertificate.ps1 Author : Marco Blessing - marco.blessing@googlemail.com Requires : @@ -40,9 +49,13 @@ function Use-PfxCertificate { [string]$CredentialStore, [Parameter(Mandatory = $true, ParameterSetName = "Shared")] - [switch]$Shared + [switch]$Shared, + + [Parameter(Mandatory = $false, ParameterSetName = "Private")] + [Parameter(Mandatory = $false, ParameterSetName = "Shared")] + [Switch]$UseCertStore ) - begin {} + begin { } process { try { @@ -93,10 +106,16 @@ Make sure you used the same AES keys for encrypting! "@ } - $CS.PfxCertificate = $validPath.Path - $CS.Thumbprint = $PfxCertificate.Thumbprint + if ($UseCertStore) { + Import-CSCertificate -Type $PSCmdlet.ParameterSetName -Path $Path + $CS.Thumbprint = $PfxCertificate.Thumbprint + $CS.PfxCertificate = $null + } + else { + $CS.PfxCertificate = $validPath.Path + } $CS | ConvertTo-Json -Depth 5 | Out-File -FilePath $StorePath -Force -Encoding utf8 } - end {} + end { } } diff --git a/src/Connection/Connect-To.ps1 b/src/Connection/Connect-To.ps1 index c39123d..b7e1abb 100644 --- a/src/Connection/Connect-To.ps1 +++ b/src/Connection/Connect-To.ps1 @@ -29,6 +29,9 @@ function Connect-To { Switch to shared mode with this param. This enforces the command to work with a shared CredentialStore which can be decrypted across systems. + .PARAMETER PassThru + Returns the value from the underlying connection type function. + .INPUTS [None] @@ -57,9 +60,9 @@ function Connect-To { Connect-To -RemoteHost "exchange01.myside.local" -Type ExchangeHTTPS .NOTES - File Name : Connect-To.ps1 - Author : Marco Blessing - marco.blessing@googlemail.com - Requires : + - File Name : Connect-To.ps1 + - Author : Marco Blessing - marco.blessing@googlemail.com + - Requires : .LINK https://github.com/OCram85/PSCredentialStore @@ -194,7 +197,7 @@ function Connect-To { } try { $FTPSessionOption = New-WinSCPSessionOption @WinSCPConParams - $Global:WinSCPSession = New-WinSCPSession @FTPSessionOption + $Global:WinSCPSession = New-WinSCPSession -SessionOption $FTPSessionOption } catch { throw "Could not connect to {0} using {1} protocol!" -f $RemoteHost, $Type diff --git a/src/Connection/Disconnect-From.ps1 b/src/Connection/Disconnect-From.ps1 index 1ccaa70..57139b9 100644 --- a/src/Connection/Disconnect-From.ps1 +++ b/src/Connection/Disconnect-From.ps1 @@ -51,9 +51,9 @@ function Disconnect-From { Disconnect-From -RemoteHost "exchange01.myside.local" -Type ExchangeHTTPS .NOTES - File Name : Disconnect-From.ps1 - Author : Marco Blessing - marco.blessing@googlemail.com - Requires : + - File Name : Disconnect-From.ps1 + - Author : Marco Blessing - marco.blessing@googlemail.com + - Requires : .LINK https://github.com/OCram85/PSCredentialStore @@ -95,7 +95,7 @@ function Disconnect-From { catch { # Write a error message to the log. $MessageParams = @{ - Message = "Unable to disconnect from {0} using Type {1}." -f $RemoteHost, $Type + Message = "Unable to disconnect from {0} using Type {1}." -f $RemoteHost, $Type ErrorAction = "Stop" } Write-Error @MessageParams @@ -114,7 +114,7 @@ function Disconnect-From { catch { # Write a error message to the log. $MessageParams = @{ - Message = "Unable to disconnect from {0} using Type {1}." -f $RemoteHost, $Type + Message = "Unable to disconnect from {0} using Type {1}." -f $RemoteHost, $Type ErrorAction = "Stop" } Write-Error @MessageParams @@ -127,7 +127,7 @@ function Disconnect-From { } else { $MessageParams = @{ - Message = "There is no open WinSCP Session" + Message = "There is no open WinSCP Session" ErrorAction = "Stop" } Write-Error @MessageParams @@ -138,7 +138,7 @@ function Disconnect-From { "NetAppFAS" { try { $MessageParams = @{ - Message = "Setting {0} to `$null, which will disconnect NetAppFAS" -f $Global:CurrentNcController + Message = "Setting {0} to `$null, which will disconnect NetAppFAS" -f $Global:CurrentNcController ErrorAction = "Continue" } Write-Verbose @MessageParams @@ -148,7 +148,7 @@ function Disconnect-From { catch { # Write a error message to the log. $MessageParams = @{ - Message = "Unable to disconnect from {0} using Type {1}." -f $RemoteHost, $Type + Message = "Unable to disconnect from {0} using Type {1}." -f $RemoteHost, $Type ErrorAction = "Stop" } Write-Error @MessageParams @@ -163,7 +163,7 @@ function Disconnect-From { catch { # Write a error message to the log. $MessageParams = @{ - Message = "Unable to disconnect from {0} using Type {1}." -f $RemoteHost, $Type + Message = "Unable to disconnect from {0} using Type {1}." -f $RemoteHost, $Type ErrorAction = "Stop" } Write-Error @MessageParams @@ -176,7 +176,7 @@ function Disconnect-From { } catch { $MessageParams = @{ - Message = "Unable to disconnect from {0} using Type {1}." -f $RemoteHost, $Type + Message = "Unable to disconnect from {0} using Type {1}." -f $RemoteHost, $Type ErrorAction = "Stop" } Write-Error @MessageParams @@ -188,7 +188,7 @@ function Disconnect-From { } else { $MessageParams = @{ - Message = "There is no open WinSCP Session" + Message = "There is no open WinSCP Session" ErrorAction = "Stop" } Write-Error @MessageParams @@ -197,7 +197,7 @@ function Disconnect-From { default { # Write a error message to the log. $MessageParams = @{ - Message = "Unable to disconnect from {0} using Type {1}." -f $RemoteHost, $Type + Message = "Unable to disconnect from {0} using Type {1}." -f $RemoteHost, $Type ErrorAction = "Stop" } Write-Error @MessageParams diff --git a/src/Connection/Test-CSConnection.ps1 b/src/Connection/Test-CSConnection.ps1 index 63f7271..08b483e 100644 --- a/src/Connection/Test-CSConnection.ps1 +++ b/src/Connection/Test-CSConnection.ps1 @@ -17,22 +17,22 @@ function Test-CSConnection { [None] .OUTPUTS - [Boolean] + [bool] .EXAMPLE - .\Test-CMConnection -RemoteHost "r0-i01-vcr01.p0r.kivbf-cloud.net" -Type VMware + Test-CMConnection -RemoteHost "vcr01.internal.net" -Type VMware .NOTES - File Name : Test-CSConnection.ps1 - Author : Marco Blessing - marco.blessing@googlemail.com - Requires : + - File Name : Test-CSConnection.ps1 + - Author : Marco Blessing - marco.blessing@googlemail.com + - Requires : .LINK https://github.com/OCram85/PSCredentialStore #> [CmdletBinding()] - [OutputType([boolean])] + [OutputType([bool])] param( [Parameter(Mandatory = $true)] [ValidateNotNullOrEmpty()] @@ -77,7 +77,7 @@ function Test-CSConnection { 'CiscoUcs' { $MsgParams = @{ ErrorAction = "Stop" - Message = "CiscoUCS connection test is not implemented yet!" + Message = "CiscoUCS connection test is not implemented yet!" } Write-Error @MsgParams return $false @@ -86,7 +86,7 @@ function Test-CSConnection { 'FTP' { $MsgParams = @{ ErrorAction = "Stop" - Message = "FTP connection test is not implemented yet!" + Message = "FTP connection test is not implemented yet!" } Write-Error @MsgParams return $false @@ -95,7 +95,7 @@ function Test-CSConnection { 'NetAppFAS' { $MsgParams = @{ ErrorAction = "Stop" - Message = "NetAppFAS connection test is not implemented yet!" + Message = "NetAppFAS connection test is not implemented yet!" } Write-Error @MsgParams return $false @@ -105,7 +105,7 @@ function Test-CSConnection { Default { $MsgParams = @{ ErrorAction = "Stop" - Message = "Panic: There is an invalid type value! This error should never be thrown." + Message = "Panic: There is an invalid type value! This error should never be thrown." } Write-Error @MsgParams return $false diff --git a/src/Formats/PSCredential.Store.Format.ps1xml b/src/Formats/PSCredential.Store.Format.ps1xml new file mode 100644 index 0000000..9779e40 --- /dev/null +++ b/src/Formats/PSCredential.Store.Format.ps1xml @@ -0,0 +1,35 @@ + + + + + PSCredentialStore.Store + + PSCredentialStore.Store + + + + + + + Version + + + Created + + + + $_.PfxCertificate | Split-Path -Leaf + + + Thumbprint + + + Type + + + + + + + + diff --git a/src/Formats/PSCredentialStore.Certificate.Attribute.ps1xml b/src/Formats/PSCredentialStore.Certificate.Attribute.ps1xml new file mode 100644 index 0000000..d75dee6 --- /dev/null +++ b/src/Formats/PSCredentialStore.Certificate.Attribute.ps1xml @@ -0,0 +1,37 @@ + + + + + PSCredentialStore.Certificate.Attribute + + PSCredentialStore.Certificate.Attribute + + + + + + + Country + + + State + + + City + + + Organization + + + OrganizationalUnitName + + + CommonName + + + + + + + + diff --git a/src/Item/Get-CredentialStoreItem.ps1 b/src/Item/Get-CredentialStoreItem.ps1 index f82f581..bf32e1a 100644 --- a/src/Item/Get-CredentialStoreItem.ps1 +++ b/src/Item/Get-CredentialStoreItem.ps1 @@ -31,11 +31,10 @@ function Get-CredentialStoreItem { $myCreds = Get-CredentialStoreItem -Path "C:\TMP\mystore.json" -RemoteHost "esx01.myside.local" .NOTES - ``` - File Name : Get-CredentialStoreItem.ps1 - Author : Marco Blessing - marco.blessing@googlemail.com - Requires : - ``` + - File Name : Get-CredentialStoreItem.ps1 + - Author : Messing - marco.blessing@googlemail.com + - Requires : + .LINK https://github.com/OCram85/PSCredentialStore #> @@ -87,23 +86,11 @@ function Get-CredentialStoreItem { $CSMembers = Get-Member -InputObject $CS # Let's first check if the given remote host exists as object property if (($CSMembers.MemberType -eq "NoteProperty") -and ($CSMembers.Name -contains $CredentialName)) { - try { - if ($null -eq $CS.PfxCertificate) { - $Cert = Get-CSCertificate -Thumbprint $CS.Thumbprint - } - else { - $Cert = Get-PfxCertificate -FilePath $CS.PfxCertificate -ErrorAction Stop - } + if ($null -eq $CS.PfxCertificate) { + $Cert = Get-CSCertificate -Type $CS.Type -Thumbprint $CS.Thumbprint } - catch { - $_.Exception.Message | Write-Error - $ErrorParams = @{ - ErrorAction = 'Stop' - Exception = [System.Security.Cryptography.CryptographicException]::new( - 'Could not read the given PFX certificate.' - ) - } - Write-Error @ErrorParams + else { + $Cert = Get-PfxCertificate -FilePath $CS.PfxCertificate -ErrorAction Stop } $DecryptedKey = $Cert.PrivateKey.Decrypt( [Convert]::FromBase64String($CS.$CredentialName.EncryptedKey), diff --git a/src/Item/New-CredentialStoreItem.ps1 b/src/Item/New-CredentialStoreItem.ps1 index 81a3524..a95c2d4 100644 --- a/src/Item/New-CredentialStoreItem.ps1 +++ b/src/Item/New-CredentialStoreItem.ps1 @@ -21,6 +21,10 @@ function New-CredentialStoreItem { .PARAMETER Credential You can provide credentials optionally as pre existing pscredential object. + .PARAMETER Shared + Define the CredentialStore where you want to add the new item. Default is always personal but can be + changed to shared, or even shared with custom path. + .INPUTS [None] @@ -31,11 +35,10 @@ function New-CredentialStoreItem { New-CredentialStoreItem -Path "C:\TMP\mystore.json" -RemoteHost "esx01.myside.local" .NOTES - ``` - File Name : New-CredentialStoreItem.ps1 - Author : Marco Blessing - marco.blessing@googlemail.com - Requires : - ``` + - File Name : New-CredentialStoreItem.ps1 + - Author : Marco Blessing - marco.blessing@googlemail.com + - Requires : + .LINK https://github.com/OCram85/PSCredentialStore #> @@ -91,15 +94,6 @@ function New-CredentialStoreItem { Write-Error @MessageParams } - # Read the file content based on the given ParameterSetName - <# - if ($PSCmdlet.ParameterSetName -eq 'Private') { - $CSContent = Get-CredentialStore - } - elseif ($PSCmdlet.ParameterSetName -eq 'Shared') { - $CSContent = Get-CredentialStore -Shared -Path $Path - } - #> $CSContent = Get-CredentialStore -Shared -Path $Path $CurrentDate = Get-Date -UFormat "%Y-%m-%d %H:%M:%S" @@ -116,32 +110,11 @@ function New-CredentialStoreItem { } if ($Credential.UserName) { - try { - if ($null -eq $CSContent.PfxCertificate) { - $Cert = Get-CSCertificate -Thumbprint $CSContent.Thumbprint - if ($null -eq $Cert) { - $ErrorParams = @{ - ErrorAction = 'Stop' - Exception = [System.Security.Cryptography.X509Certificates.FileNotFoundException]::new( - ('Could not find the linked certificate with thumbprint {0}' -f $CSContent.Thumbprint) - ) - } - Write-Error @ErrorParams - } - } - else { - $Cert = Get-PfxCertificate -FilePath $CSContent.PfxCertificate -ErrorAction Stop - } + if ($null -eq $CSContent.PfxCertificate) { + $Cert = Get-CSCertificate -Type $CSContent.Type -Thumbprint $CSContent.Thumbprint } - catch { - $_.Exception.Message | Write-Error - $ErrorParams = @{ - ErrorAction = 'Stop' - Exception = [System.Security.Cryptography.CryptographicException]::new( - 'Could not read the given PFX certificate.' - ) - } - Write-Error @ErrorParams + else { + $Cert = Get-PfxCertificate -FilePath $CSContent.PfxCertificate -ErrorAction Stop } if (Get-Member -InputObject $CSContent -Name $CredentialName -Membertype Properties) { diff --git a/src/Item/Remove-CredentialStoreItem.ps1 b/src/Item/Remove-CredentialStoreItem.ps1 index 0ea0b45..f3296b7 100644 --- a/src/Item/Remove-CredentialStoreItem.ps1 +++ b/src/Item/Remove-CredentialStoreItem.ps1 @@ -39,11 +39,9 @@ function Remove-CredentialStoreItem { Remove-CredentialStoreItem -RemoteHost "esx01.myside.local" -Identifier svc .NOTES - ``` - File Name : Remove-CredentialStoreItem.ps1 - Author : Marco Blessing - marco.blessing@googlemail.com - Requires : - ``` + - File Name : Remove-CredentialStoreItem.ps1 + - Author : Marco Blessing - marco.blessing@googlemail.com + - Requires : .LINK https://github.com/OCram85/PSCredentialStore diff --git a/src/Item/Set-CredentialStoreItem.ps1 b/src/Item/Set-CredentialStoreItem.ps1 index 313857e..3194d58 100644 --- a/src/Item/Set-CredentialStoreItem.ps1 +++ b/src/Item/Set-CredentialStoreItem.ps1 @@ -4,6 +4,7 @@ function Set-CredentialStoreItem { Changes the credentials for the given remote host in the store. .DESCRIPTION + Use this function to update your already stored RemoteHost items. .PARAMETER Path Define the store in which your given host entry already exists. @@ -19,6 +20,9 @@ function Set-CredentialStoreItem { Switch to shared mode with this param. This enforces the command to work with a shared CredentialStore which can be decrypted across systems. + .PARAMETER Credential + Provided the new credentials you want to update inside the RemoteHost item. + .INPUTS [None] @@ -27,14 +31,14 @@ function Set-CredentialStoreItem { .EXAMPLE Set-CredentialStoreItem -Path "C:\TMP\mystore.json" -RemoteHost "esx01.myside.local" + + .EXAMPLE Set-CredentialStoreItem -Path "C:\TMP\mystore.json" -RemoteHost "esx01.myside.local" -Identifier svc .NOTES - ``` - File Name : Set-CredentialStoreItem.ps1 - Author : Marco Blessing - marco.blessing@googlemail.com - Requires : - ``` + - File Name : Set-CredentialStoreItem.ps1 + - Author : Marco Blessing - marco.blessing@googlemail.com + - Requires : .LINK https://github.com/OCram85/PSCredentialStore @@ -102,23 +106,11 @@ function Set-CredentialStoreItem { } if ($Credential.UserName) { - try { - if ($null -eq $CSContent.PfxCertificate) { - $Cert = Get-CSCertificate -Thumbprint $CSContent.Thumbprint - } - else { - $Cert = Get-PfxCertificate -FilePath $CSContent.PfxCertificate -ErrorAction Stop - } + if ($null -eq $CSContent.PfxCertificate) { + $Cert = Get-CSCertificate -Type $CSContent.Type -Thumbprint $CSContent.Thumbprint } - catch { - $_.Exception.Message | Write-Error - $ErrorParams = @{ - ErrorAction = 'Stop' - Exception = [System.Security.Cryptography.CryptographicException]::new( - 'Could not read the given PFX certificate.' - ) - } - Write-Error @ErrorParams + else { + $Cert = Get-PfxCertificate -FilePath $CSContent.PfxCertificate -ErrorAction Stop } if (Get-Member -InputObject $CSContent -Name $CredentialName -Membertype Properties) { diff --git a/src/Item/Test-CredentialStoreItem.ps1 b/src/Item/Test-CredentialStoreItem.ps1 index 5f125e7..a248f0e 100644 --- a/src/Item/Test-CredentialStoreItem.ps1 +++ b/src/Item/Test-CredentialStoreItem.ps1 @@ -37,11 +37,9 @@ function Test-CredentialStoreItem { } .NOTES - ``` - File Name : Test-CredentialStoreItem.ps1 - Author : Marco Blessing - marco.blessing@googlemail.com - Requires : - ``` + - File Name : Test-CredentialStoreItem.ps1 + - Author : Marco Blessing - marco.blessing@googlemail.com + - Requires : .LINK https://github.com/OCram85/PSCredentialStore diff --git a/src/PSCredentialStore.psd1 b/src/PSCredentialStore.psd1 index 190a725..35ae51b 100644 --- a/src/PSCredentialStore.psd1 +++ b/src/PSCredentialStore.psd1 @@ -55,7 +55,10 @@ # TypesToProcess = @() # Format files (.ps1xml) to be loaded when importing this module - # FormatsToProcess = @() + FormatsToProcess = @( + 'Formats/PSCredential.Store.Format.ps1xml', + 'Formats/PSCredentialStore.Certificate.Attribute.ps1xml' + ) # Modules to import as nested modules of the module specified in RootModule/ModuleToProcess # NestedModules = @() @@ -65,10 +68,14 @@ # Certificate 'Get-CSCertificate', 'Import-CSCertificate', - 'New-CRTAttribute', - 'New-PfxCertificate', + 'New-CSCertAttribute', + 'New-CSCertificate', 'Test-CSCertificate', - 'Use-PfxCertificate', + 'Use-CSCertificate', + # Pfx Certificate + # 'Get-CSPfxCertificate', + # 'Import-CSPfxCertificate', + # 'Test-CSPfxCertificate', # Connection 'Connect-To', 'Disconnect-From', @@ -121,10 +128,10 @@ IconUri = 'https://raw.githubusercontent.com/OCram85/PSCredentialStore/master/assets/logo256.png' # ReleaseNotes of this module - ReleaseNotes = 'This is a pre-release version!. Do not use in production!' + ReleaseNotes = 'See https://github.com/OCram85/PSCredentialStore/releases page for details.' # Prerelease string of this module - Prerelease = 'preview' + #Prerelease = 'preview' # Flag to indicate whether the module requires explicit user acceptance for install/update # RequireLicenseAcceptance = $false diff --git a/src/Private/Get-CSPfxCertificate.ps1 b/src/Private/Get-CSPfxCertificate.ps1 new file mode 100644 index 0000000..9afe659 --- /dev/null +++ b/src/Private/Get-CSPfxCertificate.ps1 @@ -0,0 +1,81 @@ +function Get-CSPfxCertificate { + <# + .SYNOPSIS + Returns the certificate object given by thumbprint. + + .DESCRIPTION + You can use this function to get a stored certificate. Search for the object by its unique thumbprint. + + .PARAMETER Thumbprint + Provide one or more thumbprints. + + .PARAMETER StoreName + Select the store name in which you want to search the certificates. + + .PARAMETER StoreLocation + Select between the both available locations CurrentUser odr LocalMachine. + + .INPUTS + [string] + + .OUTPUTS + [System.Security.Cryptography.X509Certificates.X509Certificate2[]] + + .EXAMPLE + Get-CSPfxCertificate -Thumbprint '12345678' -StoreName 'My' -StoreLocation 'CurrentUser' + + .NOTES + - File Name : Get-CSPfxCertificate.ps1 + - Author : Marco Blessing - marco.blessing@googlemail.com + - Requires : + + .LINK + https://github.com/OCram85/PSCredentialStore + #> + [CmdletBinding()] + [OutputType([System.Security.Cryptography.X509Certificates.X509Certificate2])] + param( + [Parameter(Mandatory = $true, ValueFromPipeline = $true)] + [ValidateNotNullOrEmpty()] + [string[]]$Thumbprint, + + [Parameter(Mandatory = $false)] + [ValidateSet( + 'AddressBook', + 'AuthRoot', + 'CertificateAuthority', + 'Disallowed', + 'My', + 'Root', + 'TrustedPeople', + 'TrustedPublisher' + )] + [string]$StoreName = 'My', + + [Parameter(Mandatory = $false)] + [ValidateSet( + 'CurrentUser', + 'LocalMachine' + )] + [string]$StoreLocation = 'CurrentUser' + ) + + begin { + $Store = [System.Security.Cryptography.X509Certificates.X509Store]::New($StoreName, $StoreLocation) + try { + $Store.Open('ReadOnly') + } + catch { + $_.Exception.Message | Write-Error -ErrorAction Stop + } + } + + process { + foreach ($Thumb in $Thumbprint) { + Write-Output $Store.Certificates | Where-Object { $_.Thumbprint -eq $Thumb } + } + } + end { + $Store.Close() + } +} diff --git a/src/Private/Get-DefaultCredentialStorePath.ps1 b/src/Private/Get-DefaultCredentialStorePath.ps1 index 4d9d162..2ee5dc5 100644 --- a/src/Private/Get-DefaultCredentialStorePath.ps1 +++ b/src/Private/Get-DefaultCredentialStorePath.ps1 @@ -16,9 +16,9 @@ function Get-DefaultCredentialStorePath { $Path = Get-DefaultCredentialStorePath .NOTES - File Name : Get-DefaultCredentialStorePath.ps1 - Author : Marco Blessing - marco.blessing@googlemail.com - Requires : + - File Name : Get-DefaultCredentialStorePath.ps1 + - Author : Marco Blessing - marco.blessing@googlemail.com + - Requires : .LINK https://github.com/OCram85/PSCredentialStore @@ -30,7 +30,7 @@ function Get-DefaultCredentialStorePath { [switch]$Shared ) - begin {} + begin { } process { if ($Shared.IsPresent) { @@ -57,5 +57,5 @@ function Get-DefaultCredentialStorePath { } } - end {} + end { } } diff --git a/src/Private/Get-ModuleBase.ps1 b/src/Private/Get-ModuleBase.ps1 index 118dfeb..acb2451 100644 --- a/src/Private/Get-ModuleBase.ps1 +++ b/src/Private/Get-ModuleBase.ps1 @@ -11,9 +11,9 @@ function Get-ModuleBase { Returns the base path as string .NOTES - File Name : Get-ModuleBase.ps1 - Author : Marco Blessing - marco.blessing@googlemail.com - Requires : + - File Name : Get-ModuleBase.ps1 + - Author : Marco Blessing - marco.blessing@googlemail.com + - Requires : .LINK https://github.com/OCram85/PSCredentialStore @@ -21,9 +21,9 @@ function Get-ModuleBase { [CmdletBinding()] [OutputType()] param() - begin {} + begin { } process { return $MyInvocation.MyCommand.Module.ModuleBase } - end {} + end { } } diff --git a/src/Private/Get-RandomAESKey.ps1 b/src/Private/Get-RandomAESKey.ps1 index 27baae5..aff07b5 100644 --- a/src/Private/Get-RandomAESKey.ps1 +++ b/src/Private/Get-RandomAESKey.ps1 @@ -16,9 +16,9 @@ function Get-RandomAESKey { .\Get-RandomAESKey .NOTES - File Name : Get-RandomAESKey.ps1 - Author : Marco Blessing - marco.blessing@googlemail.com - Requires : + - File Name : Get-RandomAESKey.ps1 + - Author : Marco Blessing - marco.blessing@googlemail.com + - Requires : .LINK https://github.com/OCram85/PSCredentialStore @@ -28,7 +28,7 @@ function Get-RandomAESKey { [OutputType([byte[]])] param() - begin {} + begin { } process { $key = [byte[]]::new(32) @@ -40,5 +40,5 @@ function Get-RandomAESKey { } } - end {} + end { } } diff --git a/src/Private/Get-TempDir.ps1 b/src/Private/Get-TempDir.ps1 index c0b1580..b3db4d9 100644 --- a/src/Private/Get-TempDir.ps1 +++ b/src/Private/Get-TempDir.ps1 @@ -15,9 +15,9 @@ function Get-TempDir { Get-TempDir .NOTES - File Name : Get-TempDir.ps1 - Author : Marco Blessing - marco.blessing@googlemail.com - Requires : + - File Name : Get-TempDir.ps1 + - Author : Marco Blessing - marco.blessing@googlemail.com + - Requires : .LINK https://github.com/OCram85/PSCredentialStore diff --git a/src/Private/Import-CSPfxCertificate.ps1 b/src/Private/Import-CSPfxCertificate.ps1 new file mode 100644 index 0000000..b261c49 --- /dev/null +++ b/src/Private/Import-CSPfxCertificate.ps1 @@ -0,0 +1,112 @@ +function Import-CSPfxCertificate { + <# + .SYNOPSIS + Adds a given pfx certificate file to current user's personal certificate store. + + .DESCRIPTION + This function is used to import existing pfx certificate files. The Import-PFXCertificate cmdlet from the + PKI module imports the certificate into a deprecated store. Thus you can't read the private key afterwards or + using it for decrypting data. + + .PARAMETER Path + Path to an existing *.pfx certificate file. + + .PARAMETER StoreName + Additionally you change change the store where you want the certificate into. + + .INPUTS + [None] + + .OUTPUTS + [None] + + .EXAMPLE + Import-CSPfxCertificate -Path (Join-Path -Path $Env:APPDATA -ChildPath '/PSCredentialStore.pfx') + + .NOTES + File Name : Import-CSPfxCertificate.ps1 + Author : Marco Blessing - marco.blessing@googlemail.com + Requires : + + .LINK + https://github.com/OCram85/PSCredentialStore + #> + [CmdletBinding()] + [OutputType()] + param( + [Parameter(Mandatory = $true)] + [ValidateNotNullOrEmpty()] + [string]$Path, + + [Parameter(Mandatory = $false)] + [ValidateSet( + 'AddressBook', + 'AuthRoot', + 'CertificateAuthority', + 'Disallowed', + 'My', + 'Root', + 'TrustedPeople', + 'TrustedPublisher' + )] + [string]$StoreName = 'My', + + [Parameter(Mandatory = $false)] + [ValidateSet( + 'CurrentUser', + 'LocalMachine' + )] + [string]$StoreLocation = 'CurrentUser', + + [Parameter(Mandatory = $false)] + [ValidateSet( + 'ReadOnly', + 'ReadWrite', + 'MaxAllowed', + 'OpenExistingOnly', + 'IncludeArchived' + )] + [string]$OpenFlags = 'ReadWrite' + ) + begin { + $Store = [System.Security.Cryptography.X509Certificates.X509Store]::new($StoreName, $StoreLocation) + try { + $Store.Open($OpenFlags) + } + catch { + $_.Exception.Message | Write-Error -ErrorAction Stop + } + } + process { + try { + $cert = [System.Security.Cryptography.X509Certificates.X509Certificate2]::new( + $Path, + $null, + ( + [System.Security.Cryptography.X509Certificates.X509KeyStorageFlags]::Exportable -bor + [System.Security.Cryptography.X509Certificates.X509KeyStorageFlags]::PersistKeySet + ) + ) + + if (Test-CSPfxCertificate -Thumbprint $cert.Thumbprint) { + Write-Warning -Message ('The certificate with thumbprint {0} is already present!' -f $cert.Thumbprint) + } + else { + $Store.Add($cert) + } + } + catch { + $_.Exception.Message | Write-Error -ErrorAction Stop + $ErrorParams = @{ + ErrorAction = 'Stop' + Exception = [System.Exception]::new( + 'Could not read or add the pfx certificate!' + ) + } + Write-Error @ErrorParams + } + } + end { + $Store.Close() + } +} diff --git a/src/Private/Resolve-Dependency.ps1 b/src/Private/Resolve-Dependency.ps1 index c0f6a0a..4b82922 100644 --- a/src/Private/Resolve-Dependency.ps1 +++ b/src/Private/Resolve-Dependency.ps1 @@ -40,11 +40,9 @@ function Resolve-Dependency { } .NOTES - ``` - File Name : ResolveDependency.ps1 - Author : Marco Blessing - marco.blessing@googlemail.com - Requires : - ``` + - File Name : ResolveDependency.ps1 + - Author : Marco Blessing - marco.blessing@googlemail.com + - Requires : .LINK https://github.com/OCram85/PSCredentialStore @@ -69,7 +67,7 @@ function Resolve-Dependency { } process { - $SelectedDependency = $Dependency.Optional | Where-Object {$_.Name -match $Name} + $SelectedDependency = $Dependency.Optional | Where-Object { $_.Name -match $Name } # return true if there is no dependency defined if ($null -eq $SelectedDependency) { return $true diff --git a/src/Private/Test-CSPfxCertificate.ps1 b/src/Private/Test-CSPfxCertificate.ps1 new file mode 100644 index 0000000..d03fdf5 --- /dev/null +++ b/src/Private/Test-CSPfxCertificate.ps1 @@ -0,0 +1,86 @@ +function Test-CSPfxCertificate { + <# + .SYNOPSIS + Tests if the given certificate exists in a store. + + .DESCRIPTION + Use this function to ensure if a certificate is already imported into a given store. + + .PARAMETER Thumbprint + Provide one or more thumbprints. + + .PARAMETER StoreName + Select the store name in which you want to search the certificates. + + .PARAMETER StoreLocation + Select between the both available locations CurrentUser odr LocalMachine. + + .INPUTS + [None] + + .OUTPUTS + [bool] + + .EXAMPLE + Test-CSPfxCertificate -Thumbprint '12345678' -StoreName 'My' -StoreLocation 'CurrentUser' + + .NOTES + File Name : Test-CSPfxCertificate.ps1 + Author : Marco Blessing - marco.blessing@googlemail.com + Requires : + + .LINK + https://github.com/OCram85/PSCredentialStore + #> + [CmdletBinding()] + [OutputType([bool])] + param( + [Parameter(Mandatory = $true, ValueFromPipeline = $true)] + [ValidateNotNullOrEmpty()] + [string]$Thumbprint, + + [Parameter(Mandatory = $false)] + [ValidateSet( + 'AddressBook', + 'AuthRoot', + 'CertificateAuthority', + 'Disallowed', + 'My', + 'Root', + 'TrustedPeople', + 'TrustedPublisher' + )] + [string]$StoreName = 'My', + + [Parameter(Mandatory = $false)] + [ValidateSet( + 'CurrentUser', + 'LocalMachine' + )] + [string]$StoreLocation = 'CurrentUser' + ) + + begin { + $Store = [System.Security.Cryptography.X509Certificates.X509Store]::New($StoreName, $StoreLocation) + try { + $Store.Open('ReadOnly') + } + catch { + $_.Exception.Message | Write-Error -ErrorAction Stop + } + } + + process { + $Cert = $Store.Certificates | Where-Object { $_.Thumbprint -eq $Thumbprint } + + if ($null -eq $Cert) { + return $false + } + else { + return $true + } + } + end { + $Store.Close() + } +} diff --git a/src/Private/Test-Module.ps1 b/src/Private/Test-Module.ps1 index 2872db3..ab68198 100644 --- a/src/Private/Test-Module.ps1 +++ b/src/Private/Test-Module.ps1 @@ -34,11 +34,9 @@ function Test-Module { .\Test-Dependency -Name 'VMware.PowerCLI' -Type 'Module' -StopIfFails .NOTES - ``` - File Name : Test-Module.ps1 - Author : Marco Blessing - marco.blessing@googlemail.com - Requires : - ``` + - File Name : Test-Module.ps1 + - Author : Marco Blessing - marco.blessing@googlemail.com + - Requires : .LINK https://github.com/OCram85/PSCredentialStore @@ -58,7 +56,7 @@ Could not find the required {0} called {1}. Please install the required {0} to r [Parameter(Mandatory = $false)] [switch]$StopIfFails ) - begin {} + begin { } process { $Message = $MessagePattern -f $Type, $Name @@ -75,5 +73,5 @@ Could not find the required {0} called {1}. Please install the required {0} to r } } - end {} + end { } } diff --git a/src/Store/Get-CredentialStore.ps1 b/src/Store/Get-CredentialStore.ps1 index 20191ff..a30de5f 100644 --- a/src/Store/Get-CredentialStore.ps1 +++ b/src/Store/Get-CredentialStore.ps1 @@ -25,11 +25,9 @@ function Get-CredentialStore { $CSContent = Get-CredentialStore -Path "C:\TMP\mystore.json" .NOTES - ``` - File Name : Get-CredentialStore.ps1 - Author : Marco Blessing - marco.blessing@googlemail.com - Requires : - ``` + - File Name : Get-CredentialStore.ps1 + - Author : Marco Blessing - marco.blessing@googlemail.com + - Requires : .LINK https://github.com/OCram85/PSCredentialStore #> @@ -45,7 +43,7 @@ function Get-CredentialStore { [switch]$Shared ) - begin {} + begin { } process { # Set the CredentialStore for private, shared or custom mode. @@ -83,6 +81,6 @@ function Get-CredentialStore { } } - end {} + end { } } diff --git a/src/Store/New-CredentialStore.ps1 b/src/Store/New-CredentialStore.ps1 index b172e28..cfa1ce2 100644 --- a/src/Store/New-CredentialStore.ps1 +++ b/src/Store/New-CredentialStore.ps1 @@ -18,6 +18,15 @@ function New-CredentialStore { .PARAMETER Force Use this switch to reset an existing store. The complete content will be wiped. + .PARAMETER SkipPFXCertCreation + You can skip the pfx certificate creation process. This makes sense if you have a previously created cert or want to + import a cert in cross-platform environments. + + .Parameter UseCertStore + Instead of using a plain pfx file beside your CredentialStore file you can import it into the user or machine + certificate store. In this case the system itself secures the cert and you don't hat to set custom NTFS + permissions so secure your shared certificate. + .INPUTS [None] @@ -42,11 +51,10 @@ function New-CredentialStore { # Creates a new shared CredentialStore in the given location. .NOTES - ``` - File Name : New-CredentialStore.ps1 - Author : Marco Blessing - marco.blessing@googlemail.com - Requires : - ``` + - File Name : New-CredentialStore.ps1 + - Author : Marco Blessing - marco.blessing@googlemail.com + - Requires : + .LINK https://github.com/OCram85/PSCredentialStore #> @@ -100,7 +108,7 @@ function New-CredentialStore { $ErrorParams = @{ ErrorAction = 'Stop' Exception = [System.IO.InvalidDataException]::new( - 'Your provided path does not conain the required file extension .json !' + 'Your provided path does not contain the required file extension .json !' ) } Write-Error @ErrorParams @@ -141,7 +149,7 @@ function New-CredentialStore { OrganizationalUnitName = $PSCmdlet.ParameterSetName CommonName = 'PSCredentialStore' } - $CRTAttribute = New-CRTAttribute @CRTParams + $CRTAttribute = New-CSCertAttribute @CRTParams # If we are working with a ne shared store we have to create the location first. # Otherwise openssl fails with unknown path @@ -171,7 +179,7 @@ function New-CredentialStore { } try { - New-PfxCertificate @PfxParams + New-CSCertificate @PfxParams } catch { $_.Exception.Message | Write-Error @@ -202,17 +210,6 @@ function New-CredentialStore { Thumbprint = $null Type = $null } - if (! $SkipPFXCertCreation.IsPresent) { - $ObjProperties.Thumbprint = $FreshCert.Thumbprint - - if (!$UseCertStore.IsPresent) { - $ObjProperties.PfxCertificate = $PfxParams.CertName - } - else { - Write-Verbose 'Importing new PFX certificate file...' - Import-CSCertificate -Path $PfxParams.CertName -StoreName My -StoreLocation CurrentUser - } - } if ($PSCmdlet.ParameterSetName -eq "Shared") { $ObjProperties.Type = "Shared" @@ -221,6 +218,20 @@ function New-CredentialStore { $ObjProperties.Type = "Private" } + if (! $SkipPFXCertCreation.IsPresent) { + $ObjProperties.Thumbprint = $FreshCert.Thumbprint + + if ($UseCertStore.IsPresent) { + Write-Verbose 'Importing new PFX certificate file...' + Import-CSCertificate -Type $ObjProperties.Type -Path $PfxParams.CertName + } + else { + $ObjProperties.PfxCertificate = $PfxParams.CertName + + } + } + + $CredentialStoreObj = [PSCustomObject]$ObjProperties try { $JSON = ConvertTo-Json -InputObject $CredentialStoreObj -ErrorAction Stop diff --git a/src/Store/Test-CredentialStore.ps1 b/src/Store/Test-CredentialStore.ps1 index 3b62aca..afbc429 100644 --- a/src/Store/Test-CredentialStore.ps1 +++ b/src/Store/Test-CredentialStore.ps1 @@ -14,12 +14,14 @@ function Test-CredentialStore { Switch to shared mode with this param. This enforces the command to work with a shared CredentialStore which can be decrypted across systems. + .EXAMPLE + Test-CredentialStore -eq $true + .NOTES - ``` - File Name : Test-CredentialStore.ps1 - Author : Marco Blessing - marco.blessing@googlemail.com - Requires : - ``` + - File Name : Test-CredentialStore.ps1 + - Author : Marco Blessing - marco.blessing@googlemail.com + - Requires : + .LINK https://github.com/OCram85/PSCredentialStore #> @@ -60,6 +62,6 @@ function Test-CredentialStore { } } - end {} + end { } } diff --git a/tests/Certificate/50_New-CSCertAttribute.Tests.ps1 b/tests/Certificate/50_New-CSCertAttribute.Tests.ps1 new file mode 100644 index 0000000..e6f5cb4 --- /dev/null +++ b/tests/Certificate/50_New-CSCertAttribute.Tests.ps1 @@ -0,0 +1,7 @@ +Describe "New-CSCertAttribute" { + Context "Basis Tests" { + It "Test1: Should not throw " { + { New-CSCertAttribute -Country 'DE' -State 'BW' -City 'KA' -Organization 'IT' -OrganizationalUnitName'' -CommonName 'Mycert' } | Should -Not -Throw + } + } +} diff --git a/tests/Certificate/51_New-CSCertificate.Tests.ps1 b/tests/Certificate/51_New-CSCertificate.Tests.ps1 new file mode 100644 index 0000000..aac7f74 --- /dev/null +++ b/tests/Certificate/51_New-CSCertificate.Tests.ps1 @@ -0,0 +1,15 @@ +Describe "New-CSCertificate" { + Context "Basic Tests" { + It "Test1: Should not throw" { + + $attribs = New-CSCertAttribute -Country 'DE' -State 'BW' -City 'KA' -Organization 'IT' -OrganizationalUnitName'' -CommonName 'Mycert' + + $CertAttribs = @{ + CRTAttribute = $attribs + KeyName = Join-Path -Path (Get-TempDir) -ChildPath '/foo.key' + CertName = Join-Path -Path (Get-TempDir) -ChildPath '/cert.pfx' + } + { New-CSCertificate @CertAttribs } | Should -Not -Throw + } + } +} diff --git a/tests/PfxCertificate/60_Test-CSPfxCertificate.Tests.ps1 b/tests/PfxCertificate/60_Test-CSPfxCertificate.Tests.ps1 new file mode 100644 index 0000000..9665cb6 --- /dev/null +++ b/tests/PfxCertificate/60_Test-CSPfxCertificate.Tests.ps1 @@ -0,0 +1,10 @@ +Describe "Test-CSPfxCertificate" { + Context "Basic Tests" { + It "Should not Throw" { + { Test-CSPfxCertificate -Thumbprint '12345' -StoreName My -StoreLocation CurrentUser } | Should -Not -Throw + } + It "Should return false" { + Test-CSPfxCertificate -Thumbprint '12345' -StoreName My -StoreLocation CurrentUser | Should -Be $false + } + } +} diff --git a/tests/Store/02_New-CredentialStore.Tests.ps1 b/tests/Store/02_New-CredentialStore.Tests.ps1 index 028504d..ec58d99 100644 --- a/tests/Store/02_New-CredentialStore.Tests.ps1 +++ b/tests/Store/02_New-CredentialStore.Tests.ps1 @@ -80,7 +80,7 @@ Describe "New-CredentialStore" { $CS = Get-CredentialStore $CS.PfxCertificate | Should -Be $null $CS.Thumbprint | Should -Not -Be $null - $res = Test-CSCertificate -Thumbprint $CS.Thumbprint -StoreName My -StoreLocation CurrentUser + $res = Test-CSCertificate -Type Private #Write-Verbose -Message ('res: {0}' -f $res) -Verbose $res | Should -Be $true @@ -90,7 +90,7 @@ Describe "New-CredentialStore" { $CS = Get-CredentialStore -Shared $CS.PfxCertificate | Should -Be $null $CS.Thumbprint | Should -Not -Be $null - $res = Test-CSCertificate -Thumbprint $CS.Thumbprint -StoreName My -StoreLocation CurrentUser + $res = Test-CSCertificate -Type Shared #Write-Verbose -Message ('res: {0}' -f $res) -Verbose $res | Should -Be $true } diff --git a/tests/Store/03_Get-CredentialStore.Tests.ps1 b/tests/Store/03_Get-CredentialStore.Tests.ps1 index a8eabeb..0bf63aa 100644 --- a/tests/Store/03_Get-CredentialStore.Tests.ps1 +++ b/tests/Store/03_Get-CredentialStore.Tests.ps1 @@ -13,11 +13,11 @@ Describe "Get-CredentialStore" { { Get-CredentialStore } | Should -Not -Throw } It "Test2: Read Credential Store with testing data" { - { Use-PfxCertificate -Shared -CredentialStore $TestCredentialStore -Path $TestPfxCert } | Should -Not -Throw + { Use-CSCertificate -Shared -CredentialStore $TestCredentialStore -Path $TestPfxCert } | Should -Not -Throw { Get-CredentialStore -Shared -Path $TestCredentialStore } | Should -Not -Throw } It "Test3: Not existing path should return false" { - { Get-CredentialStore -Shared -Path './CredentialStore.json' }| Should -Throw "Could not find the CredentialStore." + { Get-CredentialStore -Shared -Path './CredentialStore.json' } | Should -Throw "Could not find the CredentialStore." } } Context "Testing invalid json data" {