Add RC3 release changes

CHANGELOG.md

@@ -1,5 +1,19 @@
 # CHANGELOG
 
+## 0.9.2 - 2021-3-15
+
+### Fixes
+
+- Minor changes to help file format.
+
+### Changes
+
+- The `-Force` parameter was removed from the `Set-SecretStoreConfiguration` command, and instead the `-Confirm:$false` should be used to suppress PowerShell prompting in automation scripts.
+
+### New Features
+
+- `Set-SecretStoreConfiguration` command now takes a `-Password` parameter so that there is not need to prompt for a password (Issue #46).
+
 ## 0.9.1 - 2021-3-1
 
 ### Fixes

help/Get-SecretStoreConfiguration.md

@@ -21,29 +21,25 @@ This cmdlet reads the SecretStore configuration file and writes configuration in
 Configuration information includes:
 
 - Scope
-
 - Authentication
-
 - PasswordTimeout (in seconds)
-
 - Interaction
 
 ## EXAMPLES
 
 ### Example 1
-```powershell
+```
 PS C:\> Get-SecretStoreConfiguration
 
       Scope Authentication PasswordTimeout Interaction
       ----- -------------- --------------- -----------
 CurrentUser       Password             900      Prompt
 ```
 
-This example runs the command from a command shell prompt and displays four SecretStore configuration properties:  
-Scope : 'CurrentUser'.  
-Authentication : A password is required to access the SecretStore.  
-PasswordTimeout : The session password timeout time is 15 minutes.  
-Interaction : The user will be prompted for a password if the command is run in an interactive session.  
+This example runs the command from a command shell prompt and displays four SecretStore configuration properties: Scope : 'CurrentUser'.
+Authentication : A password is required to access the SecretStore.
+PasswordTimeout : The session password timeout time is 15 minutes.
+Interaction : The user will be prompted for a password if the command is run in an interactive session.
 
 ## PARAMETERS
 
@@ -53,13 +49,11 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
 ## INPUTS
 
 ### None
-
 ## OUTPUTS
 
 ### Microsoft.PowerShell.SecretStore.SecureStoreConfig
-
 ## NOTES
-
-'AllUsers' scope is currently not supported.  Configuration scope is always 'CurrentUser'.
+'AllUsers' scope is currently not supported. 
+Configuration scope is always 'CurrentUser'.
 
 ## RELATED LINKS

help/Reset-SecretStore.md

@@ -13,19 +13,20 @@ Resets the SecretStore by deleting all secret data and configuring the store wit
 ## SYNTAX
 
 ```
-Reset-SecretStore [-Scope <SecureStoreScope>] [-Authentication <Authenticate>] [-PasswordTimeout <Int32>]
- [-Interaction <Interaction>] [-Force] [-WhatIf] [-Confirm] [<CommonParameters>]
+Reset-SecretStore [-Scope <SecureStoreScope>] [-Authentication <Authenticate>] [-Password <SecureString>]
+ [-PasswordTimeout <Int32>] [-Interaction <Interaction>] [-PassThru] [-Force] [-WhatIf] [-Confirm]
+ [<CommonParameters>]
 ```
 
 ## DESCRIPTION
 This cmdlet completely resets the SecretStore by deleting all secret data it may contain, and resetting configuration options to their default values.
-It is intended to be used only if a required password is lost, or data files become corrupted so that SecretStore no longer functions and secret data cannot be accessed.  
+It is intended to be used only if a required password is lost, or data files become corrupted so that SecretStore no longer functions and secret data cannot be accessed.
 Default configuration options can be overridden by specifying individual command configuration option parameters.
 
 ## EXAMPLES
 
 ### Example 1
-```powershell
+```
 PS C:\> Reset-SecretStore -PassThru
 WARNING: !!This operation will completely remove all SecretStore module secrets and reset configuration settings to default values!!
 
@@ -93,7 +94,7 @@ Aliases:
 
 Required: False
 Position: Named
-Default value:
+Default value: None
 Accept pipeline input: False
 Accept wildcard characters: False
 ```
@@ -203,11 +204,9 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
 ## INPUTS
 
 ### None
-
 ## OUTPUTS
 
 ### Microsoft.PowerShell.SecretStore.SecureStoreConfig
-
 ## NOTES
 
 ## RELATED LINKS

help/Set-SecretStoreConfiguration.md

@@ -15,12 +15,14 @@ Sets SecretStore configuration properties.
 ### ParameterSet (Default)
 ```
 Set-SecretStoreConfiguration [-Scope <SecureStoreScope>] [-Authentication <Authenticate>]
- [-PasswordTimeout <Int32>] [-Interaction <Interaction>] [-Force] [-WhatIf] [-Confirm] [<CommonParameters>]
+ [-PasswordTimeout <Int32>] [-Interaction <Interaction>] [-Password <SecureString>] [-PassThru] [-WhatIf]
+ [-Confirm] [<CommonParameters>]
 ```
 
 ### DefaultParameterSet
 ```
-Set-SecretStoreConfiguration [-Default] [-Force] [-WhatIf] [-Confirm] [<CommonParameters>]
+Set-SecretStoreConfiguration [-Default] [-Password <SecureString>] [-PassThru] [-WhatIf] [-Confirm]
+ [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -30,7 +32,7 @@ Or the '-Default' parameter can be used to restore SecretStore configuration to
 ## EXAMPLES
 
 ### Example 1
-```powershell
+```
 PS C:\> Set-SecretStoreConfiguration -Default
 
 Confirm
@@ -45,6 +47,46 @@ CurrentUser       Password             900      Prompt
 
 This example uses the command to restore the SecretStore configuration settings to their default values.
 
+### Example 2
+```
+Install-Module -Name Microsoft.PowerShell.SecretStore -Repository PSGallery -Force
+$password = Import-CliXml -Path $securePasswordPath.xml
+Set-SecretStoreConfiguration -Scope CurrentUser -Authentication Password -PasswordTimeout 3600 -Interaction None -Password $password -Confirm:$false
+
+Install-Module -Name Microsoft.PowerShell.SecretManagement -Repository PSGallery -Force
+Register-SecretVault -Name SecretStore -ModuleName Microsoft.PowerShell.SecretStore -DefaultVault
+
+Unlock-SecretStore -Password $password
+```
+
+This is an example of automation script that installs and configures the Microsoft.PowerShell.SecretStore module without user prompting.
+The configuration requires a password and sets user interaction to None, so that SecretStore will never prompt the user.
+The configuration also requires a password, and the password is passed in as a SecureString object.
+The \`-Confirm:false\` parameter is used so that PowerShell will not prompt for confirmation.
+
+Next, the SecretManagement module is installed and the SecretStore module registered so that  the SecretStore secrets can be managed.
+
+The \`Unlock-SecretStore\` cmdlet is used to unlock the SecretStore for this session.
+The password timeout was configured for 1 hour and SecretStore will remain unlocked in the session for that amount of time, after which it will need to be unlocked again before secrets can be accessed.
+
+### Example 3
+```
+PS C:\> Get-SecretStoreConfiguration
+
+      Scope Authentication PasswordTimeout Interaction
+      ----- -------------- --------------- -----------
+CurrentUser       Password             900        None
+
+PS C:\> Set-SecretStoreConfiguration -Authentication Password -Password $password
+Set-SecretStoreConfiguration: The Microsoft.PowerShell.SecretStore is already configured to require a password, and a new password cannot be added.
+Use the Set-SecretStorePassword cmdlet to change an existing password.
+```
+
+This example attempts to set the SecretStore configuration to require a password and provides a new password.
+But this results in an error.
+This command cannot be used to change an existing password but only to toggle authentication to require or not require a password.
+To change an existing SecretStore password, use the \`Set-SecretStorePassword\` command.
+
 ## PARAMETERS
 
 ### -Authentication
@@ -80,9 +122,8 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
-### -Force
-When used, the user will not be asked to confirm and the SecretStore will be reset without prompting.
-Default value is false, and user will be asked to confirm the operation.
+### -PassThru
+When used, will write the current SecretStore configuration to the pipeline.
 
 ```yaml
 Type: SwitchParameter
@@ -96,17 +137,21 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
-### -PassThru
-When used, will write the current SecretStore configuration to the pipeline.
+### -Password
+Password to be applied when changing the authentication configuration.
+When changing the configuration from no password required to password required, the provided password will be set as the new store password.
+When changing the configuration from password required to no password required, the provided password will be used to authorize the configuration change, and must be the current password used to unlock the store.
+This command cannot be used to change the store password.
+To change an existing password, use the \`Set-SecretStorePassword\` command.
 
 ```yaml
-Type: SwitchParameter
+Type: SecureString
 Parameter Sets: (All)
 Aliases:
 
 Required: False
 Position: Named
-Default value: False
+Default value: None
 Accept pipeline input: False
 Accept wildcard characters: False
 ```
@@ -201,11 +246,9 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
 ## INPUTS
 
 ### None
-
 ## OUTPUTS
 
 ### Microsoft.PowerShell.SecretStore.SecureStoreConfig
-
 ## NOTES
 
 ## RELATED LINKS

help/Set-SecretStorePassword.md

@@ -12,18 +12,24 @@ Replaces the current SecretStore password with a new one.
 
 ## SYNTAX
 
+### NoParameterSet (Default)
 ```
 Set-SecretStorePassword [<CommonParameters>]
 ```
 
+### ParameterSet
+```
+Set-SecretStorePassword -NewPassword <SecureString> [-Password <SecureString>] [<CommonParameters>]
+```
+
 ## DESCRIPTION
 This cmdlet updates the password for SecretStore.
 It takes no parameters and prompts the user for both the old and new passwords.
 
 ## EXAMPLES
 
 ### Example 1
-```powershell
+```
 PS C:\> Set-SecretStorePassword
 Old password
 Enter password:
@@ -40,12 +46,11 @@ The user is first prompted for the old password.
 And then prompted for the new password twice for verification.
 
 ### Example 2
-```powershell
+```
 PS C:\> Set-SecretStorePassword -NewPassword $newPassword -Password $oldPassword
 ```
 
-This example runs the command passing in both the current store password and the new
-password to be set.
+This example runs the command passing in both the current store password and the new password to be set.
 
 ## PARAMETERS
 
@@ -59,8 +64,8 @@ Aliases:
 
 Required: True
 Position: Named
-Default value:
-Accept pipeline input: True
+Default value: None
+Accept pipeline input: True (ByValue)
 Accept wildcard characters: False
 ```
 
@@ -75,7 +80,7 @@ Aliases:
 
 Required: False
 Position: Named
-Default value:
+Default value: None
 Accept pipeline input: False
 Accept wildcard characters: False
 ```
@@ -86,7 +91,6 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
 ## INPUTS
 
 ### None
-
 ## OUTPUTS
 
 ## NOTES

help/Unlock-SecretStore.md

@@ -25,7 +25,7 @@ If no password is provided by parameter argument, the user will be safely prompt
 ## EXAMPLES
 
 ### Example 1
-```powershell
+```
 PS C:\> Get-Secret secret1 -Vault LocalStore
 Get-Secret: A valid password is required to access the Microsoft.PowerShell.SecretStore vault.
 Get-Secret: The secret secret1 was not found.
@@ -84,7 +84,6 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
 ## INPUTS
 
 ### System.Security.SecureString
-
 ## OUTPUTS
 
 ## NOTES