feat(kms): add ProtectionLevel.External enum; standardize use of 'o…

…ptional' and 'required' in docstrings (via synth) (#10070)

google/cloud/kms_v1/gapic/enums.py

@@ -29,11 +29,13 @@ class ProtectionLevel(enum.IntEnum):
       PROTECTION_LEVEL_UNSPECIFIED (int): Not specified.
       SOFTWARE (int): Crypto operations are performed in software.
       HSM (int): Crypto operations are performed in a Hardware Security Module.
+      EXTERNAL (int): Crypto operations are performed by an external key manager.
     """
 
     PROTECTION_LEVEL_UNSPECIFIED = 0
     SOFTWARE = 1
     HSM = 2
+    EXTERNAL = 3
 
 
 class CryptoKey(object):

google/cloud/kms_v1/gapic/key_management_service_client.py

@@ -58,6 +58,7 @@ class KeyManagementServiceClient(object):
     -  ``KeyRing``
     -  ``CryptoKey``
     -  ``CryptoKeyVersion``
+    -  ``ImportJob``
 
     If you are using manual gRPC libraries, see `Using gRPC with Cloud
     KMS <https://cloud.google.com/kms/docs/grpc>`__.
@@ -312,8 +313,12 @@ def list_key_rings(
                 streaming is performed per-page, this determines the maximum number
                 of resources in a page.
             filter_ (str): Optional. Only include resources that match the filter in the response.
-            order_by (str): Optional. Specify how the results should be sorted. If not specified, the
-                results will be sorted in the default order.
+                For more information, see `Sorting and filtering list
+                results <https://cloud.google.com/kms/docs/sorting-and-filtering>`__.
+            order_by (str): Optional. Specify how the results should be sorted. If not specified,
+                the results will be sorted in the default order. For more information,
+                see `Sorting and filtering list
+                results <https://cloud.google.com/kms/docs/sorting-and-filtering>`__.
             retry (Optional[google.api_core.retry.Retry]):  A retry object used
                 to retry requests. If ``None`` is specified, requests will
                 be retried using a default configuration.
@@ -421,8 +426,12 @@ def list_import_jobs(
                 streaming is performed per-page, this determines the maximum number
                 of resources in a page.
             filter_ (str): Optional. Only include resources that match the filter in the response.
-            order_by (str): Optional. Specify how the results should be sorted. If not specified, the
-                results will be sorted in the default order.
+                For more information, see `Sorting and filtering list
+                results <https://cloud.google.com/kms/docs/sorting-and-filtering>`__.
+            order_by (str): Optional. Specify how the results should be sorted. If not specified,
+                the results will be sorted in the default order. For more information,
+                see `Sorting and filtering list
+                results <https://cloud.google.com/kms/docs/sorting-and-filtering>`__.
             retry (Optional[google.api_core.retry.Retry]):  A retry object used
                 to retry requests. If ``None`` is specified, requests will
                 be retried using a default configuration.
@@ -532,8 +541,12 @@ def list_crypto_keys(
                 of resources in a page.
             version_view (~google.cloud.kms_v1.types.CryptoKeyVersionView): The fields of the primary version to include in the response.
             filter_ (str): Optional. Only include resources that match the filter in the response.
-            order_by (str): Optional. Specify how the results should be sorted. If not specified, the
-                results will be sorted in the default order.
+                For more information, see `Sorting and filtering list
+                results <https://cloud.google.com/kms/docs/sorting-and-filtering>`__.
+            order_by (str): Optional. Specify how the results should be sorted. If not specified,
+                the results will be sorted in the default order. For more information,
+                see `Sorting and filtering list
+                results <https://cloud.google.com/kms/docs/sorting-and-filtering>`__.
             retry (Optional[google.api_core.retry.Retry]):  A retry object used
                 to retry requests. If ``None`` is specified, requests will
                 be retried using a default configuration.
@@ -647,8 +660,12 @@ def list_crypto_key_versions(
                 of resources in a page.
             view (~google.cloud.kms_v1.types.CryptoKeyVersionView): The fields to include in the response.
             filter_ (str): Optional. Only include resources that match the filter in the response.
-            order_by (str): Optional. Specify how the results should be sorted. If not specified, the
-                results will be sorted in the default order.
+                For more information, see `Sorting and filtering list
+                results <https://cloud.google.com/kms/docs/sorting-and-filtering>`__.
+            order_by (str): Optional. Specify how the results should be sorted. If not specified,
+                the results will be sorted in the default order. For more information,
+                see `Sorting and filtering list
+                results <https://cloud.google.com/kms/docs/sorting-and-filtering>`__.
             retry (Optional[google.api_core.retry.Retry]):  A retry object used
                 to retry requests. If ``None`` is specified, requests will
                 be retried using a default configuration.
@@ -737,7 +754,7 @@ def get_key_ring(
             >>> response = client.get_key_ring(name)
 
         Args:
-            name (str): The ``name`` of the ``KeyRing`` to get.
+            name (str): Required. The ``name`` of the ``KeyRing`` to get.
             retry (Optional[google.api_core.retry.Retry]):  A retry object used
                 to retry requests. If ``None`` is specified, requests will
                 be retried using a default configuration.
@@ -806,7 +823,7 @@ def get_import_job(
             >>> response = client.get_import_job(name)
 
         Args:
-            name (str): The ``name`` of the ``ImportJob`` to get.
+            name (str): Required. The ``name`` of the ``ImportJob`` to get.
             retry (Optional[google.api_core.retry.Retry]):  A retry object used
                 to retry requests. If ``None`` is specified, requests will
                 be retried using a default configuration.
@@ -876,7 +893,7 @@ def get_crypto_key(
             >>> response = client.get_crypto_key(name)
 
         Args:
-            name (str): The ``name`` of the ``CryptoKey`` to get.
+            name (str): Required. The ``name`` of the ``CryptoKey`` to get.
             retry (Optional[google.api_core.retry.Retry]):  A retry object used
                 to retry requests. If ``None`` is specified, requests will
                 be retried using a default configuration.
@@ -945,7 +962,7 @@ def get_crypto_key_version(
             >>> response = client.get_crypto_key_version(name)
 
         Args:
-            name (str): The ``name`` of the ``CryptoKeyVersion`` to get.
+            name (str): Required. The ``name`` of the ``CryptoKeyVersion`` to get.
             retry (Optional[google.api_core.retry.Retry]):  A retry object used
                 to retry requests. If ``None`` is specified, requests will
                 be retried using a default configuration.
@@ -1026,7 +1043,7 @@ def create_key_ring(
                 ``KeyRings``, in the format ``projects/*/locations/*``.
             key_ring_id (str): Required. It must be unique within a location and match the regular
                 expression ``[a-zA-Z0-9_-]{1,63}``
-            key_ring (Union[dict, ~google.cloud.kms_v1.types.KeyRing]): A ``KeyRing`` with initial field values.
+            key_ring (Union[dict, ~google.cloud.kms_v1.types.KeyRing]): Required. A ``KeyRing`` with initial field values.
 
                 If a dict is provided, it must be of the same form as the protobuf
                 message :class:`~google.cloud.kms_v1.types.KeyRing`
@@ -1205,7 +1222,7 @@ def create_crypto_key(
                 ``CryptoKeys``.
             crypto_key_id (str): Required. It must be unique within a KeyRing and match the regular
                 expression ``[a-zA-Z0-9_-]{1,63}``
-            crypto_key (Union[dict, ~google.cloud.kms_v1.types.CryptoKey]): A ``CryptoKey`` with initial field values.
+            crypto_key (Union[dict, ~google.cloud.kms_v1.types.CryptoKey]): Required. A ``CryptoKey`` with initial field values.
 
                 If a dict is provided, it must be of the same form as the protobuf
                 message :class:`~google.cloud.kms_v1.types.CryptoKey`
@@ -1294,7 +1311,7 @@ def create_crypto_key_version(
         Args:
             parent (str): Required. The ``name`` of the ``CryptoKey`` associated with the
                 ``CryptoKeyVersions``.
-            crypto_key_version (Union[dict, ~google.cloud.kms_v1.types.CryptoKeyVersion]): A ``CryptoKeyVersion`` with initial field values.
+            crypto_key_version (Union[dict, ~google.cloud.kms_v1.types.CryptoKeyVersion]): Required. A ``CryptoKeyVersion`` with initial field values.
 
                 If a dict is provided, it must be of the same form as the protobuf
                 message :class:`~google.cloud.kms_v1.types.CryptoKeyVersion`
@@ -1405,6 +1422,11 @@ def import_crypto_key_version(
                       </li>
                     </ol>
 
+                If importing symmetric key material, it is expected that the unwrapped
+                key contains plain bytes. If importing asymmetric key material, it is
+                expected that the unwrapped key is in PKCS#8-encoded DER format (the
+                PrivateKeyInfo structure from RFC 5208).
+
                 This format is the same as the format produced by PKCS#11 mechanism
                 CKM\_RSA\_AES\_KEY\_WRAP.
             retry (Optional[google.api_core.retry.Retry]):  A retry object used
@@ -1491,11 +1513,11 @@ def update_crypto_key(
             >>> response = client.update_crypto_key(crypto_key, update_mask)
 
         Args:
-            crypto_key (Union[dict, ~google.cloud.kms_v1.types.CryptoKey]): ``CryptoKey`` with updated values.
+            crypto_key (Union[dict, ~google.cloud.kms_v1.types.CryptoKey]): Required. ``CryptoKey`` with updated values.
 
                 If a dict is provided, it must be of the same form as the protobuf
                 message :class:`~google.cloud.kms_v1.types.CryptoKey`
-            update_mask (Union[dict, ~google.cloud.kms_v1.types.FieldMask]): Required list of fields to be updated in this request.
+            update_mask (Union[dict, ~google.cloud.kms_v1.types.FieldMask]): Required. List of fields to be updated in this request.
 
                 If a dict is provided, it must be of the same form as the protobuf
                 message :class:`~google.cloud.kms_v1.types.FieldMask`
@@ -1578,11 +1600,11 @@ def update_crypto_key_version(
             >>> response = client.update_crypto_key_version(crypto_key_version, update_mask)
 
         Args:
-            crypto_key_version (Union[dict, ~google.cloud.kms_v1.types.CryptoKeyVersion]): ``CryptoKeyVersion`` with updated values.
+            crypto_key_version (Union[dict, ~google.cloud.kms_v1.types.CryptoKeyVersion]): Required. ``CryptoKeyVersion`` with updated values.
 
                 If a dict is provided, it must be of the same form as the protobuf
                 message :class:`~google.cloud.kms_v1.types.CryptoKeyVersion`
-            update_mask (Union[dict, ~google.cloud.kms_v1.types.FieldMask]): Required list of fields to be updated in this request.
+            update_mask (Union[dict, ~google.cloud.kms_v1.types.FieldMask]): Required. List of fields to be updated in this request.
 
                 If a dict is provided, it must be of the same form as the protobuf
                 message :class:`~google.cloud.kms_v1.types.FieldMask`
@@ -1673,7 +1695,7 @@ def encrypt(
                 ``SOFTWARE`` keys, the plaintext must be no larger than 64KiB. For
                 ``HSM`` keys, the combined length of the plaintext and
                 additional\_authenticated\_data fields must be no larger than 8KiB.
-            additional_authenticated_data (bytes): Optional data that, if specified, must also be provided during
+            additional_authenticated_data (bytes): Optional. Optional data that, if specified, must also be provided during
                 decryption through ``DecryptRequest.additional_authenticated_data``.
 
                 The maximum size depends on the key version's ``protection_level``. For
@@ -1762,7 +1784,7 @@ def decrypt(
                 The server will choose the appropriate version.
             ciphertext (bytes): Required. The encrypted data originally returned in
                 ``EncryptResponse.ciphertext``.
-            additional_authenticated_data (bytes): Optional data that must match the data originally supplied in
+            additional_authenticated_data (bytes): Optional. Optional data that must match the data originally supplied in
                 ``EncryptRequest.additional_authenticated_data``.
             retry (Optional[google.api_core.retry.Retry]):  A retry object used
                 to retry requests. If ``None`` is specified, requests will
@@ -1842,8 +1864,8 @@ def update_crypto_key_primary_version(
             >>> response = client.update_crypto_key_primary_version(name, crypto_key_version_id)
 
         Args:
-            name (str): The resource name of the ``CryptoKey`` to update.
-            crypto_key_version_id (str): The id of the child ``CryptoKeyVersion`` to use as primary.
+            name (str): Required. The resource name of the ``CryptoKey`` to update.
+            crypto_key_version_id (str): Required. The id of the child ``CryptoKeyVersion`` to use as primary.
             retry (Optional[google.api_core.retry.Retry]):  A retry object used
                 to retry requests. If ``None`` is specified, requests will
                 be retried using a default configuration.
@@ -1926,7 +1948,7 @@ def destroy_crypto_key_version(
             >>> response = client.destroy_crypto_key_version(name)
 
         Args:
-            name (str): The resource name of the ``CryptoKeyVersion`` to destroy.
+            name (str): Required. The resource name of the ``CryptoKeyVersion`` to destroy.
             retry (Optional[google.api_core.retry.Retry]):  A retry object used
                 to retry requests. If ``None`` is specified, requests will
                 be retried using a default configuration.
@@ -1998,7 +2020,7 @@ def restore_crypto_key_version(
             >>> response = client.restore_crypto_key_version(name)
 
         Args:
-            name (str): The resource name of the ``CryptoKeyVersion`` to restore.
+            name (str): Required. The resource name of the ``CryptoKeyVersion`` to restore.
             retry (Optional[google.api_core.retry.Retry]):  A retry object used
                 to retry requests. If ``None`` is specified, requests will
                 be retried using a default configuration.
@@ -2069,7 +2091,7 @@ def get_public_key(
             >>> response = client.get_public_key(name)
 
         Args:
-            name (str): The ``name`` of the ``CryptoKeyVersion`` public key to get.
+            name (str): Required. The ``name`` of the ``CryptoKeyVersion`` public key to get.
             retry (Optional[google.api_core.retry.Retry]):  A retry object used
                 to retry requests. If ``None`` is specified, requests will
                 be retried using a default configuration.
@@ -2290,6 +2312,9 @@ def set_iam_policy(
         Sets the access control policy on the specified resource. Replaces
         any existing policy.
 
+        Can return Public Errors: NOT_FOUND, INVALID_ARGUMENT and
+        PERMISSION_DENIED
+
         Example:
             >>> from google.cloud import kms_v1
             >>>

google/cloud/kms_v1/gapic/transports/key_management_service_grpc_transport.py

@@ -458,6 +458,9 @@ def set_iam_policy(self):
         Sets the access control policy on the specified resource. Replaces
         any existing policy.
 
+        Can return Public Errors: NOT_FOUND, INVALID_ARGUMENT and
+        PERMISSION_DENIED
+
         Returns:
             Callable: A callable which accepts the appropriate
                 deserialized request object and returns a