|
| 1 | +# Azure Key Vault certificates client library for Rust |
| 2 | + |
| 3 | +Azure Key Vault is a cloud service that provides secure storage of certificates for encrypting your data. Multiple certificates, and multiple versions of the same certificate, can be kept in the Azure Key Vault. |
| 4 | + |
| 5 | +The Azure Key Vault certificates client library allows you to securely store and control the access to certificates. This library offers operations to create, import, retrieve the public key, update, delete, purge, backup, restore, and list the certificates and its versions. |
| 6 | + |
| 7 | +[Source code] | [Package (crates.io)] | [API reference documentation] | [Product documentation] |
| 8 | + |
| 9 | +## Getting started |
| 10 | + |
| 11 | +### Install the package |
| 12 | + |
| 13 | +Install the Azure Key Vault certificates client library for Rust with [Cargo]: |
| 14 | + |
| 15 | +```sh |
| 16 | +cargo add azure_security_keyvault_certificates |
| 17 | +``` |
| 18 | + |
| 19 | +### Prerequisites |
| 20 | + |
| 21 | +* An [Azure subscription]. |
| 22 | +* An existing Azure Key Vault. If you need to create an Azure Key Vault, you can use the Azure Portal or [Azure CLI]. |
| 23 | +* Authorization to an existing Azure Key Vault using either [RBAC] (recommended) or [access control]. |
| 24 | + |
| 25 | +If you use the Azure CLI, replace `<your-resource-group-name>` and `<your-key-vault-name>` with your own, unique names: |
| 26 | + |
| 27 | +```azurecli |
| 28 | +az keyvault create --resource-group <your-resource-group-name> --name <your-key-vault-name> |
| 29 | +``` |
| 30 | + |
| 31 | +### Install dependencies |
| 32 | + |
| 33 | +Add the following crates to your project: |
| 34 | + |
| 35 | +```sh |
| 36 | +cargo add azure_identity tokio |
| 37 | +``` |
| 38 | + |
| 39 | +### Authenticate the client |
| 40 | + |
| 41 | +In order to interact with the Azure Key Vault service, you'll need to create an instance of the `CertificateClient`. You need a **vault url**, which you may see as "DNS Name" in the portal, and credentials to instantiate a client object. |
| 42 | + |
| 43 | +The example shown below uses a `DefaultAzureCredential`, which is appropriate for local development environments. We recommend using a managed identity for authentication in production environments. You can find more information on different ways of authenticating and their corresponding credential types in the [Azure Identity] documentation. |
| 44 | + |
| 45 | +The `DefaultAzureCredential` will automatically pick up on an Azure CLI authentication. Ensure you are logged in with the Azure CLI: |
| 46 | + |
| 47 | +```azurecli |
| 48 | +az login |
| 49 | +``` |
| 50 | + |
| 51 | +Instantiate a `DefaultAzureCredential` to pass to the client. The same instance of a token credential can be used with multiple clients if they will be authenticating with the same identity. |
| 52 | + |
| 53 | +## Key concepts |
| 54 | + |
| 55 | +### CertificateBundle |
| 56 | + |
| 57 | +A Azure Key Vault certificate public key. The private key is never included when retrieving a `CertificateBundle`. |
| 58 | + |
| 59 | +### CertificateClient |
| 60 | + |
| 61 | +The `CertificateClient` provides asynchronous operations for working with Key Vault certificates. |
| 62 | + |
| 63 | +### Thread safety |
| 64 | + |
| 65 | +We guarantee that all client instance methods are thread-safe and independent of each other. This ensures that the recommendation of reusing client instances is always safe, even across threads. |
| 66 | + |
| 67 | +## Examples |
| 68 | + |
| 69 | +> TODO |
| 70 | +
|
| 71 | +## Troubleshooting |
| 72 | + |
| 73 | +### General |
| 74 | + |
| 75 | +When you interact with the Azure Key Vault certificates client library using the Rust SDK, errors returned by the service correspond to the same HTTP status codes returned for [REST API] requests. |
| 76 | + |
| 77 | +For example, if you try to retrieve a key that doesn't exist in your Azure Key Vault, a `404` error is returned, indicating `Not Found`. |
| 78 | + |
| 79 | +```rust no_run |
| 80 | +use azure_identity::DefaultAzureCredential; |
| 81 | +use azure_security_keyvault_certificates::CertificateClient; |
| 82 | + |
| 83 | +#[tokio::main] |
| 84 | +async fn main() -> Result<(), Box<dyn std::error::Error>> { |
| 85 | + let credential = DefaultAzureCredential::new()?; |
| 86 | + let client = CertificateClient::new( |
| 87 | + "https://<my-vault>.vault.azure.net/", |
| 88 | + credential.clone(), |
| 89 | + None, |
| 90 | + )?; |
| 91 | + |
| 92 | + match client.get_certificate("certificate-name".into(), "".into(), None).await { |
| 93 | + Ok(response) => println!("Certificate: {:#?}", response.into_body().await?.x509_thumbprint), |
| 94 | + Err(err) => println!("Error: {:#?}", err.into_inner()?), |
| 95 | + } |
| 96 | + |
| 97 | + Ok(()) |
| 98 | +} |
| 99 | +``` |
| 100 | + |
| 101 | +You will notice that additional information is logged, like the Client Request ID of the operation. |
| 102 | + |
| 103 | +```text |
| 104 | +Error: HttpError { |
| 105 | + status: NotFound, |
| 106 | + details: ErrorDetails { |
| 107 | + code: Some( |
| 108 | + "CertificateNotFound", |
| 109 | + ), |
| 110 | + message: Some( |
| 111 | + "A certificate with (name/id) certificate-name was not found in this key vault. If you recently deleted this certificate you may be able to recover it using the correct recovery command. For help resolving this issue, please see https://go.microsoft.com/fwlink/?linkid=2125182", |
| 112 | + ), |
| 113 | + }, |
| 114 | + .. |
| 115 | +} |
| 116 | +``` |
| 117 | + |
| 118 | +## Contributing |
| 119 | + |
| 120 | +See the [CONTRIBUTING.md] for details on building, testing, and contributing to these libraries. |
| 121 | + |
| 122 | +This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit <https://opensource.microsoft.com/cla/>. |
| 123 | + |
| 124 | +When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA. |
| 125 | + |
| 126 | +This project has adopted the [Microsoft Open Source Code of Conduct ]. For more information see the [Code of Conduct FAQ ] or contact <[email protected]> with any additional questions or comments. |
| 127 | + |
| 128 | +<!-- LINKS --> |
| 129 | +[API reference documentation]: https://docs.rs/azure_security_keyvault_certificates/latest/azure_security_keyvault_certificates |
| 130 | +[Azure CLI]: https://learn.microsoft.com/cli/azure |
| 131 | +[Azure subscription]: https://azure.microsoft.com/free/ |
| 132 | +[Azure Identity]: https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/identity/azure_identity |
| 133 | +[Microsoft Open Source Code of Conduct]: https://opensource.microsoft.com/codeofconduct/ |
| 134 | +[Product documentation]: https://learn.microsoft.com/azure/key-vault/ |
| 135 | +[REST API]: https://learn.microsoft.com/rest/api/keyvault/ |
| 136 | +[Cargo]: https://crates.io/ |
| 137 | +[Package (crates.io)]: https://crates.io/crates/azure_security_keyvault_certificates |
| 138 | +[Source code]: https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/keyvault/azure_security_keyvault_certificates/src |
| 139 | +[CONTRIBUTING.md]: https://github.com/Azure/azure-sdk-for-rust/blob/main/CONTRIBUTING.md |
| 140 | +[Code of Conduct FAQ]: https://opensource.microsoft.com/codeofconduct/faq/ |
| 141 | +[access control]: https://learn.microsoft.com/azure/key-vault/general/assign-access-policy |
| 142 | +[RBAC]: https://learn.microsoft.com/azure/key-vault/general/rbac-guide |
0 commit comments