REST Resource: projects.cryptoKeys

资源：CryptoKey

CryptoKey 表示可用于加密操作的逻辑密钥。

CryptoKey 由零个或多个 versions 组成，它们表示加密操作中使用的实际密钥材料。

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.
}
字段
name

string

仅限输出。此 CryptoKey 的资源名称，格式为：projects/*/locations/*/keyRings/*/cryptoKeys/*。
primary

object (CryptoKeyVersion)

仅限输出。在 [EncryptRequest.name][] 中授予此 CryptoKey 后，[Encrypt][KeyManagementService.Encrypt] 将使用“主”CryptoKeyVersion 的副本。

CryptoKey 的主要版本可通过 [UpdateCryptoKeyPrimaryVersion][KeyManagementService.UpdateCryptoKeyPrimaryVersion] 更新。

具有 purpose ENCRYPT_DECRYPT 的键可能具有主键。对于其他密钥，该字段将被省略。
purpose

enum (CryptoKeyPurpose)

不可变。此 CryptoKey 的不可变用途。
createTime

string (Timestamp format)

仅限输出。此 CryptoKey 的创建时间。

时间戳采用 RFC3339 世界协调时间（UTC，即“祖鲁时”）格式，精确到纳秒，最多九个小数位。示例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
nextRotationTime

string (Timestamp format)

在 nextRotationTime，密钥管理服务将自动执行以下操作：

  1. 创建此CryptoKey的新版本。
  2. 将新版本标记为主版本。

通过 [CreateCryptoKeyVersion][KeyManagementService.CreateCryptoKeyVersion] 和 [UpdateCryptoKeyPrimaryVersion][KeyManagementService.UpdateCryptoKeyPrimaryVersion] 手动执行的密钥轮替不会影响 nextRotationTime。

具有 purpose ENCRYPT_DECRYPT 的密钥支持自动轮替。对于其他密钥，必须省略该字段。

时间戳采用 RFC3339 世界协调时间（UTC，即“祖鲁时”）格式，精确到纳秒，最多九个小数位。示例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
versionTemplate

object (CryptoKeyVersionTemplate)

描述新 CryptoKeyVersion 实例的设置的模板。[CreateCryptoKeyVersion][KeyManagementService.CreateCryptoKeyVersion] 或自动轮替创建的新 CryptoKeyVersion 实例的属性由此模板控制。
labels

map (key: string, value: string)

包含用户定义的元数据的标签。如需了解详情，请参阅为密钥添加标签。
importOnly

boolean

不可变。此密钥是否只能包含导入的版本。
destroyScheduledDuration

string (Duration format)

不可变。此密钥版本在转换为 DESTROYED 之前处于 DESTROY_SCHEDULED 状态的时长。如果在创建时未指定时长，则默认时长为 24 小时。

该时长以秒为单位，最多包含九个小数位，以“s”结尾。示例："3.5s"。
cryptoKeyBackend

string

不可变。与此 CryptoKey 关联的所有 CryptoKeyVersions 的密钥材料所在的后端环境的资源名称，并执行所有相关的加密操作。仅适用于 CryptoKeyVersions 的 ProtectionLevel 为 [EXTERNAL_VPC][CryptoKeyVersion.ProtectionLevel.EXTERNAL_VPC] 且资源名称格式为 projects/*/locations/*/ekmConnections/* 时。请注意，此列表并非详尽无遗，将来可能会适用于其他ProtectionLevels。
联合字段 rotation_schedule。控制自动轮播的速率。rotation_schedule 只能是下列其中一项：
rotationPeriod

string (Duration format)

当服务自动轮替密钥时，nextRotationTime 将提前此时间段。必须至少为 24 小时，至多为 876,000 小时。

如果设置了 rotationPeriod，则必须同时设置 nextRotationTime。

具有 purpose ENCRYPT_DECRYPT 的密钥支持自动轮替。对于其他密钥，必须省略该字段。

该时长以秒为单位，最多包含九个小数位，以“s”结尾。示例："3.5s"。

CryptoKeyVersion

CryptoKeyVersion 表示单个加密密钥和关联的密钥材料。

ENABLED 版本可用于加密操作。

出于安全考虑，系统永远不能查看或导出由 CryptoKeyVersion 表示的原始加密密钥材料。该材料只能在已获授权的用户或应用调用 Cloud KMS 时用于加密、解密数据或为数据签名。

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
}
字段
name

string

仅限输出。此 CryptoKeyVersion 的资源名称，格式为：projects/*/locations/*/keyRings/*/cryptoKeys/*/cryptoKeyVersions/*。
state

enum (CryptoKeyVersionState)

CryptoKeyVersion 的当前状态。
protectionLevel

enum (ProtectionLevel)

仅限输出。ProtectionLevel，用于描述如何使用此 CryptoKeyVersion 执行加密操作。
algorithm

enum (CryptoKeyVersionAlgorithm)

仅限输出。此 CryptoKeyVersion 支持的 CryptoKeyVersionAlgorithm。
attestation

object (KeyOperationAttestation)

仅限输出。创建密钥时由 HSM 生成和签名的语句。使用此语句可以验证存储在 HSM 上的密钥属性，而不依赖于 Google。仅为具有 protectionLevel HSM 的密钥版本提供。
createTime

string (Timestamp format)

仅限输出。此 CryptoKeyVersion 的创建时间。

时间戳采用 RFC3339 世界协调时间（UTC，即“祖鲁时”）格式，精确到纳秒，最多九个小数位。示例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
generateTime

string (Timestamp format)

仅限输出。生成此 CryptoKeyVersion 的密钥材料的时间。

时间戳采用 RFC3339 世界协调时间（UTC，即“祖鲁时”）格式，精确到纳秒，最多九个小数位。示例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
destroyTime

string (Timestamp format)

仅限输出。安排销毁此 CryptoKeyVersion 的密钥材料的时间。仅当 state 为 DESTROY_SCHEDULED 时，此字段才会显示。

时间戳采用 RFC3339 世界协调时间（UTC，即“祖鲁时”）格式，精确到纳秒，最多九个小数位。示例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
destroyEventTime

string (Timestamp format)

仅限输出。此 CryptoKeyVersion 的密钥材料被销毁的时间。仅当 state 为 DESTROYED 时，此字段才会显示。

时间戳采用 RFC3339 世界协调时间（UTC，即“祖鲁时”）格式，精确到纳秒，最多九个小数位。示例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
importJob

string

仅限输出。最近一次导入此 CryptoKeyVersion 时使用的 ImportJob 的名称。仅当底层密钥材料已导入时，此字段才会显示。
importTime

string (Timestamp format)

仅限输出。此 CryptoKeyVersion 的密钥材料最近一次导入的时间。

时间戳采用 RFC3339 世界协调时间（UTC，即“祖鲁时”）格式，精确到纳秒，最多九个小数位。示例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
importFailureReason

string

仅限输出。最近一次导入失败的根本原因。仅当 state 为 IMPORT_FAILED 时，此字段才会显示。
generationFailureReason

string

仅限输出。最近一次生成失败的根本原因。仅当 state 为 GENERATION_FAILED 时，此字段才会显示。
externalDestructionFailureReason

string

仅限输出。最近一次外部销毁失败的根本原因。仅当 state 为 EXTERNAL_DESTRUCTION_FAILED 时，此字段才会显示。
externalProtectionLevelOptions

object (ExternalProtectionLevelOptions)

ExternalProtectionLevelOptions 会存储一组额外的字段，用于配置特定于 EXTERNAL 保护级别和 EXTERNAL_VPC 保护级别的 CryptoKeyVersion。
reimportEligible

boolean

仅限输出。通过在 [ImportCryptoKeyVersionRequest.crypto_key_version][] 中指定为目标，此密钥版本是否可以重新导入。

CryptoKeyVersionState

CryptoKeyVersion 的状态，指示是否可以使用它。

枚举
CRYPTO_KEY_VERSION_STATE_UNSPECIFIED 未指定。
PENDING_GENERATION 此版本仍在生成中，因此无法使用，也无法启用、停用或销毁。只要此版本可以使用，Cloud KMS 就会自动将其标记为 ENABLED。
ENABLED 此版本可用于加密操作。
DISABLED 此版本无法使用，但密钥材料仍然可用，并且此版本可以重新置于 ENABLED 状态。
DESTROYED 此版本已销毁，密钥材料不再存储在 Cloud KMS 中。仅当此版本为 reimportEligible 且原始密钥材料已通过调用 [KeyManagementService.ImportCryptoKeyVersion][] 重新导入时，此版本才能重新变为 ENABLED。
DESTROY_SCHEDULED 此版本处于已安排销毁状态，并且将很快被销毁。调用 [RestoreCryptoKeyVersion][KeyManagementService.RestoreCryptoKeyVersion]，使其重新处于 DISABLED 状态。
PENDING_IMPORT 此版本仍在导入中。因此无法使用，也无法启用、停用或销毁。只要此版本可以使用，Cloud KMS 就会自动将其标记为 ENABLED。
IMPORT_FAILED 此版本未成功导入。不得使用、启用、停用或销毁。已舍弃提交的密钥材料。如需了解更多详情，请访问 CryptoKeyVersion.import_failure_reason。
GENERATION_FAILED 此版本未成功生成。不得使用、启用、停用或销毁。如需了解更多详情，请访问 CryptoKeyVersion.generation_failure_reason。
PENDING_EXTERNAL_DESTRUCTION 此版本已销毁，无法再使用或启用。Cloud KMS 正在等待销毁外部密钥管理器中的相应密钥材料。
EXTERNAL_DESTRUCTION_FAILED 此版本已销毁，无法再使用或启用。但是，Cloud KMS 无法确认外部密钥管理器中的相应密钥材料是否已销毁。如需了解更多详情，请访问 CryptoKeyVersion.external_destruction_failure_reason。

ProtectionLevel

ProtectionLevel 用于指定加密操作的执行方式。如需了解详情，请参阅保护级别。

枚举
PROTECTION_LEVEL_UNSPECIFIED 未指定。
SOFTWARE 在软件中执行加密操作。
HSM 在硬件安全模块中执行加密操作。
EXTERNAL 加密操作由外部密钥管理器执行。
EXTERNAL_VPC 在 EKM-over-VPC 后端中执行加密操作。

CryptoKeyVersionAlgorithm

CryptoKeyVersion 的算法，指示每个加密操作必须使用哪些参数。

GOOGLE_SYMMETRIC_ENCRYPTION 算法可与 CryptoKey.purpose ENCRYPT_DECRYPT 一起使用。

以“RSA_SIGN_”开头的算法可用于 CryptoKey.purpose ASYMMETRIC_SIGN。

以“RSA_SIGN_”命名的字段对应于以下参数：填充算法、模数位长度和摘要算法。

对于 PSS，使用的盐长度等于摘要算法的长度。例如，RSA_SIGN_PSS_2048_SHA256 将使用盐长度为 256 位或 32 字节的 PSS。

以“RSA_DECRYPT_”开头的算法可用于 CryptoKey.purpose ASYMMETRIC_DECRYPT。

以“RSA_DECRYPT_”命名的字段对应于以下参数：填充算法、模数位长度和摘要算法。

以“EC_SIGN_”开头的算法可用于 CryptoKey.purpose ASYMMETRIC_SIGN。

以“EC_SIGN_”命名的字段对应于以下参数：椭圆曲线、摘要算法。

以“HMAC_”开头的算法可用于 CryptoKey.purpose MAC。

“HMAC_”后面的后缀对应所使用的哈希算法（例如，SHA256）。

如需了解详情，请参阅密钥用途和算法。

枚举
CRYPTO_KEY_VERSION_ALGORITHM_UNSPECIFIED 未指定。
GOOGLE_SYMMETRIC_ENCRYPTION 创建对称加密密钥。
RSA_SIGN_PSS_2048_SHA256 具有 SHA256 摘要的 RSASSA-PSS 2048 位密钥。
RSA_SIGN_PSS_3072_SHA256 具有 SHA256 摘要的 RSASSA-PSS 3072 位密钥。
RSA_SIGN_PSS_4096_SHA256 具有 SHA256 摘要的 RSASSA-PSS 4096 位密钥。
RSA_SIGN_PSS_4096_SHA512 具有 SHA512 摘要的 RSASSA-PSS 4096 位密钥。
RSA_SIGN_PKCS1_2048_SHA256 具有 2048 位密钥和 SHA256 摘要的 RSASSA-PKCS1-v1_5。
RSA_SIGN_PKCS1_3072_SHA256 具有 3072 位密钥和 SHA256 摘要的 RSASSA-PKCS1-v1_5。
RSA_SIGN_PKCS1_4096_SHA256 具有 4096 位密钥和 SHA256 摘要的 RSASSA-PKCS1-v1_5。
RSA_SIGN_PKCS1_4096_SHA512 具有 4096 位密钥和 SHA512 摘要的 RSASSA-PKCS1-v1_5。
RSA_SIGN_RAW_PKCS1_2048 未编码的 RSASSA-PKCS1-v1_5 签名，使用 2048 位密钥。
RSA_SIGN_RAW_PKCS1_3072 无编码的 RSASSA-PKCS1-v1_5 签名，使用 3072 位密钥。
RSA_SIGN_RAW_PKCS1_4096 无编码的 RSASSA-PKCS1-v1_5 签名，使用 4096 位密钥。
RSA_DECRYPT_OAEP_2048_SHA256 具有 SHA256 摘要的 RSAES-OAEP 2048 位密钥。
RSA_DECRYPT_OAEP_3072_SHA256 具有 SHA256 摘要的 RSAES-OAEP 3072 位密钥。
RSA_DECRYPT_OAEP_4096_SHA256 具有 SHA256 摘要的 RSAES-OAEP 4096 位密钥。
RSA_DECRYPT_OAEP_4096_SHA512 具有 SHA512 摘要的 RSAES-OAEP 4096 位密钥。
RSA_DECRYPT_OAEP_2048_SHA1 具有 SHA1 摘要的 RSAES-OAEP 2048 位密钥。
RSA_DECRYPT_OAEP_3072_SHA1 具有 SHA1 摘要的 RSAES-OAEP 3072 位密钥。
RSA_DECRYPT_OAEP_4096_SHA1 具有 SHA1 摘要的 RSAES-OAEP 4096 位密钥。
EC_SIGN_P256_SHA256 具有 SHA256 摘要的 NIST P-256 曲线上的 ECDSA。您还可以使用其他哈希函数：https://cloud.google.com/kms/docs/create-validate-signatures#ecdsa_support_for_other_hash_algorithms
EC_SIGN_P384_SHA384 具有 SHA384 摘要的 NIST P-384 曲线上的 ECDSA。您还可以使用其他哈希函数：https://cloud.google.com/kms/docs/create-validate-signatures#ecdsa_support_for_other_hash_algorithms
EC_SIGN_SECP256K1_SHA256 非 NIST secp256k1 曲线上的 ECDSA。只有 HSM 保护级别支持此曲线。您还可以使用其他哈希函数：https://cloud.google.com/kms/docs/create-validate-signatures#ecdsa_support_for_other_hash_algorithms
HMAC_SHA256 使用 256 位密钥进行 HMAC-SHA256 签名。
HMAC_SHA1 使用 160 位密钥进行 HMAC-SHA1 签名。
HMAC_SHA384 使用 384 位密钥进行 HMAC-SHA384 签名。
HMAC_SHA512 使用 512 位密钥的 HMAC-SHA512 签名。
HMAC_SHA224 使用 224 位密钥进行 HMAC-SHA224 签名。
EXTERNAL_SYMMETRIC_ENCRYPTION 表示由外部密钥管理器对称加密的算法。

KeyOperationAttestation

包含有关密钥操作的 HSM 生成的证明。如需了解详情，请参阅验证证明。

JSON 表示法 
{
  "format": enum (AttestationFormat),
  "content": string,
  "certChains": {
    object (CertificateChains)
  }
}
字段
format

enum (AttestationFormat)

仅限输出。证明数据的格式。
content

string (bytes format)

仅限输出。执行密钥操作时由 HSM 提供的证明数据。

使用 base64 编码的字符串。
certChains

object (CertificateChains)

仅限输出。验证证明所需的证书链

AttestationFormat

HSM 提供的证明格式。

枚举
ATTESTATION_FORMAT_UNSPECIFIED 未指定。
CAVIUM_V1_COMPRESSED

使用 gzip 压缩的 Cavium HSM 证明。请注意，此格式由 Cavium 定义，并且可能会随时更改。

请参阅 https://www.marvell.com/products/security-solutions/nitrox-hs-adapters/software-key-attestation.html。
CAVIUM_V2_COMPRESSED 使用 gzip 压缩的 Cavium HSM 证明 V2。这是 Cavium 的 3.2-08 版中引入的新格式。

CertificateChains

需要证书链来验证证明。链中的证书采用 PEM 编码，并根据 https://tools.ietf.org/html/rfc5246#section-7.4.2 排序。

JSON 表示法 
{
  "caviumCerts": [
    string
  ],
  "googleCardCerts": [
    string
  ],
  "googlePartitionCerts": [
    string
  ]
}
字段
caviumCerts[]

string

与认证对应的 Cavium 证书链。
googleCardCerts[]

string

与证明对应的 Google 卡证书链。
googlePartitionCerts[]

string

与证明对应的 Google 分区证书链。

ExternalProtectionLevelOptions

ExternalProtectionLevelOptions 会存储一组额外的字段，用于配置特定于 EXTERNAL 保护级别和 EXTERNAL_VPC 保护级别的 CryptoKeyVersion。

JSON 表示法 
{
  "externalKeyUri": string,
  "ekmConnectionKeyPath": string
}
字段
externalKeyUri

string

此 CryptoKeyVersion 表示的外部资源的 URI。
ekmConnectionKeyPath

string

使用 [EkmConnection][] 时，指向 EKM 上外部密钥材料的路径，例如“v0/my/key”。使用 [EkmConnection][] 时，请设置此字段，而不是 externalKeyUri。

CryptoKeyPurpose

CryptoKeyPurpose 描述了 CryptoKey 的加密功能。给定密钥只能用于其用途允许的操作。如需了解详情，请参阅密钥用途。

枚举
CRYPTO_KEY_PURPOSE_UNSPECIFIED 未指定。
ENCRYPT_DECRYPT 具有此用途的 CryptoKeys 可以与 [Encrypt][KeyManagementService.Encrypt] 和 [Decrypt][KeyManagementService.Decrypt] 搭配使用。
ASYMMETRIC_SIGN 具有此用途的 CryptoKeys 可与 [ABILLINGSID][KeyManagementService.A 发布商签名] 和 [GetPublicKey][KeyManagementService.GetPublicKey] 搭配使用。
ASYMMETRIC_DECRYPT 具有此用途的 CryptoKeys 可与 [AbillingManagementService.AbalancedDecrypt] 和 [GetPublicKey][KeyManagementService.GetPublicKey] 搭配使用。
MAC 具有此用途的 CryptoKeys 可以与 [MacSign][KeyManagementService.MacSign] 搭配使用。

CryptoKeyVersionTemplate

CryptoKeyVersionTemplate 可指定创建新 CryptoKeyVersion 时使用的属性，既可以使用 [CreateCryptoKeyVersion][KeyManagementService.CreateCryptoKeyVersion] 手动创建，也可以通过自动轮替自动指定。

JSON 表示法 
{
  "protectionLevel": enum (ProtectionLevel),
  "algorithm": enum (CryptoKeyVersionAlgorithm)
}
字段
protectionLevel

enum (ProtectionLevel)

基于此模板创建 CryptoKeyVersion 时使用的 ProtectionLevel。不可变。默认值为 SOFTWARE。
algorithm

enum (CryptoKeyVersionAlgorithm)

必需。基于此模板创建 CryptoKeyVersion 时使用的 Algorithm。

为了实现向后兼容，如果省略此字段并且 CryptoKey.purpose 为 ENCRYPT_DECRYPT，则隐含 GOOGLE_SYMMETRIC_ENCRYPTION。

方法

list

 返回给定 Cloud 项目中由 Cloud KMS 管理的加密密钥。