Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat(kms): add ProtectionLevel.External enum; standardize use of 'optional' and 'required' in docstrings (via synth) #10070

Merged
merged 1 commit into from
Jan 29, 2020
Merged

feat(kms): add ProtectionLevel.External enum; standardize use of 'optional' and 'required' in docstrings (via synth) #10070

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions kms/google/cloud/kms_v1/gapic/enums.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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):
Expand Down
77 changes: 51 additions & 26 deletions kms/google/cloud/kms_v1/gapic/key_management_service_client.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>`__.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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`
Expand Down Expand Up @@ -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`
Expand Down Expand Up @@ -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`
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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`
Expand Down Expand Up @@ -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`
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
>>>
Expand Down
3 changes: 3 additions & 0 deletions kms/google/cloud/kms_v1/gapic/transports/key_management_service_grpc_transport.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading