0
# Certificate Authority Operations
1

2
Complete certificate authority lifecycle management including creation, activation, disabling, enabling, and deletion. Supports both root and subordinate certificate authorities with comprehensive configuration options and state management.
3

4
## Capabilities
5

6
### Certificate Authority Creation
7

8
Creates a new certificate authority within a CA pool. Supports both root CAs (self-signed) and subordinate CAs (signed by another CA).
9

10
```python { .api }
11
def create_certificate_authority(
12
    self,
13
    request: Union[CreateCertificateAuthorityRequest, dict] = None,
14
    *,
15
    parent: str = None,
16
    certificate_authority: CertificateAuthority = None,
17
    certificate_authority_id: str = None,
18
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
19
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
20
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),
21
) -> operation.Operation:
22
    """
23
    Create a new certificate authority.
24

25
    Args:
26
        request: The request object
27
        parent: CA pool path (format: projects/{project}/locations/{location}/caPools/{ca_pool})
28
        certificate_authority: CA configuration
29
        certificate_authority_id: Unique CA identifier
30
        retry: Retry configuration
31
        timeout: Request timeout in seconds
32
        metadata: Additional metadata
33

34
    Returns:
35
        operation.Operation: Long-running operation for CA creation
36
    """
37
```
38

39
### Certificate Authority Activation
40

41
Activates a certificate authority by providing the signed CA certificate. Required for subordinate CAs after creation.
42

43
```python { .api }
44
def activate_certificate_authority(
45
    self,
46
    request: Union[ActivateCertificateAuthorityRequest, dict] = None,
47
    *,
48
    name: str = None,
49
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
50
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
51
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),
52
) -> operation.Operation:
53
    """
54
    Activate a certificate authority.
55

56
    Args:
57
        request: The request object containing activation details
58
        name: CA resource name
59
        retry: Retry configuration
60
        timeout: Request timeout in seconds
61
        metadata: Additional metadata
62

63
    Returns:
64
        operation.Operation: Long-running operation for CA activation
65
    """
66
```
67

68
### Certificate Authority State Management
69

70
Enables and disables certificate authorities to control their operational state without deletion.
71

72
```python { .api }
73
def disable_certificate_authority(
74
    self,
75
    request: Union[DisableCertificateAuthorityRequest, dict] = None,
76
    *,
77
    name: str = None,
78
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
79
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
80
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),
81
) -> operation.Operation:
82
    """
83
    Disable a certificate authority.
84

85
    Args:
86
        request: The request object
87
        name: CA resource name
88
        retry: Retry configuration
89
        timeout: Request timeout in seconds
90
        metadata: Additional metadata
91

92
    Returns:
93
        operation.Operation: Long-running operation for disabling CA
94
    """
95

96
def enable_certificate_authority(
97
    self,
98
    request: Union[EnableCertificateAuthorityRequest, dict] = None,
99
    *,
100
    name: str = None,
101
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
102
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
103
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),
104
) -> operation.Operation:
105
    """
106
    Enable a certificate authority.
107

108
    Args:
109
        request: The request object
110
        name: CA resource name
111
        retry: Retry configuration
112
        timeout: Request timeout in seconds
113
        metadata: Additional metadata
114

115
    Returns:
116
        operation.Operation: Long-running operation for enabling CA
117
    """
118
```
119

120
### Certificate Authority Information
121

122
Retrieves certificate authority details and lists CAs within a pool.
123

124
```python { .api }
125
def get_certificate_authority(
126
    self,
127
    request: Union[GetCertificateAuthorityRequest, dict] = None,
128
    *,
129
    name: str = None,
130
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
131
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
132
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),
133
) -> CertificateAuthority:
134
    """
135
    Get a certificate authority by name.
136

137
    Args:
138
        request: The request object
139
        name: CA resource name
140
        retry: Retry configuration
141
        timeout: Request timeout in seconds
142
        metadata: Additional metadata
143

144
    Returns:
145
        CertificateAuthority: The requested CA resource
146
    """
147

148
def list_certificate_authorities(
149
    self,
150
    request: Union[ListCertificateAuthoritiesRequest, dict] = None,
151
    *,
152
    parent: str = None,
153
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
154
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
155
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),
156
) -> pagers.ListCertificateAuthoritiesPager:
157
    """
158
    List certificate authorities in a CA pool.
159

160
    Args:
161
        request: The request object
162
        parent: CA pool path
163
        retry: Retry configuration
164
        timeout: Request timeout in seconds
165
        metadata: Additional metadata
166

167
    Returns:
168
        pagers.ListCertificateAuthoritiesPager: Paginated response of CAs
169
    """
170
```
171

172
### Certificate Authority CSR Operations
173

174
Fetches certificate signing requests for subordinate CAs that need external signing.
175

176
```python { .api }
177
def fetch_certificate_authority_csr(
178
    self,
179
    request: Union[FetchCertificateAuthorityCsrRequest, dict] = None,
180
    *,
181
    name: str = None,
182
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
183
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
184
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),
185
) -> FetchCertificateAuthorityCsrResponse:
186
    """
187
    Fetch the certificate signing request for a CA.
188

189
    Args:
190
        request: The request object
191
        name: CA resource name
192
        retry: Retry configuration
193
        timeout: Request timeout in seconds
194
        metadata: Additional metadata
195

196
    Returns:
197
        FetchCertificateAuthorityCsrResponse: CSR in PEM format
198
    """
199
```
200

201
### Certificate Authority Lifecycle Management
202

203
Updates, deletes, and undeletes certificate authorities.
204

205
```python { .api }
206
def update_certificate_authority(
207
    self,
208
    request: Union[UpdateCertificateAuthorityRequest, dict] = None,
209
    *,
210
    certificate_authority: CertificateAuthority = None,
211
    update_mask: field_mask_pb2.FieldMask = None,
212
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
213
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
214
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),
215
) -> operation.Operation:
216
    """
217
    Update a certificate authority.
218

219
    Args:
220
        request: The request object
221
        certificate_authority: CA with updated fields
222
        update_mask: Fields to update
223
        retry: Retry configuration
224
        timeout: Request timeout in seconds
225
        metadata: Additional metadata
226

227
    Returns:
228
        operation.Operation: Long-running operation for CA update
229
    """
230

231
def delete_certificate_authority(
232
    self,
233
    request: Union[DeleteCertificateAuthorityRequest, dict] = None,
234
    *,
235
    name: str = None,
236
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
237
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
238
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),
239
) -> operation.Operation:
240
    """
241
    Delete a certificate authority.
242

243
    Args:
244
        request: The request object
245
        name: CA resource name
246
        retry: Retry configuration
247
        timeout: Request timeout in seconds
248
        metadata: Additional metadata
249

250
    Returns:
251
        operation.Operation: Long-running operation for CA deletion
252
    """
253

254
def undelete_certificate_authority(
255
    self,
256
    request: Union[UndeleteCertificateAuthorityRequest, dict] = None,
257
    *,
258
    name: str = None,
259
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
260
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
261
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),
262
) -> operation.Operation:
263
    """
264
    Undelete a certificate authority.
265

266
    Args:
267
        request: The request object
268
        name: CA resource name
269
        retry: Retry configuration
270
        timeout: Request timeout in seconds
271
        metadata: Additional metadata
272

273
    Returns:
274
        operation.Operation: Long-running operation for CA undeletion
275
    """
276
```
277

278
## Request Types
279

280
```python { .api }
281
class CreateCertificateAuthorityRequest:
282
    """Request to create a certificate authority."""
283
    parent: str  # CA pool path
284
    certificate_authority_id: str  # Unique CA identifier
285
    certificate_authority: CertificateAuthority  # CA configuration
286
    request_id: str  # Idempotency token
287

288
class ActivateCertificateAuthorityRequest:
289
    """Request to activate a certificate authority."""
290
    name: str  # CA resource name
291
    pem_ca_certificate: str  # Signed CA certificate in PEM format
292
    subordinate_config: SubordinateConfig  # Subordinate CA configuration
293
    request_id: str  # Idempotency token
294

295
class DisableCertificateAuthorityRequest:
296
    """Request to disable a certificate authority."""
297
    name: str  # CA resource name
298
    request_id: str  # Idempotency token
299
    ignore_dependent_resources: bool  # Ignore dependent resources
300

301
class EnableCertificateAuthorityRequest:
302
    """Request to enable a certificate authority."""
303
    name: str  # CA resource name
304
    request_id: str  # Idempotency token
305

306
class GetCertificateAuthorityRequest:
307
    """Request to get a certificate authority."""
308
    name: str  # CA resource name
309

310
class ListCertificateAuthoritiesRequest:
311
    """Request to list certificate authorities."""
312
    parent: str  # CA pool path
313
    page_size: int  # Maximum results per page
314
    page_token: str  # Pagination token
315
    filter: str  # Filter expression
316
    order_by: str  # Sort order
317

318
class FetchCertificateAuthorityCsrRequest:
319
    """Request to fetch CA certificate signing request."""
320
    name: str  # CA resource name
321

322
class UpdateCertificateAuthorityRequest:
323
    """Request to update a certificate authority."""
324
    certificate_authority: CertificateAuthority  # CA with updates
325
    update_mask: field_mask_pb2.FieldMask  # Fields to update
326
    request_id: str  # Idempotency token
327

328
class DeleteCertificateAuthorityRequest:
329
    """Request to delete a certificate authority."""
330
    name: str  # CA resource name
331
    request_id: str  # Idempotency token
332
    ignore_dependent_resources: bool  # Ignore dependent resources
333
    skip_grace_period: bool  # Skip deletion grace period
334

335
class UndeleteCertificateAuthorityRequest:
336
    """Request to undelete a certificate authority."""
337
    name: str  # CA resource name
338
    request_id: str  # Idempotency token
339
```
340

341
## Certificate Authority Resource Type
342

343
```python { .api }
344
class CertificateAuthority:
345
    """A Certificate Authority that can issue certificates."""
346
    name: str  # Resource name
347
    type_: Type  # CA type (SELF_SIGNED or SUBORDINATE)
348
    config: CertificateAuthorityConfig  # CA configuration
349
    lifetime: duration_pb2.Duration  # CA lifetime
350
    key_spec: KeySpec  # Key specifications
351
    subordinate_config: SubordinateConfig  # Subordinate CA config (if applicable)
352
    tier: Tier  # Service tier (ENTERPRISE or DEVOPS)
353
    state: State  # Current CA state
354
    pem_ca_certificates: List[str]  # CA certificate chain (output only)
355
    ca_certificate_descriptions: List[CertificateDescription]  # Parsed CA details (output only)
356
    gcs_bucket: str  # Cloud Storage bucket for CRLs
357
    access_urls: AccessUrls  # CA access URLs (output only)
358
    create_time: timestamp_pb2.Timestamp  # Creation time (output only)
359
    update_time: timestamp_pb2.Timestamp  # Last update time (output only)
360
    delete_time: timestamp_pb2.Timestamp  # Deletion time (output only)
361
    expire_time: timestamp_pb2.Timestamp  # Expiration time (output only)
362
    labels: Dict[str, str]  # Resource labels
363

364
class CertificateAuthorityConfig:
365
    """Configuration for a Certificate Authority."""
366
    subject_config: SubjectConfig  # CA subject configuration
367
    x509_config: X509Parameters  # X.509 parameters
368
    public_key: PublicKey  # CA public key
369

370
class KeySpec:
371
    """Key specifications for CA."""
372
    cloud_kms_key_version: str  # Cloud KMS key version
373
    algorithm: Algorithm  # Key algorithm (RSA_PKCS1_2048_SHA256, etc.)
374

375
class SubordinateConfig:
376
    """Configuration for subordinate CAs."""
377
    certificate_authority: str  # Parent CA
378
    pem_issuer_chain: List[str]  # Issuer certificate chain
379

380
class AccessUrls:
381
    """Access URLs for the CA."""
382
    ca_certificate_access_url: str  # CA certificate download URL
383
    crl_access_urls: List[str]  # CRL download URLs
384
```
385

386
## Usage Examples
387

388
### Creating a Root Certificate Authority
389

390
```python
391
from google.cloud.security.privateca import (
392
    CertificateAuthorityServiceClient,
393
    CertificateAuthority,
394
    CertificateAuthorityConfig,
395
    KeySpec,
396
    SubjectConfig,
397
    X509Parameters
398
)
399

400
client = CertificateAuthorityServiceClient()
401

402
# Configure the CA
403
ca_config = CertificateAuthorityConfig(
404
    subject_config=SubjectConfig(
405
        subject={
406
            "common_name": "My Root CA",
407
            "organization": "My Company",
408
            "country_code": "US"
409
        }
410
    ),
411
    x509_config=X509Parameters(
412
        key_usage={
413
            "base_key_usage": {
414
                "cert_sign": True,
415
                "crl_sign": True
416
            },
417
            "extended_key_usage": {
418
                "server_auth": False,
419
                "client_auth": False
420
            }
421
        },
422
        ca_options={
423
            "is_ca": True,
424
            "max_issuer_path_length": 1
425
        }
426
    )
427
)
428

429
ca = CertificateAuthority(
430
    type_=CertificateAuthority.Type.SELF_SIGNED,
431
    config=ca_config,
432
    lifetime={"seconds": 86400 * 365 * 10},  # 10 years
433
    key_spec=KeySpec(algorithm=KeySpec.Algorithm.RSA_PKCS1_4096_SHA256),
434
    tier=CertificateAuthority.Tier.ENTERPRISE
435
)
436

437
# Create the CA
438
parent = "projects/my-project/locations/us-central1/caPools/my-ca-pool"
439
operation = client.create_certificate_authority(
440
    parent=parent,
441
    certificate_authority_id="my-root-ca",
442
    certificate_authority=ca
443
)
444

445
# Wait for completion
446
result = operation.result()
447
print(f"Created CA: {result.name}")
448
```
449

450
### Creating and Activating a Subordinate CA
451

452
```python
453
# Create subordinate CA
454
subordinate_ca = CertificateAuthority(
455
    type_=CertificateAuthority.Type.SUBORDINATE,
456
    config=ca_config,  # Similar config as above
457
    lifetime={"seconds": 86400 * 365 * 5},  # 5 years
458
    key_spec=KeySpec(algorithm=KeySpec.Algorithm.RSA_PKCS1_2048_SHA256),
459
    tier=CertificateAuthority.Tier.ENTERPRISE
460
)
461

462
operation = client.create_certificate_authority(
463
    parent=parent,
464
    certificate_authority_id="my-subordinate-ca",
465
    certificate_authority=subordinate_ca
466
)
467

468
created_ca = operation.result()
469
print(f"Created subordinate CA: {created_ca.name}")
470

471
# Fetch CSR for external signing
472
csr_response = client.fetch_certificate_authority_csr(name=created_ca.name)
473
print(f"CSR:\n{csr_response.pem_csr}")
474

475
# After getting the signed certificate from parent CA, activate it
476
signed_cert = "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
477

478
activation_operation = client.activate_certificate_authority(
479
    name=created_ca.name,
480
    pem_ca_certificate=signed_cert
481
)
482

483
activated_ca = activation_operation.result()
484
print(f"Activated CA: {activated_ca.name}")
485
```
486

487
### Managing CA State
488

489
```python
490
ca_name = "projects/my-project/locations/us-central1/caPools/my-ca-pool/certificateAuthorities/my-ca"
491

492
# Disable CA
493
disable_op = client.disable_certificate_authority(name=ca_name)
494
disabled_ca = disable_op.result()
495
print(f"CA state: {disabled_ca.state}")
496

497
# Enable CA
498
enable_op = client.enable_certificate_authority(name=ca_name)
499
enabled_ca = enable_op.result()
500
print(f"CA state: {enabled_ca.state}")
501

502
# List all CAs in pool
503
parent = "projects/my-project/locations/us-central1/caPools/my-ca-pool"
504
cas = client.list_certificate_authorities(parent=parent)
505

506
for ca in cas:
507
    print(f"CA: {ca.name}, State: {ca.state}, Type: {ca.type_}")
508
```