0
# External Key Management
1

2
The EkmServiceClient provides integration with external key management systems (EKM) for keys stored and managed outside of Google Cloud. This enables organizations to maintain control over their cryptographic keys while leveraging Google Cloud KMS for operations.
3

4
## Capabilities
5

6
### EKM Connection Management
7

8
EKM connections define how Cloud KMS connects to external key managers.
9

10
```python { .api }
11
def list_ekm_connections(self, request: ListEkmConnectionsRequest) -> ListEkmConnectionsResponse:
12
    """
13
    Lists EkmConnections.
14
    
15
    Parameters:
16
    - request.parent: Required. Location path (projects/{project}/locations/{location})
17
    - request.page_size: Optional. Maximum results per page
18
    - request.page_token: Optional. Pagination token
19
    - request.filter: Optional. Filter expression
20
    - request.order_by: Optional. Sorting order
21
    
22
    Returns:
23
    List of EkmConnection objects with pagination
24
    """
25

26
def get_ekm_connection(self, request: GetEkmConnectionRequest) -> EkmConnection:
27
    """
28
    Returns metadata for a given EkmConnection.
29
    
30
    Parameters:
31
    - request.name: Required. EkmConnection resource name
32
    
33
    Returns:
34
    EkmConnection object with metadata
35
    """
36

37
def create_ekm_connection(self, request: CreateEkmConnectionRequest) -> EkmConnection:
38
    """
39
    Creates a new EkmConnection in a given Project and Location.
40
    
41
    Parameters:
42
    - request.parent: Required. Location path
43
    - request.ekm_connection_id: Required. Unique ID for EkmConnection
44
    - request.ekm_connection: Required. EkmConnection object to create
45
    
46
    Returns:
47
    Created EkmConnection object
48
    """
49

50
def update_ekm_connection(self, request: UpdateEkmConnectionRequest) -> EkmConnection:
51
    """
52
    Updates an EkmConnection's metadata.
53
    
54
    Parameters:
55
    - request.ekm_connection: Required. Updated EkmConnection object
56
    - request.update_mask: Required. Fields to update
57
    
58
    Returns:
59
    Updated EkmConnection object
60
    """
61
```
62

63
### EKM Configuration Management
64

65
Global configuration settings for external key management.
66

67
```python { .api }
68
def get_ekm_config(self, request: GetEkmConfigRequest) -> EkmConfig:
69
    """
70
    Returns the EkmConfig singleton resource for a given project and location.
71
    
72
    Parameters:
73
    - request.name: Required. EkmConfig resource name
74
    
75
    Returns:
76
    EkmConfig object with configuration
77
    """
78

79
def update_ekm_config(self, request: UpdateEkmConfigRequest) -> EkmConfig:
80
    """
81
    Updates the EkmConfig singleton resource for a given project and location.
82
    
83
    Parameters:
84
    - request.ekm_config: Required. Updated EkmConfig object
85
    - request.update_mask: Required. Fields to update
86
    
87
    Returns:
88
    Updated EkmConfig object
89
    """
90
```
91

92
### Connectivity Verification
93

94
Test and verify connectivity to external key managers.
95

96
```python { .api }
97
def verify_connectivity(self, request: VerifyConnectivityRequest) -> VerifyConnectivityResponse:
98
    """
99
    Verifies that Cloud KMS can successfully connect to the external key manager specified by an EkmConnection.
100
    
101
    Parameters:
102
    - request.name: Required. EkmConnection resource name
103
    
104
    Returns:
105
    VerifyConnectivityResponse with verification results
106
    """
107
```
108

109
## Resource Types
110

111
### EkmConnection
112

113
```python { .api }
114
class EkmConnection:
115
    """
116
    Individual EKM connection for creating external VPC keys.
117
    
118
    Attributes:
119
    - name: str - Resource name of the EkmConnection
120
    - create_time: Timestamp - Creation timestamp
121
    - service_resolvers: List[ServiceResolver] - EKM replica resolvers
122
    - etag: str - Entity tag for optimistic concurrency control
123
    - key_management_mode: KeyManagementMode - Key management mode
124
    - crypto_space_path: str - Path to crypto space in EKM
125
    """
126
    
127
    class ServiceResolver:
128
        """
129
        EKM replica resolver within an EkmConnection.
130
        
131
        Attributes:
132
        - service_directory_service: str - Service Directory service name
133
        - endpoint_filter: str - Filter for selecting endpoints
134
        - hostname: str - Hostname of EKM replica
135
        - server_certificates: List[Certificate] - TLS certificates
136
        """
137
    
138
    class KeyManagementMode:
139
        """
140
        Key management mode for EKM operations.
141
        
142
        Values:
143
        - KEY_MANAGEMENT_MODE_UNSPECIFIED: Not specified
144
        - MANUAL: EKM-side key management operations
145
        - CLOUD_KMS: Cloud KMS-initiated EKM operations
146
        """
147
```
148

149
### EkmConfig
150

151
```python { .api }
152
class EkmConfig:
153
    """
154
    Singleton resource for EKM configuration parameters.
155
    
156
    Attributes:
157
    - name: str - Resource name of the EkmConfig
158
    - default_ekm_connection: str - Default EkmConnection for external keys
159
    """
160
```
161

162
### Certificate
163

164
```python { .api }
165
class Certificate:
166
    """
167
    X.509 certificate for HTTPS connections to EKM replicas.
168
    
169
    Attributes:
170
    - raw_der: bytes - DER-encoded certificate
171
    - parsed: bool - Whether certificate was successfully parsed
172
    - issuer: str - Certificate issuer
173
    - subject: str - Certificate subject
174
    - subject_alternative_dns_names: List[str] - Subject alternative DNS names
175
    - not_before_time: Timestamp - Certificate validity start time
176
    - not_after_time: Timestamp - Certificate validity end time
177
    - serial_number: str - Certificate serial number
178
    - sha256_fingerprint: str - SHA256 fingerprint
179
    """
180
```
181

182
### Request/Response Types
183

184
```python { .api }
185
class CreateEkmConnectionRequest:
186
    """
187
    Request to create an EkmConnection.
188
    
189
    Attributes:
190
    - parent: str - Required. Location path
191
    - ekm_connection_id: str - Required. Unique ID for EkmConnection
192
    - ekm_connection: EkmConnection - Required. EkmConnection to create
193
    """
194

195
class UpdateEkmConnectionRequest:
196
    """
197
    Request to update an EkmConnection.
198
    
199
    Attributes:
200
    - ekm_connection: EkmConnection - Required. Updated EkmConnection
201
    - update_mask: FieldMask - Required. Fields to update
202
    """
203

204
class ListEkmConnectionsRequest:
205
    """
206
    Request to list EkmConnections.
207
    
208
    Attributes:
209
    - parent: str - Required. Location path
210
    - page_size: int - Optional. Maximum results per page
211
    - page_token: str - Optional. Pagination token
212
    - filter: str - Optional. Filter expression
213
    - order_by: str - Optional. Sorting order
214
    """
215

216
class ListEkmConnectionsResponse:
217
    """
218
    Response from listing EkmConnections.
219
    
220
    Attributes:
221
    - ekm_connections: List[EkmConnection] - List of EkmConnection objects
222
    - next_page_token: str - Token for next page
223
    - total_size: int - Total number of connections
224
    """
225

226
class UpdateEkmConfigRequest:
227
    """
228
    Request to update EkmConfig.
229
    
230
    Attributes:
231
    - ekm_config: EkmConfig - Required. Updated EkmConfig
232
    - update_mask: FieldMask - Required. Fields to update
233
    """
234

235
class VerifyConnectivityRequest:
236
    """
237
    Request to verify EKM connectivity.
238
    
239
    Attributes:
240
    - name: str - Required. EkmConnection resource name
241
    """
242

243
class VerifyConnectivityResponse:
244
    """
245
    Response from EKM connectivity verification.
246
    """
247
```
248

249
## Usage Examples
250

251
### Creating an EKM Connection
252

253
```python
254
from google.cloud import kms
255

256
# Initialize the EKM Service client
257
client = kms.EkmServiceClient()
258

259
# Create an EKM connection
260
project_id = "my-project"
261
location_id = "us-central1"
262
connection_id = "my-ekm-connection"
263

264
# Define service resolver for EKM replica
265
service_resolver = kms.EkmConnection.ServiceResolver()
266
service_resolver.hostname = "ekm.example.com"
267
service_resolver.server_certificates = [
268
    kms.Certificate(raw_der=certificate_der_bytes)
269
]
270

271
# Create EKM connection
272
ekm_connection = kms.EkmConnection()
273
ekm_connection.service_resolvers = [service_resolver]
274
ekm_connection.key_management_mode = kms.EkmConnection.KeyManagementMode.MANUAL
275

276
parent = f"projects/{project_id}/locations/{location_id}"
277
created_connection = client.create_ekm_connection(
278
    request={
279
        "parent": parent,
280
        "ekm_connection_id": connection_id,
281
        "ekm_connection": ekm_connection,
282
    }
283
)
284

285
print(f"Created EKM connection: {created_connection.name}")
286
```
287

288
### Verifying EKM Connectivity
289

290
```python
291
from google.cloud import kms
292
from google.api_core import exceptions
293

294
# Initialize the EKM Service client
295
client = kms.EkmServiceClient()
296

297
# Verify connectivity to EKM
298
connection_name = f"projects/{project_id}/locations/{location_id}/ekmConnections/{connection_id}"
299

300
try:
301
    verify_response = client.verify_connectivity(
302
        request={"name": connection_name}
303
    )
304
    print("EKM connectivity verified successfully")
305
except exceptions.FailedPrecondition as e:
306
    print(f"Connectivity verification failed: {e}")
307
except Exception as e:
308
    print(f"Error verifying connectivity: {e}")
309
```
310

311
### Configuring Default EKM Connection
312

313
```python
314
from google.cloud import kms
315

316
# Initialize the EKM Service client
317
client = kms.EkmServiceClient()
318

319
# Set default EKM connection for a location
320
config_name = f"projects/{project_id}/locations/{location_id}/ekmConfig"
321
default_connection = f"projects/{project_id}/locations/{location_id}/ekmConnections/{connection_id}"
322

323
# Update EKM configuration
324
ekm_config = kms.EkmConfig()
325
ekm_config.name = config_name
326
ekm_config.default_ekm_connection = default_connection
327

328
updated_config = client.update_ekm_config(
329
    request={
330
        "ekm_config": ekm_config,
331
        "update_mask": {"paths": ["default_ekm_connection"]},
332
    }
333
)
334

335
print(f"Default EKM connection set to: {updated_config.default_ekm_connection}")
336
```
337

338
### Using External Keys with Key Management Service
339

340
```python
341
from google.cloud import kms
342

343
# Initialize both clients
344
kms_client = kms.KeyManagementServiceClient()
345
ekm_client = kms.EkmServiceClient()
346

347
# Create a crypto key that uses external key material
348
crypto_key = kms.CryptoKey()
349
crypto_key.purpose = kms.CryptoKey.CryptoKeyPurpose.ENCRYPT_DECRYPT
350

351
# Create version template for external key
352
version_template = kms.CryptoKeyVersionTemplate()
353
version_template.protection_level = kms.ProtectionLevel.EXTERNAL_VPC
354
version_template.algorithm = kms.CryptoKeyVersion.CryptoKeyVersionAlgorithm.EXTERNAL_SYMMETRIC_ENCRYPTION
355

356
crypto_key.version_template = version_template
357

358
# Create the crypto key
359
key_ring_name = f"projects/{project_id}/locations/{location_id}/keyRings/{key_ring_id}"
360
external_key = kms_client.create_crypto_key(
361
    request={
362
        "parent": key_ring_name,
363
        "crypto_key_id": "external-key",
364
        "crypto_key": crypto_key,
365
    }
366
)
367

368
print(f"Created external crypto key: {external_key.name}")
369

370
# Use the external key for encryption
371
plaintext = b"Data to encrypt with external key"
372
encrypt_response = kms_client.encrypt(
373
    request={
374
        "name": external_key.name,
375
        "plaintext": plaintext,
376
    }
377
)
378

379
print(f"Encrypted data using external key")
380
```
381

382
### Listing and Managing EKM Connections
383

384
```python
385
from google.cloud import kms
386

387
# Initialize the EKM Service client
388
client = kms.EkmServiceClient()
389

390
# List all EKM connections in a location
391
parent = f"projects/{project_id}/locations/{location_id}"
392
response = client.list_ekm_connections(
393
    request={
394
        "parent": parent,
395
        "page_size": 100,
396
    }
397
)
398

399
for connection in response.ekm_connections:
400
    print(f"EKM Connection: {connection.name}")
401
    print(f"  Key Management Mode: {connection.key_management_mode}")
402
    print(f"  Service Resolvers: {len(connection.service_resolvers)}")
403
    
404
    # Verify connectivity for each connection
405
    try:
406
        client.verify_connectivity(request={"name": connection.name})
407
        print(f"  Status: Connected")
408
    except Exception:
409
        print(f"  Status: Connection failed")
410
```
411

412
## Security Considerations
413

414
### Certificate Management
415

416
```python
417
# When creating EKM connections, ensure certificates are properly configured
418
from google.cloud import kms
419

420
# Load certificate data (DER encoded)
421
with open("ekm-server-cert.der", "rb") as f:
422
    certificate_der_bytes = f.read()
423

424
# Create certificate object for EKM connection
425
certificate = kms.Certificate(raw_der=certificate_der_bytes)
426

427
# Note: Certificate validation should be performed by your organization's
428
# PKI infrastructure before deploying certificates to production EKM servers
429
```
430

431
### Network Security
432

433
```python
434
# Configure EKM connection with proper network security
435
service_resolver = kms.EkmConnection.ServiceResolver()
436
service_resolver.hostname = "ekm.internal.example.com"  # Use internal hostname
437
service_resolver.endpoint_filter = "port=443"  # Ensure HTTPS
438

439
# Add multiple certificates for redundancy
440
service_resolver.server_certificates = [
441
    kms.Certificate(raw_der=primary_cert_der),
442
    kms.Certificate(raw_der=backup_cert_der),
443
]
444
```