REST Resource: projects.cryptoKeys

Recurso: CryptoKey

Um CryptoKey representa uma chave lógica que pode ser usada em operações criptográficas.

Uma CryptoKey é composta por zero ou mais versions, que representam o material de chave real usado em operações criptográficas.

Representação JSON
{
  "name": string,
  "primary": {
    object (CryptoKeyVersion)
  },
  "purpose": enum (CryptoKeyPurpose),
  "createTime": string,
  "nextRotationTime": string,
  "versionTemplate": {
    object (CryptoKeyVersionTemplate)
  },
  "labels": {
    string: string,
    ...
  },
  "importOnly": boolean,
  "destroyScheduledDuration": string,
  "cryptoKeyBackend": string,

  // Union field rotation_schedule can be only one of the following:
  "rotationPeriod": string
  // End of list of possible types for union field rotation_schedule.
}
Campos
name

string

Apenas saída. O nome do recurso para CryptoKey no formato projects/*/locations/*/keyRings/*/cryptoKeys/*.

primary

object (CryptoKeyVersion)

Apenas saída. Uma cópia do CryptoKeyVersion "principal" que será usado por [Encrypt][KeyManagementService.Encrypt] quando esse CryptoKey for fornecido em [EncryptRequest.name][].

A versão principal do CryptoKey pode ser atualizada via [UpdateCryptoKeyPrimaryVersion][KeyManagementService.UpdateCryptoKeyPrimaryVersion].

As chaves com purpose ENCRYPT_DECRYPT podem ter uma primária. Para outras chaves, esse campo será omitido.

purpose

enum (CryptoKeyPurpose)

Imutável. O propósito imutável desse CryptoKey.

createTime

string (Timestamp format)

Apenas saída. A hora em que este CryptoKey foi criado.

Um carimbo de data/hora no formato RFC3339 UTC "Zulu", com resolução de nanossegundos e até nove dígitos fracionários. Exemplos: "2014-10-02T15:01:23Z" e "2014-10-02T15:01:23.045123456Z".

nextRotationTime

string (Timestamp format)

Em nextRotationTime, o serviço de gerenciamento de chaves automaticamente:

  1. Crie uma nova versão desta CryptoKey.
  2. Marcar uma nova versão como principal.

As rotações de chaves realizadas manualmente via [Createxliff][KeyManagementService.Createxliff] e [UpdateCryptoKeyPrimaryVersion][KeyManagementService.UpdateCryptoKeyPrimaryVersion] não afetam o nextRotationTime.

As chaves com purpose ENCRYPT_DECRYPT oferecem suporte à rotação automática. Para outras chaves, esse campo precisa ser omitido.

Um carimbo de data/hora no formato RFC3339 UTC "Zulu", com resolução de nanossegundos e até nove dígitos fracionários. Exemplos: "2014-10-02T15:01:23Z" e "2014-10-02T15:01:23.045123456Z".

versionTemplate

object (CryptoKeyVersionTemplate)

Um modelo que descreve as configurações para novas instâncias de CryptoKeyVersion. As propriedades de novas instâncias do CryptoKeyVersion criadas por [CreateCryptoKey][KeyManagementService.Create particular] ou pela rotação automática são controladas por esse modelo.

labels

map (key: string, value: string)

Rótulos com metadados definidos pelo usuário. Para mais informações, consulte Como rotular chaves.

importOnly

boolean

Imutável. Indica se esta chave pode conter apenas versões importadas.

destroyScheduledDuration

string (Duration format)

Imutável. O período em que as versões dessa chave ficam no estado DESTROY_SCHEDULED antes da transição para DESTROYED. Se não for especificada no momento da criação, a duração padrão será de 24 horas.

Duração em segundos com até nove dígitos fracionários, terminando em "s". Exemplo: "3.5s".

cryptoKeyBackend

string

Imutável. O nome do recurso do ambiente de back-end onde reside o material da chave de todos os CryptoKeyVersions associados a este CryptoKey e onde todas as operações criptográficas relacionadas são realizadas. Aplicável somente se CryptoKeyVersions tiver um ProtectionLevel de [EXTERNAL_VPC][CryptoKey.ProtectionLevel.EXTERNAL_VPC], com o nome do recurso no formato projects/*/locations/*/ekmConnections/*. Essa lista não é completa e pode se aplicar a outros ProtectionLevels no futuro.

Campo de união rotation_schedule. Controla a taxa de rotação automática. rotation_schedule só pode ser de um dos seguintes tipos:
rotationPeriod

string (Duration format)

O nextRotationTime será adiantado por este período quando o serviço fizer a rotação de uma chave automaticamente. Precisa ser pelo menos 24 horas e no máximo 876.000 horas.

Se rotationPeriod for definido, nextRotationTime também vai precisar ser.

As chaves com purpose ENCRYPT_DECRYPT oferecem suporte à rotação automática. Para outras chaves, esse campo precisa ser omitido.

Duração em segundos com até nove dígitos fracionários, terminando em "s". Exemplo: "3.5s".

CryptoKeyVersion

Um CryptoKeyVersion representa uma chave criptográfica individual e o material de chave associado.

Uma versão ENABLED pode ser usada em operações criptográficas.

Por motivos de segurança, o material bruto da chave criptográfica representado por CryptoKeyVersion nunca pode ser visualizado nem exportado. Ele só pode ser usado para criptografar, descriptografar ou assinar dados quando um usuário ou aplicativo autorizado invoca o Cloud KMS.

Representação JSON
{
  "name": string,
  "state": enum (CryptoKeyVersionState),
  "protectionLevel": enum (ProtectionLevel),
  "algorithm": enum (CryptoKeyVersionAlgorithm),
  "attestation": {
    object (KeyOperationAttestation)
  },
  "createTime": string,
  "generateTime": string,
  "destroyTime": string,
  "destroyEventTime": string,
  "importJob": string,
  "importTime": string,
  "importFailureReason": string,
  "generationFailureReason": string,
  "externalDestructionFailureReason": string,
  "externalProtectionLevelOptions": {
    object (ExternalProtectionLevelOptions)
  },
  "reimportEligible": boolean
}
Campos
name

string

Apenas saída. O nome do recurso para CryptoKeyVersion no formato projects/*/locations/*/keyRings/*/cryptoKeys/*/cryptoKeyVersions/*.

state

enum (CryptoKeyVersionState)

O estado atual da CryptoKeyVersion.

protectionLevel

enum (ProtectionLevel)

Apenas saída. O ProtectionLevel que descreve como as operações de criptografia são executadas com esse CryptoKeyVersion.

algorithm

enum (CryptoKeyVersionAlgorithm)

Apenas saída. O CryptoKeyVersionAlgorithm com suporte dessa CryptoKeyVersion.

attestation

object (KeyOperationAttestation)

Apenas saída. Instrução que foi gerada e assinada pelo HSM no momento da criação da chave. Use essa instrução para verificar os atributos da chave conforme armazenados no HSM, independentemente do Google. Fornecido apenas para versões de chave com protectionLevel HSM.

createTime

string (Timestamp format)

Apenas saída. A hora em que este CryptoKeyVersion foi criado.

Um carimbo de data/hora no formato RFC3339 UTC "Zulu", com resolução de nanossegundos e até nove dígitos fracionários. Exemplos: "2014-10-02T15:01:23Z" e "2014-10-02T15:01:23.045123456Z".

generateTime

string (Timestamp format)

Apenas saída. A hora em que o material de chave deste CryptoKeyVersion foi gerado.

Um carimbo de data/hora no formato RFC3339 UTC "Zulu", com resolução de nanossegundos e até nove dígitos fracionários. Exemplos: "2014-10-02T15:01:23Z" e "2014-10-02T15:01:23.045123456Z".

destroyTime

string (Timestamp format)

Apenas saída. A hora em que a destruição do material da chave deste CryptoKeyVersion está programada. Presente apenas se state for DESTROY_SCHEDULED.

Um carimbo de data/hora no formato RFC3339 UTC "Zulu", com resolução de nanossegundos e até nove dígitos fracionários. Exemplos: "2014-10-02T15:01:23Z" e "2014-10-02T15:01:23.045123456Z".

destroyEventTime

string (Timestamp format)

Apenas saída. O horário de destruição do material da chave desta CryptoKeyVersion. Presente apenas se state for DESTROYED.

Um carimbo de data/hora no formato RFC3339 UTC "Zulu", com resolução de nanossegundos e até nove dígitos fracionários. Exemplos: "2014-10-02T15:01:23Z" e "2014-10-02T15:01:23.045123456Z".

importJob

string

Apenas saída. O nome do ImportJob usado na importação mais recente desse CryptoKeyVersion. Presente apenas se o material da chave subjacente tiver sido importado.

importTime

string (Timestamp format)

Apenas saída. A hora em que o material da chave deste CryptoKeyVersion foi importado mais recentemente.

Um carimbo de data/hora no formato RFC3339 UTC "Zulu", com resolução de nanossegundos e até nove dígitos fracionários. Exemplos: "2014-10-02T15:01:23Z" e "2014-10-02T15:01:23.045123456Z".

importFailureReason

string

Apenas saída. A causa raiz da falha de importação mais recente. Presente apenas se state for IMPORT_FAILED.

generationFailureReason

string

Apenas saída. A causa raiz da falha de geração mais recente. Presente apenas se state for GENERATION_FAILED.

externalDestructionFailureReason

string

Apenas saída. A causa raiz da falha de destruição externa mais recente. Presente apenas se state for EXTERNAL_DESTRUCTION_FAILED.

externalProtectionLevelOptions

object (ExternalProtectionLevelOptions)

O ExternalProtectionLevelOptions armazena um grupo de campos adicionais para configurar um CryptoKeyVersion específico para os níveis de proteção EXTERNAL e EXTERNAL_VPC.

reimportEligible

boolean

Apenas saída. Indica se esta versão da chave está qualificada para reimportação, sendo especificada como um destino em [ImportCryptoKeyRequest.crypto_key_version][].

CryptoKeyVersionState

O estado de uma CryptoKeyVersion, indicando se ela pode ser usada.

Tipos enumerados
CRYPTO_KEY_VERSION_STATE_UNSPECIFIED Não especificado.
PENDING_GENERATION Esta versão ainda está sendo gerada. Ela ainda não pode ser usada, ativada, desativada ou destruída. O Cloud KMS marcará automaticamente essa versão como ENABLED assim que ela estiver pronta.
ENABLED Esta versão pode ser usada em operações criptográficas.
DISABLED Esta versão não pode ser usada, mas o material da chave ainda está disponível, e a versão pode voltar ao estado ENABLED.
DESTROYED Esta versão foi destruída e o material da chave não está mais armazenado Esta versão só poderá se tornar ENABLED novamente se for reimportEligible e o material da chave original for reimportado com uma chamada para [KeyManagementService.Import adquirir][].
DESTROY_SCHEDULED Esta versão está programada para destruição e será destruída em breve. Chame [RestoreChromeVox][KeyManagementService.Restore veiculação] para colocá-la no estado DISABLED novamente.
PENDING_IMPORT Esta versão ainda está sendo importada. Ela ainda não pode ser usada, ativada, desativada ou destruída. O Cloud KMS marcará automaticamente essa versão como ENABLED assim que ela estiver pronta.
IMPORT_FAILED Esta versão não foi importada com sucesso. Ela não pode ser usada, ativada, desativada ou destruída. O material de chave enviado foi descartado. Mais detalhes podem ser encontrados em CryptoKeyVersion.import_failure_reason.
GENERATION_FAILED Esta versão não foi gerada. Ela não pode ser usada, ativada, desativada ou destruída. Mais detalhes podem ser encontrados em CryptoKeyVersion.generation_failure_reason.
PENDING_EXTERNAL_DESTRUCTION Esta versão foi destruída e não pode ser usada ou ativada novamente. O Cloud KMS está aguardando a destruição do material da chave correspondente que está em um gerenciador de chaves externo.
EXTERNAL_DESTRUCTION_FAILED Esta versão foi destruída e não pode ser usada ou ativada novamente. No entanto, o Cloud KMS não conseguiu confirmar se o material de chave correspondente que reside em um gerenciador de chaves externo foi destruído. Mais detalhes podem ser encontrados em CryptoKeyVersion.external_destruction_failure_reason.

ProtectionLevel

O ProtectionLevel especifica como as operações criptográficas são realizadas. Para mais informações, consulte Níveis de proteção.

Tipos enumerados
PROTECTION_LEVEL_UNSPECIFIED Não especificado.
SOFTWARE As operações de criptografia são executadas no software.
HSM As operações de criptografia são realizadas em um módulo de segurança de hardware.
EXTERNAL As operações de criptografia são executadas por um gerenciador de chaves externo.
EXTERNAL_VPC As operações de criptografia são executadas em um back-end de EKM sobre VPC.

CryptoKeyVersionAlgorithm

O algoritmo da CryptoKeyVersion, indicando quais parâmetros precisam ser usados em cada operação criptográfica.

O algoritmo GOOGLE_SYMMETRIC_ENCRYPTION pode ser usado com CryptoKey.purpose ENCRYPT_DECRYPT.

Algoritmos que começam com "RSA_SIGN_" podem ser usados com CryptoKey.purpose ASYMMETRIC_SIGN.

Os campos no nome após "RSA_SIGN_" correspondem aos seguintes parâmetros: algoritmo de preenchimento, comprimento de bit de módulo e algoritmo de resumo.

Para PSS, o comprimento do sal usado é igual ao do algoritmo de resumo. Por exemplo, RSA_SIGN_PSS_2048_SHA256 usará o PSS com um comprimento de sal de 256 bits ou 32 bytes.

Algoritmos que começam com "RSA_DECRYPT_" podem ser usados com CryptoKey.purpose ASYMMETRIC_DECRYPT.

Os campos no nome após "RSA_DECRYPT_" correspondem aos seguintes parâmetros: algoritmo de preenchimento, comprimento de bit de módulo e algoritmo de resumo.

Algoritmos que começam com "EC_SIGN_" podem ser usados com CryptoKey.purpose ASYMMETRIC_SIGN.

Os campos no nome após "EC_SIGN_" correspondem aos seguintes parâmetros: curva elíptica e algoritmo de resumo.

Algoritmos que começam com "HMAC_" podem ser usados com CryptoKey.purpose MAC.

O sufixo após "HMAC_" corresponde ao algoritmo de hash usado (por exemplo, SHA256).

Para mais informações, consulte Algoritmos e finalidades de chave.

Tipos enumerados
CRYPTO_KEY_VERSION_ALGORITHM_UNSPECIFIED Não especificado.
GOOGLE_SYMMETRIC_ENCRYPTION Cria chaves de criptografia simétricas.
RSA_SIGN_PSS_2048_SHA256 Chave RSASSA-PSS de 2.048 bits com um resumo SHA256.
RSA_SIGN_PSS_3072_SHA256 Chave RSASSA-PSS de 3.072 bits com um resumo SHA256.
RSA_SIGN_PSS_4096_SHA256 Chave RSASSA-PSS de 4.096 bits com um resumo SHA256.
RSA_SIGN_PSS_4096_SHA512 Chave RSASSA-PSS de 4.096 bits com um resumo SHA512.
RSA_SIGN_PKCS1_2048_SHA256 RSASSA-PKCS1-v1_5 com uma chave de 2.048 bits e um resumo SHA256.
RSA_SIGN_PKCS1_3072_SHA256 RSASSA-PKCS1-v1_5 com uma chave de 3.072 bits e um resumo SHA256.
RSA_SIGN_PKCS1_4096_SHA256 RSASSA-PKCS1-v1_5 com uma chave de 4.096 bits e um resumo SHA256.
RSA_SIGN_PKCS1_4096_SHA512 RSASSA-PKCS1-v1_5 com uma chave de 4.096 bits e um resumo SHA512.
RSA_SIGN_RAW_PKCS1_2048 Assinatura RSASSA-PKCS1-v1_5 sem codificação, com uma chave de 2.048 bits.
RSA_SIGN_RAW_PKCS1_3072 Assinatura RSASSA-PKCS1-v1_5 sem codificação, com uma chave de 3.072 bits.
RSA_SIGN_RAW_PKCS1_4096 Assinatura RSASSA-PKCS1-v1_5 sem codificação, com uma chave de 4.096 bits.
RSA_DECRYPT_OAEP_2048_SHA256 Chave RSAES-OAEP de 2.048 bits com um resumo SHA256.
RSA_DECRYPT_OAEP_3072_SHA256 Chave RSAES-OAEP de 3.072 bits com um resumo SHA256.
RSA_DECRYPT_OAEP_4096_SHA256 Chave RSAES-OAEP de 4.096 bits com um resumo SHA256.
RSA_DECRYPT_OAEP_4096_SHA512 Chave RSAES-OAEP de 4.096 bits com um resumo SHA512.
RSA_DECRYPT_OAEP_2048_SHA1 Chave RSAES-OAEP de 2.048 bits com um resumo SHA1.
RSA_DECRYPT_OAEP_3072_SHA1 Chave RSAES-OAEP de 3.072 bits com um resumo SHA1.
RSA_DECRYPT_OAEP_4096_SHA1 Chave RSAES-OAEP de 4.096 bits com um resumo SHA1.
EC_SIGN_P256_SHA256 ECDSA na curva NIST P-256 com um resumo SHA256. Também é possível usar outras funções hash: https://cloud.google.com/kms/docs/create-validate-signatures#ecdsa_support_for_other_hash_algorithms
EC_SIGN_P384_SHA384 ECDSA na curva NIST P-384 com um resumo SHA384. Também é possível usar outras funções hash: https://cloud.google.com/kms/docs/create-validate-signatures#ecdsa_support_for_other_hash_algorithms
EC_SIGN_SECP256K1_SHA256 ECDSA na curva secp256k1 não NIST. Essa curva só é compatível com o nível de proteção do HSM. Também é possível usar outras funções hash: https://cloud.google.com/kms/docs/create-validate-signatures#ecdsa_support_for_other_hash_algorithms
HMAC_SHA256 Assinatura HMAC-SHA256 com uma chave de 256 bits.
HMAC_SHA1 Assinatura HMAC-SHA1 com uma chave de 160 bits.
HMAC_SHA384 Assinatura HMAC-SHA384 com uma chave de 384 bits.
HMAC_SHA512 Assinatura HMAC-SHA512 com uma chave de 512 bits.
HMAC_SHA224 Assinatura HMAC-SHA224 com uma chave de 224 bits.
EXTERNAL_SYMMETRIC_ENCRYPTION Algoritmo que representa a criptografia simétrica por um gerenciador de chaves externo.

KeyOperationAttestation

Contém um atestado gerado pelo HSM sobre uma operação de chave. Para saber mais, consulte Como verificar atestados.

Representação JSON
{
  "format": enum (AttestationFormat),
  "content": string,
  "certChains": {
    object (CertificateChains)
  }
}
Campos
format

enum (AttestationFormat)

Apenas saída. O formato dos dados do atestado.

content

string (bytes format)

Apenas saída. Os dados do atestado fornecidos pelo HSM quando a operação de chave foi executada.

Uma string codificada em base64.

certChains

object (CertificateChains)

Apenas saída. As cadeias de certificados necessárias para validar o atestado

AttestationFormat

Formatos de atestado fornecidos pelo HSM.

Tipos enumerados
ATTESTATION_FORMAT_UNSPECIFIED Não especificado.
CAVIUM_V1_COMPRESSED

Atestado do HSM do Cavium compactado usando gzip. Esse formato é definido pelo Cavium e está sujeito a alterações a qualquer momento.

Consulte https://www.marvell.com/products/security-solutions/nitrox-hs-adapters/software-key-attestation.html.

CAVIUM_V2_COMPRESSED Atestado de HSM V2 do Cavium compactado com gzip. Esse é um novo formato introduzido na versão 3.2-08 do Cavium.

CertificateChains

Cadeias de certificados necessárias para verificar o atestado. Os certificados em cadeias são codificados por PEM e ordenados com base em https://tools.ietf.org/html/rfc5246#section-7.4.2.

Representação JSON
{
  "caviumCerts": [
    string
  ],
  "googleCardCerts": [
    string
  ],
  "googlePartitionCerts": [
    string
  ]
}
Campos
caviumCerts[]

string

Cadeia de certificados Cavium correspondente ao atestado.

googleCardCerts[]

string

Cadeia de certificados de cartão do Google correspondente ao atestado.

googlePartitionCerts[]

string

Cadeia de certificados de partição do Google correspondente ao atestado.

ExternalProtectionLevelOptions

O ExternalProtectionLevelOptions armazena um grupo de campos adicionais para configurar um CryptoKeyVersion específico para os níveis de proteção EXTERNAL e EXTERNAL_VPC.

Representação JSON
{
  "externalKeyUri": string,
  "ekmConnectionKeyPath": string
}
Campos
externalKeyUri

string

O URI de um recurso externo que este CryptoKeyVersion representa.

ekmConnectionKeyPath

string

O caminho para o material da chave externa no EKM ao usar [EkmConnection][]. Por exemplo, "v0/my/key". Defina este campo em vez de externalKeyUri ao usar uma [EkmConnection][].

CryptoKeyPurpose

CryptoKeyPurpose descreve os recursos criptográficos de uma CryptoKey. Uma determinada chave apenas pode ser usada nas operações permitidas pela finalidade dela. Para mais informações, consulte Finalidades de chave.

Tipos enumerados
CRYPTO_KEY_PURPOSE_UNSPECIFIED Não especificado.
ENCRYPT_DECRYPT CryptoKeys com essa finalidade pode ser usado com [Encrypt][KeyManagementService.Encrypt] e [Decrypt][KeyManagementService.Decrypt].
ASYMMETRIC_SIGN CryptoKeys com essa finalidade pode ser usado com [AsymmetricSign][KeyManagementService.AsymmetricSign] e [GetPublicKey][KeyManagementService.GetPublicKey].
ASYMMETRIC_DECRYPT CryptoKeys com essa finalidade pode ser usado com [AsymmetricDecrypt][KeyManagementService.AsymmetricDecrypt] e [GetPublicKey][KeyManagementService.GetPublicKey].
MAC O CryptoKeys com essa finalidade pode ser usado com [MacSign][KeyManagementService.MacSign].

CryptoKeyVersionTemplate

Um CryptoKeyVersionTemplate especifica as propriedades a serem usadas ao criar um novo CryptoKeyVersion, seja manualmente com [CreateCryptoKey][KeyManagementService.CreateLatLng] ou automaticamente como resultado da rotação automática.

Representação JSON
{
  "protectionLevel": enum (ProtectionLevel),
  "algorithm": enum (CryptoKeyVersionAlgorithm)
}
Campos
protectionLevel

enum (ProtectionLevel)

ProtectionLevel a ser usado ao criar um CryptoKeyVersion com base nesse modelo. Imutável. O padrão é SOFTWARE.

algorithm

enum (CryptoKeyVersionAlgorithm)

Obrigatório. Algorithm a ser usado ao criar um CryptoKeyVersion com base nesse modelo.

Para compatibilidade com versões anteriores, GOOGLE_SYMMETRIC_ENCRYPTION estará implícito se esse campo for omitido e CryptoKey.purpose for ENCRYPT_DECRYPT.

Métodos

list

Retorna chaves criptográficas gerenciadas pelo Cloud KMS em um determinado projeto do Cloud.