0
# Secrets Engines
1
2
Comprehensive secret management capabilities including static and dynamic secret storage, encryption services, and credential generation for databases, cloud services, and infrastructure components. HVAC supports 17+ secrets engines covering the full spectrum of modern secret management needs.
3
4
## Capabilities
5
6
### Key-Value Storage
7
8
Static secret storage with versioning, metadata, and access controls for application secrets and configuration data.
9
10
```python { .api }
11
class KvV2:
12
def create_or_update_secret(
13
self,
14
path: str,
15
secret: dict,
16
cas: int = None,
17
mount_point: str = "secret"
18
) -> dict: ...
19
20
def read_secret_version(
21
self,
22
path: str,
23
version: int = None,
24
mount_point: str = "secret",
25
raise_on_deleted_version: bool = True
26
) -> dict: ...
27
28
def patch(
29
self,
30
path: str,
31
secret: dict,
32
mount_point: str = "secret"
33
) -> dict: ...
34
35
def delete_latest_version_of_secret(
36
self,
37
path: str,
38
mount_point: str = "secret"
39
) -> None: ...
40
41
def delete_secret_versions(
42
self,
43
path: str,
44
versions: list,
45
mount_point: str = "secret"
46
) -> None: ...
47
48
def undelete_secret_versions(
49
self,
50
path: str,
51
versions: list,
52
mount_point: str = "secret"
53
) -> None: ...
54
55
def destroy_secret_versions(
56
self,
57
path: str,
58
versions: list,
59
mount_point: str = "secret"
60
) -> None: ...
61
62
def list_secrets(
63
self,
64
path: str,
65
mount_point: str = "secret"
66
) -> dict: ...
67
68
def read_secret_metadata(
69
self,
70
path: str,
71
mount_point: str = "secret"
72
) -> dict: ...
73
74
def update_metadata(
75
self,
76
path: str,
77
max_versions: int = None,
78
cas_required: bool = None,
79
delete_version_after: str = None,
80
custom_metadata: dict = None,
81
mount_point: str = "secret"
82
) -> None: ...
83
84
class KvV1:
85
def create_or_update_secret(
86
self,
87
path: str,
88
secret: dict,
89
method: str = None,
90
mount_point: str = "secret"
91
) -> dict: ...
92
93
def read_secret(
94
self,
95
path: str,
96
mount_point: str = "secret"
97
) -> dict: ...
98
99
def list_secrets(
100
self,
101
path: str,
102
mount_point: str = "secret"
103
) -> dict: ...
104
105
def delete_secret(
106
self,
107
path: str,
108
mount_point: str = "secret"
109
) -> None: ...
110
```
111
112
### Database Credential Management
113
114
Dynamic database credential generation with automatic rotation and multiple database support.
115
116
```python { .api }
117
class Database:
118
def configure(
119
self,
120
name: str,
121
plugin_name: str,
122
connection_url: str = None,
123
verify_connection: bool = True,
124
allowed_roles: list = None,
125
root_rotation_statements: list = None,
126
password_policy: str = None,
127
mount_point: str = "database",
128
**kwargs
129
) -> None: ...
130
131
def create_or_update_role(
132
self,
133
name: str,
134
db_name: str,
135
creation_statements: list,
136
default_ttl: str = None,
137
max_ttl: str = None,
138
revocation_statements: list = None,
139
renew_statements: list = None,
140
rollback_statements: list = None,
141
mount_point: str = "database"
142
) -> None: ...
143
144
def create_static_role(
145
self,
146
name: str,
147
db_name: str,
148
username: str,
149
rotation_statements: list = None,
150
rotation_period: str = "24h",
151
mount_point: str = "database"
152
) -> None: ...
153
154
def generate_credentials(
155
self,
156
name: str,
157
mount_point: str = "database"
158
) -> dict: ...
159
160
def get_static_credentials(
161
self,
162
name: str,
163
mount_point: str = "database"
164
) -> dict: ...
165
166
def rotate_static_role_credentials(
167
self,
168
name: str,
169
mount_point: str = "database"
170
) -> None: ...
171
```
172
173
### PKI Certificate Authority
174
175
Complete certificate authority operations including root CA generation, intermediate signing, and certificate issuance.
176
177
```python { .api }
178
class Pki:
179
def generate_root(
180
self,
181
type: str, # "internal" or "exported"
182
common_name: str,
183
alt_names: list = None,
184
ip_sans: list = None,
185
uri_sans: list = None,
186
other_sans: list = None,
187
ttl: str = None,
188
key_type: str = "rsa",
189
key_bits: int = 2048,
190
exclude_cn_from_sans: bool = False,
191
mount_point: str = "pki"
192
) -> dict: ...
193
194
def generate_intermediate(
195
self,
196
type: str,
197
common_name: str,
198
mount_point: str = "pki",
199
**kwargs
200
) -> dict: ...
201
202
def sign_intermediate(
203
self,
204
csr: str,
205
common_name: str,
206
ttl: str = None,
207
mount_point: str = "pki",
208
**kwargs
209
) -> dict: ...
210
211
def generate_certificate(
212
self,
213
name: str,
214
common_name: str,
215
alt_names: list = None,
216
ip_sans: list = None,
217
uri_sans: list = None,
218
other_sans: list = None,
219
ttl: str = None,
220
mount_point: str = "pki"
221
) -> dict: ...
222
223
def sign_certificate(
224
self,
225
name: str,
226
csr: str,
227
common_name: str,
228
mount_point: str = "pki",
229
**kwargs
230
) -> dict: ...
231
232
def revoke_certificate(
233
self,
234
serial_number: str,
235
mount_point: str = "pki"
236
) -> dict: ...
237
238
def create_or_update_role(
239
self,
240
name: str,
241
ttl: str = None,
242
max_ttl: str = None,
243
allow_localhost: bool = True,
244
allowed_domains: list = None,
245
allow_subdomains: bool = False,
246
allow_glob_domains: bool = False,
247
allow_any_name: bool = False,
248
enforce_hostnames: bool = True,
249
allow_ip_sans: bool = True,
250
mount_point: str = "pki",
251
**kwargs
252
) -> None: ...
253
```
254
255
### Encryption as a Service
256
257
High-performance encryption, decryption, and key management without exposing key material.
258
259
```python { .api }
260
class Transit:
261
def create_key(
262
self,
263
name: str,
264
key_type: str = "aes256-gcm96",
265
convergent_encryption: bool = None,
266
derived: bool = None,
267
exportable: bool = None,
268
allow_plaintext_backup: bool = None,
269
mount_point: str = "transit"
270
) -> None: ...
271
272
def encrypt_data(
273
self,
274
name: str,
275
plaintext: str, # base64 encoded
276
context: str = None, # base64 encoded
277
key_version: int = None,
278
nonce: str = None,
279
batch_input: list = None,
280
mount_point: str = "transit"
281
) -> dict: ...
282
283
def decrypt_data(
284
self,
285
name: str,
286
ciphertext: str,
287
context: str = None,
288
nonce: str = None,
289
batch_input: list = None,
290
mount_point: str = "transit"
291
) -> dict: ...
292
293
def rewrap_data(
294
self,
295
name: str,
296
ciphertext: str,
297
context: str = None,
298
key_version: int = None,
299
batch_input: list = None,
300
mount_point: str = "transit"
301
) -> dict: ...
302
303
def generate_data_key(
304
self,
305
name: str,
306
key_type: str = "plaintext", # "plaintext" or "wrapped"
307
context: str = None,
308
nonce: str = None,
309
bits: int = 256,
310
mount_point: str = "transit"
311
) -> dict: ...
312
313
def sign_data(
314
self,
315
name: str,
316
hash_input: str, # base64 encoded
317
hash_algorithm: str = "sha2-256",
318
signature_algorithm: str = None,
319
mount_point: str = "transit"
320
) -> dict: ...
321
322
def verify_signed_data(
323
self,
324
name: str,
325
hash_input: str,
326
signature: str,
327
hash_algorithm: str = "sha2-256",
328
signature_algorithm: str = None,
329
mount_point: str = "transit"
330
) -> dict: ...
331
332
def rotate_key(
333
self,
334
name: str,
335
mount_point: str = "transit"
336
) -> None: ...
337
```
338
339
### Cloud Provider Credentials
340
341
Dynamic credential generation for major cloud platforms with fine-grained permissions.
342
343
```python { .api }
344
class Aws:
345
def configure_root_iam_credentials(
346
self,
347
access_key: str,
348
secret_key: str,
349
region: str = "us-east-1",
350
iam_endpoint: str = None,
351
sts_endpoint: str = None,
352
mount_point: str = "aws"
353
) -> None: ...
354
355
def create_or_update_role(
356
self,
357
name: str,
358
credential_type: str, # "iam_user", "assumed_role", "federation_token"
359
policy_document: str = None,
360
policy_arns: list = None,
361
role_arns: list = None,
362
default_sts_ttl: str = None,
363
max_sts_ttl: str = None,
364
mount_point: str = "aws"
365
) -> None: ...
366
367
def generate_credentials(
368
self,
369
name: str,
370
role_arn: str = None,
371
role_session_name: str = None,
372
ttl: str = None,
373
mount_point: str = "aws"
374
) -> dict: ...
375
376
class Azure:
377
def configure(
378
self,
379
subscription_id: str,
380
tenant_id: str,
381
client_id: str = None,
382
client_secret: str = None,
383
environment: str = "AzurePublicCloud",
384
mount_point: str = "azure"
385
) -> None: ...
386
387
def create_or_update_role(
388
self,
389
name: str,
390
azure_roles: list,
391
ttl: str = None,
392
max_ttl: str = None,
393
mount_point: str = "azure"
394
) -> None: ...
395
396
def generate_credentials(
397
self,
398
name: str,
399
mount_point: str = "azure"
400
) -> dict: ...
401
402
class Gcp:
403
def create_or_update_roleset(
404
self,
405
name: str,
406
project: str,
407
bindings: str, # HCL string
408
token_scopes: list = None,
409
mount_point: str = "gcp"
410
) -> None: ...
411
412
def generate_oauth2_access_token(
413
self,
414
roleset: str,
415
mount_point: str = "gcp"
416
) -> dict: ...
417
418
def generate_service_account_key(
419
self,
420
roleset: str,
421
key_algorithm: str = "KEY_ALG_RSA_2048",
422
key_type: str = "TYPE_GOOGLE_CREDENTIALS_FILE",
423
mount_point: str = "gcp"
424
) -> dict: ...
425
```
426
427
### Identity and Directory Services
428
429
Automated credential rotation for Active Directory and LDAP service accounts.
430
431
```python { .api }
432
class ActiveDirectory:
433
def configure(
434
self,
435
binddn: str,
436
bindpass: str,
437
url: str,
438
userdn: str = None,
439
upndomain: str = None,
440
mount_point: str = "ad"
441
) -> None: ...
442
443
def create_or_update_role(
444
self,
445
name: str,
446
service_account_name: str,
447
ttl: str = None,
448
mount_point: str = "ad"
449
) -> None: ...
450
451
def generate_credentials(
452
self,
453
name: str,
454
mount_point: str = "ad"
455
) -> dict: ...
456
457
class Ldap:
458
def configure(
459
self,
460
binddn: str,
461
bindpass: str,
462
url: str,
463
schema: str = "openldap", # "openldap", "ad", "racf"
464
userdn: str = None,
465
mount_point: str = "ldap"
466
) -> None: ...
467
468
def create_or_update_static_role(
469
self,
470
name: str,
471
username: str,
472
dn: str,
473
rotation_period: str = "24h",
474
mount_point: str = "ldap"
475
) -> None: ...
476
477
def generate_static_credentials(
478
self,
479
name: str,
480
mount_point: str = "ldap"
481
) -> dict: ...
482
```
483
484
### Infrastructure Access
485
486
SSH access management and service discovery credentials for infrastructure automation.
487
488
```python { .api }
489
class Ssh:
490
def create_role(
491
self,
492
name: str,
493
key_type: str, # "otp", "dynamic", "ca"
494
default_user: str = None,
495
cidr_list: str = None,
496
allowed_users: str = None,
497
ttl: str = None,
498
max_ttl: str = None,
499
mount_point: str = "ssh"
500
) -> None: ...
501
502
def generate_ssh_credentials(
503
self,
504
name: str,
505
username: str = None,
506
ip: str = None,
507
mount_point: str = "ssh"
508
) -> dict: ...
509
510
def sign_ssh_key(
511
self,
512
name: str,
513
public_key: str,
514
ttl: str = None,
515
valid_principals: str = None,
516
cert_type: str = "user", # "user" or "host"
517
key_id: str = None,
518
mount_point: str = "ssh"
519
) -> dict: ...
520
521
class Consul:
522
def configure_access(
523
self,
524
address: str,
525
token: str,
526
scheme: str = "http",
527
mount_point: str = "consul"
528
) -> None: ...
529
530
def create_or_update_role(
531
self,
532
name: str,
533
policies: list = None,
534
policy: str = None, # base64 encoded
535
token_type: str = "client", # "client" or "management"
536
ttl: str = None,
537
max_ttl: str = None,
538
mount_point: str = "consul"
539
) -> None: ...
540
541
def generate_credentials(
542
self,
543
name: str,
544
mount_point: str = "consul"
545
) -> dict: ...
546
547
class RabbitMQ:
548
def configure_connection(
549
self,
550
connection_uri: str,
551
username: str = None,
552
password: str = None,
553
verify_connection: bool = True,
554
mount_point: str = "rabbitmq"
555
) -> None: ...
556
557
def create_role(
558
self,
559
name: str,
560
tags: str = None,
561
vhosts: str = None,
562
vhost_topics: str = None,
563
mount_point: str = "rabbitmq"
564
) -> None: ...
565
566
def generate_credentials(
567
self,
568
name: str,
569
mount_point: str = "rabbitmq"
570
) -> dict: ...
571
```
572
573
### Data Protection and Transformation
574
575
Format-preserving encryption, tokenization, and data masking for compliance and privacy.
576
577
```python { .api }
578
class Transform:
579
def create_or_update_transformation(
580
self,
581
name: str,
582
type: str, # "fpe", "masking", "tokenization"
583
template: str = None,
584
tweak_source: str = "supplied",
585
allowed_roles: list = None,
586
mount_point: str = "transform"
587
) -> None: ...
588
589
def create_or_update_role(
590
self,
591
name: str,
592
transformations: list,
593
mount_point: str = "transform"
594
) -> None: ...
595
596
def encode(
597
self,
598
role_name: str,
599
value: str = None,
600
transformation: str = None,
601
tweak: str = None,
602
batch_input: list = None,
603
mount_point: str = "transform"
604
) -> dict: ...
605
606
def decode(
607
self,
608
role_name: str,
609
value: str = None,
610
transformation: str = None,
611
tweak: str = None,
612
batch_input: list = None,
613
mount_point: str = "transform"
614
) -> dict: ...
615
616
class Identity:
617
def create_or_update_entity(
618
self,
619
name: str = None,
620
entity_id: str = None,
621
metadata: dict = None,
622
policies: list = None,
623
disabled: bool = None,
624
mount_point: str = "identity"
625
) -> dict: ...
626
627
def create_or_update_group(
628
self,
629
name: str,
630
group_id: str = None,
631
group_type: str = "internal", # "internal" or "external"
632
metadata: dict = None,
633
policies: list = None,
634
member_entity_ids: list = None,
635
mount_point: str = "identity"
636
) -> dict: ...
637
638
def generate_signed_id_token(
639
self,
640
name: str,
641
audience: str = None,
642
template: str = None,
643
mount_point: str = "identity"
644
) -> dict: ...
645
```
646
647
## Usage Examples
648
649
### Key-Value Secret Management
650
651
```python
652
import hvac
653
654
client = hvac.Client(url='https://vault.example.com:8200')
655
client.token = 'your-token'
656
657
# Store application secrets
658
response = client.secrets.kv_v2.create_or_update_secret(
659
path='myapp/config',
660
secret={
661
'database_url': 'postgres://user:pass@host:5432/db',
662
'api_key': 'secret123',
663
'debug': True
664
}
665
)
666
667
# Read secret
668
secret = client.secrets.kv_v2.read_secret_version(path='myapp/config')
669
config = secret['data']['data']
670
print(f"Database URL: {config['database_url']}")
671
672
# Update specific keys without overwriting
673
client.secrets.kv_v2.patch(
674
path='myapp/config',
675
secret={'api_key': 'newsecret456'}
676
)
677
678
# Read specific version
679
old_version = client.secrets.kv_v2.read_secret_version(
680
path='myapp/config',
681
version=1
682
)
683
```
684
685
### Dynamic Database Credentials
686
687
```python
688
# Configure database connection
689
client.secrets.database.configure(
690
name='postgres-db',
691
plugin_name='postgresql-database-plugin',
692
connection_url='postgresql://{{username}}:{{password}}@postgres:5432/mydb',
693
allowed_roles=['readonly', 'readwrite'],
694
username='vault',
695
password='vault-password'
696
)
697
698
# Create role for read-only access
699
client.secrets.database.create_or_update_role(
700
name='readonly',
701
db_name='postgres-db',
702
creation_statements=[
703
'CREATE ROLE "{{name}}" WITH LOGIN PASSWORD \'{{password}}\' VALID UNTIL \'{{expiration}}\';',
704
'GRANT SELECT ON ALL TABLES IN SCHEMA public TO "{{name}}";'
705
],
706
default_ttl='1h',
707
max_ttl='24h'
708
)
709
710
# Generate dynamic credentials
711
creds = client.secrets.database.generate_credentials(name='readonly')
712
username = creds['data']['username']
713
password = creds['data']['password']
714
lease_duration = creds['lease_duration']
715
print(f"Database user: {username}, expires in {lease_duration}s")
716
```
717
718
### PKI Certificate Operations
719
720
```python
721
# Generate root CA
722
root_ca = client.secrets.pki.generate_root(
723
type='internal',
724
common_name='My Company Root CA',
725
ttl='8760h' # 1 year
726
)
727
728
# Create certificate role
729
client.secrets.pki.create_or_update_role(
730
name='web-server',
731
allowed_domains=['example.com'],
732
allow_subdomains=True,
733
max_ttl='720h' # 30 days
734
)
735
736
# Generate certificate
737
cert = client.secrets.pki.generate_certificate(
738
name='web-server',
739
common_name='api.example.com',
740
alt_names=['www.example.com'],
741
ttl='168h' # 7 days
742
)
743
744
certificate = cert['data']['certificate']
745
private_key = cert['data']['private_key']
746
ca_chain = cert['data']['ca_chain']
747
```
748
749
### Transit Encryption Service
750
751
```python
752
# Create encryption key
753
client.secrets.transit.create_key(
754
name='app-key',
755
key_type='aes256-gcm96'
756
)
757
758
# Encrypt sensitive data
759
import base64
760
plaintext = base64.b64encode(b'sensitive data').decode('utf-8')
761
encrypted = client.secrets.transit.encrypt_data(
762
name='app-key',
763
plaintext=plaintext
764
)
765
ciphertext = encrypted['data']['ciphertext']
766
767
# Decrypt data
768
decrypted = client.secrets.transit.decrypt_data(
769
name='app-key',
770
ciphertext=ciphertext
771
)
772
original_data = base64.b64decode(decrypted['data']['plaintext']).decode('utf-8')
773
print(f"Decrypted: {original_data}")
774
775
# Generate data encryption key
776
data_key = client.secrets.transit.generate_data_key(
777
name='app-key',
778
key_type='plaintext'
779
)
780
plaintext_key = data_key['data']['plaintext']
781
ciphertext_key = data_key['data']['ciphertext']
782
```
783
784
### AWS Dynamic Credentials
785
786
```python
787
# Configure AWS secrets engine
788
client.secrets.aws.configure_root_iam_credentials(
789
access_key='AWS_ACCESS_KEY',
790
secret_key='AWS_SECRET_KEY',
791
region='us-east-1'
792
)
793
794
# Create role for S3 access
795
client.secrets.aws.create_or_update_role(
796
name='s3-readonly',
797
credential_type='iam_user',
798
policy_document='''{
799
"Version": "2012-10-17",
800
"Statement": [
801
{
802
"Effect": "Allow",
803
"Action": "s3:GetObject",
804
"Resource": "arn:aws:s3:::my-bucket/*"
805
}
806
]
807
}'''
808
)
809
810
# Generate AWS credentials
811
aws_creds = client.secrets.aws.generate_credentials(name='s3-readonly')
812
access_key = aws_creds['data']['access_key']
813
secret_key = aws_creds['data']['secret_key']
814
lease_duration = aws_creds['lease_duration']
815
```