REST Resource: projects.locations.ekmConnections

Resource: EkmConnection

An EkmConnection represents an individual EKM connection. It can be used for creating CryptoKeys and CryptoKeyVersions with a ProtectionLevel of [EXTERNAL_VPC][CryptoKeyVersion.ProtectionLevel.EXTERNAL_VPC], as well as performing cryptographic operations using keys created within the EkmConnection.

JSON representation
{
  "name": string,
  "createTime": string,
  "serviceResolvers": [
    {
      object (ServiceResolver)
    }
  ],
  "etag": string,
  "keyManagementMode": enum (KeyManagementMode),
  "cryptoSpacePath": string
}
Fields
name

string

Output only. The resource name for the EkmConnection in the format projects/*/locations/*/ekmConnections/*.

createTime

string (Timestamp format)

Output only. The time at which the EkmConnection was created.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

serviceResolvers[]

object (ServiceResolver)

Optional. A list of ServiceResolvers where the EKM can be reached. There should be one ServiceResolver per EKM replica. Currently, only a single ServiceResolver is supported.

etag

string

Optional. Etag of the currently stored EkmConnection.

keyManagementMode

enum (KeyManagementMode)

Optional. Describes who can perform control plane operations on the EKM. If unset, this defaults to MANUAL.

cryptoSpacePath

string

Optional. Identifies the EKM Crypto Space that this EkmConnection maps to. Note: This field is required if KeyManagementMode is CLOUD_KMS.

ServiceResolver

A ServiceResolver represents an EKM replica that can be reached within an EkmConnection.

JSON representation
{
  "serviceDirectoryService": string,
  "endpointFilter": string,
  "hostname": string,
  "serverCertificates": [
    {
      object (Certificate)
    }
  ]
}
Fields
serviceDirectoryService

string

Required. The resource name of the Service Directory service pointing to an EKM replica, in the format projects/*/locations/*/namespaces/*/services/*.

endpointFilter

string

Optional. The filter applied to the endpoints of the resolved service. If no filter is specified, all endpoints will be considered. An endpoint will be chosen arbitrarily from the filtered list for each request.

For endpoint filter syntax and examples, see https://cloud.google.com/service-directory/docs/reference/rpc/google.cloud.servicedirectory.v1#resolveservicerequest.

hostname

string

Required. The hostname of the EKM replica used at TLS and HTTP layers.

serverCertificates[]

object (Certificate)

Required. A list of leaf server certificates used to authenticate HTTPS connections to the EKM replica. Currently, a maximum of 10 Certificate is supported.

Certificate

A Certificate represents an X.509 certificate used to authenticate HTTPS connections to EKM replicas.

JSON representation
{
  "rawDer": string,
  "parsed": boolean,
  "issuer": string,
  "subject": string,
  "subjectAlternativeDnsNames": [
    string
  ],
  "notBeforeTime": string,
  "notAfterTime": string,
  "serialNumber": string,
  "sha256Fingerprint": string
}
Fields
rawDer

string (bytes format)

Required. The raw certificate bytes in DER format.

A base64-encoded string.

parsed

boolean

Output only. True if the certificate was parsed successfully.

issuer

string

Output only. The issuer distinguished name in RFC 2253 format. Only present if parsed is true.

subject

string

Output only. The subject distinguished name in RFC 2253 format. Only present if parsed is true.

subjectAlternativeDnsNames[]

string

Output only. The subject Alternative DNS names. Only present if parsed is true.

notBeforeTime

string (Timestamp format)

Output only. The certificate is not valid before this time. Only present if parsed is true.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

notAfterTime

string (Timestamp format)

Output only. The certificate is not valid after this time. Only present if parsed is true.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

serialNumber

string

Output only. The certificate serial number as a hex string. Only present if parsed is true.

sha256Fingerprint

string

Output only. The SHA-256 certificate fingerprint as a hex string. Only present if parsed is true.

KeyManagementMode

KeyManagementMode describes who can perform control plane cryptographic operations using this EkmConnection.

Enums
KEY_MANAGEMENT_MODE_UNSPECIFIED Not specified.
MANUAL EKM-side key management operations on CryptoKeys created with this EkmConnection must be initiated from the EKM directly and cannot be performed from Cloud KMS. This means that: * When creating a CryptoKeyVersion associated with this EkmConnection, the caller must supply the key path of pre-existing external key material that will be linked to the CryptoKeyVersion. * Destruction of external key material cannot be requested via the Cloud KMS API and must be performed directly in the EKM. * Automatic rotation of key material is not supported.
CLOUD_KMS All CryptoKeys created with this EkmConnection use EKM-side key management operations initiated from Cloud KMS. This means that: * When a CryptoKeyVersion associated with this EkmConnection is created, the EKM automatically generates new key material and a new key path. The caller cannot supply the key path of pre-existing external key material. * Destruction of external key material associated with this EkmConnection can be requested by calling [cryptoKeyVersions.destroy][EkmService.DestroyCryptoKeyVersion]. * Automatic rotation of key material is supported.

Methods

create

Creates a new EkmConnection in a given Project and Location.

get

Returns metadata for a given EkmConnection.

getIamPolicy

Gets the access control policy for a resource.

list

Lists EkmConnections.

patch

Updates an EkmConnection's metadata.

setIamPolicy

Sets the access control policy on the specified resource.

testIamPermissions

Returns permissions that a caller has on the specified resource.

verifyConnectivity

Verifies that Cloud KMS can successfully connect to the external key manager specified by an EkmConnection.