Types and Enums

class KeyRing:
    """
    Top-level logical grouping of CryptoKeys within a specific location.
    
    Attributes:
    - name: str - Resource name (projects/{project}/locations/{location}/keyRings/{key_ring})
    - create_time: Timestamp - Creation timestamp
    """

class CryptoKey:
    """
    Logical key for cryptographic operations containing one or more CryptoKeyVersions.
    
    Attributes:
    - name: str - Resource name
    - primary: CryptoKeyVersion - Primary version for encrypt operations
    - purpose: CryptoKeyPurpose - Cryptographic purpose
    - create_time: Timestamp - Creation timestamp
    - next_rotation_time: Timestamp - Next automatic rotation time
    - rotation_period: Duration - Automatic rotation period
    - version_template: CryptoKeyVersionTemplate - Template for new versions
    - labels: Dict[str, str] - User-defined labels
    - import_only: bool - Whether key can only accept imported versions
    - destroy_scheduled_duration: Duration - Scheduled destruction duration
    - crypto_key_backend: str - Backend system for key operations
    - key_access_justifications_policy: KeyAccessJustificationsPolicy - Access justification policy
    """
    
    class CryptoKeyPurpose:
        """
        Cryptographic purpose of a CryptoKey.
        
        Values:
        - CRYPTO_KEY_PURPOSE_UNSPECIFIED: Not specified
        - ENCRYPT_DECRYPT: Symmetric encryption and decryption
        - ASYMMETRIC_SIGN: Asymmetric signing
        - ASYMMETRIC_DECRYPT: Asymmetric decryption  
        - RAW_ENCRYPT_DECRYPT: Raw symmetric encryption and decryption
        - MAC: Message Authentication Code operations
        """

class CryptoKeyVersion:
    """
    Individual cryptographic key with key material.
    
    Attributes:
    - name: str - Resource name
    - state: CryptoKeyVersionState - Current state
    - protection_level: ProtectionLevel - Protection level
    - algorithm: CryptoKeyVersionAlgorithm - Cryptographic algorithm
    - attestation: KeyOperationAttestation - HSM attestation
    - create_time: Timestamp - Creation timestamp
    - generate_time: Timestamp - Key material generation timestamp
    - destroy_time: Timestamp - Destruction timestamp
    - destroy_event_time: Timestamp - Event that triggered destruction
    - import_job: str - ImportJob used for key material
    - import_time: Timestamp - Import timestamp
    - import_failure_reason: str - Import failure reason
    - generation_failure_reason: str - Generation failure reason
    - external_destruction_failure_reason: str - External destruction failure reason
    - external_protection_level_options: ExternalProtectionLevelOptions - External protection options
    """
    
    class CryptoKeyVersionAlgorithm:
        """
        Supported cryptographic algorithms.
        
        Symmetric Algorithms:
        - GOOGLE_SYMMETRIC_ENCRYPTION: Google-managed symmetric encryption
        - AES_128_GCM, AES_256_GCM: AES with Galois/Counter Mode
        - AES_128_CBC, AES_256_CBC: AES with Cipher Block Chaining
        - AES_128_CTR, AES_256_CTR: AES with Counter Mode
        
        RSA Signing Algorithms:
        - RSA_SIGN_PSS_2048_SHA256, RSA_SIGN_PSS_3072_SHA256, RSA_SIGN_PSS_4096_SHA256: RSA PSS with SHA-256
        - RSA_SIGN_PSS_4096_SHA512: RSA PSS with SHA-512
        - RSA_SIGN_PKCS1_2048_SHA256, RSA_SIGN_PKCS1_3072_SHA256, RSA_SIGN_PKCS1_4096_SHA256: RSA PKCS#1 v1.5 with SHA-256
        - RSA_SIGN_PKCS1_4096_SHA512: RSA PKCS#1 v1.5 with SHA-512
        - RSA_SIGN_RAW_PKCS1_2048, RSA_SIGN_RAW_PKCS1_3072, RSA_SIGN_RAW_PKCS1_4096: Raw RSA PKCS#1
        
        RSA Encryption Algorithms:
        - RSA_DECRYPT_OAEP_2048_SHA256, RSA_DECRYPT_OAEP_3072_SHA256, RSA_DECRYPT_OAEP_4096_SHA256: RSA OAEP with SHA-256
        - RSA_DECRYPT_OAEP_4096_SHA512: RSA OAEP with SHA-512
        - RSA_DECRYPT_OAEP_2048_SHA1, RSA_DECRYPT_OAEP_3072_SHA1, RSA_DECRYPT_OAEP_4096_SHA1: RSA OAEP with SHA-1
        
        Elliptic Curve Algorithms:
        - EC_SIGN_P256_SHA256: ECDSA with P-256 curve and SHA-256
        - EC_SIGN_P384_SHA384: ECDSA with P-384 curve and SHA-384
        - EC_SIGN_SECP256K1_SHA256: ECDSA with secp256k1 curve and SHA-256
        - EC_SIGN_ED25519: EdDSA with Ed25519 curve
        
        HMAC Algorithms:
        - HMAC_SHA256, HMAC_SHA1, HMAC_SHA384, HMAC_SHA512, HMAC_SHA224: HMAC with various hash functions
        
        External and Post-Quantum:
        - EXTERNAL_SYMMETRIC_ENCRYPTION: External symmetric encryption
        - PQ_SIGN_ML_DSA_65: Post-quantum ML-DSA-65 signing
        - PQ_SIGN_SLH_DSA_SHA2_128S: Post-quantum SLH-DSA-SHA2-128s signing
        """
    
    class CryptoKeyVersionState:
        """
        State of a CryptoKeyVersion.
        
        Values:
        - CRYPTO_KEY_VERSION_STATE_UNSPECIFIED: Unspecified state
        - PENDING_GENERATION: Still being generated
        - ENABLED: Available for cryptographic operations
        - DISABLED: Not usable but key material available
        - DESTROYED: Key material destroyed
        - DESTROY_SCHEDULED: Scheduled for destruction
        - PENDING_IMPORT: Still being imported
        - IMPORT_FAILED: Import failed
        - GENERATION_FAILED: Generation failed
        - PENDING_EXTERNAL_DESTRUCTION: Destroyed, waiting for external confirmation
        - EXTERNAL_DESTRUCTION_FAILED: External destruction failed
        """
    
    class CryptoKeyVersionView:
        """
        View level for CryptoKeyVersion details.
        
        Values:
        - CRYPTO_KEY_VERSION_VIEW_UNSPECIFIED: Default view
        - FULL: Full view including attestation data
        """

class CryptoKeyVersionTemplate:
    """
    Template for creating new CryptoKeyVersions.
    
    Attributes:
    - protection_level: ProtectionLevel - Protection level for new versions
    - algorithm: CryptoKeyVersionAlgorithm - Algorithm for new versions
    """

class ProtectionLevel:
    """
    Protection level for cryptographic operations.
    
    Values:
    - PROTECTION_LEVEL_UNSPECIFIED: Not specified
    - SOFTWARE: Crypto operations performed in software
    - HSM: Crypto operations performed in Hardware Security Module
    - EXTERNAL: Crypto operations performed by external key manager
    - EXTERNAL_VPC: Crypto operations performed in EKM-over-VPC backend
    """

class AccessReason:
    """
    Reason for accessing cryptographic key material.
    
    Values:
    - REASON_UNSPECIFIED: Unspecified access reason
    - CUSTOMER_INITIATED_SUPPORT: Customer-initiated support case
    - GOOGLE_INITIATED_SERVICE: Google-initiated system management access
    - THIRD_PARTY_DATA_REQUEST: Google-initiated legal request response
    - GOOGLE_INITIATED_REVIEW: Google-initiated security/fraud/compliance access
    - CUSTOMER_INITIATED_ACCESS: Customer account access
    - GOOGLE_INITIATED_SYSTEM_OPERATION: Google systems optimization access
    - REASON_NOT_EXPECTED: No reason expected for this operation
    - MODIFIED_CUSTOMER_INITIATED_ACCESS: Customer access with recent admin reset/emergency operation
    - MODIFIED_GOOGLE_INITIATED_SYSTEM_OPERATION: Google system access with recent admin reset/emergency operation
    - GOOGLE_RESPONSE_TO_PRODUCTION_ALERT: Google-initiated system reliability access
    - CUSTOMER_AUTHORIZED_WORKFLOW_SERVICING: Workflow servicing with technical issue
    """

class KeyAccessJustificationsPolicy:
    """
    Policy specifying allowed access reasons for key material.
    
    Attributes:
    - allowed_access_reasons: List[AccessReason] - List of allowed access reasons
    """

class KeyOperationAttestation:
    """
    HSM-generated attestation about key operations.
    
    Attributes:
    - format: AttestationFormat - Format of the attestation data
    - content: bytes - Attestation content
    - cert_chains: CertificateChains - Certificate chains for verification
    """
    
    class AttestationFormat:
        """
        Format of HSM attestation data.
        
        Values:
        - ATTESTATION_FORMAT_UNSPECIFIED: Unspecified format
        - CAVIUM_V1_COMPRESSED: Cavium HSM attestation compressed with gzip
        - CAVIUM_V2_COMPRESSED: Cavium HSM attestation V2 compressed with gzip
        """
    
    class CertificateChains:
        """
        Certificate chains for attestation verification.
        
        Attributes:
        - cavium_certs: List[str] - Cavium HSM certificate chain
        - google_card_certs: List[str] - Google Card certificate chain
        - google_partition_certs: List[str] - Google Partition certificate chain
        """

class PublicKey:
    """
    Public key information for asymmetric CryptoKeyVersions.
    
    Attributes:
    - pem: str - PEM-encoded public key
    - algorithm: CryptoKeyVersionAlgorithm - Cryptographic algorithm
    - pem_crc32c: int - CRC32C checksum of PEM data
    - name: str - Resource name of the CryptoKeyVersion
    - protection_level: ProtectionLevel - Protection level
    """
    
    class PublicKeyFormat:
        """
        Format for public key encoding.
        
        Values:
        - PUBLIC_KEY_FORMAT_UNSPECIFIED: Unspecified format
        - PEM: Privacy-Enhanced Mail format
        - NIST_PQC: NIST Post-Quantum Cryptography format
        """

class ImportJob:
    """
    Job for importing pre-existing key material into Google Cloud KMS.
    
    Attributes:
    - name: str - Resource name
    - import_method: ImportMethod - Method for importing key material
    - protection_level: ProtectionLevel - Protection level for imported keys
    - create_time: Timestamp - Creation timestamp
    - generate_time: Timestamp - Wrapping key generation timestamp
    - expire_time: Timestamp - Expiration timestamp
    - expire_event_time: Timestamp - Event that triggered expiration
    - state: ImportJobState - Current state
    - public_key: WrappingPublicKey - Public key for wrapping key material
    - attestation: KeyOperationAttestation - HSM attestation
    """
    
    class ImportMethod:
        """
        Method for importing wrapped key material.
        
        Values:
        - IMPORT_METHOD_UNSPECIFIED: Unspecified method
        - RSA_OAEP_3072_SHA1_AES_256: RSA AES key wrap with 3072-bit RSA and SHA-1
        - RSA_OAEP_4096_SHA1_AES_256: RSA AES key wrap with 4096-bit RSA and SHA-1
        - RSA_OAEP_3072_SHA256_AES_256: RSA AES key wrap with 3072-bit RSA and SHA-256
        - RSA_OAEP_4096_SHA256_AES_256: RSA AES key wrap with 4096-bit RSA and SHA-256
        - RSA_OAEP_3072_SHA256: RSAES-OAEP with 3072-bit RSA and SHA-256
        - RSA_OAEP_4096_SHA256: RSAES-OAEP with 4096-bit RSA and SHA-256
        """
    
    class ImportJobState:
        """
        State of an ImportJob.
        
        Values:
        - IMPORT_JOB_STATE_UNSPECIFIED: Unspecified state
        - PENDING_GENERATION: Wrapping key being generated
        - ACTIVE: Ready for key import operations
        - EXPIRED: No longer usable for imports
        """
    
    class WrappingPublicKey:
        """
        Public key component of wrapping key for import operations.
        
        Attributes:
        - pem: str - PEM-encoded public key
        """

class ExternalProtectionLevelOptions:
    """
    Configuration options for external protection levels.
    
    Attributes:
    - external_key_uri: str - URI of the external key
    - ekm_connection_key_path: str - Path to key in EKM connection
    """

class ChecksummedData:
    """
    Data with integrity verification field.
    
    Attributes:
    - data: bytes - Raw data
    - crc32c: int - CRC32C checksum of data
    """

class Digest:
    """
    Cryptographic message digest for signing operations.
    
    Attributes:
    - sha256: bytes - SHA-256 digest
    - sha384: bytes - SHA-384 digest
    - sha512: bytes - SHA-512 digest
    """

class LocationMetadata:
    """
    Cloud KMS metadata for geographical locations.
    
    Attributes:
    - hsm_available: bool - Whether HSM protection is available
    - ekm_available: bool - Whether EKM protection is available
    """

class ListKeyRingsRequest:
    """
    Request to list KeyRings in a location.
    
    Attributes:
    - parent: str - Required. Location path
    - page_size: int - Optional. Maximum results per page (1-1000)
    - page_token: str - Optional. Pagination token
    - filter: str - Optional. Filter expression
    - order_by: str - Optional. Sorting order
    """

class ListKeyRingsResponse:
    """
    Response from listing KeyRings.
    
    Attributes:
    - key_rings: List[KeyRing] - List of KeyRing objects
    - next_page_token: str - Token for next page
    - total_size: int - Total number of key rings
    """

class EncryptRequest:
    """
    Request to encrypt data.
    
    Attributes:
    - name: str - Required. CryptoKey or CryptoKeyVersion resource name
    - plaintext: bytes - Required. Data to encrypt (max 64KiB)
    - additional_authenticated_data: bytes - Optional. AAD for authenticated encryption
    - plaintext_crc32c: int - Optional. CRC32C checksum of plaintext
    - additional_authenticated_data_crc32c: int - Optional. CRC32C checksum of AAD
    """

class EncryptResponse:
    """
    Response from encrypt operation.
    
    Attributes:
    - name: str - CryptoKeyVersion used for encryption
    - ciphertext: bytes - Encrypted data
    - ciphertext_crc32c: int - CRC32C checksum of ciphertext
    - verified_plaintext_crc32c: bool - Whether plaintext checksum was verified
    - verified_additional_authenticated_data_crc32c: bool - Whether AAD checksum was verified
    - protection_level: ProtectionLevel - Protection level used
    """

class DecryptRequest:
    """
    Request to decrypt data.
    
    Attributes:
    - name: str - Required. CryptoKey resource name
    - ciphertext: bytes - Required. Encrypted data
    - additional_authenticated_data: bytes - Optional. AAD used during encryption
    - ciphertext_crc32c: int - Optional. CRC32C checksum of ciphertext
    - additional_authenticated_data_crc32c: int - Optional. CRC32C checksum of AAD
    """

class DecryptResponse:
    """
    Response from decrypt operation.
    
    Attributes:
    - plaintext: bytes - Decrypted data
    - plaintext_crc32c: int - CRC32C checksum of plaintext
    - used_primary: bool - Whether primary version was used
    - protection_level: ProtectionLevel - Protection level used
    """

class AsymmetricSignRequest:
    """
    Request to create asymmetric signature.
    
    Attributes:
    - name: str - Required. CryptoKeyVersion resource name
    - digest: Digest - Optional. Pre-computed digest to sign
    - digest_crc32c: int - Optional. CRC32C checksum of digest
    - data: bytes - Optional. Raw data to sign (alternative to digest)
    - data_crc32c: int - Optional. CRC32C checksum of data
    """

class AsymmetricSignResponse:
    """
    Response from asymmetric sign operation.
    
    Attributes:
    - signature: bytes - Digital signature
    - signature_crc32c: int - CRC32C checksum of signature
    - verified_digest_crc32c: bool - Whether digest checksum was verified
    - verified_data_crc32c: bool - Whether data checksum was verified
    - name: str - CryptoKeyVersion used for signing
    - protection_level: ProtectionLevel - Protection level used
    """

class MacSignRequest:
    """
    Request to create MAC signature.
    
    Attributes:
    - name: str - Required. CryptoKeyVersion resource name
    - data: bytes - Required. Data to sign
    - data_crc32c: int - Optional. CRC32C checksum of data
    """

class MacSignResponse:
    """
    Response from MAC sign operation.
    
    Attributes:
    - name: str - CryptoKeyVersion used for signing
    - mac: bytes - MAC signature
    - mac_crc32c: int - CRC32C checksum of MAC
    - verified_data_crc32c: bool - Whether data checksum was verified
    - protection_level: ProtectionLevel - Protection level used
    """

class MacVerifyRequest:
    """
    Request to verify MAC signature.
    
    Attributes:
    - name: str - Required. CryptoKeyVersion resource name
    - data: bytes - Required. Original data
    - data_crc32c: int - Optional. CRC32C checksum of data
    - mac: bytes - Required. MAC signature to verify
    - mac_crc32c: int - Optional. CRC32C checksum of MAC
    """

class MacVerifyResponse:
    """
    Response from MAC verify operation.
    
    Attributes:
    - name: str - CryptoKeyVersion used for verification
    - success: bool - Whether MAC verification succeeded
    - verified_data_crc32c: bool - Whether data checksum was verified
    - verified_mac_crc32c: bool - Whether MAC checksum was verified
    - verified_success_integrity: bool - Whether success field integrity was verified
    - protection_level: ProtectionLevel - Protection level used
    """

class GenerateRandomBytesRequest:
    """
    Request to generate random bytes.
    
    Attributes:
    - location: str - Required. Location path for randomness generation
    - length_bytes: int - Required. Number of random bytes to generate (1-1024)
    - protection_level: ProtectionLevel - Optional. Protection level for randomness generation
    """

class GenerateRandomBytesResponse:
    """
    Response from random bytes generation.
    
    Attributes:
    - data: bytes - Generated random data
    - data_crc32c: int - CRC32C checksum of data
    - verified_data_crc32c: bool - Whether data checksum was verified
    """

from google.cloud import kms

# Use enums for type safety
purpose = kms.CryptoKey.CryptoKeyPurpose.ENCRYPT_DECRYPT
algorithm = kms.CryptoKeyVersion.CryptoKeyVersionAlgorithm.AES_256_GCM
protection_level = kms.ProtectionLevel.HSM

# Create crypto key with specific configuration
crypto_key = kms.CryptoKey()
crypto_key.purpose = purpose
crypto_key.version_template = kms.CryptoKeyVersionTemplate()
crypto_key.version_template.algorithm = algorithm
crypto_key.version_template.protection_level = protection_level

from google.cloud import kms

def validate_crypto_key_purpose(purpose_value):
    """Validate CryptoKey purpose value."""
    valid_purposes = [
        kms.CryptoKey.CryptoKeyPurpose.ENCRYPT_DECRYPT,
        kms.CryptoKey.CryptoKeyPurpose.ASYMMETRIC_SIGN,
        kms.CryptoKey.CryptoKeyPurpose.ASYMMETRIC_DECRYPT,
        kms.CryptoKey.CryptoKeyPurpose.RAW_ENCRYPT_DECRYPT,
        kms.CryptoKey.CryptoKeyPurpose.MAC,
    ]
    return purpose_value in valid_purposes

# Use in key creation
purpose = kms.CryptoKey.CryptoKeyPurpose.ENCRYPT_DECRYPT
if validate_crypto_key_purpose(purpose):
    crypto_key = kms.CryptoKey(purpose=purpose)

from google.cloud import kms

# Create comprehensive key access justification policy
access_policy = kms.KeyAccessJustificationsPolicy()
access_policy.allowed_access_reasons = [
    kms.AccessReason.CUSTOMER_INITIATED_SUPPORT,
    kms.AccessReason.CUSTOMER_INITIATED_ACCESS,
    kms.AccessReason.GOOGLE_INITIATED_SYSTEM_OPERATION,
]

# Create crypto key with access policy
crypto_key = kms.CryptoKey()
crypto_key.purpose = kms.CryptoKey.CryptoKeyPurpose.ENCRYPT_DECRYPT
crypto_key.key_access_justifications_policy = access_policy

# Create external protection configuration
external_options = kms.ExternalProtectionLevelOptions()
external_options.external_key_uri = "https://external-kms.example.com/keys/my-key"
external_options.ekm_connection_key_path = "/path/to/key"

# Use in version template
version_template = kms.CryptoKeyVersionTemplate()
version_template.protection_level = kms.ProtectionLevel.EXTERNAL
version_template.algorithm = kms.CryptoKeyVersion.CryptoKeyVersionAlgorithm.EXTERNAL_SYMMETRIC_ENCRYPTION

crypto_key.version_template = version_template