CryptographyClient implemented with service calls

doc/sphinx/ref/azure.keyvault.keys.aio.rst

@@ -1,6 +1,18 @@
 azure.keyvault.keys.aio package
 ===============================
 
+Submodules
+----------
+
+azure.keyvault.keys.aio.client module
+-------------------------------------
+
+.. automodule:: azure.keyvault.keys.aio.client
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
 Module contents
 ---------------
 

doc/sphinx/ref/azure.keyvault.keys.crypto.aio.rst

@@ -0,0 +1,22 @@
+azure.keyvault.keys.crypto.aio package
+======================================
+
+Submodules
+----------
+
+azure.keyvault.keys.crypto.aio.client module
+--------------------------------------------
+
+.. automodule:: azure.keyvault.keys.crypto.aio.client
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: azure.keyvault.keys.crypto.aio
+   :members:
+   :undoc-members:
+   :show-inheritance:

doc/sphinx/ref/azure.keyvault.keys.crypto.rst

@@ -0,0 +1,37 @@
+azure.keyvault.keys.crypto package
+==================================
+
+Subpackages
+-----------
+
+.. toctree::
+
+   azure.keyvault.keys.crypto.aio
+
+Submodules
+----------
+
+azure.keyvault.keys.crypto.client module
+----------------------------------------
+
+.. automodule:: azure.keyvault.keys.crypto.client
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+azure.keyvault.keys.crypto.enums module
+---------------------------------------
+
+.. automodule:: azure.keyvault.keys.crypto.enums
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: azure.keyvault.keys.crypto
+   :members:
+   :undoc-members:
+   :show-inheritance:

doc/sphinx/ref/azure.keyvault.keys.rst

@@ -7,14 +7,31 @@ Subpackages
 .. toctree::
 
    azure.keyvault.keys.aio
+   azure.keyvault.keys.crypto
 
 Submodules
 ----------
 
-azure.keyvault.keys.version module
-----------------------------------
+azure.keyvault.keys.client module
+---------------------------------
 
-.. automodule:: azure.keyvault.keys.version
+.. automodule:: azure.keyvault.keys.client
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+azure.keyvault.keys.enums module
+--------------------------------
+
+.. automodule:: azure.keyvault.keys.enums
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+azure.keyvault.keys.models module
+---------------------------------
+
+.. automodule:: azure.keyvault.keys.models
    :members:
    :undoc-members:
    :show-inheritance:

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

@@ -5,13 +5,17 @@
 - Removed `azure.core.Configuration` from the public API in preparation for a
 revamped configuration API. Static `create_config` methods have been renamed
 `_create_config`, and will be removed in a future release.
+- Removed `wrap_key` and `unwrap_key` from `KeyClient`. These are now available
+through `CryptographyClient`.
 - This version of the library requires `azure-core` 1.0.0b2
   - If you later want to revert to a version requiring azure-core 1.0.0b1,
   of this or another Azure SDK library, you must explicitly install azure-core
   1.0.0b1 as well. For example:
   `pip install azure-core==1.0.0b1 azure-keyvault-keys==4.0.0b1`
 
 ### New features:
+- Added `CryptographyClient`, a client for performing cryptographic operations
+(encrypt/decrypt, wrap/unwrap, sign/verify) with a key.
 - Distributed tracing framework OpenCensus is now supported
 - Added support for HTTP challenge based authentication, allowing clients to
 interact with vaults in sovereign clouds.
@@ -54,7 +58,7 @@ only)
 
 ### `azure-keyvault` features not implemented in this release
 - Certificate management APIs
-- Cryptographic operations, e.g. sign, un/wrap, verify, en- and
+- Cryptographic operations, e.g. sign, un/wrap_key, verify, en- and
 decrypt
 - National cloud support. This release supports public global cloud vaults,
     e.g. https://{vault-name}.vault.azure.net

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

@@ -152,6 +152,26 @@ for key in keys:
     print(key.name)
 ```
 
+### Cryptographic operations
+`CryptographyClient` enables cryptographic operations (encrypt/decrypt,
+wrap/unwrap, sign/verify) using a particular key.
+
+```py
+from azure.identity import DefaultAzureCredential
+from azure.keyvault.keys import KeyClient
+from azure.keyvault.keys.crypto import EncryptionAlgorithm
+
+credential = DefaultAzureCredential()
+key_client = KeyClient(vault_url=vault_url, credential=credential)
+
+key = key_client.get_key("my-key")
+crypto_client = key_client.get_cryptography_client(key)
+
+result = crypto_client.encrypt(EncryptionAlgorithm.rsa_oaep, plaintext)
+crypto_client.decrypt(result.algorithm, result.ciphertext)
+```
+See the [reference documentation][reference_docs] for more information.
+
 ### Async operations
 This library includes a complete async API supported on Python 3.5+. To use it, you must
 first install an async transport, such as [`aiohttp`](https://pypi.org/project/aiohttp/).

sdk/keyvault/azure-keyvault-keys/azure/keyvault/keys/aio/client.py

@@ -3,14 +3,16 @@
 # Licensed under the MIT License.
 # ------------------------------------
 from datetime import datetime
-from typing import Any, AsyncIterable, Mapping, Optional, Dict, List
+from typing import Any, AsyncIterable, Mapping, Optional, Dict, List, Union
 
 from azure.core.exceptions import ResourceExistsError, ResourceNotFoundError
 from azure.core.tracing.decorator import distributed_trace
 from azure.core.tracing.decorator_async import distributed_trace_async
 from azure.keyvault.keys.models import DeletedKey, JsonWebKey, Key, KeyBase, KeyOperationResult
 from azure.keyvault.keys._shared import AsyncKeyVaultClientBase
 
+from ..crypto.aio import CryptographyClient
+
 
 class KeyClient(AsyncKeyVaultClientBase):
     """A high-level asynchronous interface for managing a vault's keys.
@@ -30,6 +32,12 @@ class KeyClient(AsyncKeyVaultClientBase):
 
     # pylint:disable=protected-access
 
+    def get_cryptography_client(self, key: Union[Key, str], **kwargs: Any) -> CryptographyClient:
+        # the initializer requires a credential but won't actually use it in this case because we pass in this
+        # KeyClient's generated client, whose pipeline (and auth policy) is fully configured
+        credential = object()
+        return CryptographyClient(key, credential, generated_client=self._client, **kwargs)
+
     @distributed_trace_async
     async def create_key(
         self,

sdk/keyvault/azure-keyvault-keys/azure/keyvault/keys/client.py

@@ -19,6 +19,7 @@
 from azure.core.tracing.decorator import distributed_trace
 
 from ._shared import KeyVaultClientBase
+from .crypto import CryptographyClient
 from .models import Key, KeyBase, DeletedKey, KeyOperationResult
 
 
@@ -40,6 +41,14 @@ class KeyClient(KeyVaultClientBase):
 
     # pylint:disable=protected-access
 
+    def get_cryptography_client(self, key, **kwargs):
+        # type: (Union[Key, str], Any) -> CryptographyClient
+
+        # the initializer requires a credential but won't actually use it in this case because we pass in this
+        # KeyClient's generated client, whose pipeline (and auth policy) is fully configured
+        credential = object()
+        return CryptographyClient(key, credential, generated_client=self._client, **kwargs)
+
     @distributed_trace
     def create_key(
         self,
@@ -510,69 +519,3 @@ def import_key(self, name, key, hsm=None, enabled=None, not_before=None, expires
             self.vault_url, name, key=key, hsm=hsm, key_attributes=attributes, tags=tags, **kwargs
         )
         return Key._from_key_bundle(bundle)
-
-    @distributed_trace
-    def wrap_key(self, name, algorithm, value, version=None, **kwargs):
-        # type: (str, str, Optional[str], bytes, Mapping[str, Any]) -> KeyOperationResult
-        """Wraps a symmetric key using a specified key.
-
-        The WRAP operation supports encryption of a symmetric key using a key
-        encryption key that has previously been stored in an Azure Key Vault.
-        The WRAP operation is only strictly necessary for symmetric keys stored
-        in Azure Key Vault since protection with an asymmetric key can be
-        performed using the public portion of the key. This operation is
-        supported for asymmetric keys as a convenience for callers that have a
-        key-reference but do not have access to the public key material. This
-        operation requires the keys/wrapKey permission.
-
-        :param str name: The name of the key
-        :param str version: The version of the key.
-        :param algorithm: algorithm identifier. Possible values include:
-         'RSA-OAEP', 'RSA-OAEP-256', 'RSA1_5'
-        :type algorithm: str or
-         ~azure.security.keyvault.v7_0.models.JsonWebKeyEncryptionAlgorithm
-        :param value:
-        :type value: bytes
-        :returns: The wrapped symmetric key.
-        :rtype: ~azure.keyvault.keys.models.Key
-
-        """
-        if version is None:
-            version = ""
-
-        bundle = self._client.wrap_key(
-            self.vault_url, name, key_version=version, algorithm=algorithm, value=value, **kwargs
-        )
-        return KeyOperationResult(id=bundle.kid, value=bundle.result)
-
-    @distributed_trace
-    def unwrap_key(self, name, algorithm, value, version=None, **kwargs):
-        # type: (str, str, Optional[str], bytes, Mapping[str, Any]) -> KeyOperationResult
-        """Unwraps a symmetric key using the specified key that was initially used
-        for wrapping that key.
-
-        The UNWRAP operation supports decryption of a symmetric key using the
-        target key encryption key. This operation is the reverse of the WRAP
-        operation. The UNWRAP operation applies to asymmetric and symmetric
-        keys stored in Azure Key Vault since it uses the private portion of the
-        key. This operation requires the keys/unwrapKey permission.
-
-        :param str name: The name of the key
-        :param str version: The version of the key.
-        :param algorithm: algorithm identifier. Possible values include:
-         'RSA-OAEP', 'RSA-OAEP-256', 'RSA1_5'
-        :type algorithm: str or
-         ~azure.security.keyvault.v7_0.models.JsonWebKeyEncryptionAlgorithm
-        :param value:
-        :type value: bytes
-        :returns: The unwrapped symmetric key.
-        :rtype: ~azure.keyvault.keys.models.Key
-
-        """
-        if version is None:
-            version = ""
-
-        bundle = self._client.unwrap_key(
-            self.vault_url, name, key_version=version, algorithm=algorithm, value=value, **kwargs
-        )
-        return KeyOperationResult(id=bundle.kid, value=bundle.result)

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

@@ -0,0 +1,29 @@
+# ------------------------------------
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+# ------------------------------------
+from collections import namedtuple
+
+DecryptResult = namedtuple("DecryptResult", ["decrypted_bytes"])
+EncryptResult = namedtuple("EncryptResult", ["key_id", "algorithm", "ciphertext", "authentication_tag"])
+SignResult = namedtuple("SignResult", ["key_id", "algorithm", "signature"])
+VerifyResult = namedtuple("VerifyResult", ["result"])
+UnwrapKeyResult = namedtuple("UnwrapKeyResult", ["unwrapped_bytes"])
+WrapKeyResult = namedtuple("WrapKeyResult", ["key_id", "algorithm", "encrypted_key"])
+
+from .client import CryptographyClient
+from .enums import EncryptionAlgorithm, KeyWrapAlgorithm, SignatureAlgorithm
+
+
+__all__ = [
+    "CryptographyClient",
+    "DecryptResult",
+    "EncryptionAlgorithm",
+    "EncryptResult",
+    "KeyWrapAlgorithm",
+    "SignatureAlgorithm",
+    "SignResult",
+    "UnwrapKeyResult",
+    "VerifyResult",
+    "WrapKeyResult",
+]

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

@@ -0,0 +1,17 @@
+# ------------------------------------
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+# ------------------------------------
+from .client import CryptographyClient
+from .. import EncryptionAlgorithm, KeyWrapAlgorithm, SignatureAlgorithm
+from .. import EncryptResult, SignResult, WrapKeyResult
+
+__all__ = [
+    "CryptographyClient",
+    "EncryptionAlgorithm",
+    "EncryptResult",
+    "KeyWrapAlgorithm",
+    "SignatureAlgorithm",
+    "SignResult",
+    "WrapKeyResult",
+]