Skip to content

Commit 803cfcf

Browse files
mccoypmccoyp
authored
[Key Vault] Create Security Domain library (#37929)
1 parent 77a5c9e commit 803cfcf

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

53 files changed

+8053
-1
lines changed

‎sdk/keyvault/.gitignore

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
11
*.cer
22
*.key
3-
*.pfx
3+
*.pfx
4+
*security-domain.json
5+
*.pem

‎sdk/keyvault/azure-keyvault-securitydomain/CHANGELOG.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Release History
2+
3+
## 1.0.0b1 (2025-05-06)
4+
5+
### Features Added
6+
7+
- Initial version

‎sdk/keyvault/azure-keyvault-securitydomain/LICENSE

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
Copyright (c) Microsoft Corporation.
2+
3+
MIT License
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED *AS IS*, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎sdk/keyvault/azure-keyvault-securitydomain/MANIFEST.in

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
include *.md
2+
include LICENSE
3+
include azure/keyvault/securitydomain/py.typed
4+
recursive-include tests *.py
5+
recursive-include samples *.py *.md
6+
include azure/__init__.py
7+
include azure/keyvault/__init__.py

‎sdk/keyvault/azure-keyvault-securitydomain/README.md

Lines changed: 206 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,206 @@
1+
# Azure Key Vault Security Domain client library for Python
2+
3+
Azure Key Vault helps solve the following problems:
4+
5+
- Managed HSM security domain management (this library) - securely download and restore a managed HSM's security domain
6+
- Cryptographic key management ([azure-keyvault-keys](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/keyvault/azure-keyvault-keys))- create, store, and control
7+
access to the keys used to encrypt your data
8+
- Secrets management
9+
([azure-keyvault-secrets](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/keyvault/azure-keyvault-secrets)) -
10+
securely store and control access to tokens, passwords, certificates, API keys,
11+
and other secrets
12+
- Certificate management
13+
([azure-keyvault-certificates](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/keyvault/azure-keyvault-certificates)) -
14+
create, manage, and deploy public and private SSL/TLS certificates
15+
- Vault administration ([azure-keyvault-administration](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/keyvault/azure-keyvault-administration)) - role-based access control (RBAC), and vault-level backup and restore options
16+
17+
[Source code][library_src]
18+
| [Package (PyPI)][pypi_package]
19+
| [API reference documentation][reference_docs]
20+
| [Key Vault documentation][azure_keyvault]
21+
| [Managed HSM documentation][azure_managedhsm]
22+
| [Samples][samples]
23+
24+
## Getting started
25+
26+
### Install the package
27+
28+
Install [azure-keyvault-securitydomain][pypi_package] and [azure-identity][azure_identity_pypi] with [pip][pip]:
29+
30+
```Bash
31+
python -m pip install azure-keyvault-securitydomain azure-identity
32+
```
33+
34+
[azure-identity][azure_identity] is used for Microsoft Entra ID authentication as demonstrated below.
35+
36+
#### Prequisites
37+
38+
- Python 3.9 or later
39+
- An [Azure subscription][azure_sub]
40+
- An existing [Key Vault Managed HSM][azure_managedhsm]. If you need to create a Managed HSM, you can do so using the Azure CLI by following the steps in [this document][managed_hsm_cli].
41+
42+
### Authenticate the client
43+
44+
In order to interact with the Azure Key Vault service, you will need an instance of a
45+
[SecurityDomainClient][securitydomain_client_docs], as well as a **vault URL** and a credential object. This document
46+
demonstrates using a [DefaultAzureCredential][default_cred_ref], which is appropriate for most scenarios. We recommend
47+
using a [managed identity][managed_identity] for authentication in production environments.
48+
49+
See [azure-identity][azure_identity] documentation for more information about other methods of authentication and their
50+
corresponding credential types.
51+
52+
#### Create a client
53+
54+
After configuring your environment for the [DefaultAzureCredential][default_cred_ref] to use a suitable method of
55+
authentication, you can do the following to create a security domain client (replacing the value of `VAULT_URL` with
56+
your vault's URL):
57+
58+
<!-- SNIPPET:hello_world.create_a_security_domain_client -->
59+
60+
```python
61+
from azure.identity import DefaultAzureCredential
62+
from azure.keyvault.securitydomain import SecurityDomainClient
63+
64+
VAULT_URL = os.environ["VAULT_URL"]
65+
credential = DefaultAzureCredential()
66+
client = SecurityDomainClient(vault_url=VAULT_URL, credential=credential)
67+
```
68+
69+
<!-- END SNIPPET -->
70+
71+
> **NOTE:** For an asynchronous client, import `azure.keyvault.securitydomain.aio`'s `SecurityDomainClient` instead.
72+
73+
## Key concepts
74+
75+
### Security domain
76+
77+
To operate, a managed HSM must have a security domain. The security domain is an encrypted blob file that contains
78+
artifacts like the HSM backup, user credentials, the signing key, and the data encryption key that's unique to the
79+
managed HSM. For more information, please see [service documentation][securitydomain_docs].
80+
81+
### SecurityDomainClient
82+
83+
A `SecurityDomainClient` can download and upload managed HSM security domains and get transfer keys.
84+
85+
### Download operation
86+
87+
A download operation retrieves the security domain of a managed HSM. This can be used to activate a provisioned
88+
managed HSM.
89+
90+
### Upload operation
91+
92+
An upload operation restores a managed HSM using a provided security domain.
93+
94+
### Transfer key
95+
96+
A transfer key, or exchange key, is used to encrypt a security domain before uploading it to a managed HSM. For more
97+
information, please see the [disaster recovery guide][disaster_recovery].
98+
99+
## Examples
100+
101+
This section contains code snippets covering common tasks:
102+
103+
- [Download a security domain](#download-a-security-domain)
104+
- [Get a transfer key](#get-a-transfer-key)
105+
- [Upload a security domain](#upload-a-security-domain)
106+
107+
### Download a security domain
108+
109+
`begin_download` can be used by a `SecurityDomainClient` to fetch a managed HSM's security domain, and this will also
110+
activate a provisioned managed HSM. By default, the poller returned by this operation will poll on the managed HSM's
111+
activation status, finishing when it's activated. To return immediately with the security domain object without waiting
112+
for activation, you can pass the keyword argument `skip_activation_polling=True`.
113+
114+
```python
115+
from azure.keyvault.securitydomain.models import SecurityDomain
116+
117+
security_domain: SecurityDomain = client.begin_download(certificate_info=certs_object).result()
118+
assert security_domain.value
119+
print("The managed HSM is now active.")
120+
```
121+
122+
### Get a transfer key
123+
124+
Using a different managed HSM than the one the security domain was downloaded from, `get_transfer_key` can be used by
125+
a `SecurityDomainClient` to fetch a transfer key (also known as an exchange key).
126+
127+
```python
128+
from azure.keyvault.securitydomain.models import TransferKey
129+
130+
NEW_VAULT_URL = os.environ["NEW_VAULT_URL"]
131+
upload_client = SecurityDomainClient(vault_url=NEW_VAULT_URL, credential=credential)
132+
133+
transfer_key: TransferKey = upload_client.get_transfer_key()
134+
assert transfer_key.transfer_key_jwk
135+
```
136+
137+
### Upload a security domain
138+
139+
`begin_upload` can be used by a `SecurityDomainClient` to restore a different managed HSM with a security domain, for
140+
example for disaster recovery. Like the download operation this will activate a provisioned managed HSM, but the poller
141+
will return None if successful (and an error if unsuccessful) instead of the security domain object.
142+
143+
```python
144+
from azure.keyvault.securitydomain.models import SecurityDomainOperationStatus
145+
146+
result: SecurityDomainOperationStatus = upload_client.begin_upload(security_domain=result).result()
147+
print("The managed HSM has been successfully restored with the security domain.")
148+
```
149+
150+
## Troubleshooting
151+
152+
See the Azure Key Vault SDK's
153+
[troubleshooting guide](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/keyvault/TROUBLESHOOTING.md) for
154+
details on how to diagnose various failure scenarios.
155+
156+
## Next steps
157+
Samples are available in the Azure SDK for Python GitHub repository. These samples provide example code for the
158+
following scenarios:
159+
160+
- [Download a security domain][hello_world_sample] ([async version][hello_world_async_sample])
161+
162+
## Contributing
163+
164+
This project welcomes contributions and suggestions. Most contributions require
165+
you to agree to a Contributor License Agreement (CLA) declaring that you have
166+
the right to, and actually do, grant us the rights to use your contribution.
167+
For details, visit https://cla.microsoft.com.
168+
169+
When you submit a pull request, a CLA-bot will automatically determine whether
170+
you need to provide a CLA and decorate the PR appropriately (e.g., label,
171+
comment). Simply follow the instructions provided by the bot. You will only
172+
need to do this once across all repos using our CLA.
173+
174+
This project has adopted the
175+
[Microsoft Open Source Code of Conduct][code_of_conduct]. For more information,
176+
see the Code of Conduct FAQ or contact [email protected] with any
177+
additional questions or comments.
178+
179+
<!-- LINKS -->
180+
[azure_identity]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/identity/azure-identity
181+
[azure_identity_pypi]: https://pypi.org/project/azure-identity/
182+
[azure_keyvault]: https://learn.microsoft.com/azure/key-vault/
183+
[azure_managedhsm]: https://learn.microsoft.com/azure/key-vault/managed-hsm/
184+
[azure_sub]: https://azure.microsoft.com/free/
185+
186+
[code_of_conduct]: https://opensource.microsoft.com/codeofconduct/
187+
188+
[default_cred_ref]: https://aka.ms/azsdk/python/identity/docs#azure.identity.DefaultAzureCredential
189+
[disaster_recovery]: https://learn.microsoft.com/azure/key-vault/managed-hsm/disaster-recovery-guide
190+
191+
[hello_world_sample]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/keyvault/azure-keyvault-securitydomain/samples/hello_world.py
192+
[hello_world_async_sample]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/keyvault/azure-keyvault-securitydomain/samples/hello_world_async.py
193+
194+
[library_src]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/keyvault/azure-keyvault-securitydomain/azure/keyvault/securitydomain
195+
196+
[managed_hsm_cli]: https://learn.microsoft.com/azure/key-vault/managed-hsm/quick-create-cli
197+
[managed_identity]: https://learn.microsoft.com/entra/identity/managed-identities-azure-resources/overview
198+
199+
[pip]: https://pypi.org/project/pip/
200+
[pypi_package]: https://pypi.org/project/azure-keyvault-securitydomain/
201+
202+
[reference_docs]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/keyvault/azure-keyvault-securitydomain/azure/keyvault/securitydomain
203+
204+
[samples]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/keyvault/azure-keyvault-securitydomain/samples
205+
[securitydomain_client_docs]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/keyvault/azure-keyvault-securitydomain/azure/keyvault/securitydomain/_patch.py
206+
[securitydomain_docs]: https://learn.microsoft.com/azure/key-vault/managed-hsm/security-domain

‎sdk/keyvault/azure-keyvault-securitydomain/apiview-properties.json

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
{
2+
"CrossLanguagePackageId": "KeyVault",
3+
"CrossLanguageDefinitionId": {
4+
"azure.keyvault.securitydomain.models.CertificateInfo": "KeyVault.CertificateInfoObject",
5+
"azure.keyvault.securitydomain.models.Error": "Error",
6+
"azure.keyvault.securitydomain.models.KeyVaultError": "KeyVaultError",
7+
"azure.keyvault.securitydomain.models.SecurityDomain": "KeyVault.SecurityDomainObject",
8+
"azure.keyvault.securitydomain.models.SecurityDomainJsonWebKey": "KeyVault.SecurityDomainJsonWebKey",
9+
"azure.keyvault.securitydomain.models.SecurityDomainOperationStatus": "KeyVault.SecurityDomainOperationStatus",
10+
"azure.keyvault.securitydomain.models.TransferKey": "KeyVault.TransferKey",
11+
"azure.keyvault.securitydomain.models.OperationStatus": "KeyVault.OperationStatus",
12+
"azure.keyvault.securitydomain.SecurityDomainClient.get_download_status": "ClientCustomizations.SecurityDomainClient.getDownloadStatus",
13+
"azure.keyvault.securitydomain.aio.SecurityDomainClient.get_download_status": "ClientCustomizations.SecurityDomainClient.getDownloadStatus",
14+
"azure.keyvault.securitydomain.SecurityDomainClient.get_upload_status": "ClientCustomizations.SecurityDomainClient.getUploadStatus",
15+
"azure.keyvault.securitydomain.aio.SecurityDomainClient.get_upload_status": "ClientCustomizations.SecurityDomainClient.getUploadStatus",
16+
"azure.keyvault.securitydomain.SecurityDomainClient.get_transfer_key": "ClientCustomizations.SecurityDomainClient.getTransferKey",
17+
"azure.keyvault.securitydomain.aio.SecurityDomainClient.get_transfer_key": "ClientCustomizations.SecurityDomainClient.getTransferKey"
18+
}
19+
}

‎sdk/keyvault/azure-keyvault-securitydomain/azure/__init__.py

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
__path__ = __import__("pkgutil").extend_path(__path__, __name__) # type: ignore

‎sdk/keyvault/azure-keyvault-securitydomain/azure/keyvault/__init__.py

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
__path__ = __import__("pkgutil").extend_path(__path__, __name__) # type: ignore

‎sdk/keyvault/azure-keyvault-securitydomain/azure/keyvault/securitydomain/__init__.py

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# coding=utf-8
2+
# --------------------------------------------------------------------------
3+
# Copyright (c) Microsoft Corporation. All rights reserved.
4+
# Licensed under the MIT License. See License.txt in the project root for license information.
5+
# Code generated by Microsoft (R) Python Code Generator.
6+
# Changes may cause incorrect behavior and will be lost if the code is regenerated.
7+
# --------------------------------------------------------------------------
8+
# pylint: disable=wrong-import-position
9+
10+
from typing import TYPE_CHECKING
11+
12+
if TYPE_CHECKING:
13+
from ._patch import * # pylint: disable=unused-wildcard-import
14+
15+
from ._client import SecurityDomainClient # type: ignore
16+
from ._version import VERSION
17+
18+
__version__ = VERSION
19+
20+
try:
21+
from ._patch import __all__ as _patch_all
22+
from ._patch import *
23+
except ImportError:
24+
_patch_all = []
25+
from ._patch import patch_sdk as _patch_sdk
26+
27+
__all__ = [
28+
"SecurityDomainClient",
29+
]
30+
__all__.extend([p for p in _patch_all if p not in __all__]) # pyright: ignore
31+
32+
_patch_sdk()

0 commit comments

Comments
 (0)