Functions/Protect-String.ps1
|
# Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. filter Protect-String { <# .SYNOPSIS Encrypts a string. .DESCRIPTION The `Protect-String` function encrypts a string using the Data Protection API (DPAPI), RSA, or AES. In Carbon 2.3.0 or earlier, the plaintext string to encrypt is passed to the `String` parameter. Beginning in Carbon 2.4.0, you can also pass a `SecureString`. When encrypting a `SecureString`, it is converted to an array of bytes, encrypted, then the array of bytes is cleared from memory (i.e. the plaintext version of the `SecureString` is only in memory long enough to encrypt it). ## DPAPI The DPAPI hides the encryptiong/decryption keys from you. As such, anything encrpted with via DPAPI can only be decrypted on the same computer it was encrypted on. Use the `ForUser` switch so that only the user who encrypted can decrypt. Use the `ForComputer` switch so that any user who can log into the computer can decrypt. To encrypt as a specific user on the local computer, pass that user's credentials with the `Credential` parameter. (Note this method doesn't work over PowerShell remoting.) ## RSA RSA is an assymetric encryption/decryption algorithm, which requires a public/private key pair. The secret is encrypted with the public key, and can only be decrypted with the corresponding private key. The secret being encrypted can't be larger than the RSA key pair's size/length, usually 1024, 2048, or 4096 bits (128, 256, and 512 bytes, respectively). `Protect-String` encrypts with .NET's `System.Security.Cryptography.RSACryptoServiceProvider` class. You can specify the public key in three ways: * with a `System.Security.Cryptography.X509Certificates.X509Certificate2` object, via the `Certificate` parameter * with a certificate in one of the Windows certificate stores, passing its unique thumbprint via the `Thumbprint` parameter, or via the `PublicKeyPath` parameter cn be certificat provider path, e.g. it starts with `cert:\`. * with a X509 certificate file, via the `PublicKeyPath` parameter You can generate an RSA public/private key pair with the `New-RsaKeyPair` function. ## AES AES is a symmetric encryption/decryption algorithm. You supply a 16-, 24-, or 32-byte key/password/passphrase with the `Key` parameter, and that key is used to encrypt. There is no limit on the size of the data you want to encrypt. `Protect-String` encrypts with .NET's `System.Security.Cryptography.AesCryptoServiceProvider` class. Symmetric encryption requires a random, unique initialization vector (i.e. IV) everytime you encrypt something. `Protect-String` generates one for you. This IV must be known to decrypt the secret, so it is pre-pendeded to the encrypted text. This code demonstrates how to generate a key: $key = (New-Object 'Security.Cryptography.AesManaged').Key You can save this key as a string by encoding it as a base-64 string: $base64EncodedKey = [Convert]::ToBase64String($key) If you base-64 encode your string, it must be converted back to bytes before passing it to `Protect-String`. Protect-String -String 'the secret sauce' -Key ([Convert]::FromBase64String($base64EncodedKey)) The ability to encrypt with AES was added in Carbon 2.3.0. .LINK New-RsaKeyPair .LINK Unprotect-String .LINK http://msdn.microsoft.com/en-us/library/system.security.cryptography.protecteddata.aspx .EXAMPLE Protect-String -String 'TheStringIWantToEncrypt' -ForUser | Out-File MySecret.txt Encrypts the given string and saves the encrypted string into MySecret.txt. Only the user who encrypts the string can unencrypt it. .EXAMPLE Protect-String -String $credential.Password -ForUser | Out-File MySecret.txt Demonstrates that `Protect-String` can encrypt a `SecureString`. This functionality was added in Carbon 2.4.0. .EXAMPLE $cipherText = Protect-String -String "MySuperSecretIdentity" -ForComputer Encrypts the given string and stores the value in $cipherText. Because the encryption scope is set to LocalMachine, any user logged onto the local computer can decrypt `$cipherText`. .EXAMPLE Protect-String -String 's0000p33333r s33333cr33333t' -Credential (Get-Credential 'builduser') Demonstrates how to use `Protect-String` to encrypt a secret as a specific user. This is useful for situation where a secret needs to be encrypted by a user other than the user running `Protect-String`. Encrypting as a specific user won't work over PowerShell remoting. .EXAMPLE Protect-String -String 'the secret sauce' -Certificate $myCert Demonstrates how to encrypt a secret using RSA with a `System.Security.Cryptography.X509Certificates.X509Certificate2` object. You're responsible for creating/loading it. The `New-RsaKeyPair` function will create a key pair for you, if you've got a Windows SDK installed. .EXAMPLE Protect-String -String 'the secret sauce' -Thumbprint '44A7C27F3353BC53F82318C14490D7E2500B6D9E' Demonstrates how to encrypt a secret using RSA with a certificate in one of the Windows certificate stores. All local machine and user stores are searched. .EXAMPLE Protect-String -String 'the secret sauce' -PublicKeyPath 'C:\Projects\Security\publickey.cer' Demonstrates how to encrypt a secret using RSA with a certificate file. The file must be loadable by the `System.Security.Cryptography.X509Certificates.X509Certificate` class. .EXAMPLE Protect-String -String 'the secret sauce' -PublicKeyPath 'cert:\LocalMachine\My\44A7C27F3353BC53F82318C14490D7E2500B6D9E' Demonstrates how to encrypt a secret using RSA with a certificate in the store, giving its exact path. .EXAMPLE Protect-String -String 'the secret sauce' -Key 'gT4XPfvcJmHkQ5tYjY3fNgi7uwG4FB9j' Demonstrates how to encrypt a secret with a key, password, or passphrase. In this case, we are encrypting with a plaintext password. This functionality was added in Carbon 2.3.0. .EXAMPLE Protect-String -String 'the secret sauce' -Key (Read-Host -Prompt 'Enter password (must be 16, 24, or 32 characters long):' -AsSecureString) Demonstrates that you can use a `SecureString` as the key, password, or passphrase. This functionality was added in Carbon 2.3.0. .EXAMPLE Protect-String -String 'the secret sauce' -Key ([byte[]]@(163,163,185,174,205,55,157,219,121,146,251,116,43,203,63,38,73,154,230,112,82,112,151,29,189,135,254,187,164,104,45,30)) Demonstrates that you can use an array of bytes as the key, password, or passphrase. This functionality was added in Carbon 2.3.0. #> [CmdletBinding()] param( [Parameter(Mandatory = $true, Position=0, ValueFromPipeline = $true)] [object] # The string to encrypt. Any non-string object you pass will be converted to a string before encrypting by calling the object's `ToString` method. # # Beginning in Carbon 2.4.0, this can also be a `SecureString` object. The `SecureString` is converted to an array of bytes, the bytes are encrypted, then the plaintext bytes are cleared from memory (i.e. the plaintext password is in memory for the amount of time it takes to encrypt it). $String, [Parameter(Mandatory=$true,ParameterSetName='DPAPICurrentUser')] # Encrypts for the current user so that only he can decrypt. [Switch] $ForUser, [Parameter(Mandatory=$true,ParameterSetName='DPAPILocalMachine')] # Encrypts for the current computer so that any user logged into the computer can decrypt. [Switch] $ForComputer, [Parameter(Mandatory=$true,ParameterSetName='DPAPIForUser')] [Management.Automation.PSCredential] # Encrypts for a specific user. $Credential, [Parameter(Mandatory=$true,ParameterSetName='RSAByCertificate')] [Security.Cryptography.X509Certificates.X509Certificate2] # The public key to use for encrypting. $Certificate, [Parameter(Mandatory=$true,ParameterSetName='RSAByThumbprint')] [string] # The thumbprint of the certificate, found in one of the Windows certificate stores, to use when encrypting. All certificate stores are searched. $Thumbprint, [Parameter(Mandatory=$true,ParameterSetName='RSAByPath')] [string] # The path to the public key to use for encrypting. Must be to an `X509Certificate2` object. $PublicKeyPath, [Parameter(ParameterSetName='RSAByCertificate')] [Parameter(ParameterSetName='RSAByThumbprint')] [Parameter(ParameterSetName='RSAByPath')] [Switch] # If true, uses Direct Encryption (PKCS#1 v1.5) padding. Otherwise (the default), uses OAEP (PKCS#1 v2) padding. See [Encrypt](http://msdn.microsoft.com/en-us/library/system.security.cryptography.rsacryptoserviceprovider.encrypt(v=vs.110).aspx) for information. $UseDirectEncryptionPadding, [Parameter(Mandatory=$true,ParameterSetName='Symmetric')] # The key to use to encrypt the secret. Can be a `SecureString`, a `String`, or an array of bytes. Must be 16, 24, or 32 characters/bytes in length. [object] $Key ) Set-StrictMode -Version 'Latest' Use-CallerPreference -Cmdlet $PSCmdlet -Session $ExecutionContext.SessionState if( $String -is [System.Security.SecureString] ) { $stringBytes = [Carbon.Security.SecureStringConverter]::ToBytes($String) } else { $stringBytes = [Text.Encoding]::UTF8.GetBytes( $String.ToString() ) } try { if( $PSCmdlet.ParameterSetName -like 'DPAPI*' ) { if( $PSCmdlet.ParameterSetName -eq 'DPAPIForUser' ) { $protectStringPath = Join-Path -Path $CarbonBinDir -ChildPath 'Protect-String.ps1' -Resolve $encodedString = Protect-String -String $String -ForComputer $argumentList = '-ProtectedString {0}' -f $encodedString Invoke-PowerShell -ExecutionPolicy 'ByPass' -NonInteractive -FilePath $protectStringPath -ArgumentList $argumentList -Credential $Credential | Select-Object -First 1 return } else { $scope = [Security.Cryptography.DataProtectionScope]::CurrentUser if( $PSCmdlet.ParameterSetName -eq 'DPAPILocalMachine' ) { $scope = [Security.Cryptography.DataProtectionScope]::LocalMachine } $encryptedBytes = [Security.Cryptography.ProtectedData]::Protect( $stringBytes, $null, $scope ) } } elseif( $PSCmdlet.ParameterSetName -like 'RSA*' ) { if( $PSCmdlet.ParameterSetName -eq 'RSAByThumbprint' ) { $Certificate = Get-ChildItem -Path ('cert:\*\*\{0}' -f $Thumbprint) -Recurse | Select-Object -First 1 if( -not $Certificate ) { Write-Error ('Certificate with thumbprint ''{0}'' not found.' -f $Thumbprint) return } } elseif( $PSCmdlet.ParameterSetName -eq 'RSAByPath' ) { $Certificate = Get-Certificate -Path $PublicKeyPath if( -not $Certificate ) { return } } $rsaKey = $Certificate.PublicKey.Key if( $rsaKey -isnot ([Security.Cryptography.RSACryptoServiceProvider]) ) { Write-Error ('Certificate ''{0}'' (''{1}'') is not an RSA key. Found a public key of type ''{2}'', but expected type ''{3}''.' -f $Certificate.Subject,$Certificate.Thumbprint,$rsaKey.GetType().FullName,[Security.Cryptography.RSACryptoServiceProvider].FullName) return } try { $encryptedBytes = $rsaKey.Encrypt( $stringBytes, (-not $UseDirectEncryptionPadding) ) } catch { if( $_.Exception.Message -match 'Bad Length\.' -or $_.Exception.Message -match 'The parameter is incorrect\.') { [int]$maxLengthGuess = ($rsaKey.KeySize - (2 * 160 - 2)) / 8 Write-Error -Message ('Failed to encrypt. String is longer than maximum length allowed by RSA and your key size, which is {0} bits. We estimate the maximum string size you can encrypt with certificate ''{1}'' ({2}) is {3} bytes. You may still get errors when you attempt to decrypt a string within a few bytes of this estimated maximum.' -f $rsaKey.KeySize,$Certificate.Subject,$Certificate.Thumbprint,$maxLengthGuess) return } else { Write-Error -Exception $_.Exception return } } } elseif( $PSCmdlet.ParameterSetName -eq 'Symmetric' ) { $Key = ConvertTo-Key -InputObject $Key -From 'Protect-String' if( -not $Key ) { return } $aes = New-Object 'Security.Cryptography.AesCryptoServiceProvider' try { $aes.Padding = [Security.Cryptography.PaddingMode]::PKCS7 $aes.KeySize = $Key.Length * 8 $aes.Key = $Key $memoryStream = New-Object 'IO.MemoryStream' try { $cryptoStream = New-Object 'Security.Cryptography.CryptoStream' $memoryStream,$aes.CreateEncryptor(),([Security.Cryptography.CryptoStreamMode]::Write) try { $cryptoStream.Write($stringBytes,0,$stringBytes.Length) } finally { $cryptoStream.Dispose() } $encryptedBytes = Invoke-Command -ScriptBlock { $aes.IV $memoryStream.ToArray() } } finally { $memoryStream.Dispose() } } finally { $aes.Dispose() } } return [Convert]::ToBase64String( $encryptedBytes ) } finally { $stringBytes.Clear() } } |