or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

Files

docs

autokey-service.mdexternal-key-management.mdindex.mdkey-management-service.mdtypes-and-enums.md

types-and-enums.mddocs/

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

```