0
# Types and Enums
1
2
Google Cloud KMS provides a comprehensive type system including resource types for key management, request/response objects for API operations, and enums for algorithms, states, and configuration options.
3
4
## Core Resource Types
5
6
### KeyRing
7
8
```python { .api }
9
class KeyRing:
10
"""
11
Top-level logical grouping of CryptoKeys within a specific location.
12
13
Attributes:
14
- name: str - Resource name (projects/{project}/locations/{location}/keyRings/{key_ring})
15
- create_time: Timestamp - Creation timestamp
16
"""
17
```
18
19
### CryptoKey
20
21
```python { .api }
22
class CryptoKey:
23
"""
24
Logical key for cryptographic operations containing one or more CryptoKeyVersions.
25
26
Attributes:
27
- name: str - Resource name
28
- primary: CryptoKeyVersion - Primary version for encrypt operations
29
- purpose: CryptoKeyPurpose - Cryptographic purpose
30
- create_time: Timestamp - Creation timestamp
31
- next_rotation_time: Timestamp - Next automatic rotation time
32
- rotation_period: Duration - Automatic rotation period
33
- version_template: CryptoKeyVersionTemplate - Template for new versions
34
- labels: Dict[str, str] - User-defined labels
35
- import_only: bool - Whether key can only accept imported versions
36
- destroy_scheduled_duration: Duration - Scheduled destruction duration
37
- crypto_key_backend: str - Backend system for key operations
38
- key_access_justifications_policy: KeyAccessJustificationsPolicy - Access justification policy
39
"""
40
41
class CryptoKeyPurpose:
42
"""
43
Cryptographic purpose of a CryptoKey.
44
45
Values:
46
- CRYPTO_KEY_PURPOSE_UNSPECIFIED: Not specified
47
- ENCRYPT_DECRYPT: Symmetric encryption and decryption
48
- ASYMMETRIC_SIGN: Asymmetric signing
49
- ASYMMETRIC_DECRYPT: Asymmetric decryption
50
- RAW_ENCRYPT_DECRYPT: Raw symmetric encryption and decryption
51
- MAC: Message Authentication Code operations
52
"""
53
```
54
55
### CryptoKeyVersion
56
57
```python { .api }
58
class CryptoKeyVersion:
59
"""
60
Individual cryptographic key with key material.
61
62
Attributes:
63
- name: str - Resource name
64
- state: CryptoKeyVersionState - Current state
65
- protection_level: ProtectionLevel - Protection level
66
- algorithm: CryptoKeyVersionAlgorithm - Cryptographic algorithm
67
- attestation: KeyOperationAttestation - HSM attestation
68
- create_time: Timestamp - Creation timestamp
69
- generate_time: Timestamp - Key material generation timestamp
70
- destroy_time: Timestamp - Destruction timestamp
71
- destroy_event_time: Timestamp - Event that triggered destruction
72
- import_job: str - ImportJob used for key material
73
- import_time: Timestamp - Import timestamp
74
- import_failure_reason: str - Import failure reason
75
- generation_failure_reason: str - Generation failure reason
76
- external_destruction_failure_reason: str - External destruction failure reason
77
- external_protection_level_options: ExternalProtectionLevelOptions - External protection options
78
"""
79
80
class CryptoKeyVersionAlgorithm:
81
"""
82
Supported cryptographic algorithms.
83
84
Symmetric Algorithms:
85
- GOOGLE_SYMMETRIC_ENCRYPTION: Google-managed symmetric encryption
86
- AES_128_GCM, AES_256_GCM: AES with Galois/Counter Mode
87
- AES_128_CBC, AES_256_CBC: AES with Cipher Block Chaining
88
- AES_128_CTR, AES_256_CTR: AES with Counter Mode
89
90
RSA Signing Algorithms:
91
- RSA_SIGN_PSS_2048_SHA256, RSA_SIGN_PSS_3072_SHA256, RSA_SIGN_PSS_4096_SHA256: RSA PSS with SHA-256
92
- RSA_SIGN_PSS_4096_SHA512: RSA PSS with SHA-512
93
- RSA_SIGN_PKCS1_2048_SHA256, RSA_SIGN_PKCS1_3072_SHA256, RSA_SIGN_PKCS1_4096_SHA256: RSA PKCS#1 v1.5 with SHA-256
94
- RSA_SIGN_PKCS1_4096_SHA512: RSA PKCS#1 v1.5 with SHA-512
95
- RSA_SIGN_RAW_PKCS1_2048, RSA_SIGN_RAW_PKCS1_3072, RSA_SIGN_RAW_PKCS1_4096: Raw RSA PKCS#1
96
97
RSA Encryption Algorithms:
98
- RSA_DECRYPT_OAEP_2048_SHA256, RSA_DECRYPT_OAEP_3072_SHA256, RSA_DECRYPT_OAEP_4096_SHA256: RSA OAEP with SHA-256
99
- RSA_DECRYPT_OAEP_4096_SHA512: RSA OAEP with SHA-512
100
- RSA_DECRYPT_OAEP_2048_SHA1, RSA_DECRYPT_OAEP_3072_SHA1, RSA_DECRYPT_OAEP_4096_SHA1: RSA OAEP with SHA-1
101
102
Elliptic Curve Algorithms:
103
- EC_SIGN_P256_SHA256: ECDSA with P-256 curve and SHA-256
104
- EC_SIGN_P384_SHA384: ECDSA with P-384 curve and SHA-384
105
- EC_SIGN_SECP256K1_SHA256: ECDSA with secp256k1 curve and SHA-256
106
- EC_SIGN_ED25519: EdDSA with Ed25519 curve
107
108
HMAC Algorithms:
109
- HMAC_SHA256, HMAC_SHA1, HMAC_SHA384, HMAC_SHA512, HMAC_SHA224: HMAC with various hash functions
110
111
External and Post-Quantum:
112
- EXTERNAL_SYMMETRIC_ENCRYPTION: External symmetric encryption
113
- PQ_SIGN_ML_DSA_65: Post-quantum ML-DSA-65 signing
114
- PQ_SIGN_SLH_DSA_SHA2_128S: Post-quantum SLH-DSA-SHA2-128s signing
115
"""
116
117
class CryptoKeyVersionState:
118
"""
119
State of a CryptoKeyVersion.
120
121
Values:
122
- CRYPTO_KEY_VERSION_STATE_UNSPECIFIED: Unspecified state
123
- PENDING_GENERATION: Still being generated
124
- ENABLED: Available for cryptographic operations
125
- DISABLED: Not usable but key material available
126
- DESTROYED: Key material destroyed
127
- DESTROY_SCHEDULED: Scheduled for destruction
128
- PENDING_IMPORT: Still being imported
129
- IMPORT_FAILED: Import failed
130
- GENERATION_FAILED: Generation failed
131
- PENDING_EXTERNAL_DESTRUCTION: Destroyed, waiting for external confirmation
132
- EXTERNAL_DESTRUCTION_FAILED: External destruction failed
133
"""
134
135
class CryptoKeyVersionView:
136
"""
137
View level for CryptoKeyVersion details.
138
139
Values:
140
- CRYPTO_KEY_VERSION_VIEW_UNSPECIFIED: Default view
141
- FULL: Full view including attestation data
142
"""
143
```
144
145
### CryptoKeyVersionTemplate
146
147
```python { .api }
148
class CryptoKeyVersionTemplate:
149
"""
150
Template for creating new CryptoKeyVersions.
151
152
Attributes:
153
- protection_level: ProtectionLevel - Protection level for new versions
154
- algorithm: CryptoKeyVersionAlgorithm - Algorithm for new versions
155
"""
156
```
157
158
## Protection and Access Types
159
160
### ProtectionLevel
161
162
```python { .api }
163
class ProtectionLevel:
164
"""
165
Protection level for cryptographic operations.
166
167
Values:
168
- PROTECTION_LEVEL_UNSPECIFIED: Not specified
169
- SOFTWARE: Crypto operations performed in software
170
- HSM: Crypto operations performed in Hardware Security Module
171
- EXTERNAL: Crypto operations performed by external key manager
172
- EXTERNAL_VPC: Crypto operations performed in EKM-over-VPC backend
173
"""
174
```
175
176
### AccessReason
177
178
```python { .api }
179
class AccessReason:
180
"""
181
Reason for accessing cryptographic key material.
182
183
Values:
184
- REASON_UNSPECIFIED: Unspecified access reason
185
- CUSTOMER_INITIATED_SUPPORT: Customer-initiated support case
186
- GOOGLE_INITIATED_SERVICE: Google-initiated system management access
187
- THIRD_PARTY_DATA_REQUEST: Google-initiated legal request response
188
- GOOGLE_INITIATED_REVIEW: Google-initiated security/fraud/compliance access
189
- CUSTOMER_INITIATED_ACCESS: Customer account access
190
- GOOGLE_INITIATED_SYSTEM_OPERATION: Google systems optimization access
191
- REASON_NOT_EXPECTED: No reason expected for this operation
192
- MODIFIED_CUSTOMER_INITIATED_ACCESS: Customer access with recent admin reset/emergency operation
193
- MODIFIED_GOOGLE_INITIATED_SYSTEM_OPERATION: Google system access with recent admin reset/emergency operation
194
- GOOGLE_RESPONSE_TO_PRODUCTION_ALERT: Google-initiated system reliability access
195
- CUSTOMER_AUTHORIZED_WORKFLOW_SERVICING: Workflow servicing with technical issue
196
"""
197
```
198
199
### KeyAccessJustificationsPolicy
200
201
```python { .api }
202
class KeyAccessJustificationsPolicy:
203
"""
204
Policy specifying allowed access reasons for key material.
205
206
Attributes:
207
- allowed_access_reasons: List[AccessReason] - List of allowed access reasons
208
"""
209
```
210
211
## Attestation and Security Types
212
213
### KeyOperationAttestation
214
215
```python { .api }
216
class KeyOperationAttestation:
217
"""
218
HSM-generated attestation about key operations.
219
220
Attributes:
221
- format: AttestationFormat - Format of the attestation data
222
- content: bytes - Attestation content
223
- cert_chains: CertificateChains - Certificate chains for verification
224
"""
225
226
class AttestationFormat:
227
"""
228
Format of HSM attestation data.
229
230
Values:
231
- ATTESTATION_FORMAT_UNSPECIFIED: Unspecified format
232
- CAVIUM_V1_COMPRESSED: Cavium HSM attestation compressed with gzip
233
- CAVIUM_V2_COMPRESSED: Cavium HSM attestation V2 compressed with gzip
234
"""
235
236
class CertificateChains:
237
"""
238
Certificate chains for attestation verification.
239
240
Attributes:
241
- cavium_certs: List[str] - Cavium HSM certificate chain
242
- google_card_certs: List[str] - Google Card certificate chain
243
- google_partition_certs: List[str] - Google Partition certificate chain
244
"""
245
```
246
247
### PublicKey
248
249
```python { .api }
250
class PublicKey:
251
"""
252
Public key information for asymmetric CryptoKeyVersions.
253
254
Attributes:
255
- pem: str - PEM-encoded public key
256
- algorithm: CryptoKeyVersionAlgorithm - Cryptographic algorithm
257
- pem_crc32c: int - CRC32C checksum of PEM data
258
- name: str - Resource name of the CryptoKeyVersion
259
- protection_level: ProtectionLevel - Protection level
260
"""
261
262
class PublicKeyFormat:
263
"""
264
Format for public key encoding.
265
266
Values:
267
- PUBLIC_KEY_FORMAT_UNSPECIFIED: Unspecified format
268
- PEM: Privacy-Enhanced Mail format
269
- NIST_PQC: NIST Post-Quantum Cryptography format
270
"""
271
```
272
273
## Import and External Key Types
274
275
### ImportJob
276
277
```python { .api }
278
class ImportJob:
279
"""
280
Job for importing pre-existing key material into Google Cloud KMS.
281
282
Attributes:
283
- name: str - Resource name
284
- import_method: ImportMethod - Method for importing key material
285
- protection_level: ProtectionLevel - Protection level for imported keys
286
- create_time: Timestamp - Creation timestamp
287
- generate_time: Timestamp - Wrapping key generation timestamp
288
- expire_time: Timestamp - Expiration timestamp
289
- expire_event_time: Timestamp - Event that triggered expiration
290
- state: ImportJobState - Current state
291
- public_key: WrappingPublicKey - Public key for wrapping key material
292
- attestation: KeyOperationAttestation - HSM attestation
293
"""
294
295
class ImportMethod:
296
"""
297
Method for importing wrapped key material.
298
299
Values:
300
- IMPORT_METHOD_UNSPECIFIED: Unspecified method
301
- RSA_OAEP_3072_SHA1_AES_256: RSA AES key wrap with 3072-bit RSA and SHA-1
302
- RSA_OAEP_4096_SHA1_AES_256: RSA AES key wrap with 4096-bit RSA and SHA-1
303
- RSA_OAEP_3072_SHA256_AES_256: RSA AES key wrap with 3072-bit RSA and SHA-256
304
- RSA_OAEP_4096_SHA256_AES_256: RSA AES key wrap with 4096-bit RSA and SHA-256
305
- RSA_OAEP_3072_SHA256: RSAES-OAEP with 3072-bit RSA and SHA-256
306
- RSA_OAEP_4096_SHA256: RSAES-OAEP with 4096-bit RSA and SHA-256
307
"""
308
309
class ImportJobState:
310
"""
311
State of an ImportJob.
312
313
Values:
314
- IMPORT_JOB_STATE_UNSPECIFIED: Unspecified state
315
- PENDING_GENERATION: Wrapping key being generated
316
- ACTIVE: Ready for key import operations
317
- EXPIRED: No longer usable for imports
318
"""
319
320
class WrappingPublicKey:
321
"""
322
Public key component of wrapping key for import operations.
323
324
Attributes:
325
- pem: str - PEM-encoded public key
326
"""
327
```
328
329
### ExternalProtectionLevelOptions
330
331
```python { .api }
332
class ExternalProtectionLevelOptions:
333
"""
334
Configuration options for external protection levels.
335
336
Attributes:
337
- external_key_uri: str - URI of the external key
338
- ekm_connection_key_path: str - Path to key in EKM connection
339
"""
340
```
341
342
## Data and Utility Types
343
344
### ChecksummedData
345
346
```python { .api }
347
class ChecksummedData:
348
"""
349
Data with integrity verification field.
350
351
Attributes:
352
- data: bytes - Raw data
353
- crc32c: int - CRC32C checksum of data
354
"""
355
```
356
357
### Digest
358
359
```python { .api }
360
class Digest:
361
"""
362
Cryptographic message digest for signing operations.
363
364
Attributes:
365
- sha256: bytes - SHA-256 digest
366
- sha384: bytes - SHA-384 digest
367
- sha512: bytes - SHA-512 digest
368
"""
369
```
370
371
### LocationMetadata
372
373
```python { .api }
374
class LocationMetadata:
375
"""
376
Cloud KMS metadata for geographical locations.
377
378
Attributes:
379
- hsm_available: bool - Whether HSM protection is available
380
- ekm_available: bool - Whether EKM protection is available
381
"""
382
```
383
384
## Request and Response Types
385
386
### List Request/Response Pattern
387
388
```python { .api }
389
class ListKeyRingsRequest:
390
"""
391
Request to list KeyRings in a location.
392
393
Attributes:
394
- parent: str - Required. Location path
395
- page_size: int - Optional. Maximum results per page (1-1000)
396
- page_token: str - Optional. Pagination token
397
- filter: str - Optional. Filter expression
398
- order_by: str - Optional. Sorting order
399
"""
400
401
class ListKeyRingsResponse:
402
"""
403
Response from listing KeyRings.
404
405
Attributes:
406
- key_rings: List[KeyRing] - List of KeyRing objects
407
- next_page_token: str - Token for next page
408
- total_size: int - Total number of key rings
409
"""
410
```
411
412
### Cryptographic Operation Types
413
414
```python { .api }
415
class EncryptRequest:
416
"""
417
Request to encrypt data.
418
419
Attributes:
420
- name: str - Required. CryptoKey or CryptoKeyVersion resource name
421
- plaintext: bytes - Required. Data to encrypt (max 64KiB)
422
- additional_authenticated_data: bytes - Optional. AAD for authenticated encryption
423
- plaintext_crc32c: int - Optional. CRC32C checksum of plaintext
424
- additional_authenticated_data_crc32c: int - Optional. CRC32C checksum of AAD
425
"""
426
427
class EncryptResponse:
428
"""
429
Response from encrypt operation.
430
431
Attributes:
432
- name: str - CryptoKeyVersion used for encryption
433
- ciphertext: bytes - Encrypted data
434
- ciphertext_crc32c: int - CRC32C checksum of ciphertext
435
- verified_plaintext_crc32c: bool - Whether plaintext checksum was verified
436
- verified_additional_authenticated_data_crc32c: bool - Whether AAD checksum was verified
437
- protection_level: ProtectionLevel - Protection level used
438
"""
439
440
class DecryptRequest:
441
"""
442
Request to decrypt data.
443
444
Attributes:
445
- name: str - Required. CryptoKey resource name
446
- ciphertext: bytes - Required. Encrypted data
447
- additional_authenticated_data: bytes - Optional. AAD used during encryption
448
- ciphertext_crc32c: int - Optional. CRC32C checksum of ciphertext
449
- additional_authenticated_data_crc32c: int - Optional. CRC32C checksum of AAD
450
"""
451
452
class DecryptResponse:
453
"""
454
Response from decrypt operation.
455
456
Attributes:
457
- plaintext: bytes - Decrypted data
458
- plaintext_crc32c: int - CRC32C checksum of plaintext
459
- used_primary: bool - Whether primary version was used
460
- protection_level: ProtectionLevel - Protection level used
461
"""
462
```
463
464
### Asymmetric Operation Types
465
466
```python { .api }
467
class AsymmetricSignRequest:
468
"""
469
Request to create asymmetric signature.
470
471
Attributes:
472
- name: str - Required. CryptoKeyVersion resource name
473
- digest: Digest - Optional. Pre-computed digest to sign
474
- digest_crc32c: int - Optional. CRC32C checksum of digest
475
- data: bytes - Optional. Raw data to sign (alternative to digest)
476
- data_crc32c: int - Optional. CRC32C checksum of data
477
"""
478
479
class AsymmetricSignResponse:
480
"""
481
Response from asymmetric sign operation.
482
483
Attributes:
484
- signature: bytes - Digital signature
485
- signature_crc32c: int - CRC32C checksum of signature
486
- verified_digest_crc32c: bool - Whether digest checksum was verified
487
- verified_data_crc32c: bool - Whether data checksum was verified
488
- name: str - CryptoKeyVersion used for signing
489
- protection_level: ProtectionLevel - Protection level used
490
"""
491
```
492
493
### MAC Operation Types
494
495
```python { .api }
496
class MacSignRequest:
497
"""
498
Request to create MAC signature.
499
500
Attributes:
501
- name: str - Required. CryptoKeyVersion resource name
502
- data: bytes - Required. Data to sign
503
- data_crc32c: int - Optional. CRC32C checksum of data
504
"""
505
506
class MacSignResponse:
507
"""
508
Response from MAC sign operation.
509
510
Attributes:
511
- name: str - CryptoKeyVersion used for signing
512
- mac: bytes - MAC signature
513
- mac_crc32c: int - CRC32C checksum of MAC
514
- verified_data_crc32c: bool - Whether data checksum was verified
515
- protection_level: ProtectionLevel - Protection level used
516
"""
517
518
class MacVerifyRequest:
519
"""
520
Request to verify MAC signature.
521
522
Attributes:
523
- name: str - Required. CryptoKeyVersion resource name
524
- data: bytes - Required. Original data
525
- data_crc32c: int - Optional. CRC32C checksum of data
526
- mac: bytes - Required. MAC signature to verify
527
- mac_crc32c: int - Optional. CRC32C checksum of MAC
528
"""
529
530
class MacVerifyResponse:
531
"""
532
Response from MAC verify operation.
533
534
Attributes:
535
- name: str - CryptoKeyVersion used for verification
536
- success: bool - Whether MAC verification succeeded
537
- verified_data_crc32c: bool - Whether data checksum was verified
538
- verified_mac_crc32c: bool - Whether MAC checksum was verified
539
- verified_success_integrity: bool - Whether success field integrity was verified
540
- protection_level: ProtectionLevel - Protection level used
541
"""
542
```
543
544
### Random Generation Types
545
546
```python { .api }
547
class GenerateRandomBytesRequest:
548
"""
549
Request to generate random bytes.
550
551
Attributes:
552
- location: str - Required. Location path for randomness generation
553
- length_bytes: int - Required. Number of random bytes to generate (1-1024)
554
- protection_level: ProtectionLevel - Optional. Protection level for randomness generation
555
"""
556
557
class GenerateRandomBytesResponse:
558
"""
559
Response from random bytes generation.
560
561
Attributes:
562
- data: bytes - Generated random data
563
- data_crc32c: int - CRC32C checksum of data
564
- verified_data_crc32c: bool - Whether data checksum was verified
565
"""
566
```
567
568
## Usage Examples
569
570
### Working with Enums
571
572
```python
573
from google.cloud import kms
574
575
# Use enums for type safety
576
purpose = kms.CryptoKey.CryptoKeyPurpose.ENCRYPT_DECRYPT
577
algorithm = kms.CryptoKeyVersion.CryptoKeyVersionAlgorithm.AES_256_GCM
578
protection_level = kms.ProtectionLevel.HSM
579
580
# Create crypto key with specific configuration
581
crypto_key = kms.CryptoKey()
582
crypto_key.purpose = purpose
583
crypto_key.version_template = kms.CryptoKeyVersionTemplate()
584
crypto_key.version_template.algorithm = algorithm
585
crypto_key.version_template.protection_level = protection_level
586
```
587
588
### Type Validation and Error Handling
589
590
```python
591
from google.cloud import kms
592
593
def validate_crypto_key_purpose(purpose_value):
594
"""Validate CryptoKey purpose value."""
595
valid_purposes = [
596
kms.CryptoKey.CryptoKeyPurpose.ENCRYPT_DECRYPT,
597
kms.CryptoKey.CryptoKeyPurpose.ASYMMETRIC_SIGN,
598
kms.CryptoKey.CryptoKeyPurpose.ASYMMETRIC_DECRYPT,
599
kms.CryptoKey.CryptoKeyPurpose.RAW_ENCRYPT_DECRYPT,
600
kms.CryptoKey.CryptoKeyPurpose.MAC,
601
]
602
return purpose_value in valid_purposes
603
604
# Use in key creation
605
purpose = kms.CryptoKey.CryptoKeyPurpose.ENCRYPT_DECRYPT
606
if validate_crypto_key_purpose(purpose):
607
crypto_key = kms.CryptoKey(purpose=purpose)
608
```
609
610
### Working with Complex Types
611
612
```python
613
from google.cloud import kms
614
615
# Create comprehensive key access justification policy
616
access_policy = kms.KeyAccessJustificationsPolicy()
617
access_policy.allowed_access_reasons = [
618
kms.AccessReason.CUSTOMER_INITIATED_SUPPORT,
619
kms.AccessReason.CUSTOMER_INITIATED_ACCESS,
620
kms.AccessReason.GOOGLE_INITIATED_SYSTEM_OPERATION,
621
]
622
623
# Create crypto key with access policy
624
crypto_key = kms.CryptoKey()
625
crypto_key.purpose = kms.CryptoKey.CryptoKeyPurpose.ENCRYPT_DECRYPT
626
crypto_key.key_access_justifications_policy = access_policy
627
628
# Create external protection configuration
629
external_options = kms.ExternalProtectionLevelOptions()
630
external_options.external_key_uri = "https://external-kms.example.com/keys/my-key"
631
external_options.ekm_connection_key_path = "/path/to/key"
632
633
# Use in version template
634
version_template = kms.CryptoKeyVersionTemplate()
635
version_template.protection_level = kms.ProtectionLevel.EXTERNAL
636
version_template.algorithm = kms.CryptoKeyVersion.CryptoKeyVersionAlgorithm.EXTERNAL_SYMMETRIC_ENCRYPTION
637
638
crypto_key.version_template = version_template
639
```