[Key Vault] Implement secure key release (Azure#20048)

Author: mccoyp

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

@@ -3,6 +3,13 @@
 ## 4.5.0b2 (Unreleased)
 
 ### Features Added
+- Added support for secure key release from a Managed HSM
+  ([#19588](https://github.com/Azure/azure-sdk-for-python/issues/19588))
+  - Added `release_key` method to `KeyClient` for releasing the private component of a key
+  - Added `exportable` and `release_policy` keyword-only arguments to key creation and import
+    methods
+  - Added `KeyExportEncryptionAlgorithm` enum for specifying an encryption algorithm to be used
+    in key release
 
 ### Breaking Changes
 > These changes do not impact the API of stable versions such as 4.4.0.

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

@@ -2,9 +2,18 @@
 # Copyright (c) Microsoft Corporation.
 # Licensed under the MIT License.
 # -------------------------------------
-from ._enums import KeyCurveName, KeyOperation, KeyType
+from ._enums import KeyCurveName, KeyExportEncryptionAlgorithm, KeyOperation, KeyType
 from ._shared.client_base import ApiVersion
-from ._models import DeletedKey, JsonWebKey, KeyProperties, KeyVaultKey, KeyVaultKeyIdentifier, RandomBytes
+from ._models import (
+    DeletedKey,
+    JsonWebKey,
+    KeyProperties,
+    KeyReleasePolicy,
+    KeyVaultKey,
+    KeyVaultKeyIdentifier,
+    RandomBytes,
+    ReleaseKeyResult,
+)
 from ._client import KeyClient
 
 __all__ = [
@@ -14,11 +23,14 @@
     "KeyVaultKey",
     "KeyVaultKeyIdentifier",
     "KeyCurveName",
+    "KeyExportEncryptionAlgorithm",
     "KeyOperation",
     "KeyType",
     "DeletedKey",
     "KeyProperties",
+    "KeyReleasePolicy",
     "RandomBytes",
+    "ReleaseKeyResult",
 ]
 
 from ._version import VERSION

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

@@ -2,10 +2,14 @@
 # Copyright (c) Microsoft Corporation.
 # Licensed under the MIT License.
 # ------------------------------------
+# pylint:skip-file (avoids crash due to six.with_metaclass https://github.com/PyCQA/astroid/issues/713)
 from enum import Enum
+from six import with_metaclass
 
+from azure.core import CaseInsensitiveEnumMeta
 
-class KeyCurveName(str, Enum):
+
+class KeyCurveName(with_metaclass(CaseInsensitiveEnumMeta, str, Enum)):
     """Supported elliptic curves"""
 
     p_256 = "P-256"  #: The NIST P-256 elliptic curve, AKA SECG curve SECP256R1.
@@ -14,7 +18,15 @@ class KeyCurveName(str, Enum):
     p_256_k = "P-256K"  #: The SECG SECP256K1 elliptic curve.
 
 
-class KeyOperation(str, Enum):
+class KeyExportEncryptionAlgorithm(with_metaclass(CaseInsensitiveEnumMeta, str, Enum)):
+    """Supported algorithms for protecting exported key material"""
+
+    CKM_RSA_AES_KEY_WRAP = "CKM_RSA_AES_KEY_WRAP"
+    RSA_AES_KEY_WRAP_256 = "RSA_AES_KEY_WRAP_256"
+    RSA_AES_KEY_WRAP_384 = "RSA_AES_KEY_WRAP_384"
+
+
+class KeyOperation(with_metaclass(CaseInsensitiveEnumMeta, str, Enum)):
     """Supported key operations"""
 
     encrypt = "encrypt"
@@ -24,9 +36,10 @@ class KeyOperation(str, Enum):
     verify = "verify"
     wrap_key = "wrapKey"
     unwrap_key = "unwrapKey"
+    export = "export"
 
 
-class KeyType(str, Enum):
+class KeyType(with_metaclass(CaseInsensitiveEnumMeta, str, Enum)):
     """Supported key types"""
 
     ec = "EC"  #: Elliptic Curve

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

@@ -71,6 +71,7 @@ def __init__(self, key_id, attributes=None, **kwargs):
         self._vault_id = KeyVaultKeyIdentifier(key_id)
         self._managed = kwargs.get("managed", None)
         self._tags = kwargs.get("tags", None)
+        self._release_policy = kwargs.pop("release_policy", None)
 
     def __repr__(self):
         # type () -> str
@@ -80,8 +81,19 @@ def __repr__(self):
     def _from_key_bundle(cls, key_bundle):
         # type: (_models.KeyBundle) -> KeyProperties
         """Construct a KeyProperties from an autorest-generated KeyBundle"""
+        # release_policy was added in 7.3-preview
+        release_policy = None
+        if hasattr(key_bundle, "release_policy") and key_bundle.release_policy is not None:
+            release_policy = KeyReleasePolicy(
+                data=key_bundle.release_policy.data, content_type=key_bundle.release_policy.content_type
+            )
+
         return cls(
-            key_bundle.key.kid, attributes=key_bundle.attributes, managed=key_bundle.managed, tags=key_bundle.tags
+            key_bundle.key.kid,
+            attributes=key_bundle.attributes,
+            managed=key_bundle.managed,
+            tags=key_bundle.tags,
+            release_policy=release_policy,
         )
 
     @classmethod
@@ -179,8 +191,8 @@ def recoverable_days(self):
         :rtype: int
         """
         # recoverable_days was added in 7.1-preview
-        if self._attributes and hasattr(self._attributes, "recoverable_days"):
-            return self._attributes.recoverable_days
+        if self._attributes:
+            return getattr(self._attributes, "recoverable_days", None)
         return None
 
     @property
@@ -210,6 +222,55 @@ def managed(self):
         """
         return self._managed
 
+    @property
+    def exportable(self):
+        # type: () -> Optional[bool]
+        """Whether the private key can be exported
+
+        :rtype: bool
+        """
+        # exportable was added in 7.3-preview
+        if self._attributes:
+            return getattr(self._attributes, "exportable", None)
+        return None
+
+    @property
+    def release_policy(self):
+        # type: () -> Optional[KeyReleasePolicy]
+        """The :class:`~azure.keyvault.keys.KeyReleasePolicy` specifying the rules under which the key can be exported.
+
+        :rtype: ~azure.keyvault.keys.KeyReleasePolicy
+        """
+        return self._release_policy
+
+
+class KeyReleasePolicy(object):
+    """The policy rules under which a key can be exported.
+
+    :param data: Blob encoding the policy rules under which the key can be released.
+    :type data: bytes
+
+    :keyword content_type: Content type and version of the release policy. Defaults to "application/json; charset=utf-8"
+        if omitted.
+    :paramtype content_type: str
+    """
+
+    def __init__(self, data, **kwargs):
+        # type: (bytes, **Any) -> None
+        self.data = data
+        self.content_type = kwargs.get("content_type", None)
+
+
+class ReleaseKeyResult(object):
+    """The result of a key release operation.
+
+    :ivar str value: A signed token containing the released key.
+    """
+
+    def __init__(self, value):
+        # type: (str) -> None
+        self.value = value
+
 
 class KeyVaultKey(object):
     """A key's attributes and cryptographic material.