diff --git a/README.md b/README.md index 21de181..d6c4f9c 100644 --- a/README.md +++ b/README.md @@ -1,129 +1,327 @@ # Invoke-SymmectricCryptography + +## SYNOPSIS Performs value encryption or decryption using a specified algorithm. - .SYNOPSIS - Performs value encryption or decryption using a specified algorithm. - - .DESCRIPTION - A random key and initialization vector (IV) will be generated with each execution for maximum security. - - This means that the resulting encrypted data will NEVER be the same, even if the value to be encrypted is! - - This function is great for encrypting data that will NOT be transmitted over a network. In other words, data at rest. +## SYNTAX - If transmitting the data over a network is required, consider breaking the encrypted data, key, and initialization vector apart. - - .PARAMETER Encrypt - Specifies that encryption will be performed. +### Encryption (Default) +``` +Invoke-SymmectricCryptography [-Encrypt] -Algorithm -Data [-Export] + [-ExportFormat ] [-ExportPath ] [-ContinueOnError] [] +``` - .PARAMETER Decrypt - Specifies that decryption will be performed. +### Decryption +``` +Invoke-SymmectricCryptography [-Decrypt] -Algorithm -EncryptedData -Key + -InitializationVector [-ContinueOnError] [] +``` - .PARAMETER Algorithm - Specifies the algorithm used for encryption or decryption. +## DESCRIPTION +A random key and initialization vector (IV) will be generated with each execution for maximum security. - .PARAMETER Data - Specifies the original string value that will be encrypted. +This means that the resulting encrypted data will NEVER be the same, even if the value to be encrypted is! - .PARAMETER EncryptedData - Specifies the previously encrypted string value that will be decrypted. +This function is great for encrypting data that will NOT be transmitted over a network. +In other words, data at rest. - .PARAMETER Key - Specifies the decryption key that is required for decryption. +If transmitting the data over a network is required, consider breaking the encrypted data, key, and initialization vector apart. - .PARAMETER InitializationVector - Specifies the initialization vector (IV) that is required for decryption. +## EXAMPLES - .PARAMETER Export - Specifies that the encrypted data is to be exported. +### EXAMPLE 1 +``` +$EncryptionResult = Invoke-SymmectricCryptography -Encrypt -Algorithm AES -Data 'SomeValueRequiringEncryption' - .PARAMETER ExportFormat - Specifies the format that the encrypted data will be exported in. +Write-Output -InputObject ($EncryptionResult) +``` +### EXAMPLE 2 +``` +$DecryptionResult = Invoke-SymmectricCryptography -Decrypt -Algorithm AES -Data 'msDFP5hUQo8flkb+qnRSl+1yEaKEhl5Lr3LBfClXSMY=' -Key 'oc5cuCuOhw1qJvwr1iwHr9mOWXmLTMCgw1zlIOZDf78=' -InitializationVector 'zDpcPE2a4YWF/gFmGQoZhQ==' - .PARAMETER ExportPath - Specifies the path that the encrypted data will be exported to. +Write-Output -InputObject ($DecryptionResult) +``` +### EXAMPLE 3 +``` +$InvokeSymmectricCryptographyParameters = New-Object -TypeName 'System.Collections.Specialized.OrderedDictionary' - .PARAMETER ContinueOnError - Specifies that errors will be logged as warnings, but not considered fatal. - - .EXAMPLE - $EncryptionResult = Invoke-SymmectricCryptography -Encrypt -Algorithm AES -Data 'SomeValueRequiringEncryption' +$InvokeSymmectricCryptographyParameters.Encrypt = $True + $InvokeSymmectricCryptographyParameters.Algorithm = 'AES' + $InvokeSymmectricCryptographyParameters.Data = New-Object -TypeName 'System.Collections.Generic.List\[System.String\]' + $InvokeSymmectricCryptographyParameters.Data.Add("AValueThatNeedsToBeEncrypted") + $InvokeSymmectricCryptographyParameters.Data.Add("AnotherValueThatNeedsToBeEncrypted") + $InvokeSymmectricCryptographyParameters.Export = $True + $InvokeSymmectricCryptographyParameters.ExportFormat = 'XML' + $InvokeSymmectricCryptographyParameters.ExportPath = "$($Env:UserProfile)\Downloads\EncryptedData.xml" + $InvokeSymmectricCryptographyParameters.ContinueOnError = $False + $InvokeSymmectricCryptographyParameters.Verbose = $True - Write-Output -InputObject ($EncryptionResult) +$EncryptionResult = Invoke-SymmectricCryptography @InvokeSymmectricCryptographyParameters - .EXAMPLE - $DecryptionResult = Invoke-SymmectricCryptography -Decrypt -Algorithm AES -Data 'msDFP5hUQo8flkb+qnRSl+1yEaKEhl5Lr3LBfClXSMY=' -Key 'oc5cuCuOhw1qJvwr1iwHr9mOWXmLTMCgw1zlIOZDf78=' -InitializationVector 'zDpcPE2a4YWF/gFmGQoZhQ==' +Write-Output -InputObject ($EncryptionResult) +``` +### EXAMPLE 4 +``` +$InvokeSymmectricCryptographyParameters = New-Object -TypeName 'System.Collections.Specialized.OrderedDictionary' - Write-Output -InputObject ($DecryptionResult) +$InvokeSymmectricCryptographyParameters.Decrypt = $True + $InvokeSymmectricCryptographyParameters.Algorithm = 'AES' + $InvokeSymmectricCryptographyParameters.EncryptedData = 'msDFP5hUQo8flkb+qnRSl+1yEaKEhl5Lr3LBfClXSMY=' + $InvokeSymmectricCryptographyParameters.Key = 'oc5cuCuOhw1qJvwr1iwHr9mOWXmLTMCgw1zlIOZDf78=' + $InvokeSymmectricCryptographyParameters.InitializationVector = 'zDpcPE2a4YWF/gFmGQoZhQ==' + $InvokeSymmectricCryptographyParameters.ContinueOnError = $False + $InvokeSymmectricCryptographyParameters.Verbose = $True - .EXAMPLE - $InvokeSymmectricCryptographyParameters = New-Object -TypeName 'System.Collections.Specialized.OrderedDictionary' - $InvokeSymmectricCryptographyParameters.Encrypt = $True - $InvokeSymmectricCryptographyParameters.Algorithm = 'AES' - $InvokeSymmectricCryptographyParameters.Data = New-Object -TypeName 'System.Collections.Generic.List[System.String]' - $InvokeSymmectricCryptographyParameters.Data.Add("AValueThatNeedsToBeEncrypted") - $InvokeSymmectricCryptographyParameters.Data.Add("AnotherValueThatNeedsToBeEncrypted") - $InvokeSymmectricCryptographyParameters.Export = $True - $InvokeSymmectricCryptographyParameters.ExportFormat = 'XML' - $InvokeSymmectricCryptographyParameters.ExportPath = "$($Env:UserProfile)\Downloads\EncryptedData.xml" - $InvokeSymmectricCryptographyParameters.ContinueOnError = $False - $InvokeSymmectricCryptographyParameters.Verbose = $True +$DecryptionResult = Invoke-SymmectricCryptography @InvokeSymmectricCryptographyParameters - $EncryptionResult = Invoke-SymmectricCryptography @InvokeSymmectricCryptographyParameters +Write-Output -InputObject ($DecryptionResult) +``` +### EXAMPLE 5 +``` +$InvokeSymmectricCryptographyParameters = New-Object -TypeName 'System.Collections.Specialized.OrderedDictionary' - Write-Output -InputObject ($EncryptionResult) +$InvokeSymmectricCryptographyParameters.Encrypt = $True + $InvokeSymmectricCryptographyParameters.Algorithm = 'AES' + $InvokeSymmectricCryptographyParameters.Data = "AValueThatNeedsToBeEncrypted" + $InvokeSymmectricCryptographyParameters.ContinueOnError = $False + $InvokeSymmectricCryptographyParameters.Verbose = $True - .EXAMPLE - $InvokeSymmectricCryptographyParameters = New-Object -TypeName 'System.Collections.Specialized.OrderedDictionary' - $InvokeSymmectricCryptographyParameters.Decrypt = $True - $InvokeSymmectricCryptographyParameters.Algorithm = 'AES' - $InvokeSymmectricCryptographyParameters.EncryptedData = 'msDFP5hUQo8flkb+qnRSl+1yEaKEhl5Lr3LBfClXSMY=' - $InvokeSymmectricCryptographyParameters.Key = 'oc5cuCuOhw1qJvwr1iwHr9mOWXmLTMCgw1zlIOZDf78=' - $InvokeSymmectricCryptographyParameters.InitializationVector = 'zDpcPE2a4YWF/gFmGQoZhQ==' - $InvokeSymmectricCryptographyParameters.ContinueOnError = $False - $InvokeSymmectricCryptographyParameters.Verbose = $True +$EncryptionResult = Invoke-SymmectricCryptography @InvokeSymmectricCryptographyParameters - $DecryptionResult = Invoke-SymmectricCryptography @InvokeSymmectricCryptographyParameters +Write-Output -InputObject ($EncryptionResult) - Write-Output -InputObject ($DecryptionResult) +$InvokeSymmectricCryptographyParameters = New-Object -TypeName 'System.Collections.Specialized.OrderedDictionary' + $InvokeSymmectricCryptographyParameters.Decrypt = $True + $InvokeSymmectricCryptographyParameters.Algorithm = $EncryptionResult.Algorithm + $InvokeSymmectricCryptographyParameters.EncryptedData = $EncryptionResult.Data + $InvokeSymmectricCryptographyParameters.Key = $EncryptionResult.Key + $InvokeSymmectricCryptographyParameters.InitializationVector = $EncryptionResult.InitializationVector + $InvokeSymmectricCryptographyParameters.ContinueOnError = $False + $InvokeSymmectricCryptographyParameters.Verbose = $True - .EXAMPLE - $InvokeSymmectricCryptographyParameters = New-Object -TypeName 'System.Collections.Specialized.OrderedDictionary' - $InvokeSymmectricCryptographyParameters.Encrypt = $True - $InvokeSymmectricCryptographyParameters.Algorithm = 'AES' - $InvokeSymmectricCryptographyParameters.Data = "AValueThatNeedsToBeEncrypted" - $InvokeSymmectricCryptographyParameters.ContinueOnError = $False - $InvokeSymmectricCryptographyParameters.Verbose = $True +$DecryptionResult = Invoke-SymmectricCryptography @InvokeSymmectricCryptographyParameters - $EncryptionResult = Invoke-SymmectricCryptography @InvokeSymmectricCryptographyParameters +Write-Output -InputObject ($DecryptionResult) +``` +## PARAMETERS - Write-Output -InputObject ($EncryptionResult) - - $InvokeSymmectricCryptographyParameters = New-Object -TypeName 'System.Collections.Specialized.OrderedDictionary' - $InvokeSymmectricCryptographyParameters.Decrypt = $True - $InvokeSymmectricCryptographyParameters.Algorithm = $EncryptionResult.Algorithm - $InvokeSymmectricCryptographyParameters.EncryptedData = $EncryptionResult.Data - $InvokeSymmectricCryptographyParameters.Key = $EncryptionResult.Key - $InvokeSymmectricCryptographyParameters.InitializationVector = $EncryptionResult.InitializationVector - $InvokeSymmectricCryptographyParameters.ContinueOnError = $False - $InvokeSymmectricCryptographyParameters.Verbose = $True +### -Algorithm +Specifies the algorithm used for encryption or decryption. - $DecryptionResult = Invoke-SymmectricCryptography @InvokeSymmectricCryptographyParameters +```yaml +Type: System.String +Parameter Sets: (All) +Aliases: - Write-Output -InputObject ($DecryptionResult) +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` - .NOTES - Any useful tidbits +### -ContinueOnError +Specifies that errors will be logged as warnings, but not considered fatal. - .LINK - https://codeandkeep.com/PowerShell-Aes-Encryption/ - - .LINK - https://smsagent.blog/2022/09/23/encrypting-sensitive-data-for-transit-or-rest-with-powershell/ - - .LINK - https://stackoverflow.com/questions/67883498/powershell-password-encryption-decryption-with-key - - .LINK - https://medium.com/@sumindaniro/encrypt-decrypt-data-with-powershell-4a1316a0834b - +```yaml +Type: System.Management.Automation.SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Data +Specifies the original string value that will be encrypted. + +```yaml +Type: System.String[] +Parameter Sets: Encryption +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Decrypt +Specifies that decryption will be performed. + +```yaml +Type: System.Management.Automation.SwitchParameter +Parameter Sets: Decryption +Aliases: + +Required: True +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Encrypt +Specifies that encryption will be performed. + +```yaml +Type: System.Management.Automation.SwitchParameter +Parameter Sets: Encryption +Aliases: + +Required: True +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -EncryptedData +Specifies the previously encrypted string value that will be decrypted. + +```yaml +Type: System.String +Parameter Sets: Decryption +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Export +Specifies that the encrypted data is to be exported. + +```yaml +Type: System.Management.Automation.SwitchParameter +Parameter Sets: Encryption +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ExportFormat +Specifies the format that the encrypted data will be exported in. + +```yaml +Type: System.String +Parameter Sets: Encryption +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ExportPath +Specifies the path that the encrypted data will be exported to. + +```yaml +Type: System.IO.FileInfo +Parameter Sets: Encryption +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -InitializationVector +Specifies the initialization vector (IV) that is required for decryption. + +```yaml +Type: System.String +Parameter Sets: Decryption +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Key +Specifies the decryption key that is required for decryption. + +```yaml +Type: System.String +Parameter Sets: Decryption +Aliases: + +Required: True +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 + +## OUTPUTS + +### System.Management.Automation.PSObject[] +## NOTES +Any useful tidbits + +## RELATED LINKS + +[https://codeandkeep.com/PowerShell-Aes-Encryption/](https://codeandkeep.com/PowerShell-Aes-Encryption/) + +[https://smsagent.blog/2022/09/23/encrypting-sensitive-data-for-transit-or-rest-with-powershell/](https://smsagent.blog/2022/09/23/encrypting-sensitive-data-for-transit-or-rest-with-powershell/) + +[https://stackoverflow.com/questions/67883498/powershell-password-encryption-decryption-with-key](https://stackoverflow.com/questions/67883498/powershell-password-encryption-decryption-with-key) + +[https://medium.com/@sumindaniro/encrypt-decrypt-data-with-powershell-4a1316a0834b](https://medium.com/@sumindaniro/encrypt-decrypt-data-with-powershell-4a1316a0834b) + +## SAMPLE OUTPUT: + +``` +Algorithm : AES +CryptoServiceProvider : System.Security.Cryptography.AESCryptoServiceProvider +CryptoServiceProviderName : AESCryptoServiceProvider +EncryptedDataObjectList : {@{Algorithm=AES; EncryptedData=IGHYeiv2xgIx5bk3JtZvvgsex2p4KV3TL4GGDs9jfzY=; Key=Jpt2nyeCOfxDZb2UuzM92DCrBAhLiv1gXoASo2zOfL4=; + InitializationVector=SOpUqOH6CRvhtF40eM8Cng==; + DKIV=IGHYeiv2xgIx5bk3JtZvvgsex2p4KV3TL4GGDs9jfzY=:Jpt2nyeCOfxDZb2UuzM92DCrBAhLiv1gXoASo2zOfL4=:SOpUqOH6CRvhtF40eM8Cng==}, @{Algorithm=AES; + EncryptedData=gulf1oID8ueF0SgrziYCF8VDHmKNJUCg+CgolgVHE2acMvFQYL26OvaSww83lxSI; Key=3LZn9vQWAonvhSSavNectgiBex9goOFI/Nq6Wht16ao=; + InitializationVector=SkQewVlEyy5Qp1O6yOWH9A==; + DKIV=gulf1oID8ueF0SgrziYCF8VDHmKNJUCg+CgolgVHE2acMvFQYL26OvaSww83lxSI:3LZn9vQWAonvhSSavNectgiBex9goOFI/Nq6Wht16ao=:SkQewVlEyy5Qp1O6yOWH9A==}} +ExportFormat : XML +ExportContent : + + + + 2023-10-21T22:10:44 + + + + + + + + + + + + + + +ExportPath : C:\Users\alpha\Downloads\EncryptedData.xml +```