Remove parameter Value from Invoke-AzKeyVaultKeyOperation and property Result from the output type PSKeyOperationResult (#24651)

* Remove parameter Value from Invoke-AzKeyVaultKeyOperation and property Result from the output type PSKeyOperationResult

* add change log

* add BreakingChangeIssues.csv

Author: BethanyZhou

src/KeyVault/KeyVault.Test/PesterTests/Key.Tests.ps1

@@ -61,14 +61,18 @@ Describe "Import key" {
 
 Describe "Invoke key operation" {
     It "Encrypt and Decrypt a sequence using key" {
-        $encryptedResult = Invoke-AzKeyVaultKeyOperation -Operation Encrypt -Algorithm RSA1_5 -HsmName bez-hsm -Name bez-k -Value (ConvertTo-SecureString -String "test" -AsPlainText -Force) 
-        $decryptedResult = Invoke-AzKeyVaultKeyOperation -Operation Decrypt -Algorithm RSA1_5 -HsmName bez-hsm -Name bez-k -Value (ConvertTo-SecureString -String $$encryptedResult.result -AsPlainText -Force) 
-        $decryptedResult.result | Should -Be "test"
+        $plainText = "test"
+        $byteArray = [system.Text.Encoding]::UTF8.GetBytes($plainText)
+        $encryptedResult = Invoke-AzKeyVaultKeyOperation -Operation Encrypt -Algorithm RSA1_5 -HsmName bez-hsm -Name bez-k -ByteArrayValue $byteArray
+        $decryptedResult = Invoke-AzKeyVaultKeyOperation -Operation Decrypt -Algorithm RSA1_5 -HsmName bez-hsm -Name bez-k -ByteArrayValue $encryptedData.RawResult
+        [system.Text.Encoding]::UTF8.GetString($decryptedData.RawResult) | Should -Be "test"
     }
 
     It "Wrap and Unwrap a sequence using key" {
-        $wrappedResult = Invoke-AzKeyVaultKeyOperation -Operation Wrap -Algorithm RSA1_5 -HsmName bez-hsm -Name bez-k -Value (ConvertTo-SecureString -String "test" -AsPlainText -Force) 
-        $unwrappedResult = Invoke-AzKeyVaultKeyOperation -Operation Unwrap -Algorithm RSA1_5 -HsmName bez-hsm -Name bez-k -Value (ConvertTo-SecureString -String $wrappedResult.result -AsPlainText -Force) 
-        $unwrappedResult.result | Should -Be "test"
+        $key = "ovQIlbB0DgWhZA7sgkPxbg9H-Ly-VlNGPSgGrrZvlIo"
+        $byteArray = [system.Text.Encoding]::UTF8.GetBytes($key)
+        $wrappedResult = Invoke-AzKeyVaultKeyOperation -Operation Wrap -Algorithm RSA1_5 -HsmName bez-hsm -Name bez-k -ByteArrayValue $byteArray
+        $unwrappedResult = Invoke-AzKeyVaultKeyOperation -Operation Unwrap -Algorithm RSA1_5 -HsmName bez-hsm -Name bez-k -ByteArrayValue $wrappedResult.RawResult
+        [system.Text.Encoding]::UTF8.GetString($unwrappedResult.RawResult) | Should -Be $key
     }
 }

src/KeyVault/KeyVault/ChangeLog.md

@@ -18,6 +18,8 @@
         - Additional information about change #1
 -->
 ## Upcoming Release
+* [Breaking change] Removed parameter `Value` from `Invoke-AzKeyVaultKeyOperation`.
+* [Breaking change] Removed property `Result` from the output type `PSKeyOperationResult` of `Invoke-AzKeyVaultKeyOperation`.
 * [Breaking Change] Replaced parameter `EnableRbacAuthorization` by `DisableRbacAuthorization` in `New-AzKeyVault` and `Update-AzKeyVault`.
     - RBAC will be enabled by default during the process of key vault creation. 
 * Introduced secrets detection feature to safeguard sensitive data.

src/KeyVault/KeyVault/Commands/Key/InvokeAzureKeyVaultKeyOperation.cs

@@ -18,7 +18,6 @@ namespace Microsoft.Azure.Commands.KeyVault.Commands.Key
     /// 3. Wraps a symmetric key using a specified key.
     /// 4. Unwraps a symmetric key using the specified key that was initially used for wrapping that key.
     /// </summary>
-    [CmdletOutputBreakingChangeWithVersion(typeof(PSKeyOperationResult), "12.0.0", "6.0.0", DeprecatedOutputProperties = new string[] { "Result" }, NewOutputProperties = new string[] { "RawResult" })]
     [Cmdlet(VerbsLifecycle.Invoke, ResourceManager.Common.AzureRMConstants.AzurePrefix + "KeyVaultKeyOperation", SupportsShouldProcess = true, DefaultParameterSetName = ByVaultNameParameterSet)]
     [OutputType(typeof(PSKeyOperationResult))]
     public class InvokeAzureKeyVaultKeyOperation : KeyVaultKeyCmdletBase
@@ -57,62 +56,25 @@ enum Operations
         [Alias("EncryptionAlgorithm", "WrapAlgorithm")]
         public string Algorithm { get; set; }
 
-        [Parameter(Mandatory = false, HelpMessage = "The value to be operated. This parameter will be converted to byte array in UTF-8 encoding way. If your value can't be encoded by UTF-8, please use parameter ByteArrayValue as its alternative.")]
-        [ValidateNotNullOrEmpty]
-        [CmdletParameterBreakingChangeWithVersion(nameof(Value), "12.0.0", "6.0.0", ReplaceMentCmdletParameterName = nameof(ByteArrayValue))]
-        public SecureString Value { get; set; }
-
-        [Parameter(Mandatory = false, HelpMessage = "The value to be operated in byte array format.")]
+        [Parameter(Mandatory = true, HelpMessage = "The value to be operated in byte array format.")]
         [ValidateNotNullOrEmpty]
         public byte[] ByteArrayValue { get; set; }
 
         #endregion Input Parameter Definitions
 
         private Operations opt = Operations.Unknown;
 
-        internal void ValidateParameters()
-        {
-            if (this.IsParameterBound(c => c.Value) && this.IsParameterBound(c => c.ByteArrayValue))
-            {
-                throw new AzPSArgumentException(string.Format("Please provide only one of parameter Value and ByteArrayValue"), nameof(ByteArrayValue));
-            }
-            else if (!this.IsParameterBound(c => c.Value) && !this.IsParameterBound(c => c.ByteArrayValue))
-            {
-                throw new AzPSArgumentException(string.Format("Must provide one of parameter Value and ByteArrayValue"), nameof(ByteArrayValue));
-            }
-        }
+        internal void ValidateParameters() { }
 
         internal override void NormalizeParameterSets()
         {
-
             if (InputObject != null)
             {
                 Version = Version ?? InputObject.Version;
             }
 
             Enum.TryParse(Operation, out opt);
 
-            if (this.IsParameterBound(c => c.Value))
-            {
-                switch (opt)
-                {
-                    case Operations.Encrypt:
-                        ByteArrayValue = Encoding.UTF8.GetBytes(Value.ConvertToString()); 
-                        break;
-                    case Operations.Decrypt:
-                        ByteArrayValue = Convert.FromBase64String(Value.ConvertToString()); 
-                        break;
-                    case Operations.Wrap:
-                        ByteArrayValue = Encoding.UTF8.GetBytes(Value.ConvertToString());
-                        break;
-                    case Operations.Unwrap:
-                        ByteArrayValue = Convert.FromBase64String(Value.ConvertToString());
-                        break;
-                    default:
-                        throw new NotSupportedException("Not supported ${Operation} yet");
-                }
-            }
-
             base.NormalizeParameterSets();
         }
 
@@ -142,7 +104,7 @@ public override void ExecuteCmdlet()
                             this.Track2DataClient.UnwrapKey(VaultName, Name, Version, ByteArrayValue, Algorithm));
                         break;
                     case Operations.Unknown:
-                        throw new NotSupportedException("Not supported ${Operation} yet");
+                        throw new NotSupportedException($"Not supported operation '{Operation}' yet");
                 }
             }
             else
@@ -166,7 +128,7 @@ public override void ExecuteCmdlet()
                             this.Track2DataClient.ManagedHsmUnwrapKey(HsmName, Name, Version, ByteArrayValue, Algorithm));
                         break;
                     case Operations.Unknown:
-                        throw new NotSupportedException("Not supported ${Operation} yet");
+                        throw new NotSupportedException($"Not supported operation '{Operation}' yet");
                 }
 
             }

src/KeyVault/KeyVault/Models/Key/PSKeyOperationResult.cs

@@ -23,9 +23,6 @@ public class PSKeyOperationResult
         [Ps1Xml(Target = ViewControl.List, Label = nameof(RawResult), Position = 1)]
         public byte[] RawResult { get; }
 
-        // Summary: encryted result or wraped result is base64 format. decryted result or unwraped result is plain text
-        public string Result { get; }
-
         // Summary: Algorithm used.
         [Ps1Xml(Target = ViewControl.List, Label = nameof(Algorithm), Position = 2)]
         public string Algorithm { get; }
@@ -34,31 +31,27 @@ public PSKeyOperationResult(WrapResult wrapResult)
         {
             this.KeyId = wrapResult.KeyId;
             this.RawResult = wrapResult.EncryptedKey;
-            this.Result = System.Convert.ToBase64String(wrapResult.EncryptedKey);
             this.Algorithm = wrapResult.Algorithm.ToString();
         }
 
         public PSKeyOperationResult(UnwrapResult unwrapResult)
         {
             this.KeyId = unwrapResult.KeyId;
             this.RawResult = unwrapResult.Key;
-            this.Result = System.Text.Encoding.UTF8.GetString(unwrapResult.Key);
             this.Algorithm = unwrapResult.Algorithm.ToString();
         }
 
         public PSKeyOperationResult(EncryptResult encryptResult)
         {
             this.KeyId = encryptResult.KeyId;
             this.RawResult = encryptResult.Ciphertext;
-            this.Result = System.Convert.ToBase64String(encryptResult.Ciphertext);
             this.Algorithm = encryptResult.Algorithm.ToString();
         }
 
         public PSKeyOperationResult(DecryptResult decryptResult)
         {
             this.KeyId = decryptResult.KeyId;
             this.RawResult = decryptResult.Plaintext;
-            this.Result = System.Text.Encoding.UTF8.GetString(decryptResult.Plaintext);
             this.Algorithm = decryptResult.Algorithm.ToString();
         }
     }

src/KeyVault/KeyVault/help/Invoke-AzKeyVaultKeyOperation.md

@@ -15,25 +15,22 @@ Performs operation like "Encrypt", "Decrypt", "Wrap" or "Unwrap" using a specifi
 ### ByVaultName (Default)
 ```
 Invoke-AzKeyVaultKeyOperation [-Version <String>] -Operation <String> -Algorithm <String>
- [-Value <SecureString>] [-ByteArrayValue <Byte[]>] [-Name] <String> [-VaultName] <String>
- [-DefaultProfile <IAzureContextContainer>] [-WhatIf] [-Confirm]
- [<CommonParameters>]
+ [-ByteArrayValue <Byte[]>] [-Name] <String> [-VaultName] <String> [-DefaultProfile <IAzureContextContainer>]
+ [-WhatIf] [-Confirm] [<CommonParameters>]
 ```
 
 ### ByHsmName
 ```
 Invoke-AzKeyVaultKeyOperation [-Version <String>] -Operation <String> -Algorithm <String>
- [-Value <SecureString>] [-ByteArrayValue <Byte[]>] [-HsmName] <String> [-Name] <String>
- [-DefaultProfile <IAzureContextContainer>] [-WhatIf] [-Confirm]
- [<CommonParameters>]
+ [-ByteArrayValue <Byte[]>] [-HsmName] <String> [-Name] <String> [-DefaultProfile <IAzureContextContainer>]
+ [-WhatIf] [-Confirm] [<CommonParameters>]
 ```
 
 ### ByKeyInputObject
 ```
 Invoke-AzKeyVaultKeyOperation [-Version <String>] -Operation <String> -Algorithm <String>
- [-Value <SecureString>] [-ByteArrayValue <Byte[]>] [-InputObject] <PSKeyVaultKeyIdentityItem>
- [-DefaultProfile <IAzureContextContainer>] [-WhatIf] [-Confirm]
- [<CommonParameters>]
+ [-ByteArrayValue <Byte[]>] [-InputObject] <PSKeyVaultKeyIdentityItem>
+ [-DefaultProfile <IAzureContextContainer>] [-WhatIf] [-Confirm] [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -76,7 +73,9 @@ Decrypts `$encryptedData.RawResult` using test-key stored in test-kv. The `$decr
 
 ### Example 3: Encrypts plain text using an encryption key
 ```powershell
-$encryptedData = Invoke-AzKeyVaultKeyOperation -Operation Encrypt -Algorithm RSA1_5 -VaultName test-kv -Name test-key -Value (ConvertTo-SecureString -String "test" -AsPlainText -Force)
+$plainText = "test"
+$byteArray = [system.Text.Encoding]::UTF8.GetBytes($plainText)
+$encryptedData = Invoke-AzKeyVaultKeyOperation -Operation Encrypt -Algorithm RSA1_5 -VaultName test-kv -Name test-key -ByteArrayValue $byteArray
 $encryptedData
 ```
 
@@ -86,26 +85,26 @@ RawResult : {58, 219, 6, 236…}
 Algorithm : RSA1_5
 ```
 
-Encrypts string "test" using test-key stored in test-kv. The `RawResult` is the encrypted result in byte array format, where [System.Convert]::ToBase64String($encryptedData.RawResult) equals $encryptedData.Result.
+Encrypts string "test" using test-key stored in test-kv. The `RawResult` is the encrypted result in byte array format.
 
 ### Example 4: Decrypt encrypted data to plain text
 ```powershell
 $decryptedData = Invoke-AzKeyVaultKeyOperation -Operation Decrypt -Algorithm RSA1_5 -VaultName test-kv -Name test-key -ByteArrayValue $encryptedData.RawResult
-$decryptedData
+$plainText = [system.Text.Encoding]::UTF8.GetString($decryptedData.RawResult)
+$plainText
 ```
 
 ```output
-KeyId     : https://bez-kv.vault.azure.net/keys/bez-key/c96ce0fb18de446c9f4b911b686988af
-RawResult : $byteArray
-Algorithm : RSA1_5
+test
 ```
 
-Decrypts encrypted data that is encrypted using test-key stored in test-kv. The `$decryptedData.Result` is `test`. The `RawResult` is the decrypted result in byte array format, where [System.Text.UTF8Encoding]::UTF8.GetString($decryptedData.RawResult) equals $decryptedData.Result.
+Decrypts encrypted data that is encrypted using test-key stored in test-kv. The `RawResult` is the decrypted result in byte array format.
 
 ### Example 5: Wraps a symmetric key using a specified key
 ```powershell
-$wrappedResult = Invoke-AzKeyVaultKeyOperation -Operation Wrap -Algorithm RSA1_5 -VaultName test-kv -Name test-key -Value (ConvertTo-SecureString -String "ovQIlbB0DgWhZA7sgkPxbg9H-Ly-VlNGPSgGrrZvlIo" -AsPlainText -Force) 
-
+$key = "ovQIlbB0DgWhZA7sgkPxbg9H-Ly-VlNGPSgGrrZvlIo"
+$byteArray = [system.Text.Encoding]::UTF8.GetBytes($key)
+$wrappedResult = Invoke-AzKeyVaultKeyOperation -Operation Wrap -Algorithm RSA1_5 -VaultName test-kv -Name test-key -ByteArrayValue $byteArray
 $wrappedResult | Format-List
 ```
 
@@ -115,20 +114,20 @@ RawResult : {58, 219, 6, 236…}
 Algorithm : RSA1_5
 ```
 
-Wraps a symmetric key using key named test-key stored in test-kv. The `Result` is wrapped result in Base64 string format.
+Wraps a symmetric key using key named test-key stored in test-kv. The `RawResult` is wrapped result in byte array format.
 
 ### Example 6: Unwraps a symmetric key using a specified key
 ```powershell
-Invoke-AzKeyVaultKeyOperation -Operation Unwrap -Algorithm RSA1_5 -VaultName test-kv -Name test-key -Value (ConvertTo-SecureString -String $result.Result -AsPlainText -Force)
+$unwrappedResult = Invoke-AzKeyVaultKeyOperation -Operation Unwrap -Algorithm RSA1_5 -VaultName test-kv -Name test-key -ByteArrayValue $wrappedResult.RawResult
+$key = [system.Text.Encoding]::UTF8.GetString($unwrappedResult.RawResult)
+$key
 ```
 
 ```output
-KeyId     : https://test-kv.vault.azure.net/keys/test-key/375cdf20252043b79c8ca0c57b6c7679
-RawResult : {58, 219, 6, 236…}
-Algorithm : RSA1_5
+ovQIlbB0DgWhZA7sgkPxbg9H-Ly-VlNGPSgGrrZvlIo
 ```
 
-Unwraps a symmetric key using a specified key test-key stored in test-kv. The `Result` is a plain string.
+Unwraps a symmetric key using a specified key test-key stored in test-kv. The `RawResult` is unwrapped result in byte array format.
 
 ## PARAMETERS
 
@@ -237,21 +236,6 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
-### -Value
-The value to be operated. This parameter will be converted to byte array in UTF-8 encoding way. If your value can't be encoded by UTF-8, please use parameter ByteArrayValue as its alternative.
-
-```yaml
-Type: System.Security.SecureString
-Parameter Sets: (All)
-Aliases:
-
-Required: False
-Position: Named
-Default value: None
-Accept pipeline input: False
-Accept wildcard characters: False
-```
-
 ### -VaultName
 Vault name.
 

tools/StaticAnalysis/Exceptions/Az.KeyVault/BreakingChangeIssues.csv

@@ -1,8 +1,14 @@
 "Module","ClassName","Target","Severity","ProblemId","Description","Remediation"
+"Az.KeyVault","Microsoft.Azure.Commands.KeyVault.Commands.Key.InvokeAzureKeyVaultKeyOperation","Invoke-AzKeyVaultKeyOperation","0","3010","The property 'Result' of type 'Microsoft.Azure.Commands.KeyVault.Models.PSKeyOperationResult' has been removed.","Add the property 'Result' back to type 'Microsoft.Azure.Commands.KeyVault.Models.PSKeyOperationResult'."
+"Az.KeyVault","Microsoft.Azure.Commands.KeyVault.Commands.Key.InvokeAzureKeyVaultKeyOperation","Invoke-AzKeyVaultKeyOperation","0","2000","The cmdlet 'Invoke-AzKeyVaultKeyOperation' no longer supports the parameter 'Value' and no alias was found for the original parameter name.","Add the parameter 'Value' back to the cmdlet 'Invoke-AzKeyVaultKeyOperation', or add an alias to the original parameter name."
+"Az.KeyVault","Microsoft.Azure.Commands.KeyVault.Commands.Key.InvokeAzureKeyVaultKeyOperation","Invoke-AzKeyVaultKeyOperation","0","1050","The parameter set '__AllParameterSets' for cmdlet 'Invoke-AzKeyVaultKeyOperation' has been removed.","Add parameter set '__AllParameterSets' back to cmdlet 'Invoke-AzKeyVaultKeyOperation'."
+"Az.KeyVault","Microsoft.Azure.Commands.KeyVault.Commands.Key.InvokeAzureKeyVaultKeyOperation","Invoke-AzKeyVaultKeyOperation","0","1050","The parameter set 'ByHsmName' for cmdlet 'Invoke-AzKeyVaultKeyOperation' has been removed.","Add parameter set 'ByHsmName' back to cmdlet 'Invoke-AzKeyVaultKeyOperation'."
+"Az.KeyVault","Microsoft.Azure.Commands.KeyVault.Commands.Key.InvokeAzureKeyVaultKeyOperation","Invoke-AzKeyVaultKeyOperation","0","1050","The parameter set 'ByVaultName' for cmdlet 'Invoke-AzKeyVaultKeyOperation' has been removed.","Add parameter set 'ByVaultName' back to cmdlet 'Invoke-AzKeyVaultKeyOperation'."
+"Az.KeyVault","Microsoft.Azure.Commands.KeyVault.Commands.Key.InvokeAzureKeyVaultKeyOperation","Invoke-AzKeyVaultKeyOperation","0","1050","The parameter set 'ByKeyInputObject' for cmdlet 'Invoke-AzKeyVaultKeyOperation' has been removed.","Add parameter set 'ByKeyInputObject' back to cmdlet 'Invoke-AzKeyVaultKeyOperation'."
 "Az.KeyVault","Microsoft.Azure.Commands.KeyVault.NewAzureKeyVault","New-AzKeyVault","0","2000","The cmdlet 'New-AzKeyVault' no longer supports the parameter 'EnableRbacAuthorization' and no alias was found for the original parameter name.","Add the parameter 'EnableRbacAuthorization' back to the cmdlet 'New-AzKeyVault', or add an alias to the original parameter name."
 "Az.KeyVault","Microsoft.Azure.Commands.KeyVault.NewAzureKeyVault","New-AzKeyVault","0","1050","The parameter set '__AllParameterSets' for cmdlet 'New-AzKeyVault' has been removed.","Add parameter set '__AllParameterSets' back to cmdlet 'New-AzKeyVault'."
 "Az.KeyVault","Microsoft.Azure.Commands.KeyVault.UpdateTopLevelResourceCommand","Update-AzKeyVault","0","2000","The cmdlet 'Update-AzKeyVault' no longer supports the parameter 'EnableRbacAuthorization' and no alias was found for the original parameter name.","Add the parameter 'EnableRbacAuthorization' back to the cmdlet 'Update-AzKeyVault', or add an alias to the original parameter name."
 "Az.KeyVault","Microsoft.Azure.Commands.KeyVault.UpdateTopLevelResourceCommand","Update-AzKeyVault","0","1050","The parameter set 'UpdateByNameParameterSet' for cmdlet 'Update-AzKeyVault' has been removed.","Add parameter set 'UpdateByNameParameterSet' back to cmdlet 'Update-AzKeyVault'."
 "Az.KeyVault","Microsoft.Azure.Commands.KeyVault.UpdateTopLevelResourceCommand","Update-AzKeyVault","0","1050","The parameter set 'UpdateByInputObjectParameterSet' for cmdlet 'Update-AzKeyVault' has been removed.","Add parameter set 'UpdateByInputObjectParameterSet' back to cmdlet 'Update-AzKeyVault'."
 "Az.KeyVault","Microsoft.Azure.Commands.KeyVault.UpdateTopLevelResourceCommand","Update-AzKeyVault","0","1050","The parameter set 'UpdateByResourceIdParameterSet' for cmdlet 'Update-AzKeyVault' has been removed.","Add parameter set 'UpdateByResourceIdParameterSet' back to cmdlet 'Update-AzKeyVault'."
-"Az.KeyVault","Microsoft.Azure.Commands.KeyVault.UpdateTopLevelResourceCommand","Update-AzKeyVault","0","1050","The parameter set '__AllParameterSets' for cmdlet 'Update-AzKeyVault' has been removed.","Add parameter set '__AllParameterSets' back to cmdlet 'Update-AzKeyVault'."
+"Az.KeyVault","Microsoft.Azure.Commands.KeyVault.UpdateTopLevelResourceCommand","Update-AzKeyVault","0","1050","The parameter set '__AllParameterSets' for cmdlet 'Update-AzKeyVault' has been removed.","Add parameter set '__AllParameterSets' back to cmdlet 'Update-AzKeyVault'."