[Key Vault] Revise KeyClient.get_random_bytes (Azure#20097)

Author: mccoyp

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

@@ -5,6 +5,10 @@
 ### Features Added
 
 ### Breaking Changes
+> These changes do not impact the API of stable versions such as 4.4.0.
+> Only code written against a beta version such as 4.5.0b1 may be affected.
+- `KeyClient.get_random_bytes` now returns a `RandomBytes` model with bytes in a `value`
+  property, rather than returning the bytes directly
 
 ### Bugs Fixed
 

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

@@ -4,7 +4,7 @@
 # -------------------------------------
 from ._enums import KeyCurveName, KeyOperation, KeyType
 from ._shared.client_base import ApiVersion
-from ._models import DeletedKey, JsonWebKey, KeyProperties, KeyVaultKey, KeyVaultKeyIdentifier
+from ._models import DeletedKey, JsonWebKey, KeyProperties, KeyVaultKey, KeyVaultKeyIdentifier, RandomBytes
 from ._client import KeyClient
 
 __all__ = [
@@ -18,6 +18,7 @@
     "KeyType",
     "DeletedKey",
     "KeyProperties",
+    "RandomBytes",
 ]
 
 from ._version import VERSION

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

@@ -8,7 +8,7 @@
 from ._shared import KeyVaultClientBase
 from ._shared.exceptions import error_map as _error_map
 from ._shared._polling import DeleteRecoverPollingMethod, KeyVaultOperationPoller
-from ._models import DeletedKey, KeyVaultKey, KeyProperties
+from ._models import DeletedKey, KeyVaultKey, KeyProperties, RandomBytes
 
 try:
     from typing import TYPE_CHECKING
@@ -615,13 +615,26 @@ def import_key(self, name, key, **kwargs):
 
     @distributed_trace
     def get_random_bytes(self, count, **kwargs):
-        # type: (int, **Any) -> bytes
+        # type: (int, **Any) -> RandomBytes
         """Get the requested number of random bytes from a managed HSM.
 
         :param int count: The requested number of random bytes.
         :return: The random bytes.
-        :rtype: bytes
+        :rtype: ~azure.keyvault.keys.RandomBytes
+        :raises:
+            :class:`ValueError` if less than one random byte is requested,
+            :class:`~azure.core.exceptions.HttpResponseError` for other errors
+
+        Example:
+            .. literalinclude:: ../tests/test_key_client.py
+                :start-after: [START get_random_bytes]
+                :end-before: [END get_random_bytes]
+                :language: python
+                :caption: Get random bytes
+                :dedent: 12
         """
+        if count < 1:
+            raise ValueError("At least one random byte must be requested")
         parameters = self._models.GetRandomBytesRequest(count=count)
         result = self._client.get_random_bytes(vault_base_url=self._vault_url, parameters=parameters, **kwargs)
-        return result.value
+        return RandomBytes(value=result.value)

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

@@ -438,3 +438,13 @@ def scheduled_purge_date(self):
         :rtype: ~datetime.datetime
         """
         return self._scheduled_purge_date
+
+
+class RandomBytes(object):
+    """Contains random bytes returned from a managed HSM.
+
+    :param bytes value: the random bytes
+    """
+
+    def __init__(self, value):
+        self.value = value

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

@@ -11,7 +11,7 @@
 from .._shared._polling_async import AsyncDeleteRecoverPollingMethod
 from .._shared import AsyncKeyVaultClientBase
 from .._shared.exceptions import error_map as _error_map
-from .. import DeletedKey, JsonWebKey, KeyVaultKey, KeyProperties
+from .. import DeletedKey, JsonWebKey, KeyVaultKey, KeyProperties, RandomBytes
 
 if TYPE_CHECKING:
     # pylint:disable=ungrouped-imports
@@ -590,13 +590,26 @@ async def import_key(self, name: str, key: JsonWebKey, **kwargs: "Any") -> KeyVa
         return KeyVaultKey._from_key_bundle(bundle)
 
     @distributed_trace_async
-    async def get_random_bytes(self, count: int, **kwargs: "Any") -> bytes:
+    async def get_random_bytes(self, count: int, **kwargs: "Any") -> RandomBytes:
         """Get the requested number of random bytes from a managed HSM.
 
         :param int count: The requested number of random bytes.
         :return: The random bytes.
-        :rtype: bytes
+        :rtype: ~azure.keyvault.keys.RandomBytes
+        :raises:
+            :class:`ValueError` if less than one random byte is requested,
+            :class:`~azure.core.exceptions.HttpResponseError` for other errors
+
+        Example:
+            .. literalinclude:: ../tests/test_keys_async.py
+                :start-after: [START get_random_bytes]
+                :end-before: [END get_random_bytes]
+                :language: python
+                :caption: Get random bytes
+                :dedent: 12
         """
+        if count < 1:
+            raise ValueError("At least one random byte must be requested")
         parameters = self._models.GetRandomBytesRequest(count=count)
         result = await self._client.get_random_bytes(vault_base_url=self._vault_url, parameters=parameters, **kwargs)
-        return result.value
+        return RandomBytes(value=result.value)

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

@@ -12,6 +12,7 @@
 from azure.core.exceptions import ResourceExistsError, ResourceNotFoundError
 from azure.core.pipeline.policies import SansIOHTTPPolicy
 from azure.keyvault.keys import ApiVersion, JsonWebKey, KeyClient
+import pytest
 from six import byte2int
 
 from _shared.test_case import KeyVaultTestCase
@@ -422,12 +423,24 @@ def test_get_random_bytes(self, client, **kwargs):
 
         generated_random_bytes = []
         for i in range(5):
-            random_bytes = client.get_random_bytes(count=8)
+            # [START get_random_bytes]
+            # get eight random bytes from a managed HSM
+            result = client.get_random_bytes(count=8)
+            random_bytes = result.value
+            # [END get_random_bytes]
             assert len(random_bytes) == 8
-            assert all([random_bytes != rb] for rb in generated_random_bytes)
+            assert all(random_bytes != rb for rb in generated_random_bytes)
             generated_random_bytes.append(random_bytes)
 
 
+def test_positive_bytes_count_required():
+    client = KeyClient("...", object())
+    with pytest.raises(ValueError):
+        client.get_random_bytes(count=0)
+    with pytest.raises(ValueError):
+        client.get_random_bytes(count=-1)
+
+
 def test_service_headers_allowed_in_logs():
     service_headers = {"x-ms-keyvault-network-info", "x-ms-keyvault-region", "x-ms-keyvault-service-version"}
     client = KeyClient("...", object())

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

@@ -13,6 +13,7 @@
 from azure.core.pipeline.policies import SansIOHTTPPolicy
 from azure.keyvault.keys import ApiVersion, JsonWebKey
 from azure.keyvault.keys.aio import KeyClient
+import pytest
 from six import byte2int
 
 from _shared.test_case_async import KeyVaultTestCase
@@ -452,12 +453,25 @@ async def test_get_random_bytes(self, client, **kwargs):
 
         generated_random_bytes = []
         for i in range(5):
-            random_bytes = await client.get_random_bytes(count=8)
+            # [START get_random_bytes]
+            # get eight random bytes from a managed HSM
+            result = await client.get_random_bytes(count=8)
+            random_bytes = result.value
+            # [END get_random_bytes]
             assert len(random_bytes) == 8
-            assert all([random_bytes != rb] for rb in generated_random_bytes)
+            assert all(random_bytes != rb for rb in generated_random_bytes)
             generated_random_bytes.append(random_bytes)
 
 
+@pytest.mark.asyncio
+async def test_positive_bytes_count_required():
+    client = KeyClient("...", object())
+    with pytest.raises(ValueError):
+        await client.get_random_bytes(count=0)
+    with pytest.raises(ValueError):
+        await client.get_random_bytes(count=-1)
+
+
 def test_service_headers_allowed_in_logs():
     service_headers = {"x-ms-keyvault-network-info", "x-ms-keyvault-region", "x-ms-keyvault-service-version"}
     client = KeyClient("...", object())