Key Vault: making crypto models congruent with .net's

sdk/keyvault/azure-keyvault-keys/HISTORY.md

@@ -11,13 +11,20 @@ detail the new keyword arguments):
   - `update_key_properties` now has two positional parameters, `name` and
      (optional) `version`
   - `import_key` now has positional parameters `name` and `key`
-- `CryptographyClient` operations return class instances instead of tuples. The
-new classes have the same attributes as the tuples.
+- `CryptographyClient` operations return class instances instead of tuples and renamed the following
+properties
+    - Renamed the `decrypted_bytes` property of `DecryptResult` to `plaintext`
+    - Renamed the `unwrapped_bytes` property of `UnwrapResult` to `key`
+    - Renamed the `result` property of `VerifyResult` to `is_valid`
+- Renamed the `UnwrapKeyResult` and `WrapKeyResult` classes to `UnwrapResult` and `WrapResult`
 - Renamed `list_keys` to `list_properties_of_keys`
 - Renamed `Key` to `KeyVaultKey`
 - `KeyVaultKey` properties `created`, `expires`, and `updated` renamed to `created_on`,
 `expires_on`, and `updated_on`
 
+### New features:
+- Now all `CryptographyClient` returns include `key_id` and `algorithm` properties
+
 
 ## 4.0.0b4 (2019-10-08)
 - Enums `JsonWebKeyCurveName`, `JsonWebKeyOperation`, and `JsonWebKeyType` have

sdk/keyvault/azure-keyvault-keys/azure/keyvault/keys/crypto/__init__.py

@@ -2,7 +2,7 @@
 # Copyright (c) Microsoft Corporation.
 # Licensed under the MIT License.
 # ------------------------------------
-from ._models import DecryptResult, EncryptResult, SignResult, UnwrapKeyResult, VerifyResult, WrapKeyResult
+from ._models import DecryptResult, EncryptResult, SignResult, WrapResult, VerifyResult, UnwrapResult
 from ._client import CryptographyClient
 from ._enums import EncryptionAlgorithm, KeyWrapAlgorithm, SignatureAlgorithm
 
@@ -15,7 +15,7 @@
     "KeyWrapAlgorithm",
     "SignatureAlgorithm",
     "SignResult",
-    "UnwrapKeyResult",
+    "WrapResult",
     "VerifyResult",
-    "WrapKeyResult",
+    "UnwrapResult",
 ]

sdk/keyvault/azure-keyvault-keys/azure/keyvault/keys/crypto/_client.py

@@ -6,7 +6,7 @@
 from azure.core.exceptions import AzureError, HttpResponseError
 from azure.core.tracing.decorator import distributed_trace
 
-from . import DecryptResult, EncryptResult, SignResult, VerifyResult, UnwrapKeyResult, WrapKeyResult
+from . import DecryptResult, EncryptResult, SignResult, VerifyResult, WrapResult, UnwrapResult
 from ._internal import EllipticCurveKey, RsaKey
 from .._models import KeyVaultKey
 from .._shared import KeyVaultClientBase, parse_vault_id
@@ -208,7 +208,7 @@ def decrypt(self, algorithm, ciphertext, **kwargs):
             from azure.keyvault.keys.crypto import EncryptionAlgorithm
 
             result = client.decrypt(EncryptionAlgorithm.rsa_oaep, ciphertext)
-            print(result.decrypted_bytes)
+            print(result.plaintext)
 
         """
         result = self._client.decrypt(
@@ -219,18 +219,18 @@ def decrypt(self, algorithm, ciphertext, **kwargs):
             value=ciphertext,
             **kwargs
         )
-        return DecryptResult(decrypted_bytes=result.result)
+        return DecryptResult(key_id=self.key_id, algorithm=algorithm, plaintext=result.result)
 
     @distributed_trace
     def wrap_key(self, algorithm, key, **kwargs):
-        # type: (KeyWrapAlgorithm, bytes, **Any) -> WrapKeyResult
+        # type: (KeyWrapAlgorithm, bytes, **Any) -> WrapResult
         """
         Wrap a key with the client's key. Requires the keys/wrapKey permission.
 
         :param algorithm: wrapping algorithm to use
         :type algorithm: :class:`~azure.keyvault.keys.crypto.enums.KeyWrapAlgorithm`
         :param bytes key: key to wrap
-        :rtype: :class:`~azure.keyvault.keys.crypto.WrapKeyResult`
+        :rtype: :class:`~azure.keyvault.keys.crypto.WrapResult`
 
         Example:
 
@@ -261,18 +261,18 @@ def wrap_key(self, algorithm, key, **kwargs):
                 **kwargs
             ).result
 
-        return WrapKeyResult(key_id=self.key_id, algorithm=algorithm, encrypted_key=result)
+        return WrapResult(key_id=self.key_id, algorithm=algorithm, encrypted_key=result)
 
     @distributed_trace
     def unwrap_key(self, algorithm, encrypted_key, **kwargs):
-        # type: (KeyWrapAlgorithm, bytes, **Any) -> UnwrapKeyResult
+        # type: (KeyWrapAlgorithm, bytes, **Any) -> UnwrapResult
         """
         Unwrap a key previously wrapped with the client's key. Requires the keys/unwrapKey permission.
 
         :param algorithm: wrapping algorithm to use
         :type algorithm: :class:`~azure.keyvault.keys.crypto.enums.KeyWrapAlgorithm`
         :param bytes encrypted_key: the wrapped key
-        :rtype: :class:`~azure.keyvault.keys.crypto.UnwrapKeyResult`
+        :rtype: :class:`~azure.keyvault.keys.crypto.UnwrapResult`
 
         Example:
 
@@ -281,7 +281,7 @@ def unwrap_key(self, algorithm, encrypted_key, **kwargs):
             from azure.keyvault.keys.crypto import KeyWrapAlgorithm
 
             result = client.unwrap_key(KeyWrapAlgorithm.rsa_oaep, wrapped_bytes)
-            unwrapped_bytes = result.unwrapped_bytes
+            key = result.key
 
         """
 
@@ -293,7 +293,7 @@ def unwrap_key(self, algorithm, encrypted_key, **kwargs):
             value=encrypted_key,
             **kwargs
         )
-        return UnwrapKeyResult(unwrapped_bytes=result.result)
+        return UnwrapResult(key_id=self.key_id, algorithm=algorithm, key=result.result)
 
     @distributed_trace
     def sign(self, algorithm, digest, **kwargs):
@@ -354,7 +354,7 @@ def verify(self, algorithm, digest, signature, **kwargs):
             from azure.keyvault.keys.crypto import SignatureAlgorithm
 
             verified = client.verify(SignatureAlgorithm.rs256, digest, signature)
-            assert verified.result is True
+            assert verified.is_valid
 
         """
         local_key = self._get_local_key(**kwargs)
@@ -372,4 +372,4 @@ def verify(self, algorithm, digest, signature, **kwargs):
                 signature=signature,
                 **kwargs
             ).value
-        return VerifyResult(result=result)
+        return VerifyResult(key_id=self.key_id, algorithm=algorithm, is_valid=result)

sdk/keyvault/azure-keyvault-keys/azure/keyvault/keys/crypto/_models.py

@@ -11,12 +11,17 @@
 class DecryptResult:
     """The result of a decrypt operation.
 
-    :param bytes decrypted_bytes: The decrypted bytes
+    :param str key_id: The encryption key's Key Vault identifier
+    :param algorithm: The encryption algorithm used
+    :type algorithm: ~azure.keyvault.keys.crypto.EncryptionAlgorithm
+    :param bytes plaintext: The decrypted bytes
     """
 
-    def __init__(self, decrypted_bytes):
-        # type: (bytes) -> None
-        self.decrypted_bytes = decrypted_bytes
+    def __init__(self, key_id, algorithm, plaintext):
+        # type: (str, str, EncryptionAlgorithm, bytes) -> None
+        self.key_id = key_id
+        self.algorithm = algorithm
+        self.plaintext = plaintext
 
 
 class EncryptResult:
@@ -54,24 +59,35 @@ def __init__(self, key_id, algorithm, signature):
 class VerifyResult:
     """The result of a verify operation.
 
-    :param bool result: Whether the signature is valid
+    :param str key_id: The signing key's Key Vault identifier
+    :param bool is_valid: Whether the signature is valid
+    :param algorithm: The signature algorithm used
+    :type algorithm: ~azure.keyvault.keys.crypto.SignatureAlgorithm
     """
 
-    def __init__(self, result):
-        self.result = result
-
+    def __init__(self, key_id, is_valid, algorithm):
+        # type: (str, bool, SignatureAlgorithm) -> None
+        self.key_id = key_id
+        self.is_valid = is_valid
+        self.algorithm = algorithm
 
-class UnwrapKeyResult:
+class UnwrapResult:
     """The result of an unwrap key operation.
 
-    :param bytes unwrapped_bytes: The unwrapped key's bytes
+    :param str key_id: Key encryption key's Key Vault identifier
+    :param algorithm: The key wrap algorithm used
+    :type algorithm: ~azure.keyvault.keys.crypto.KeyWrapAlgorithm
+    :param bytes key: The unwrapped key
     """
 
-    def __init__(self, unwrapped_bytes):
-        self.unwrapped_bytes = unwrapped_bytes
+    def __init__(self, key_id, algorithm, key):
+        # type: (str, KeyWrapAlgorithm, bytes) -> None
+        self.key_id = key_id
+        self.algorithm = algorithm
+        self.key = key
 
 
-class WrapKeyResult:
+class WrapResult:
     """The result of a wrap key operation.
 
     :param str key_id: The wrapping key's Key Vault identifier

sdk/keyvault/azure-keyvault-keys/azure/keyvault/keys/crypto/aio/__init__.py

@@ -4,7 +4,7 @@
 # ------------------------------------
 from ._client import CryptographyClient
 from .. import EncryptionAlgorithm, KeyWrapAlgorithm, SignatureAlgorithm
-from .. import EncryptResult, SignResult, WrapKeyResult
+from .. import EncryptResult, SignResult, WrapResult
 
 __all__ = [
     "CryptographyClient",
@@ -13,5 +13,5 @@
     "KeyWrapAlgorithm",
     "SignatureAlgorithm",
     "SignResult",
-    "WrapKeyResult",
+    "WrapResult",
 ]

sdk/keyvault/azure-keyvault-keys/azure/keyvault/keys/crypto/aio/_client.py

@@ -6,7 +6,7 @@
 from azure.core.tracing.decorator_async import distributed_trace_async
 from azure.keyvault.keys._shared import AsyncKeyVaultClientBase, parse_vault_id
 
-from .. import DecryptResult, EncryptResult, SignResult, VerifyResult, UnwrapKeyResult, WrapKeyResult
+from .. import DecryptResult, EncryptResult, SignResult, VerifyResult, WrapResult, UnwrapResult
 from .._internal import EllipticCurveKey, RsaKey
 from ..._models import KeyVaultKey
 
@@ -195,7 +195,7 @@ async def decrypt(self, algorithm: "EncryptionAlgorithm", ciphertext: bytes, **k
             from azure.keyvault.keys.crypto import EncryptionAlgorithm
 
             result = await client.decrypt(EncryptionAlgorithm.rsa_oaep, ciphertext)
-            print(result.decrypted_bytes)
+            print(result.plaintext)
 
         """
         result = await self._client.decrypt(
@@ -206,17 +206,17 @@ async def decrypt(self, algorithm: "EncryptionAlgorithm", ciphertext: bytes, **k
             value=ciphertext,
             **kwargs
         )
-        return DecryptResult(decrypted_bytes=result.result)
+        return DecryptResult(key_id=self.key_id, algorithm=algorithm, plaintext=result.result)
 
     @distributed_trace_async
-    async def wrap_key(self, algorithm: "KeyWrapAlgorithm", key: bytes, **kwargs: "Any") -> WrapKeyResult:
+    async def wrap_key(self, algorithm: "KeyWrapAlgorithm", key: bytes, **kwargs: "Any") -> WrapResult:
         """
         Wrap a key with the client's key. Requires the keys/wrapKey permission.
 
         :param algorithm: wrapping algorithm to use
         :type algorithm: :class:`~azure.keyvault.keys.crypto.enums.KeyWrapAlgorithm`
         :param bytes key: key to wrap
-        :rtype: :class:`~azure.keyvault.keys.crypto.WrapKeyResult`
+        :rtype: :class:`~azure.keyvault.keys.crypto.WrapResult`
 
         Example:
 
@@ -246,17 +246,17 @@ async def wrap_key(self, algorithm: "KeyWrapAlgorithm", key: bytes, **kwargs: "A
                 value=key,
                 **kwargs
             ).result
-        return WrapKeyResult(key_id=self.key_id, algorithm=algorithm, encrypted_key=result)
+        return WrapResult(key_id=self.key_id, algorithm=algorithm, encrypted_key=result)
 
     @distributed_trace_async
-    async def unwrap_key(self, algorithm: "KeyWrapAlgorithm", encrypted_key: bytes, **kwargs: "Any") -> UnwrapKeyResult:
+    async def unwrap_key(self, algorithm: "KeyWrapAlgorithm", encrypted_key: bytes, **kwargs: "Any") -> UnwrapResult:
         """
         Unwrap a key previously wrapped with the client's key. Requires the keys/unwrapKey permission.
 
         :param algorithm: wrapping algorithm to use
         :type algorithm: :class:`~azure.keyvault.keys.crypto.enums.KeyWrapAlgorithm`
         :param bytes encrypted_key: the wrapped key
-        :rtype: :class:`~azure.keyvault.keys.crypto.UnwrapKeyResult`
+        :rtype: :class:`~azure.keyvault.keys.crypto.UnwrapResult`
 
         Example:
 
@@ -265,7 +265,7 @@ async def unwrap_key(self, algorithm: "KeyWrapAlgorithm", encrypted_key: bytes,
             from azure.keyvault.keys.crypto import KeyWrapAlgorithm
 
             result = await client.unwrap_key(KeyWrapAlgorithm.rsa_oaep, wrapped_bytes)
-            unwrapped_bytes = result.unwrapped_bytes
+            key = result.key
 
         """
 
@@ -277,7 +277,7 @@ async def unwrap_key(self, algorithm: "KeyWrapAlgorithm", encrypted_key: bytes,
             value=encrypted_key,
             **kwargs
         )
-        return UnwrapKeyResult(unwrapped_bytes=result.result)
+        return UnwrapResult(key_id=self.key_id, algorithm=algorithm, key=result.result)
 
     @distributed_trace_async
     async def sign(self, algorithm: "SignatureAlgorithm", digest: bytes, **kwargs: "**Any") -> SignResult:
@@ -338,7 +338,7 @@ async def verify(
             from azure.keyvault.keys.crypto import SignatureAlgorithm
 
             verified = await client.verify(SignatureAlgorithm.rs256, digest, signature)
-            assert verified.result is True
+            assert verified.is_valid
 
         """
 
@@ -357,4 +357,4 @@ async def verify(
                 signature=signature,
                 **kwargs
             ).value
-        return VerifyResult(result=result)
+        return VerifyResult(key_id=self.key_id, algorithm=algorithm, is_valid=result)

sdk/keyvault/azure-keyvault-keys/tests/test_crypto_client.py

@@ -86,7 +86,9 @@ def test_encrypt_and_decrypt(self, vault_client, **kwargs):
         self.assertEqual(result.key_id, imported_key.id)
 
         result = crypto_client.decrypt(result.algorithm, result.ciphertext)
-        self.assertEqual(self.plaintext, result.decrypted_bytes)
+        self.assertEqual(result.key_id, imported_key.id)
+        self.assertEqual(EncryptionAlgorithm.rsa_oaep, result.algorithm)
+        self.assertEqual(self.plaintext, result.plaintext)
 
     @ResourceGroupPreparer(name_prefix=name_prefix)
     @VaultClientPreparer(permissions=NO_GET)
@@ -106,7 +108,9 @@ def test_sign_and_verify(self, vault_client, **kwargs):
         self.assertEqual(result.key_id, imported_key.id)
 
         verified = crypto_client.verify(result.algorithm, digest, result.signature)
-        self.assertTrue(verified.result)
+        self.assertEqual(result.key_id, imported_key.id)
+        self.assertEqual(result.algorithm, SignatureAlgorithm.rs256)
+        self.assertTrue(verified.is_valid)
 
     @ResourceGroupPreparer(name_prefix=name_prefix)
     @VaultClientPreparer(permissions=NO_GET)
@@ -124,7 +128,7 @@ def test_wrap_and_unwrap(self, vault_client, **kwargs):
         self.assertEqual(result.key_id, created_key.id)
 
         result = crypto_client.unwrap_key(result.algorithm, result.encrypted_key)
-        self.assertEqual(key_bytes, result.unwrapped_bytes)
+        self.assertEqual(key_bytes, result.key)
 
     @ResourceGroupPreparer(name_prefix=name_prefix)
     @VaultClientPreparer()
@@ -140,7 +144,7 @@ def test_encrypt_local(self, vault_client, **kwargs):
             self.assertEqual(result.key_id, key.id)
 
             result = crypto_client.decrypt(result.algorithm, result.ciphertext)
-            self.assertEqual(result.decrypted_bytes, self.plaintext)
+            self.assertEqual(result.plaintext, self.plaintext)
 
     @ResourceGroupPreparer(name_prefix=name_prefix)
     @VaultClientPreparer()
@@ -156,7 +160,7 @@ def test_wrap_local(self, vault_client, **kwargs):
             self.assertEqual(result.key_id, key.id)
 
             result = crypto_client.unwrap_key(result.algorithm, result.encrypted_key)
-            self.assertEqual(result.unwrapped_bytes, self.plaintext)
+            self.assertEqual(result.key, self.plaintext)
 
     @ResourceGroupPreparer(name_prefix=name_prefix)
     @VaultClientPreparer()
@@ -182,7 +186,7 @@ def test_rsa_verify_local(self, vault_client, **kwargs):
                 self.assertEqual(result.key_id, key.id)
 
                 result = crypto_client.verify(result.algorithm, digest, result.signature)
-                self.assertTrue(result.result)
+                self.assertTrue(result.is_valid)
 
     @ResourceGroupPreparer(name_prefix=name_prefix)
     @VaultClientPreparer()
@@ -208,4 +212,4 @@ def test_ec_verify_local(self, vault_client, **kwargs):
             self.assertEqual(result.key_id, key.id)
 
             result = crypto_client.verify(result.algorithm, digest, result.signature)
-            self.assertTrue(result.result)
+            self.assertTrue(result.is_valid)