From f03173fd2f9d6ff43b71e2e4e127961428d0e2fc Mon Sep 17 00:00:00 2001 From: David Coulter Date: Sat, 27 Apr 2019 09:45:56 -0700 Subject: [PATCH] Fix #4231 - Correct digit and other markdown cleanup (#4232) --- .../ConvertFrom-SecureString.md | 120 +++++++++++------- .../ConvertFrom-SecureString.md | 112 +++++++++------- .../ConvertFrom-SecureString.md | 96 +++++++------- .../ConvertFrom-SecureString.md | 100 +++++++++------ .../ConvertFrom-SecureString.md | 85 +++++++------ 5 files changed, 297 insertions(+), 216 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Security/ConvertFrom-SecureString.md b/reference/3.0/Microsoft.PowerShell.Security/ConvertFrom-SecureString.md index 9bce669600a4..0861ebf7481a 100644 --- a/reference/3.0/Microsoft.PowerShell.Security/ConvertFrom-SecureString.md +++ b/reference/3.0/Microsoft.PowerShell.Security/ConvertFrom-SecureString.md @@ -1,73 +1,89 @@ --- -ms.date: 06/09/2017 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -online version: http://go.microsoft.com/fwlink/?LinkID=113287 -external help file: Microsoft.PowerShell.Security.dll-Help.xml -title: ConvertFrom-SecureString +ms.date: 04/27/2019 +schema: 2.0.0 +locale: en-us +keywords: powershell,cmdlet +online version: http://go.microsoft.com/fwlink/?LinkID=113287 +external help file: Microsoft.PowerShell.Security.dll-Help.xml +title: ConvertFrom-SecureString --- - # ConvertFrom-SecureString + ## SYNOPSIS Converts a secure string into an encrypted standard string. + ## SYNTAX ### Secure (Default) + ``` ConvertFrom-SecureString [-SecureString] [[-SecureKey] ] [] ``` ### Open + ``` ConvertFrom-SecureString [-SecureString] [-Key ] [] ``` ## DESCRIPTION -The **ConvertFrom-SecureString** cmdlet converts a secure string (System.Security.SecureString) into an encrypted standard string (System.String). -Unlike a secure string, an encrypted standard string can be saved in a file for later use. -The encrypted standard string can be converted back to its secure string format by using the ConvertTo-SecureString cmdlet. -If an encryption key is specified by using the **Key** or **SecureKey** parameters, the Advanced Encryption Standard (AES) encryption algorithm is used. -The specified key must have a length of 128, 192, or 256 bits because those are the key lengths supported by the AES encryption algorithm. -If no key is specified, the Windows Data Protection API (DPAPI) is used to encrypt the standard string representation. +The **ConvertFrom-SecureString** cmdlet converts a secure string (**System.Security.SecureString**) +into an encrypted standard string (**System.String**). Unlike a secure string, an encrypted standard +string can be saved in a file for later use. The encrypted standard string can be converted back to +its secure string format by using the `ConvertTo-SecureString` cmdlet. + +If an encryption key is specified by using the **Key** or **SecureKey** parameters, the Advanced +Encryption Standard (AES) encryption algorithm is used. The specified key must have a length of 128, +192, or 256 bits because those are the key lengths supported by the AES encryption algorithm. If no +key is specified, the Windows Data Protection API (DPAPI) is used to encrypt the standard string +representation. + ## EXAMPLES -### Example 1 -``` -PS C:\> $SecureString = Read-Host -AsSecureString -``` +### Example 1: Create a secure string -This command creates a secure string from characters that you type at the command prompt. -After entering the command, type the string you want to store as a secure string. -An asterisk (*) is displayed to represent each character that you type. -### Example 2 -``` -PS C:\> $StandardString = ConvertFrom-SecureString $SecureString +```powershell +$SecureString = Read-Host -AsSecureString ``` -This command converts the secure string in the $SecureString variable to an encrypted standard string. -The resulting encrypted standard string is stored in the $StandardString variable. -### Example 3 +This command creates a secure string from characters that you type at the command prompt. After +entering the command, type the string you want to store as a secure string. An asterisk (`*`) is +displayed to represent each character that you type. + +### Example 2: Convert a secure string to an encrypted standard string + +```powershell +$StandardString = ConvertFrom-SecureString $SecureString ``` -PS C:\> $Key = (3,4,2,3,56,34,254,222,1,1,2,23,42,54,33,233,1,34,2,7,6,5,35,43) -PS C:\> $StandardString = ConvertFrom-SecureString $SecureString -Key $Key + +This command converts the secure string in the `$SecureString` variable to an encrypted standard +string. The resulting encrypted standard string is stored in the `$StandardString` variable. + +### Example 3: Convert a secure string to an encrypted standard string with a 192-bit key + +```powershell +$Key = (3,4,2,3,56,34,254,222,1,1,2,23,42,54,33,233,1,34,2,7,6,5,35,43) +$StandardString = ConvertFrom-SecureString $SecureString -Key $Key ``` -These commands use the Advanced Encryption Standard (AES) algorithm to convert the secure string stored in the $SecureString variable to an encrypted standard string with a 192-bit key. -The resulting encrypted standard string is stored in the $standardstring variable. +These commands use the Advanced Encryption Standard (AES) algorithm to convert the secure string +stored in the `$SecureString` variable to an encrypted standard string with a 192-bit key. The +resulting encrypted standard string is stored in the `$StandardString` variable. + +The first command stores a key in the `$Key` variable. The key is an array of 24 decimal numerals, +each of which must be less than 256 to fit within a single unsigned byte. -The first command stores a key in the $Key variable. -The key is an array of 24 digits, all of which are less than 256. +Because each decimal numeral represents a single byte (8 bits), the key has 24 digits for a total of +192 bits (8 x 24). This is a valid key length for the AES algorithm. -Because each digit represents a byte (8 bits), the key has 24 digits for a total of 192 bits (8 x 24). -This is a valid key length for the AES algorithm. -Each individual value is less than 256, which is the maximum value that can be stored in an unsigned byte. +The second command uses the key in the `$Key` variable to convert the secure string to an encrypted +standard string. -The second command uses the key in the $Key variable to convert the secure string to an encrypted standard string. ## PARAMETERS ### -Key + Specifies the encryption key as a byte array. ```yaml @@ -83,8 +99,9 @@ Accept wildcard characters: False ``` ### -SecureKey -Specifies the encryption key as a secure string. -The secure string value is converted to a byte array before being used as the key. + +Specifies the encryption key as a secure string. The secure string value is converted to a byte +array before being used as the key. ```yaml Type: SecureString @@ -99,6 +116,7 @@ Accept wildcard characters: False ``` ### -SecureString + Specifies the secure string to convert to an encrypted standard string. ```yaml @@ -114,23 +132,33 @@ 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 ### System.Security.SecureString -You can pipe a SecureString object to ConvertFrom-SecureString. + +You can pipe a **SecureString** object to ConvertFrom-SecureString. + ## OUTPUTS ### System.String + ConvertFrom-SecureString returns a standard string object. + ## NOTES -* To create a secure string from characters that are typed at the command prompt, use the AsSecureString parameter of the Read-Host cmdlet. - When you use the Key or SecureKey parameters to specify a key, the key length must be correct. -For example, a key of 128 bits can be specified as a byte array of 16 digits. -Similarly, 192-bit and 256-bit keys correspond to byte arrays of 24 and 32 digits, respectively. +- To create a secure string from characters that are typed at the command prompt, use the + **AsSecureString** parameter of the `Read-Host` cmdlet. +- When you use the **Key** or **SecureKey** parameters to specify a key, the key length must be + correct. For example, a key of 128 bits can be specified as a byte array of 16 decimal numerals. + Similarly, 192-bit and 256-bit keys correspond to byte arrays of 24 and 32 decimal numerals, + respectively. -* ## RELATED LINKS [ConvertTo-SecureString](ConvertTo-SecureString.md) diff --git a/reference/4.0/Microsoft.PowerShell.Security/ConvertFrom-SecureString.md b/reference/4.0/Microsoft.PowerShell.Security/ConvertFrom-SecureString.md index d6f206a14a4b..9dac49b4673f 100644 --- a/reference/4.0/Microsoft.PowerShell.Security/ConvertFrom-SecureString.md +++ b/reference/4.0/Microsoft.PowerShell.Security/ConvertFrom-SecureString.md @@ -1,13 +1,12 @@ --- -ms.date: 06/09/2017 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -online version: http://go.microsoft.com/fwlink/p/?linkid=293932 -external help file: Microsoft.PowerShell.Security.dll-Help.xml -title: ConvertFrom-SecureString +ms.date: 04/27/2019 +schema: 2.0.0 +locale: en-us +keywords: powershell,cmdlet +online version: http://go.microsoft.com/fwlink/p/?linkid=293932 +external help file: Microsoft.PowerShell.Security.dll-Help.xml +title: ConvertFrom-SecureString --- - # ConvertFrom-SecureString ## SYNOPSIS @@ -16,64 +15,75 @@ Converts a secure string into an encrypted standard string. ## SYNTAX ### Secure (Default) + ``` ConvertFrom-SecureString [-SecureString] [[-SecureKey] ] [] ``` ### Open + ``` ConvertFrom-SecureString [-SecureString] [-Key ] [] ``` ## DESCRIPTION -The **ConvertFrom-SecureString** cmdlet converts a secure string (System.Security.SecureString) into an encrypted standard string (System.String). -Unlike a secure string, an encrypted standard string can be saved in a file for later use. -The encrypted standard string can be converted back to its secure string format by using the ConvertTo-SecureString cmdlet. -If an encryption key is specified by using the **Key** or **SecureKey** parameters, the Advanced Encryption Standard (AES) encryption algorithm is used. -The specified key must have a length of 128, 192, or 256 bits because those are the key lengths supported by the AES encryption algorithm. -If no key is specified, the Windows Data Protection API (DPAPI) is used to encrypt the standard string representation. +The **ConvertFrom-SecureString** cmdlet converts a secure string (**System.Security.SecureString**) +into an encrypted standard string (**System.String**). Unlike a secure string, an encrypted standard +string can be saved in a file for later use. The encrypted standard string can be converted back to +its secure string format by using the `ConvertTo-SecureString` cmdlet. + +If an encryption key is specified by using the **Key** or **SecureKey** parameters, the Advanced +Encryption Standard (AES) encryption algorithm is used. The specified key must have a length of 128, +192, or 256 bits because those are the key lengths supported by the AES encryption algorithm. If no +key is specified, the Windows Data Protection API (DPAPI) is used to encrypt the standard string +representation. ## EXAMPLES -### Example 1 -``` -PS C:\> $SecureString = Read-Host -AsSecureString +### Example 1: Create a secure string + +```powershell +$SecureString = Read-Host -AsSecureString ``` -This command creates a secure string from characters that you type at the command prompt. -After entering the command, type the string you want to store as a secure string. -An asterisk (*) is displayed to represent each character that you type. +This command creates a secure string from characters that you type at the command prompt. After +entering the command, type the string you want to store as a secure string. An asterisk (`*`) is +displayed to represent each character that you type. -### Example 2 -``` -PS C:\> $StandardString = ConvertFrom-SecureString $SecureString +### Example 2: Convert a secure string to an encrypted standard string + +```powershell +$StandardString = ConvertFrom-SecureString $SecureString ``` -This command converts the secure string in the $SecureString variable to an encrypted standard string. -The resulting encrypted standard string is stored in the $StandardString variable. +This command converts the secure string in the `$SecureString` variable to an encrypted standard +string. The resulting encrypted standard string is stored in the `$StandardString` variable. -### Example 3 -``` -PS C:\> $Key = (3,4,2,3,56,34,254,222,1,1,2,23,42,54,33,233,1,34,2,7,6,5,35,43) -PS C:\> $StandardString = ConvertFrom-SecureString $SecureString -Key $Key +### Example 3: Convert a secure string to an encrypted standard string with a 192-bit key + +```powershell +$Key = (3,4,2,3,56,34,254,222,1,1,2,23,42,54,33,233,1,34,2,7,6,5,35,43) +$StandardString = ConvertFrom-SecureString $SecureString -Key $Key ``` -These commands use the Advanced Encryption Standard (AES) algorithm to convert the secure string stored in the $SecureString variable to an encrypted standard string with a 192-bit key. -The resulting encrypted standard string is stored in the $standardstring variable. +These commands use the Advanced Encryption Standard (AES) algorithm to convert the secure string +stored in the `$SecureString` variable to an encrypted standard string with a 192-bit key. The +resulting encrypted standard string is stored in the `$StandardString` variable. -The first command stores a key in the $Key variable. -The key is an array of 24 digits, all of which are less than 256. +The first command stores a key in the `$Key` variable. The key is an array of 24 decimal numerals, +each of which must be less than 256 to fit within a single unsigned byte. -Because each digit represents a byte (8 bits), the key has 24 digits for a total of 192 bits (8 x 24). -This is a valid key length for the AES algorithm. -Each individual value is less than 256, which is the maximum value that can be stored in an unsigned byte. +Because each decimal numeral represents a single byte (8 bits), the key has 24 digits for a total of +192 bits (8 x 24). This is a valid key length for the AES algorithm. -The second command uses the key in the $Key variable to convert the secure string to an encrypted standard string. +The second command uses the key in the `$Key` variable to convert the secure string to an encrypted +standard string. ## PARAMETERS ### -Key + Specifies the encryption key as a byte array. ```yaml @@ -89,8 +99,9 @@ Accept wildcard characters: False ``` ### -SecureKey -Specifies the encryption key as a secure string. -The secure string value is converted to a byte array before being used as the key. + +Specifies the encryption key as a secure string. The secure string value is converted to a byte +array before being used as the key. ```yaml Type: SecureString @@ -105,6 +116,7 @@ Accept wildcard characters: False ``` ### -SecureString + Specifies the secure string to convert to an encrypted standard string. ```yaml @@ -120,26 +132,32 @@ 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 ### System.Security.SecureString -You can pipe a SecureString object to ConvertFrom-SecureString. + +You can pipe a **SecureString** object to ConvertFrom-SecureString. ## OUTPUTS ### System.String + ConvertFrom-SecureString returns a standard string object. ## NOTES -* To create a secure string from characters that are typed at the command prompt, use the AsSecureString parameter of the Read-Host cmdlet. - - When you use the Key or SecureKey parameters to specify a key, the key length must be correct. -For example, a key of 128 bits can be specified as a byte array of 16 digits. -Similarly, 192-bit and 256-bit keys correspond to byte arrays of 24 and 32 digits, respectively. -* +- To create a secure string from characters that are typed at the command prompt, use the + **AsSecureString** parameter of the `Read-Host` cmdlet. +- When you use the **Key** or **SecureKey** parameters to specify a key, the key length must be + correct. For example, a key of 128 bits can be specified as a byte array of 16 decimal numerals. + Similarly, 192-bit and 256-bit keys correspond to byte arrays of 24 and 32 decimal numerals, + respectively. ## RELATED LINKS diff --git a/reference/5.0/Microsoft.PowerShell.Security/ConvertFrom-SecureString.md b/reference/5.0/Microsoft.PowerShell.Security/ConvertFrom-SecureString.md index e4dbe193c767..2d9bdea316c6 100644 --- a/reference/5.0/Microsoft.PowerShell.Security/ConvertFrom-SecureString.md +++ b/reference/5.0/Microsoft.PowerShell.Security/ConvertFrom-SecureString.md @@ -1,11 +1,11 @@ --- -ms.date: 06/09/2017 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -online version: http://go.microsoft.com/fwlink/?LinkId=821708 -external help file: Microsoft.PowerShell.Security.dll-Help.xml -title: ConvertFrom-SecureString +ms.date: 04/27/2019 +schema: 2.0.0 +locale: en-us +keywords: powershell,cmdlet +online version: http://go.microsoft.com/fwlink/?LinkId=821708 +external help file: Microsoft.PowerShell.Security.dll-Help.xml +title: ConvertFrom-SecureString --- # ConvertFrom-SecureString @@ -28,53 +28,57 @@ ConvertFrom-SecureString [-SecureString] [-Key ] [ $SecureString = Read-Host -AsSecureString +```powershell +$SecureString = Read-Host -AsSecureString ``` -This command creates a secure string from characters that you type at the command prompt. -After entering the command, type the string you want to store as a secure string. -An asterisk (*) is displayed to represent each character that you type. +This command creates a secure string from characters that you type at the command prompt. After +entering the command, type the string you want to store as a secure string. An asterisk (`*`) is +displayed to represent each character that you type. ### Example 2: Convert a secure string to an encrypted standard string -``` -PS C:\> $StandardString = ConvertFrom-SecureString $SecureString +```powershell +$StandardString = ConvertFrom-SecureString $SecureString ``` -This command converts the secure string in the $SecureString variable to an encrypted standard string. -The resulting encrypted standard string is stored in the $StandardString variable. +This command converts the secure string in the `$SecureString` variable to an encrypted standard +string. The resulting encrypted standard string is stored in the `$StandardString` variable. ### Example 3: Convert a secure string to an encrypted standard string with a 192-bit key -``` -PS C:\> $Key = (3,4,2,3,56,34,254,222,1,1,2,23,42,54,33,233,1,34,2,7,6,5,35,43) -PS C:\> $StandardString = ConvertFrom-SecureString $SecureString -Key $Key +```powershell +$Key = (3,4,2,3,56,34,254,222,1,1,2,23,42,54,33,233,1,34,2,7,6,5,35,43) +$StandardString = ConvertFrom-SecureString $SecureString -Key $Key ``` -These commands use the AES algorithm to convert the secure string stored in the $SecureString variable to an encrypted standard string with a 192-bit key. -The resulting encrypted standard string is stored in the $StandardString variable. +These commands use the Advanced Encryption Standard (AES) algorithm to convert the secure string +stored in the `$SecureString` variable to an encrypted standard string with a 192-bit key. The +resulting encrypted standard string is stored in the `$StandardString` variable. -The first command stores a key in the $Key variable. -The key is an array of 24 digits, all of which are less than 256. +The first command stores a key in the `$Key` variable. The key is an array of 24 decimal numerals, +each of which must be less than 256 to fit within a single unsigned byte. -Because each digit represents a byte (8 bits), the key has 24 digits for a total of 192 bits (8 x 24). -This is a valid key length for the AES algorithm. -Each individual value is less than 256, which is the maximum value that can be stored in an unsigned byte. +Because each decimal numeral represents a single byte (8 bits), the key has 24 digits for a total of +192 bits (8 x 24). This is a valid key length for the AES algorithm. -The second command uses the key in the $Key variable to convert the secure string to an encrypted standard string. +The second command uses the key in the `$Key` variable to convert the secure string to an encrypted +standard string. ## PARAMETERS @@ -96,8 +100,8 @@ Accept wildcard characters: False ### -SecureKey -Specifies the encryption key as a secure string. -The secure string value is converted to a byte array before being used as the key. +Specifies the encryption key as a secure string. The secure string value is converted to a byte +array before being used as the key. ```yaml Type: SecureString @@ -129,29 +133,31 @@ 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 ### System.Security.SecureString -You can pipe a **SecureString** object to **ConvertFrom-SecureString**. +You can pipe a **SecureString** object to ConvertFrom-SecureString. ## OUTPUTS ### System.String -**ConvertFrom-SecureString** returns a standard string object. +ConvertFrom-SecureString returns a standard string object. ## NOTES -* To create a secure string from characters that are typed at the command prompt, use the *AsSecureString* parameter of the Read-Host cmdlet. - - When you use the *Key* or *SecureKey* parameters to specify a key, the key length must be correct. -For example, a key of 128 bits can be specified as a byte array of 16 digits. -Similarly, 192-bit and 256-bit keys correspond to byte arrays of 24 and 32 digits, respectively. - -* +- To create a secure string from characters that are typed at the command prompt, use the + **AsSecureString** parameter of the `Read-Host` cmdlet. +- When you use the **Key** or **SecureKey** parameters to specify a key, the key length must be + correct. For example, a key of 128 bits can be specified as a byte array of 16 decimal numerals. + Similarly, 192-bit and 256-bit keys correspond to byte arrays of 24 and 32 decimal numerals, + respectively. ## RELATED LINKS diff --git a/reference/5.1/Microsoft.PowerShell.Security/ConvertFrom-SecureString.md b/reference/5.1/Microsoft.PowerShell.Security/ConvertFrom-SecureString.md index 4bc792834247..517a23131399 100644 --- a/reference/5.1/Microsoft.PowerShell.Security/ConvertFrom-SecureString.md +++ b/reference/5.1/Microsoft.PowerShell.Security/ConvertFrom-SecureString.md @@ -3,12 +3,11 @@ external help file: Microsoft.PowerShell.Security.dll-help.xml keywords: powershell,cmdlet locale: en-us Module Name: Microsoft.PowerShell.Security -ms.date: 06/09/2017 +ms.date: 04/27/2019 online version: http://go.microsoft.com/fwlink/?LinkId=821708 schema: 2.0.0 title: ConvertFrom-SecureString --- - # ConvertFrom-SecureString ## SYNOPSIS @@ -17,64 +16,75 @@ Converts a secure string to an encrypted standard string. ## SYNTAX ### Secure (Default) + ``` ConvertFrom-SecureString [-SecureString] [[-SecureKey] ] [] ``` ### Open + ``` ConvertFrom-SecureString [-SecureString] [-Key ] [] ``` ## DESCRIPTION -The **ConvertFrom-SecureString** cmdlet converts a secure string (**System.Security.SecureString**) to an encrypted standard string (**System.String**). -Unlike a secure string, an encrypted standard string can be saved in a file for later use. -The encrypted standard string can be converted back to a secure string by using the ConvertTo-SecureString cmdlet. -If an encryption key is specified by using the *Key* or *SecureKey* parameters, the Advanced Encryption Standard (AES) encryption algorithm is used. -The specified key must have a length of 128, 192, or 256 bits, because those are the key lengths supported by the AES encryption algorithm. -If no key is specified, the Windows Data Protection API (DPAPI) is used to encrypt the standard string representation. +The **ConvertFrom-SecureString** cmdlet converts a secure string (**System.Security.SecureString**) +into an encrypted standard string (**System.String**). Unlike a secure string, an encrypted standard +string can be saved in a file for later use. The encrypted standard string can be converted back to +its secure string format by using the `ConvertTo-SecureString` cmdlet. + +If an encryption key is specified by using the **Key** or **SecureKey** parameters, the Advanced +Encryption Standard (AES) encryption algorithm is used. The specified key must have a length of 128, +192, or 256 bits because those are the key lengths supported by the AES encryption algorithm. If no +key is specified, the Windows Data Protection API (DPAPI) is used to encrypt the standard string +representation. ## EXAMPLES ### Example 1: Create a secure string -``` -PS C:\> $SecureString = Read-Host -AsSecureString + +```powershell +$SecureString = Read-Host -AsSecureString ``` -This command creates a secure string from characters that you type at the command prompt. -After entering the command, type the string you want to store as a secure string. -An asterisk (*) is displayed to represent each character that you type. +This command creates a secure string from characters that you type at the command prompt. After +entering the command, type the string you want to store as a secure string. An asterisk (`*`) is +displayed to represent each character that you type. ### Example 2: Convert a secure string to an encrypted standard string -``` -PS C:\> $StandardString = ConvertFrom-SecureString $SecureString + +```powershell +$StandardString = ConvertFrom-SecureString $SecureString ``` -This command converts the secure string in the $SecureString variable to an encrypted standard string. -The resulting encrypted standard string is stored in the $StandardString variable. +This command converts the secure string in the `$SecureString` variable to an encrypted standard +string. The resulting encrypted standard string is stored in the `$StandardString` variable. ### Example 3: Convert a secure string to an encrypted standard string with a 192-bit key -``` -PS C:\> $Key = (3,4,2,3,56,34,254,222,1,1,2,23,42,54,33,233,1,34,2,7,6,5,35,43) -PS C:\> $StandardString = ConvertFrom-SecureString $SecureString -Key $Key + +```powershell +$Key = (3,4,2,3,56,34,254,222,1,1,2,23,42,54,33,233,1,34,2,7,6,5,35,43) +$StandardString = ConvertFrom-SecureString $SecureString -Key $Key ``` -These commands use the AES algorithm to convert the secure string stored in the $SecureString variable to an encrypted standard string with a 192-bit key. -The resulting encrypted standard string is stored in the $StandardString variable. +These commands use the Advanced Encryption Standard (AES) algorithm to convert the secure string +stored in the `$SecureString` variable to an encrypted standard string with a 192-bit key. The +resulting encrypted standard string is stored in the `$StandardString` variable. -The first command stores a key in the $Key variable. -The key is an array of 24 digits, all of which are less than 256. +The first command stores a key in the `$Key` variable. The key is an array of 24 decimal numerals, +each of which must be less than 256 to fit within a single unsigned byte. -Because each digit represents a byte (8 bits), the key has 24 digits for a total of 192 bits (8 x 24). -This is a valid key length for the AES algorithm. -Each individual value is less than 256, which is the maximum value that can be stored in an unsigned byte. +Because each decimal numeral represents a single byte (8 bits), the key has 24 digits for a total of +192 bits (8 x 24). This is a valid key length for the AES algorithm. -The second command uses the key in the $Key variable to convert the secure string to an encrypted standard string. +The second command uses the key in the `$Key` variable to convert the secure string to an encrypted +standard string. ## PARAMETERS ### -Key + Specifies the encryption key as a byte array. ```yaml @@ -90,8 +100,9 @@ Accept wildcard characters: False ``` ### -SecureKey -Specifies the encryption key as a secure string. -The secure string value is converted to a byte array before being used as the key. + +Specifies the encryption key as a secure string. The secure string value is converted to a byte +array before being used as the key. ```yaml Type: SecureString @@ -106,6 +117,7 @@ Accept wildcard characters: False ``` ### -SecureString + Specifies the secure string to convert to an encrypted standard string. ```yaml @@ -121,27 +133,35 @@ 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 ### System.Security.SecureString -You can pipe a **SecureString** object to **ConvertFrom-SecureString**. + +You can pipe a **SecureString** object to ConvertFrom-SecureString. ## OUTPUTS ### System.String -**ConvertFrom-SecureString** returns a standard string object. -## NOTES -* To create a secure string from characters that are typed at the command prompt, use the *AsSecureString* parameter of the Read-Host cmdlet. +ConvertFrom-SecureString returns a standard string object. - When you use the *Key* or *SecureKey* parameters to specify a key, the key length must be correct. -For example, a key of 128 bits can be specified as a byte array of 16 digits. -Similarly, 192-bit and 256-bit keys correspond to byte arrays of 24 and 32 digits, respectively. +## NOTES -* +- To create a secure string from characters that are typed at the command prompt, use the + **AsSecureString** parameter of the `Read-Host` cmdlet. +- When you use the **Key** or **SecureKey** parameters to specify a key, the key length must be + correct. For example, a key of 128 bits can be specified as a byte array of 16 decimal numerals. + Similarly, 192-bit and 256-bit keys correspond to byte arrays of 24 and 32 decimal numerals, + respectively. ## RELATED LINKS -[ConvertTo-SecureString](ConvertTo-SecureString.md) \ No newline at end of file +[ConvertTo-SecureString](ConvertTo-SecureString.md) + +[Read-Host](../Microsoft.PowerShell.Utility/Read-Host.md) \ No newline at end of file diff --git a/reference/6/Microsoft.PowerShell.Security/ConvertFrom-SecureString.md b/reference/6/Microsoft.PowerShell.Security/ConvertFrom-SecureString.md index ad2b40fa17ed..0ce8a5d90f7e 100644 --- a/reference/6/Microsoft.PowerShell.Security/ConvertFrom-SecureString.md +++ b/reference/6/Microsoft.PowerShell.Security/ConvertFrom-SecureString.md @@ -3,7 +3,7 @@ external help file: Microsoft.PowerShell.Security.dll-Help.xml keywords: powershell,cmdlet locale: en-us Module Name: Microsoft.PowerShell.Security -ms.date: 06/09/2017 +ms.date: 04/27/2019 online version: http://go.microsoft.com/fwlink/?LinkId=821708 schema: 2.0.0 title: ConvertFrom-SecureString @@ -29,13 +29,16 @@ ConvertFrom-SecureString [-SecureString] [-Key ] [ [!NOTE] > Note that per [DotNet](/dotnet/api/system.security.securestring?view=netcore-2.1#remarks), the @@ -45,41 +48,42 @@ If no key is specified, the Windows Data Protection API (DPAPI) is used to encry ### Example 1: Create a secure string -``` -PS C:\> $SecureString = Read-Host -AsSecureString +```powershell +$SecureString = Read-Host -AsSecureString ``` -This command creates a secure string from characters that you type at the command prompt. -After entering the command, type the string you want to store as a secure string. -An asterisk (*) is displayed to represent each character that you type. +This command creates a secure string from characters that you type at the command prompt. After +entering the command, type the string you want to store as a secure string. An asterisk (`*`) is +displayed to represent each character that you type. ### Example 2: Convert a secure string to an encrypted standard string -``` -PS C:\> $StandardString = ConvertFrom-SecureString $SecureString +```powershell +$StandardString = ConvertFrom-SecureString $SecureString ``` -This command converts the secure string in the $SecureString variable to an encrypted standard string. -The resulting encrypted standard string is stored in the $StandardString variable. +This command converts the secure string in the `$SecureString` variable to an encrypted standard +string. The resulting encrypted standard string is stored in the `$StandardString` variable. ### Example 3: Convert a secure string to an encrypted standard string with a 192-bit key -``` -PS C:\> $Key = (3,4,2,3,56,34,254,222,1,1,2,23,42,54,33,233,1,34,2,7,6,5,35,43) -PS C:\> $StandardString = ConvertFrom-SecureString $SecureString -Key $Key +```powershell +$Key = (3,4,2,3,56,34,254,222,1,1,2,23,42,54,33,233,1,34,2,7,6,5,35,43) +$StandardString = ConvertFrom-SecureString $SecureString -Key $Key ``` -These commands use the AES algorithm to convert the secure string stored in the $SecureString variable to an encrypted standard string with a 192-bit key. -The resulting encrypted standard string is stored in the $StandardString variable. +These commands use the Advanced Encryption Standard (AES) algorithm to convert the secure string +stored in the `$SecureString` variable to an encrypted standard string with a 192-bit key. The +resulting encrypted standard string is stored in the `$StandardString` variable. -The first command stores a key in the $Key variable. -The key is an array of 24 digits, all of which are less than 256. +The first command stores a key in the `$Key` variable. The key is an array of 24 decimal numerals, +each of which must be less than 256 to fit within a single unsigned byte. -Because each digit represents a byte (8 bits), the key has 24 digits for a total of 192 bits (8 x 24). -This is a valid key length for the AES algorithm. -Each individual value is less than 256, which is the maximum value that can be stored in an unsigned byte. +Because each decimal numeral represents a single byte (8 bits), the key has 24 digits for a total of +192 bits (8 x 24). This is a valid key length for the AES algorithm. -The second command uses the key in the $Key variable to convert the secure string to an encrypted standard string. +The second command uses the key in the `$Key` variable to convert the secure string to an encrypted +standard string. ## PARAMETERS @@ -101,8 +105,8 @@ Accept wildcard characters: False ### -SecureKey -Specifies the encryption key as a secure string. -The secure string value is converted to a byte array before being used as the key. +Specifies the encryption key as a secure string. The secure string value is converted to a byte +array before being used as the key. ```yaml Type: SecureString @@ -134,28 +138,33 @@ 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](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS ### System.Security.SecureString -You can pipe a **SecureString** object to **ConvertFrom-SecureString**. +You can pipe a **SecureString** object to ConvertFrom-SecureString. ## OUTPUTS ### System.String -**ConvertFrom-SecureString** returns a standard string object. +ConvertFrom-SecureString returns a standard string object. ## NOTES -* To create a secure string from characters that are typed at the command prompt, use the *AsSecureString* parameter of the Read-Host cmdlet. - -* When you use the *Key* or *SecureKey* parameters to specify a key, the key length must be correct. -For example, a key of 128 bits can be specified as a byte array of 16 digits. -Similarly, 192-bit and 256-bit keys correspond to byte arrays of 24 and 32 digits, respectively. +- To create a secure string from characters that are typed at the command prompt, use the + **AsSecureString** parameter of the `Read-Host` cmdlet. +- When you use the **Key** or **SecureKey** parameters to specify a key, the key length must be + correct. For example, a key of 128 bits can be specified as a byte array of 16 decimal numerals. + Similarly, 192-bit and 256-bit keys correspond to byte arrays of 24 and 32 decimal numerals, + respectively. ## RELATED LINKS -[ConvertTo-SecureString](ConvertTo-SecureString.md) \ No newline at end of file +[ConvertTo-SecureString](ConvertTo-SecureString.md) + +[Read-Host](../Microsoft.PowerShell.Utility/Read-Host.md) \ No newline at end of file