[Key Vault] Align keys with other languages (Azure#18765)

Author: mccoyp

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

@@ -1,10 +1,14 @@
 # Release History
 
 ## 4.4.0b5 (Unreleased)
+### Added
+- `KeyClient` has a `create_oct_key` method for creating symmetric keys
 
+### Breaking Changes
+- `parse_key_vault_key_id` and `KeyVaultResourceId` have been replaced by a
+  `KeyVaultKeyIdentifier` class, which can be initialized with a key ID
 
 ## 4.4.0b4 (2021-04-06)
-
 ### Added
 - `CryptographyClient` can perform AES-CBCPAD encryption and decryption locally
   ([#17762](https://github.com/Azure/azure-sdk-for-python/pull/17762))

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

@@ -3,24 +3,21 @@
 # Licensed under the MIT License.
 # -------------------------------------
 from ._enums import KeyCurveName, KeyOperation, KeyType
-from ._parse_id import parse_key_vault_key_id
 from ._shared.client_base import ApiVersion
-from ._shared import KeyVaultResourceId
-from ._models import DeletedKey, JsonWebKey, KeyProperties, KeyVaultKey
+from ._models import DeletedKey, JsonWebKey, KeyProperties, KeyVaultKey, KeyVaultKeyIdentifier
 from ._client import KeyClient
 
 __all__ = [
     "ApiVersion",
     "KeyClient",
     "JsonWebKey",
     "KeyVaultKey",
+    "KeyVaultKeyIdentifier",
     "KeyCurveName",
     "KeyOperation",
     "KeyType",
     "DeletedKey",
-    "KeyProperties",
-    "parse_key_vault_key_id",
-    "KeyVaultResourceId"
+    "KeyProperties"
 ]
 
 from ._version import VERSION

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

@@ -17,8 +17,7 @@
 
 if TYPE_CHECKING:
     # pylint:disable=unused-import
-    from typing import Any, List, Optional, Union
-    from datetime import datetime
+    from typing import Any, Optional, Union
     from azure.core.paging import ItemPaged
     from ._models import JsonWebKey
 
@@ -55,8 +54,8 @@ def create_key(self, name, key_type, **kwargs):
         :param str name: The name of the new key.
         :param key_type: The type of key to create
         :type key_type: ~azure.keyvault.keys.KeyType or str
-        :keyword int size: RSA key size in bits, for example 2048, 3072, or 4096. Applies only to RSA keys. To
-         create an RSA key, consider using :func:`create_rsa_key` instead.
+        :keyword int size: Key size in bits. Applies only to RSA and symmetric keys. Consider using
+         :func:`create_rsa_key` or :func:`create_oct_key` instead.
         :keyword curve: Elliptic curve name. Applies only to elliptic curve keys. Defaults to the NIST P-256
          elliptic curve. To create an elliptic curve key, consider using :func:`create_ec_key` instead.
         :paramtype curve: ~azure.keyvault.keys.KeyCurveName or str
@@ -175,6 +174,39 @@ def create_ec_key(self, name, **kwargs):
         hsm = kwargs.pop("hardware_protected", False)
         return self.create_key(name, key_type="EC-HSM" if hsm else "EC", **kwargs)
 
+    @distributed_trace
+    def create_oct_key(self, name, **kwargs):
+        # type: (str, **Any) -> KeyVaultKey
+        """Create a new octet sequence (symmetric) key or, if `name` is already in use, create a new version of the key.
+
+        Requires the keys/create permission.
+
+        :param str name: The name for the new key.
+        :keyword int size: Key size in bits, for example 128, 192, or 256.
+        :keyword key_operations: Allowed key operations.
+        :paramtype key_operations: list[~azure.keyvault.keys.KeyOperation or str]
+        :keyword bool hardware_protected: Whether the key should be created in a hardware security module.
+         Defaults to ``False``.
+        :keyword bool enabled: Whether the key is enabled for use.
+        :keyword tags: Application specific metadata in the form of key-value pairs.
+        :paramtype tags: dict[str, str]
+        :keyword ~datetime.datetime not_before: Not before date of the key in UTC
+        :keyword ~datetime.datetime expires_on: Expiry date of the key in UTC
+        :returns: The created key
+        :rtype: ~azure.keyvault.keys.KeyVaultKey
+        :raises: :class:`~azure.core.exceptions.HttpResponseError`
+
+        Example:
+            .. literalinclude:: ../tests/test_samples_keys.py
+                :start-after: [START create_oct_key]
+                :end-before: [END create_oct_key]
+                :language: python
+                :caption: Create an octet sequence (symmetric) key
+                :dedent: 8
+        """
+        hsm = kwargs.pop("hardware_protected", False)
+        return self.create_key(name, key_type="oct-HSM" if hsm else "oct", **kwargs)
+
     @distributed_trace
     def begin_delete_key(self, name, **kwargs):
         # type: (str, **Any) -> DeletedKey

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

@@ -68,7 +68,7 @@ def __init__(self, key_id, attributes=None, **kwargs):
         # type: (str, Optional[_models.KeyAttributes], **Any) -> None
         self._attributes = attributes
         self._id = key_id
-        self._vault_id = parse_key_vault_id(key_id)
+        self._vault_id = KeyVaultKeyIdentifier(key_id)
         self._managed = kwargs.get("managed", None)
         self._tags = kwargs.get("tags", None)
 
@@ -325,6 +325,45 @@ def key_operations(self):
         return self._key_material.key_ops  # pylint:disable=no-member
 
 
+class KeyVaultKeyIdentifier(object):
+    """Information about a KeyVaultKey parsed from a key ID.
+
+    :param str id: the full original identifier of a key
+    :raises ValueError: if the key ID is improperly formatted
+    Example:
+        .. literalinclude:: ../tests/test_parse_id.py
+            :start-after: [START parse_key_vault_key_id]
+            :end-before: [END parse_key_vault_key_id]
+            :language: python
+            :caption: Parse a key's ID
+            :dedent: 8
+    """
+
+    def __init__(self, id):  # pylint: disable=W0622
+        # type: (str) -> None
+        self._resource_id = parse_key_vault_id(id)
+
+    @property
+    def source_id(self):
+        # type: () -> str
+        return self._resource_id.source_id
+
+    @property
+    def vault_url(self):
+        # type: () -> str
+        return self._resource_id.vault_url
+
+    @property
+    def name(self):
+        # type: () -> str
+        return self._resource_id.name
+
+    @property
+    def version(self):
+        # type: () -> Optional[str]
+        return self._resource_id.version
+
+
 class DeletedKey(KeyVaultKey):
     """A deleted key's properties, cryptographic material and its deletion information. If soft-delete
     is enabled, returns information about its recovery as well."""

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

@@ -15,9 +15,8 @@
 
 if TYPE_CHECKING:
     # pylint:disable=ungrouped-imports
-    from datetime import datetime
     from azure.core.async_paging import AsyncItemPaged
-    from typing import Any, Optional, List, Union
+    from typing import Any, Optional, Union
     from .. import KeyType
 
 
@@ -53,8 +52,8 @@ async def create_key(self, name: str, key_type: "Union[str, KeyType]", **kwargs:
         :param str name: The name of the new key.
         :param key_type: The type of key to create
         :type key_type: ~azure.keyvault.keys.KeyType or str
-        :keyword int size: RSA key size in bits, for example 2048, 3072, or 4096. Applies only to RSA keys. To
-         create an RSA key, consider using :func:`create_rsa_key` instead.
+        :keyword int size: Key size in bits. Applies only to RSA and symmetric keys. Consider using
+         :func:`create_rsa_key` or :func:`create_oct_key` instead.
         :keyword curve: Elliptic curve name. Applies only to elliptic curve keys. Defaults to the NIST P-256
          elliptic curve. To create an elliptic curve key, consider using :func:`create_ec_key` instead.
         :paramtype curve: ~azure.keyvault.keys.KeyCurveName or str
@@ -172,6 +171,38 @@ async def create_ec_key(self, name: str, **kwargs: "Any") -> KeyVaultKey:
         hsm = kwargs.pop("hardware_protected", False)
         return await self.create_key(name, key_type="EC-HSM" if hsm else "EC", **kwargs)
 
+    @distributed_trace_async
+    async def create_oct_key(self, name: str, **kwargs: "Any") -> KeyVaultKey:
+        """Create a new octet sequence (symmetric) key or, if `name` is already in use, create a new version of the key.
+
+        Requires the keys/create permission.
+
+        :param str name: The name for the new key.
+        :keyword int size: Key size in bits, for example 128, 192, or 256.
+        :keyword key_operations: Allowed key operations.
+        :paramtype key_operations: list[~azure.keyvault.keys.KeyOperation or str]
+        :keyword bool hardware_protected: Whether the key should be created in a hardware security module.
+         Defaults to ``False``.
+        :keyword bool enabled: Whether the key is enabled for use.
+        :keyword tags: Application specific metadata in the form of key-value pairs.
+        :paramtype tags: dict[str, str]
+        :keyword ~datetime.datetime not_before: Not before date of the key in UTC
+        :keyword ~datetime.datetime expires_on: Expiry date of the key in UTC
+        :returns: The created key
+        :rtype: ~azure.keyvault.keys.KeyVaultKey
+        :raises: :class:`~azure.core.exceptions.HttpResponseError`
+
+        Example:
+            .. literalinclude:: ../tests/test_samples_keys_async.py
+                :start-after: [START create_oct_key]
+                :end-before: [END create_oct_key]
+                :language: python
+                :caption: Create an octet sequence (symmetric) key
+                :dedent: 8
+        """
+        hsm = kwargs.pop("hardware_protected", False)
+        return await self.create_key(name, key_type="oct-HSM" if hsm else "oct", **kwargs)
+
     @distributed_trace_async
     async def delete_key(self, name: str, **kwargs: "Any") -> DeletedKey:
         """Delete all versions of a key and its cryptographic material. Requires keys/delete permission.

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

@@ -47,6 +47,8 @@ def _validate_arguments(operation, algorithm, **kwargs):
             raise ValueError(
                 "iv should only be provided with AES-CBC algorithms; {} does not accept an iv".format(algorithm)
             )
+        if iv is None and "CBC" in algorithm:
+            raise ValueError("iv is a required parameter for encryption with AES-CBC algorithms.")
         if aad and not ("CBC" in algorithm or "GCM" in algorithm):
             raise ValueError(
                 "additional_authenticated_data should only be provided with AES algorithms; {} does not accept "
@@ -58,12 +60,16 @@ def _validate_arguments(operation, algorithm, **kwargs):
             raise ValueError(
                 "iv should only be provided with AES algorithms; {} does not accept an iv".format(algorithm)
             )
+        if iv is None and ("CBC" in algorithm or "GCM" in algorithm):
+            raise ValueError("iv is a required parameter for decryption with AES algorithms.")
         if tag and "GCM" not in algorithm:
             raise ValueError(
                 "authentication_tag should only be provided with AES-GCM algorithms; {} does not accept a tag".format(
                     algorithm
                 )
             )
+        if tag is None and "GCM" in algorithm:
+            raise ValueError("authentication_tag is a required parameter for AES-GCM decryption.")
         if aad and not ("CBC" in algorithm or "GCM" in algorithm):
             raise ValueError(
                 "additional_authenticated_data should only be provided with AES algorithms; {} does not accept "
@@ -211,7 +217,7 @@ def encrypt(self, algorithm, plaintext, **kwargs):
         :param algorithm: encryption algorithm to use
         :type algorithm: :class:`~azure.keyvault.keys.crypto.EncryptionAlgorithm`
         :param bytes plaintext: bytes to encrypt
-        :keyword bytes iv: optional initialization vector. For use with AES-CBC encryption.
+        :keyword bytes iv: initialization vector. Required for only AES-CBC(PAD) encryption.
         :keyword bytes additional_authenticated_data: optional data that is authenticated but not encrypted. For use
             with AES-GCM encryption.
         :rtype: :class:`~azure.keyvault.keys.crypto.EncryptResult`
@@ -269,11 +275,11 @@ def decrypt(self, algorithm, ciphertext, **kwargs):
         :param algorithm: encryption algorithm to use
         :type algorithm: :class:`~azure.keyvault.keys.crypto.EncryptionAlgorithm`
         :param bytes ciphertext: encrypted bytes to decrypt
-        :keyword bytes iv: the initialization vector used during encryption. For use with AES encryption.
-        :keyword bytes authentication_tag: the authentication tag generated during encryption. For use with AES-GCM
-            encryption.
+        :keyword bytes iv: the initialization vector used during encryption. Required for AES decryption.
+        :keyword bytes authentication_tag: the authentication tag generated during encryption. Required for only AES-GCM
+            decryption.
         :keyword bytes additional_authenticated_data: optional data that is authenticated but not encrypted. For use
-            with AES-GCM encryption.
+            with AES-GCM decryption.
         :rtype: :class:`~azure.keyvault.keys.crypto.DecryptResult`
         :raises ValueError: if parameters that are incompatible with the specified algorithm are provided.
 

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

@@ -160,7 +160,7 @@ async def encrypt(self, algorithm: "EncryptionAlgorithm", plaintext: bytes, **kw
         :param algorithm: encryption algorithm to use
         :type algorithm: :class:`~azure.keyvault.keys.crypto.EncryptionAlgorithm`
         :param bytes plaintext: bytes to encrypt
-        :keyword bytes iv: optional initialization vector. For use with AES-CBC encryption.
+        :keyword bytes iv: initialization vector. Required for only AES-CBC(PAD) encryption.
         :keyword bytes additional_authenticated_data: optional data that is authenticated but not encrypted. For use
             with AES-GCM encryption.
         :rtype: :class:`~azure.keyvault.keys.crypto.EncryptResult`
@@ -217,11 +217,11 @@ async def decrypt(self, algorithm: "EncryptionAlgorithm", ciphertext: bytes, **k
         :param algorithm: encryption algorithm to use
         :type algorithm: :class:`~azure.keyvault.keys.crypto.EncryptionAlgorithm`
         :param bytes ciphertext: encrypted bytes to decrypt
-        :keyword bytes iv: the initialization vector used during encryption. For use with AES encryption.
-        :keyword bytes authentication_tag: the authentication tag generated during encryption. For use with AES-GCM
-            encryption.
+        :keyword bytes iv: the initialization vector used during encryption. Required for AES decryption.
+        :keyword bytes authentication_tag: the authentication tag generated during encryption. Required for only AES-GCM
+            decryption.
         :keyword bytes additional_authenticated_data: optional data that is authenticated but not encrypted. For use
-            with AES-GCM encryption.
+            with AES-GCM decryption.
         :rtype: :class:`~azure.keyvault.keys.crypto.DecryptResult`
         :raises ValueError: if parameters that are incompatible with the specified algorithm are provided.