Client for Cloud Key Management Service (KMS) API#
-
class
google.cloud.kms_v1.
KeyManagementServiceClient
(transport=None, channel=None, credentials=None, client_config=None, client_info=None, client_options=None)[source]# Google Cloud Key Management Service
Manages cryptographic keys and operations using those keys. Implements a REST model with the following objects:
KeyRing
CryptoKey
CryptoKeyVersion
If you are using manual gRPC libraries, see Using gRPC with Cloud KMS.
Constructor.
- Parameters
(Union[KeyManagementServiceGrpcTransport, (transport) – Callable[[~.Credentials, type], ~.KeyManagementServiceGrpcTransport]): A transport instance, responsible for actually making the API calls. The default transport uses the gRPC protocol. This argument may also be a callable which returns a transport instance. Callables will be sent the credentials as the first argument and the default transport class as the second argument.
channel (grpc.Channel) – DEPRECATED. A
Channel
instance through which to make calls. This argument is mutually exclusive withcredentials
; providing both will raise an exception.credentials (google.auth.credentials.Credentials) – The authorization credentials to attach to requests. These credentials identify this application to the service. If none are specified, the client will attempt to ascertain the credentials from the environment. This argument is mutually exclusive with providing a transport instance to
transport
; doing so will raise an exception.client_config (dict) – DEPRECATED. A dictionary of call options for each method. If not specified, the default configuration is used.
client_info (google.api_core.gapic_v1.client_info.ClientInfo) – The client info used to send a user-agent string along with API requests. If
None
, then default info will be used. Generally, you only need to set this if you’re developing your own client library.client_options (Union[dict, google.api_core.client_options.ClientOptions]) – Client options used to set user options on the client. API Endpoint should be set through client_options.
-
asymmetric_decrypt
(name, ciphertext, retry=<object object>, timeout=<object object>, metadata=None)[source]# Decrypts data that was encrypted with a public key retrieved from
GetPublicKey
corresponding to aCryptoKeyVersion
withCryptoKey.purpose
ASYMMETRIC_DECRYPT.Example
>>> from google.cloud import kms_v1 >>> >>> client = kms_v1.KeyManagementServiceClient() >>> >>> name = client.crypto_key_version_path('[PROJECT]', '[LOCATION]', '[KEY_RING]', '[CRYPTO_KEY]', '[CRYPTO_KEY_VERSION]') >>> >>> # TODO: Initialize `ciphertext`: >>> ciphertext = b'' >>> >>> response = client.asymmetric_decrypt(name, ciphertext)
- Parameters
name (str) – Required. The resource name of the
CryptoKeyVersion
to use for decryption.ciphertext (bytes) – Required. The data encrypted with the named
CryptoKeyVersion
’s public key using OAEP.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.timeout (Optional[float]) – The amount of time, in seconds, to wait for the request to complete. Note that if
retry
is specified, the timeout applies to each individual attempt.metadata (Optional[Sequence[Tuple[str, str]]]) – Additional metadata that is provided to the method.
- Returns
A
AsymmetricDecryptResponse
instance.- Raises
google.api_core.exceptions.GoogleAPICallError – If the request failed for any reason.
google.api_core.exceptions.RetryError – If the request failed due to a retryable error and retry attempts failed.
ValueError – If the parameters are invalid.
-
asymmetric_sign
(name, digest, retry=<object object>, timeout=<object object>, metadata=None)[source]# Signs data using a
CryptoKeyVersion
withCryptoKey.purpose
ASYMMETRIC_SIGN, producing a signature that can be verified with the public key retrieved fromGetPublicKey
.Example
>>> from google.cloud import kms_v1 >>> >>> client = kms_v1.KeyManagementServiceClient() >>> >>> name = client.crypto_key_version_path('[PROJECT]', '[LOCATION]', '[KEY_RING]', '[CRYPTO_KEY]', '[CRYPTO_KEY_VERSION]') >>> >>> # TODO: Initialize `digest`: >>> digest = {} >>> >>> response = client.asymmetric_sign(name, digest)
- Parameters
name (str) – Required. The resource name of the
CryptoKeyVersion
to use for signing.digest (Union[dict, Digest]) –
Required. The digest of the data to sign. The digest must be produced with the same digest algorithm as specified by the key version’s
algorithm
.If a dict is provided, it must be of the same form as the protobuf message
Digest
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.timeout (Optional[float]) – The amount of time, in seconds, to wait for the request to complete. Note that if
retry
is specified, the timeout applies to each individual attempt.metadata (Optional[Sequence[Tuple[str, str]]]) – Additional metadata that is provided to the method.
- Returns
A
AsymmetricSignResponse
instance.- Raises
google.api_core.exceptions.GoogleAPICallError – If the request failed for any reason.
google.api_core.exceptions.RetryError – If the request failed due to a retryable error and retry attempts failed.
ValueError – If the parameters are invalid.
-
create_crypto_key
(parent, crypto_key_id, crypto_key, skip_initial_version_creation=None, retry=<object object>, timeout=<object object>, metadata=None)[source]# Create a new
CryptoKey
within aKeyRing
.CryptoKey.purpose
andCryptoKey.version_template.algorithm
are required.Example
>>> from google.cloud import kms_v1 >>> from google.cloud.kms_v1 import enums >>> >>> client = kms_v1.KeyManagementServiceClient() >>> >>> parent = client.key_ring_path('[PROJECT]', '[LOCATION]', '[KEY_RING]') >>> crypto_key_id = 'my-app-key' >>> purpose = enums.CryptoKey.CryptoKeyPurpose.ENCRYPT_DECRYPT >>> seconds = 2147483647 >>> next_rotation_time = {'seconds': seconds} >>> seconds_2 = 604800 >>> rotation_period = {'seconds': seconds_2} >>> crypto_key = {'purpose': purpose, 'next_rotation_time': next_rotation_time, 'rotation_period': rotation_period} >>> >>> response = client.create_crypto_key(parent, crypto_key_id, crypto_key)
- Parameters
parent (str) – Required. The
name
of the KeyRing associated with theCryptoKeys
.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, CryptoKey]) –
A
CryptoKey
with initial field values.If a dict is provided, it must be of the same form as the protobuf message
CryptoKey
skip_initial_version_creation (bool) – If set to true, the request will create a
CryptoKey
without anyCryptoKeyVersions
. You must manually callCreateCryptoKeyVersion
orImportCryptoKeyVersion
before you can use thisCryptoKey
.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.timeout (Optional[float]) – The amount of time, in seconds, to wait for the request to complete. Note that if
retry
is specified, the timeout applies to each individual attempt.metadata (Optional[Sequence[Tuple[str, str]]]) – Additional metadata that is provided to the method.
- Returns
A
CryptoKey
instance.- Raises
google.api_core.exceptions.GoogleAPICallError – If the request failed for any reason.
google.api_core.exceptions.RetryError – If the request failed due to a retryable error and retry attempts failed.
ValueError – If the parameters are invalid.
-
create_crypto_key_version
(parent, crypto_key_version, retry=<object object>, timeout=<object object>, metadata=None)[source]# Create a new
CryptoKeyVersion
in aCryptoKey
.The server will assign the next sequential id. If unset,
state
will be set toENABLED
.Example
>>> from google.cloud import kms_v1 >>> >>> client = kms_v1.KeyManagementServiceClient() >>> >>> parent = client.crypto_key_path('[PROJECT]', '[LOCATION]', '[KEY_RING]', '[CRYPTO_KEY]') >>> >>> # TODO: Initialize `crypto_key_version`: >>> crypto_key_version = {} >>> >>> response = client.create_crypto_key_version(parent, crypto_key_version)
- Parameters
parent (str) – Required. The
name
of theCryptoKey
associated with theCryptoKeyVersions
.crypto_key_version (Union[dict, CryptoKeyVersion]) –
A
CryptoKeyVersion
with initial field values.If a dict is provided, it must be of the same form as the protobuf message
CryptoKeyVersion
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.timeout (Optional[float]) – The amount of time, in seconds, to wait for the request to complete. Note that if
retry
is specified, the timeout applies to each individual attempt.metadata (Optional[Sequence[Tuple[str, str]]]) – Additional metadata that is provided to the method.
- Returns
A
CryptoKeyVersion
instance.- Raises
google.api_core.exceptions.GoogleAPICallError – If the request failed for any reason.
google.api_core.exceptions.RetryError – If the request failed due to a retryable error and retry attempts failed.
ValueError – If the parameters are invalid.
-
create_import_job
(parent, import_job_id, import_job, retry=<object object>, timeout=<object object>, metadata=None)[source]# Create a new
ImportJob
within aKeyRing
.ImportJob.import_method
is required.Example
>>> from google.cloud import kms_v1 >>> from google.cloud.kms_v1 import enums >>> >>> client = kms_v1.KeyManagementServiceClient() >>> >>> parent = client.key_ring_path('[PROJECT]', '[LOCATION]', '[KEY_RING]') >>> import_job_id = 'my-import-job' >>> import_method = enums.ImportJob.ImportMethod.RSA_OAEP_3072_SHA1_AES_256 >>> protection_level = enums.ProtectionLevel.HSM >>> import_job = {'import_method': import_method, 'protection_level': protection_level} >>> >>> response = client.create_import_job(parent, import_job_id, import_job)
- Parameters
parent (str) – Required. The
name
of theKeyRing
associated with theImportJobs
.import_job_id (str) – Required. It must be unique within a KeyRing and match the regular expression
[a-zA-Z0-9_-]{1,63}
import_job (Union[dict, ImportJob]) –
Required. An
ImportJob
with initial field values.If a dict is provided, it must be of the same form as the protobuf message
ImportJob
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.timeout (Optional[float]) – The amount of time, in seconds, to wait for the request to complete. Note that if
retry
is specified, the timeout applies to each individual attempt.metadata (Optional[Sequence[Tuple[str, str]]]) – Additional metadata that is provided to the method.
- Returns
A
ImportJob
instance.- Raises
google.api_core.exceptions.GoogleAPICallError – If the request failed for any reason.
google.api_core.exceptions.RetryError – If the request failed due to a retryable error and retry attempts failed.
ValueError – If the parameters are invalid.
-
create_key_ring
(parent, key_ring_id, key_ring, retry=<object object>, timeout=<object object>, metadata=None)[source]# Create a new
KeyRing
in a given Project and Location.Example
>>> from google.cloud import kms_v1 >>> >>> client = kms_v1.KeyManagementServiceClient() >>> >>> parent = client.location_path('[PROJECT]', '[LOCATION]') >>> >>> # TODO: Initialize `key_ring_id`: >>> key_ring_id = '' >>> >>> # TODO: Initialize `key_ring`: >>> key_ring = {} >>> >>> response = client.create_key_ring(parent, key_ring_id, key_ring)
- Parameters
parent (str) – Required. The resource name of the location associated with the
KeyRings
, in the formatprojects/*/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, KeyRing]) –
A
KeyRing
with initial field values.If a dict is provided, it must be of the same form as the protobuf message
KeyRing
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.timeout (Optional[float]) – The amount of time, in seconds, to wait for the request to complete. Note that if
retry
is specified, the timeout applies to each individual attempt.metadata (Optional[Sequence[Tuple[str, str]]]) – Additional metadata that is provided to the method.
- Returns
A
KeyRing
instance.- Raises
google.api_core.exceptions.GoogleAPICallError – If the request failed for any reason.
google.api_core.exceptions.RetryError – If the request failed due to a retryable error and retry attempts failed.
ValueError – If the parameters are invalid.
-
classmethod
crypto_key_path
(project, location, key_ring, crypto_key)[source]# Return a fully-qualified crypto_key string.
-
classmethod
crypto_key_path_path
(project, location, key_ring, crypto_key_path)[source]# Return a fully-qualified crypto_key_path string.
-
classmethod
crypto_key_version_path
(project, location, key_ring, crypto_key, crypto_key_version)[source]# Return a fully-qualified crypto_key_version string.
-
decrypt
(name, ciphertext, additional_authenticated_data=None, retry=<object object>, timeout=<object object>, metadata=None)[source]# Decrypts data that was protected by
Encrypt
. TheCryptoKey.purpose
must beENCRYPT_DECRYPT
.Example
>>> from google.cloud import kms_v1 >>> >>> client = kms_v1.KeyManagementServiceClient() >>> >>> name = client.crypto_key_path('[PROJECT]', '[LOCATION]', '[KEY_RING]', '[CRYPTO_KEY]') >>> >>> # TODO: Initialize `ciphertext`: >>> ciphertext = b'' >>> >>> response = client.decrypt(name, ciphertext)
- Parameters
name (str) – Required. The resource name of the
CryptoKey
to use for decryption. 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
EncryptRequest.additional_authenticated_data
.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.timeout (Optional[float]) – The amount of time, in seconds, to wait for the request to complete. Note that if
retry
is specified, the timeout applies to each individual attempt.metadata (Optional[Sequence[Tuple[str, str]]]) – Additional metadata that is provided to the method.
- Returns
A
DecryptResponse
instance.- Raises
google.api_core.exceptions.GoogleAPICallError – If the request failed for any reason.
google.api_core.exceptions.RetryError – If the request failed due to a retryable error and retry attempts failed.
ValueError – If the parameters are invalid.
-
destroy_crypto_key_version
(name, retry=<object object>, timeout=<object object>, metadata=None)[source]# Schedule a
CryptoKeyVersion
for destruction.Upon calling this method,
CryptoKeyVersion.state
will be set toDESTROY_SCHEDULED
anddestroy_time
will be set to a time 24 hours in the future, at which point thestate
will be changed toDESTROYED
, and the key material will be irrevocably destroyed.Before the
destroy_time
is reached,RestoreCryptoKeyVersion
may be called to reverse the process.Example
>>> from google.cloud import kms_v1 >>> >>> client = kms_v1.KeyManagementServiceClient() >>> >>> name = client.crypto_key_version_path('[PROJECT]', '[LOCATION]', '[KEY_RING]', '[CRYPTO_KEY]', '[CRYPTO_KEY_VERSION]') >>> >>> response = client.destroy_crypto_key_version(name)
- Parameters
name (str) – 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.timeout (Optional[float]) – The amount of time, in seconds, to wait for the request to complete. Note that if
retry
is specified, the timeout applies to each individual attempt.metadata (Optional[Sequence[Tuple[str, str]]]) – Additional metadata that is provided to the method.
- Returns
A
CryptoKeyVersion
instance.- Raises
google.api_core.exceptions.GoogleAPICallError – If the request failed for any reason.
google.api_core.exceptions.RetryError – If the request failed due to a retryable error and retry attempts failed.
ValueError – If the parameters are invalid.
-
encrypt
(name, plaintext, additional_authenticated_data=None, retry=<object object>, timeout=<object object>, metadata=None)[source]# Encrypts data, so that it can only be recovered by a call to
Decrypt
. TheCryptoKey.purpose
must beENCRYPT_DECRYPT
.Example
>>> from google.cloud import kms_v1 >>> >>> client = kms_v1.KeyManagementServiceClient() >>> >>> name = client.crypto_key_path_path('[PROJECT]', '[LOCATION]', '[KEY_RING]', '[CRYPTO_KEY_PATH]') >>> >>> # TODO: Initialize `plaintext`: >>> plaintext = b'' >>> >>> response = client.encrypt(name, plaintext)
- Parameters
name (str) –
Required. The resource name of the
CryptoKey
orCryptoKeyVersion
to use for encryption.If a
CryptoKey
is specified, the server will use itsprimary version
.plaintext (bytes) –
Required. The data to encrypt. Must be no larger than 64KiB.
The maximum size depends on the key version’s
protection_level
. ForSOFTWARE
keys, the plaintext must be no larger than 64KiB. ForHSM
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 decryption through
DecryptRequest.additional_authenticated_data
.The maximum size depends on the key version’s
protection_level
. ForSOFTWARE
keys, the AAD must be no larger than 64KiB. ForHSM
keys, the combined length of the plaintext and additional_authenticated_data fields must be no larger than 8KiB.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.timeout (Optional[float]) – The amount of time, in seconds, to wait for the request to complete. Note that if
retry
is specified, the timeout applies to each individual attempt.metadata (Optional[Sequence[Tuple[str, str]]]) – Additional metadata that is provided to the method.
- Returns
A
EncryptResponse
instance.- Raises
google.api_core.exceptions.GoogleAPICallError – If the request failed for any reason.
google.api_core.exceptions.RetryError – If the request failed due to a retryable error and retry attempts failed.
ValueError – If the parameters are invalid.
-
enums
= <module 'google.cloud.kms_v1.gapic.enums' from '/usr/local/lib/python3.7/site-packages/google/cloud/kms_v1/gapic/enums.py'>#
-
classmethod
from_service_account_file
(filename, *args, **kwargs)[source]# Creates an instance of this client using the provided credentials file.
- Parameters
filename (str) – The path to the service account private key json file.
args – Additional arguments to pass to the constructor.
kwargs – Additional arguments to pass to the constructor.
- Returns
The constructed client.
- Return type
-
classmethod
from_service_account_json
(filename, *args, **kwargs)# Creates an instance of this client using the provided credentials file.
- Parameters
filename (str) – The path to the service account private key json file.
args – Additional arguments to pass to the constructor.
kwargs – Additional arguments to pass to the constructor.
- Returns
The constructed client.
- Return type
-
get_crypto_key
(name, retry=<object object>, timeout=<object object>, metadata=None)[source]# Returns metadata for a given
CryptoKey
, as well as itsprimary
CryptoKeyVersion
.Example
>>> from google.cloud import kms_v1 >>> >>> client = kms_v1.KeyManagementServiceClient() >>> >>> name = client.crypto_key_path('[PROJECT]', '[LOCATION]', '[KEY_RING]', '[CRYPTO_KEY]') >>> >>> response = client.get_crypto_key(name)
- Parameters
name (str) – The
name
of theCryptoKey
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.timeout (Optional[float]) – The amount of time, in seconds, to wait for the request to complete. Note that if
retry
is specified, the timeout applies to each individual attempt.metadata (Optional[Sequence[Tuple[str, str]]]) – Additional metadata that is provided to the method.
- Returns
A
CryptoKey
instance.- Raises
google.api_core.exceptions.GoogleAPICallError – If the request failed for any reason.
google.api_core.exceptions.RetryError – If the request failed due to a retryable error and retry attempts failed.
ValueError – If the parameters are invalid.
-
get_crypto_key_version
(name, retry=<object object>, timeout=<object object>, metadata=None)[source]# Returns metadata for a given
CryptoKeyVersion
.Example
>>> from google.cloud import kms_v1 >>> >>> client = kms_v1.KeyManagementServiceClient() >>> >>> name = client.crypto_key_version_path('[PROJECT]', '[LOCATION]', '[KEY_RING]', '[CRYPTO_KEY]', '[CRYPTO_KEY_VERSION]') >>> >>> response = client.get_crypto_key_version(name)
- Parameters
name (str) – The
name
of theCryptoKeyVersion
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.timeout (Optional[float]) – The amount of time, in seconds, to wait for the request to complete. Note that if
retry
is specified, the timeout applies to each individual attempt.metadata (Optional[Sequence[Tuple[str, str]]]) – Additional metadata that is provided to the method.
- Returns
A
CryptoKeyVersion
instance.- Raises
google.api_core.exceptions.GoogleAPICallError – If the request failed for any reason.
google.api_core.exceptions.RetryError – If the request failed due to a retryable error and retry attempts failed.
ValueError – If the parameters are invalid.
-
get_iam_policy
(resource, options_=None, retry=<object object>, timeout=<object object>, metadata=None)[source]# Gets the access control policy for a resource. Returns an empty policy if the resource exists and does not have a policy set.
Example
>>> from google.cloud import kms_v1 >>> >>> client = kms_v1.KeyManagementServiceClient() >>> >>> resource = client.key_ring_path('[PROJECT]', '[LOCATION]', '[KEY_RING]') >>> >>> response = client.get_iam_policy(resource)
- Parameters
resource (str) – REQUIRED: The resource for which the policy is being requested. See the operation documentation for the appropriate value for this field.
options_ (Union[dict, GetPolicyOptions]) –
OPTIONAL: A
GetPolicyOptions
object for specifying options toGetIamPolicy
. This field is only used by Cloud IAM.If a dict is provided, it must be of the same form as the protobuf message
GetPolicyOptions
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.timeout (Optional[float]) – The amount of time, in seconds, to wait for the request to complete. Note that if
retry
is specified, the timeout applies to each individual attempt.metadata (Optional[Sequence[Tuple[str, str]]]) – Additional metadata that is provided to the method.
- Returns
A
Policy
instance.- Raises
google.api_core.exceptions.GoogleAPICallError – If the request failed for any reason.
google.api_core.exceptions.RetryError – If the request failed due to a retryable error and retry attempts failed.
ValueError – If the parameters are invalid.
-
get_import_job
(name, retry=<object object>, timeout=<object object>, metadata=None)[source]# Returns metadata for a given
ImportJob
.Example
>>> from google.cloud import kms_v1 >>> >>> client = kms_v1.KeyManagementServiceClient() >>> >>> name = client.import_job_path('[PROJECT]', '[LOCATION]', '[KEY_RING]', '[IMPORT_JOB]') >>> >>> response = client.get_import_job(name)
- Parameters
name (str) – The
name
of theImportJob
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.timeout (Optional[float]) – The amount of time, in seconds, to wait for the request to complete. Note that if
retry
is specified, the timeout applies to each individual attempt.metadata (Optional[Sequence[Tuple[str, str]]]) – Additional metadata that is provided to the method.
- Returns
A
ImportJob
instance.- Raises
google.api_core.exceptions.GoogleAPICallError – If the request failed for any reason.
google.api_core.exceptions.RetryError – If the request failed due to a retryable error and retry attempts failed.
ValueError – If the parameters are invalid.
-
get_key_ring
(name, retry=<object object>, timeout=<object object>, metadata=None)[source]# Returns metadata for a given
KeyRing
.Example
>>> from google.cloud import kms_v1 >>> >>> client = kms_v1.KeyManagementServiceClient() >>> >>> name = client.key_ring_path('[PROJECT]', '[LOCATION]', '[KEY_RING]') >>> >>> response = client.get_key_ring(name)
- Parameters
name (str) – The
name
of theKeyRing
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.timeout (Optional[float]) – The amount of time, in seconds, to wait for the request to complete. Note that if
retry
is specified, the timeout applies to each individual attempt.metadata (Optional[Sequence[Tuple[str, str]]]) – Additional metadata that is provided to the method.
- Returns
A
KeyRing
instance.- Raises
google.api_core.exceptions.GoogleAPICallError – If the request failed for any reason.
google.api_core.exceptions.RetryError – If the request failed due to a retryable error and retry attempts failed.
ValueError – If the parameters are invalid.
-
get_public_key
(name, retry=<object object>, timeout=<object object>, metadata=None)[source]# Returns the public key for the given
CryptoKeyVersion
. TheCryptoKey.purpose
must beASYMMETRIC_SIGN
orASYMMETRIC_DECRYPT
.Example
>>> from google.cloud import kms_v1 >>> >>> client = kms_v1.KeyManagementServiceClient() >>> >>> name = client.crypto_key_version_path('[PROJECT]', '[LOCATION]', '[KEY_RING]', '[CRYPTO_KEY]', '[CRYPTO_KEY_VERSION]') >>> >>> response = client.get_public_key(name)
- Parameters
name (str) – The
name
of theCryptoKeyVersion
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.timeout (Optional[float]) – The amount of time, in seconds, to wait for the request to complete. Note that if
retry
is specified, the timeout applies to each individual attempt.metadata (Optional[Sequence[Tuple[str, str]]]) – Additional metadata that is provided to the method.
- Returns
A
PublicKey
instance.- Raises
google.api_core.exceptions.GoogleAPICallError – If the request failed for any reason.
google.api_core.exceptions.RetryError – If the request failed due to a retryable error and retry attempts failed.
ValueError – If the parameters are invalid.
-
import_crypto_key_version
(parent, algorithm, import_job, rsa_aes_wrapped_key=None, retry=<object object>, timeout=<object object>, metadata=None)[source]# Imports a new
CryptoKeyVersion
into an existingCryptoKey
using the wrapped key material provided in the request.The version ID will be assigned the next sequential id within the
CryptoKey
.Example
>>> from google.cloud import kms_v1 >>> from google.cloud.kms_v1 import enums >>> >>> client = kms_v1.KeyManagementServiceClient() >>> >>> parent = client.crypto_key_path('[PROJECT]', '[LOCATION]', '[KEY_RING]', '[CRYPTO_KEY]') >>> >>> # TODO: Initialize `algorithm`: >>> algorithm = enums.CryptoKeyVersion.CryptoKeyVersionAlgorithm.CRYPTO_KEY_VERSION_ALGORITHM_UNSPECIFIED >>> >>> # TODO: Initialize `import_job`: >>> import_job = '' >>> >>> response = client.import_crypto_key_version(parent, algorithm, import_job)
- Parameters
parent (str) – Required. The
name
of theCryptoKey
to be imported into.algorithm (CryptoKeyVersionAlgorithm) – Required. The
algorithm
of the key being imported. This does not need to match theversion_template
of theCryptoKey
this version imports into.import_job (str) – Required. The
name
of theImportJob
that was used to wrap this key material.rsa_aes_wrapped_key (bytes) –
Wrapped key material produced with
RSA_OAEP_3072_SHA1_AES_256
orRSA_OAEP_4096_SHA1_AES_256
.This field contains the concatenation of two wrapped keys:
- An ephemeral AES-256 wrapping key wrapped with the `public_key` using RSAES-OAEP with SHA-1, MGF1 with SHA-1, and an empty label.
- The key to be imported, wrapped with the ephemeral AES-256 key using AES-KWP (RFC 5649).
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 to retry requests. If
None
is specified, requests will be retried using a default configuration.timeout (Optional[float]) – The amount of time, in seconds, to wait for the request to complete. Note that if
retry
is specified, the timeout applies to each individual attempt.metadata (Optional[Sequence[Tuple[str, str]]]) – Additional metadata that is provided to the method.
- Returns
A
CryptoKeyVersion
instance.- Raises
google.api_core.exceptions.GoogleAPICallError – If the request failed for any reason.
google.api_core.exceptions.RetryError – If the request failed due to a retryable error and retry attempts failed.
ValueError – If the parameters are invalid.
-
classmethod
import_job_path
(project, location, key_ring, import_job)[source]# Return a fully-qualified import_job string.
-
classmethod
key_ring_path
(project, location, key_ring)[source]# Return a fully-qualified key_ring string.
-
list_crypto_key_versions
(parent, page_size=None, view=None, filter_=None, order_by=None, retry=<object object>, timeout=<object object>, metadata=None)[source]# Lists
CryptoKeyVersions
.Example
>>> from google.cloud import kms_v1 >>> >>> client = kms_v1.KeyManagementServiceClient() >>> >>> parent = client.crypto_key_path('[PROJECT]', '[LOCATION]', '[KEY_RING]', '[CRYPTO_KEY]') >>> >>> # Iterate over all results >>> for element in client.list_crypto_key_versions(parent): ... # process element ... pass >>> >>> >>> # Alternatively: >>> >>> # Iterate over results one page at a time >>> for page in client.list_crypto_key_versions(parent).pages: ... for element in page: ... # process element ... pass
- Parameters
parent (str) – Required. The resource name of the
CryptoKey
to list, in the formatprojects/*/locations/*/keyRings/*/cryptoKeys/*
.page_size (int) – The maximum number of resources contained in the underlying API response. If page streaming is performed per- resource, this parameter does not affect the return value. If page streaming is performed per-page, this determines the maximum number of resources in a page.
view (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.
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.timeout (Optional[float]) – The amount of time, in seconds, to wait for the request to complete. Note that if
retry
is specified, the timeout applies to each individual attempt.metadata (Optional[Sequence[Tuple[str, str]]]) – Additional metadata that is provided to the method.
- Returns
A
PageIterator
instance. An iterable ofCryptoKeyVersion
instances. You can also iterate over the pages of the response using its pages property.- Raises
google.api_core.exceptions.GoogleAPICallError – If the request failed for any reason.
google.api_core.exceptions.RetryError – If the request failed due to a retryable error and retry attempts failed.
ValueError – If the parameters are invalid.
-
list_crypto_keys
(parent, page_size=None, version_view=None, filter_=None, order_by=None, retry=<object object>, timeout=<object object>, metadata=None)[source]# Lists
CryptoKeys
.Example
>>> from google.cloud import kms_v1 >>> >>> client = kms_v1.KeyManagementServiceClient() >>> >>> parent = client.key_ring_path('[PROJECT]', '[LOCATION]', '[KEY_RING]') >>> >>> # Iterate over all results >>> for element in client.list_crypto_keys(parent): ... # process element ... pass >>> >>> >>> # Alternatively: >>> >>> # Iterate over results one page at a time >>> for page in client.list_crypto_keys(parent).pages: ... for element in page: ... # process element ... pass
- Parameters
parent (str) – Required. The resource name of the
KeyRing
to list, in the formatprojects/*/locations/*/keyRings/*
.page_size (int) – The maximum number of resources contained in the underlying API response. If page streaming is performed per- resource, this parameter does not affect the return value. If page streaming is performed per-page, this determines the maximum number of resources in a page.
version_view (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.
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.timeout (Optional[float]) – The amount of time, in seconds, to wait for the request to complete. Note that if
retry
is specified, the timeout applies to each individual attempt.metadata (Optional[Sequence[Tuple[str, str]]]) – Additional metadata that is provided to the method.
- Returns
A
PageIterator
instance. An iterable ofCryptoKey
instances. You can also iterate over the pages of the response using its pages property.- Raises
google.api_core.exceptions.GoogleAPICallError – If the request failed for any reason.
google.api_core.exceptions.RetryError – If the request failed due to a retryable error and retry attempts failed.
ValueError – If the parameters are invalid.
-
list_import_jobs
(parent, page_size=None, filter_=None, order_by=None, retry=<object object>, timeout=<object object>, metadata=None)[source]# Lists
ImportJobs
.Example
>>> from google.cloud import kms_v1 >>> >>> client = kms_v1.KeyManagementServiceClient() >>> >>> parent = client.key_ring_path('[PROJECT]', '[LOCATION]', '[KEY_RING]') >>> >>> # Iterate over all results >>> for element in client.list_import_jobs(parent): ... # process element ... pass >>> >>> >>> # Alternatively: >>> >>> # Iterate over results one page at a time >>> for page in client.list_import_jobs(parent).pages: ... for element in page: ... # process element ... pass
- Parameters
parent (str) – Required. The resource name of the
KeyRing
to list, in the formatprojects/*/locations/*/keyRings/*
.page_size (int) – The maximum number of resources contained in the underlying API response. If page streaming is performed per- resource, this parameter does not affect the return value. If page 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.
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.timeout (Optional[float]) – The amount of time, in seconds, to wait for the request to complete. Note that if
retry
is specified, the timeout applies to each individual attempt.metadata (Optional[Sequence[Tuple[str, str]]]) – Additional metadata that is provided to the method.
- Returns
A
PageIterator
instance. An iterable ofImportJob
instances. You can also iterate over the pages of the response using its pages property.- Raises
google.api_core.exceptions.GoogleAPICallError – If the request failed for any reason.
google.api_core.exceptions.RetryError – If the request failed due to a retryable error and retry attempts failed.
ValueError – If the parameters are invalid.
-
list_key_rings
(parent, page_size=None, filter_=None, order_by=None, retry=<object object>, timeout=<object object>, metadata=None)[source]# Lists
KeyRings
.Example
>>> from google.cloud import kms_v1 >>> >>> client = kms_v1.KeyManagementServiceClient() >>> >>> parent = client.location_path('[PROJECT]', '[LOCATION]') >>> >>> # Iterate over all results >>> for element in client.list_key_rings(parent): ... # process element ... pass >>> >>> >>> # Alternatively: >>> >>> # Iterate over results one page at a time >>> for page in client.list_key_rings(parent).pages: ... for element in page: ... # process element ... pass
- Parameters
parent (str) – Required. The resource name of the location associated with the
KeyRings
, in the formatprojects/*/locations/*
.page_size (int) – The maximum number of resources contained in the underlying API response. If page streaming is performed per- resource, this parameter does not affect the return value. If page 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.
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.timeout (Optional[float]) – The amount of time, in seconds, to wait for the request to complete. Note that if
retry
is specified, the timeout applies to each individual attempt.metadata (Optional[Sequence[Tuple[str, str]]]) – Additional metadata that is provided to the method.
- Returns
A
PageIterator
instance. An iterable ofKeyRing
instances. You can also iterate over the pages of the response using its pages property.- Raises
google.api_core.exceptions.GoogleAPICallError – If the request failed for any reason.
google.api_core.exceptions.RetryError – If the request failed due to a retryable error and retry attempts failed.
ValueError – If the parameters are invalid.
-
restore_crypto_key_version
(name, retry=<object object>, timeout=<object object>, metadata=None)[source]# Restore a
CryptoKeyVersion
in theDESTROY_SCHEDULED
state.Upon restoration of the CryptoKeyVersion,
state
will be set toDISABLED
, anddestroy_time
will be cleared.Example
>>> from google.cloud import kms_v1 >>> >>> client = kms_v1.KeyManagementServiceClient() >>> >>> name = client.crypto_key_version_path('[PROJECT]', '[LOCATION]', '[KEY_RING]', '[CRYPTO_KEY]', '[CRYPTO_KEY_VERSION]') >>> >>> response = client.restore_crypto_key_version(name)
- Parameters
name (str) – 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.timeout (Optional[float]) – The amount of time, in seconds, to wait for the request to complete. Note that if
retry
is specified, the timeout applies to each individual attempt.metadata (Optional[Sequence[Tuple[str, str]]]) – Additional metadata that is provided to the method.
- Returns
A
CryptoKeyVersion
instance.- Raises
google.api_core.exceptions.GoogleAPICallError – If the request failed for any reason.
google.api_core.exceptions.RetryError – If the request failed due to a retryable error and retry attempts failed.
ValueError – If the parameters are invalid.
-
set_iam_policy
(resource, policy, retry=<object object>, timeout=<object object>, metadata=None)[source]# Sets the access control policy on the specified resource. Replaces any existing policy.
Example
>>> from google.cloud import kms_v1 >>> >>> client = kms_v1.KeyManagementServiceClient() >>> >>> resource = client.key_ring_path('[PROJECT]', '[LOCATION]', '[KEY_RING]') >>> >>> # TODO: Initialize `policy`: >>> policy = {} >>> >>> response = client.set_iam_policy(resource, policy)
- Parameters
resource (str) – REQUIRED: The resource for which the policy is being specified. See the operation documentation for the appropriate value for this field.
policy (Union[dict, Policy]) –
REQUIRED: The complete policy to be applied to the
resource
. The size of the policy is limited to a few 10s of KB. An empty policy is a valid policy but certain Cloud Platform services (such as Projects) might reject them.If a dict is provided, it must be of the same form as the protobuf message
Policy
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.timeout (Optional[float]) – The amount of time, in seconds, to wait for the request to complete. Note that if
retry
is specified, the timeout applies to each individual attempt.metadata (Optional[Sequence[Tuple[str, str]]]) – Additional metadata that is provided to the method.
- Returns
A
Policy
instance.- Raises
google.api_core.exceptions.GoogleAPICallError – If the request failed for any reason.
google.api_core.exceptions.RetryError – If the request failed due to a retryable error and retry attempts failed.
ValueError – If the parameters are invalid.
-
test_iam_permissions
(resource, permissions, retry=<object object>, timeout=<object object>, metadata=None)[source]# Returns permissions that a caller has on the specified resource. If the resource does not exist, this will return an empty set of permissions, not a NOT_FOUND error.
Note: This operation is designed to be used for building permission-aware UIs and command-line tools, not for authorization checking. This operation may “fail open” without warning.
Example
>>> from google.cloud import kms_v1 >>> >>> client = kms_v1.KeyManagementServiceClient() >>> >>> resource = client.key_ring_path('[PROJECT]', '[LOCATION]', '[KEY_RING]') >>> >>> # TODO: Initialize `permissions`: >>> permissions = [] >>> >>> response = client.test_iam_permissions(resource, permissions)
- Parameters
resource (str) – REQUIRED: The resource for which the policy detail is being requested. See the operation documentation for the appropriate value for this field.
permissions (list[str]) – The set of permissions to check for the
resource
. Permissions with wildcards (such as ‘*’ or ‘storage.*’) are not allowed. For more information see IAM Overview.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.timeout (Optional[float]) – The amount of time, in seconds, to wait for the request to complete. Note that if
retry
is specified, the timeout applies to each individual attempt.metadata (Optional[Sequence[Tuple[str, str]]]) – Additional metadata that is provided to the method.
- Returns
A
TestIamPermissionsResponse
instance.- Raises
google.api_core.exceptions.GoogleAPICallError – If the request failed for any reason.
google.api_core.exceptions.RetryError – If the request failed due to a retryable error and retry attempts failed.
ValueError – If the parameters are invalid.
-
update_crypto_key
(crypto_key, update_mask, retry=<object object>, timeout=<object object>, metadata=None)[source]# Update a
CryptoKey
.Example
>>> from google.cloud import kms_v1 >>> >>> client = kms_v1.KeyManagementServiceClient() >>> >>> # TODO: Initialize `crypto_key`: >>> crypto_key = {} >>> >>> # TODO: Initialize `update_mask`: >>> update_mask = {} >>> >>> response = client.update_crypto_key(crypto_key, update_mask)
- Parameters
crypto_key (Union[dict, CryptoKey]) –
CryptoKey
with updated values.If a dict is provided, it must be of the same form as the protobuf message
CryptoKey
update_mask (Union[dict, 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
FieldMask
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.timeout (Optional[float]) – The amount of time, in seconds, to wait for the request to complete. Note that if
retry
is specified, the timeout applies to each individual attempt.metadata (Optional[Sequence[Tuple[str, str]]]) – Additional metadata that is provided to the method.
- Returns
A
CryptoKey
instance.- Raises
google.api_core.exceptions.GoogleAPICallError – If the request failed for any reason.
google.api_core.exceptions.RetryError – If the request failed due to a retryable error and retry attempts failed.
ValueError – If the parameters are invalid.
-
update_crypto_key_primary_version
(name, crypto_key_version_id, retry=<object object>, timeout=<object object>, metadata=None)[source]# Update the version of a
CryptoKey
that will be used inEncrypt
.Returns an error if called on an asymmetric key.
Example
>>> from google.cloud import kms_v1 >>> >>> client = kms_v1.KeyManagementServiceClient() >>> >>> name = client.crypto_key_path('[PROJECT]', '[LOCATION]', '[KEY_RING]', '[CRYPTO_KEY]') >>> >>> # TODO: Initialize `crypto_key_version_id`: >>> crypto_key_version_id = '' >>> >>> response = client.update_crypto_key_primary_version(name, crypto_key_version_id)
- Parameters
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.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.timeout (Optional[float]) – The amount of time, in seconds, to wait for the request to complete. Note that if
retry
is specified, the timeout applies to each individual attempt.metadata (Optional[Sequence[Tuple[str, str]]]) – Additional metadata that is provided to the method.
- Returns
A
CryptoKey
instance.- Raises
google.api_core.exceptions.GoogleAPICallError – If the request failed for any reason.
google.api_core.exceptions.RetryError – If the request failed due to a retryable error and retry attempts failed.
ValueError – If the parameters are invalid.
-
update_crypto_key_version
(crypto_key_version, update_mask, retry=<object object>, timeout=<object object>, metadata=None)[source]# Update a
CryptoKeyVersion
’s metadata.state
may be changed betweenENABLED
andDISABLED
using this method. SeeDestroyCryptoKeyVersion
andRestoreCryptoKeyVersion
to move between other states.Example
>>> from google.cloud import kms_v1 >>> >>> client = kms_v1.KeyManagementServiceClient() >>> >>> # TODO: Initialize `crypto_key_version`: >>> crypto_key_version = {} >>> >>> # TODO: Initialize `update_mask`: >>> update_mask = {} >>> >>> response = client.update_crypto_key_version(crypto_key_version, update_mask)
- Parameters
crypto_key_version (Union[dict, CryptoKeyVersion]) –
CryptoKeyVersion
with updated values.If a dict is provided, it must be of the same form as the protobuf message
CryptoKeyVersion
update_mask (Union[dict, 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
FieldMask
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.timeout (Optional[float]) – The amount of time, in seconds, to wait for the request to complete. Note that if
retry
is specified, the timeout applies to each individual attempt.metadata (Optional[Sequence[Tuple[str, str]]]) – Additional metadata that is provided to the method.
- Returns
A
CryptoKeyVersion
instance.- Raises
google.api_core.exceptions.GoogleAPICallError – If the request failed for any reason.
google.api_core.exceptions.RetryError – If the request failed due to a retryable error and retry attempts failed.
ValueError – If the parameters are invalid.