CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/golang-cloud-google-com--go--kms

Go Client Library for Google Cloud Key Management Service (KMS) API for managing cryptographic keys and performing cryptographic operations

Overview
Eval results
Files

ekm-client.mddocs/

EkmClient - External Key Manager

Overview

The EkmClient manages connections to external key managers and enables using externally-managed cryptographic keys with Cloud KMS. This allows you to use keys stored in external key management systems while leveraging Cloud KMS's API and integration capabilities.

Package: cloud.google.com/go/kms/apiv1

Thread Safety: Methods (except Close) may be called concurrently. Fields must not be modified concurrently with method calls.

Client Creation

NewEkmClient

func NewEkmClient(ctx context.Context, opts ...option.ClientOption) (*EkmClient, error)

Creates a new ekm service client based on gRPC. The returned client must be Closed when done.

NewEkmRESTClient

func NewEkmRESTClient(ctx context.Context, opts ...option.ClientOption) (*EkmClient, error)

Creates a new ekm service REST client.

Example:

import kms "cloud.google.com/go/kms/apiv1"

ctx := context.Background()
client, err := kms.NewEkmClient(ctx)
if err != nil {
    // Handle error
}
defer client.Close()

Client Type

type EkmClient struct {
    // CallOptions contains the retry settings for each method
    CallOptions *EkmCallOptions

    // Has unexported fields
}

EKM Connection Management

CreateEkmConnection

func (c *EkmClient) CreateEkmConnection(ctx context.Context, req *kmspb.CreateEkmConnectionRequest, opts ...gax.CallOption) (*kmspb.EkmConnection, error)

Creates a new EkmConnection in a given Project and Location.

Request:

type CreateEkmConnectionRequest struct {
    Parent          string         // Required: "projects/{project}/locations/{location}"
    EkmConnectionId string         // Required: EkmConnection ID
    EkmConnection   *EkmConnection // Required: Initial field values
}

Example:

req := &kmspb.CreateEkmConnectionRequest{
    Parent:          "projects/my-project/locations/us-central1",
    EkmConnectionId: "my-ekm-connection",
    EkmConnection: &kmspb.EkmConnection{
        ServiceResolvers: []*kmspb.EkmConnection_ServiceResolver{
            {
                ServiceDirectoryService: "projects/my-project/locations/us-central1/namespaces/my-namespace/services/my-service",
                Hostname:                "ekm.example.com",
                ServerCertificates: []*kmspb.Certificate{
                    {RawDer: certBytes},
                },
            },
        },
    },
}

ekmConn, err := client.CreateEkmConnection(ctx, req)

GetEkmConnection

func (c *EkmClient) GetEkmConnection(ctx context.Context, req *kmspb.GetEkmConnectionRequest, opts ...gax.CallOption) (*kmspb.EkmConnection, error)

Returns metadata for a given EkmConnection.

Request:

type GetEkmConnectionRequest struct {
    Name string // Required: "projects/{project}/locations/{location}/ekmConnections/{ekmConnection}"
}

UpdateEkmConnection

func (c *EkmClient) UpdateEkmConnection(ctx context.Context, req *kmspb.UpdateEkmConnectionRequest, opts ...gax.CallOption) (*kmspb.EkmConnection, error)

Updates an EkmConnection's metadata.

Request:

type UpdateEkmConnectionRequest struct {
    EkmConnection *EkmConnection         // Required: Updated values
    UpdateMask    *fieldmaskpb.FieldMask // Required: Fields to update
}

ListEkmConnections

func (c *EkmClient) ListEkmConnections(ctx context.Context, req *kmspb.ListEkmConnectionsRequest, opts ...gax.CallOption) *EkmConnectionIterator

Lists EkmConnections in a location.

Request:

type ListEkmConnectionsRequest struct {
    Parent    string // Required: "projects/{project}/locations/{location}"
    PageSize  int32  // Optional: Max items per page
    PageToken string // Optional: Pagination token
    Filter    string // Optional: Filter expression
    OrderBy   string // Optional: Ordering specification
}

EKM Configuration

GetEkmConfig

func (c *EkmClient) GetEkmConfig(ctx context.Context, req *kmspb.GetEkmConfigRequest, opts ...gax.CallOption) (*kmspb.EkmConfig, error)

Returns the EkmConfig singleton resource for a given project and location.

Request:

type GetEkmConfigRequest struct {
    Name string // Required: "projects/{project}/locations/{location}/ekmConfig"
}

UpdateEkmConfig

func (c *EkmClient) UpdateEkmConfig(ctx context.Context, req *kmspb.UpdateEkmConfigRequest, opts ...gax.CallOption) (*kmspb.EkmConfig, error)

Updates the EkmConfig singleton resource for a given project and location.

Request:

type UpdateEkmConfigRequest struct {
    EkmConfig  *EkmConfig             // Required: Updated values
    UpdateMask *fieldmaskpb.FieldMask // Required: Fields to update
}

Example:

import "google.golang.org/protobuf/types/known/fieldmaskpb"

req := &kmspb.UpdateEkmConfigRequest{
    EkmConfig: &kmspb.EkmConfig{
        Name:                 "projects/my-project/locations/us-central1/ekmConfig",
        DefaultEkmConnection: "projects/my-project/locations/us-central1/ekmConnections/my-ekm-connection",
    },
    UpdateMask: &fieldmaskpb.FieldMask{
        Paths: []string{"default_ekm_connection"},
    },
}

config, err := client.UpdateEkmConfig(ctx, req)

VerifyConnectivity

func (c *EkmClient) VerifyConnectivity(ctx context.Context, req *kmspb.VerifyConnectivityRequest, opts ...gax.CallOption) (*kmspb.VerifyConnectivityResponse, error)

Verifies that Cloud KMS can successfully connect to the external key manager specified by an EkmConnection. If the request is successful, the response is empty.

Request:

type VerifyConnectivityRequest struct {
    Name string // Required: EkmConnection resource name
}

Example:

req := &kmspb.VerifyConnectivityRequest{
    Name: "projects/my-project/locations/us-central1/ekmConnections/my-ekm-connection",
}

_, err := client.VerifyConnectivity(ctx, req)
if err != nil {
    log.Printf("EKM connection verification failed: %v", err)
} else {
    log.Println("EKM connection verified successfully")
}

IAM and Utility Methods

func (c *EkmClient) GetIamPolicy(ctx context.Context, req *iampb.GetIamPolicyRequest, opts ...gax.CallOption) (*iampb.Policy, error)
func (c *EkmClient) SetIamPolicy(ctx context.Context, req *iampb.SetIamPolicyRequest, opts ...gax.CallOption) (*iampb.Policy, error)
func (c *EkmClient) TestIamPermissions(ctx context.Context, req *iampb.TestIamPermissionsRequest, opts ...gax.CallOption) (*iampb.TestIamPermissionsResponse, error)
func (c *EkmClient) GetLocation(ctx context.Context, req *locationpb.GetLocationRequest, opts ...gax.CallOption) (*locationpb.Location, error)
func (c *EkmClient) ListLocations(ctx context.Context, req *locationpb.ListLocationsRequest, opts ...gax.CallOption) *LocationIterator
func (c *EkmClient) GetOperation(ctx context.Context, req *longrunningpb.GetOperationRequest, opts ...gax.CallOption) (*longrunningpb.Operation, error)
func (c *EkmClient) Close() error
func (c *EkmClient) Connection() *grpc.ClientConn // Deprecated

CallOptions Type

type EkmCallOptions struct {
    ListEkmConnections  []gax.CallOption
    GetEkmConnection    []gax.CallOption
    CreateEkmConnection []gax.CallOption
    UpdateEkmConnection []gax.CallOption
    GetEkmConfig        []gax.CallOption
    UpdateEkmConfig     []gax.CallOption
    VerifyConnectivity  []gax.CallOption
    GetLocation         []gax.CallOption
    ListLocations       []gax.CallOption
    GetIamPolicy        []gax.CallOption
    SetIamPolicy        []gax.CallOption
    TestIamPermissions  []gax.CallOption
    GetOperation        []gax.CallOption
}

EKM Resource Types

EkmConnection

type EkmConnection struct {
    Name              string                              // Output only: Resource name
    CreateTime        *timestamppb.Timestamp              // Output only: Creation time
    ServiceResolvers  []*EkmConnection_ServiceResolver    // List of ServiceResolvers
    Etag              string                              // Optional: For concurrent updates
    KeyManagementMode EkmConnection_KeyManagementMode     // Optional: MANUAL or CLOUD_KMS
    CryptoSpacePath   string                              // Optional: Crypto space path (EKM replicas)
}

An EkmConnection represents an individual EKM connection. Can be used for creating CryptoKeys and CryptoKeyVersions with ProtectionLevel EXTERNAL_VPC.

EkmConnection_ServiceResolver

type EkmConnection_ServiceResolver struct {
    ServiceDirectoryService string         // Service Directory service name
    EndpointFilter          string         // Optional: Filter for endpoints
    Hostname                string         // Required: Hostname of the EKM replica
    ServerCertificates      []*Certificate // Required: X.509 certificates
}

EkmConnection_KeyManagementMode

type EkmConnection_KeyManagementMode int32

const (
    EkmConnection_KEY_MANAGEMENT_MODE_UNSPECIFIED EkmConnection_KeyManagementMode = 0 // Not specified
    EkmConnection_MANUAL                          EkmConnection_KeyManagementMode = 1 // Keys manually managed
    EkmConnection_CLOUD_KMS                       EkmConnection_KeyManagementMode = 2 // Keys managed by Cloud KMS
)

EkmConfig

type EkmConfig struct {
    Name                 string // Output only: "projects/{project}/locations/{location}/ekmConfig"
    DefaultEkmConnection string // Optional: Default EkmConnection resource name
}

An EkmConfig is a singleton resource representing configuration for the External Key Manager in a given project and location.

Certificate

type Certificate struct {
    RawDer                   []byte                     // Required: Raw certificate bytes in DER format
    Parsed                   bool                       // Output only: True if parsed successfully
    Issuer                   string                     // Output only: Issuer name
    Subject                  string                     // Output only: Subject name
    SubjectAlternativeDnsNames []string                 // Output only: Subject Alternative DNS names
    NotBeforeTime            *timestamppb.Timestamp     // Output only: Not Before time
    NotAfterTime             *timestamppb.Timestamp     // Output only: Not After time
    SerialNumber             string                     // Output only: Serial number
    Sha256Fingerprint        string                     // Output only: SHA-256 fingerprint
}

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

Complete EKM Workflow Example

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    kms "cloud.google.com/go/kms/apiv1"
    "cloud.google.com/go/kms/apiv1/kmspb"
    "google.golang.org/protobuf/types/known/fieldmaskpb"
)

func setupEKM() {
    ctx := context.Background()

    // Create EKM client
    client, err := kms.NewEkmClient(ctx)
    if err != nil {
        log.Fatal(err)
    }
    defer client.Close()

    // Load certificate
    certBytes, err := os.ReadFile("ekm-cert.der")
    if err != nil {
        log.Fatal(err)
    }

    // Create EKM connection
    ekmConn, err := client.CreateEkmConnection(ctx, &kmspb.CreateEkmConnectionRequest{
        Parent:          "projects/my-project/locations/us-central1",
        EkmConnectionId: "my-ekm-connection",
        EkmConnection: &kmspb.EkmConnection{
            ServiceResolvers: []*kmspb.EkmConnection_ServiceResolver{
                {
                    ServiceDirectoryService: "projects/my-project/locations/us-central1/namespaces/my-ns/services/my-svc",
                    Hostname:                "ekm.example.com",
                    ServerCertificates: []*kmspb.Certificate{
                        {RawDer: certBytes},
                    },
                },
            },
            KeyManagementMode: kmspb.EkmConnection_MANUAL,
        },
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Created EkmConnection: %s\n", ekmConn.Name)

    // Verify connectivity
    _, err = client.VerifyConnectivity(ctx, &kmspb.VerifyConnectivityRequest{
        Name: ekmConn.Name,
    })
    if err != nil {
        log.Fatalf("Connectivity verification failed: %v", err)
    }
    fmt.Println("EKM connection verified")

    // Set as default EKM connection
    _, err = client.UpdateEkmConfig(ctx, &kmspb.UpdateEkmConfigRequest{
        EkmConfig: &kmspb.EkmConfig{
            Name:                 "projects/my-project/locations/us-central1/ekmConfig",
            DefaultEkmConnection: ekmConn.Name,
        },
        UpdateMask: &fieldmaskpb.FieldMask{
            Paths: []string{"default_ekm_connection"},
        },
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println("Set as default EKM connection")

    // Now create CryptoKeys with EXTERNAL_VPC protection level
    keyClient, err := kms.NewKeyManagementClient(ctx)
    if err != nil {
        log.Fatal(err)
    }
    defer keyClient.Close()

    cryptoKey, err := keyClient.CreateCryptoKey(ctx, &kmspb.CreateCryptoKeyRequest{
        Parent:      "projects/my-project/locations/us-central1/keyRings/my-keyring",
        CryptoKeyId: "my-ekm-key",
        CryptoKey: &kmspb.CryptoKey{
            Purpose: kmspb.CryptoKey_ENCRYPT_DECRYPT,
            VersionTemplate: &kmspb.CryptoKeyVersionTemplate{
                Algorithm:       kmspb.CryptoKeyVersion_EXTERNAL_SYMMETRIC_ENCRYPTION,
                ProtectionLevel: kmspb.ProtectionLevel_EXTERNAL_VPC,
            },
        },
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Created CryptoKey with EKM: %s\n", cryptoKey.Name)
}

Best Practices

  1. Verify connectivity after creating or updating EKM connections
  2. Use Service Directory for dynamic endpoint resolution
  3. Keep certificates up to date - monitor expiration times
  4. Test failover scenarios if using multiple service resolvers
  5. Monitor EKM connection health in production environments
  6. Use EXTERNAL_VPC protection level for keys managed by EKM

See Also

  • Core Types
  • KeyManagementClient
  • Enumerations

Install with Tessl CLI

npx tessl i tessl/golang-cloud-google-com--go--kms

docs

autokey-client.md

core-types.md

ekm-client.md

enums.md

index.md

inventory-clients.md

iterators.md

key-management-client.md

operations.md

request-response-types.md

tile.json