|
| 1 | +# Azure Key Vault Keys client module for Go |
| 2 | + |
| 3 | +* Cryptographic key management (this module) - create, store, and control access to the keys used to encrypt your data |
| 4 | +* Secrets management ([azsecrets](https://aka.ms/azsdk/go/keyvault-secrets/docs)) - securely store and control access to tokens, passwords, certificates, API keys, and other secrets |
| 5 | +* Certificate management ([azcertificates](https://aka.ms/azsdk/go/keyvault-certificates/docs)) - create, manage, and deploy public and private SSL/TLS certificates |
| 6 | + |
| 7 | +[Source code][key_client_src] | [Package (pkg.go.dev)][goget_azkeys] | [Product documentation][keyvault_docs] | [Samples][keys_samples] |
| 8 | + |
| 9 | +## Getting started |
| 10 | + |
| 11 | +### Install packages |
| 12 | + |
| 13 | +Install `azkeys` and `azidentity` with `go get`: |
| 14 | +```Bash |
| 15 | +go get github.com/Azure/azure-sdk-for-go/sdk/security/keyvault/azkeys |
| 16 | +go get github.com/Azure/azure-sdk-for-go/sdk/azidentity |
| 17 | +``` |
| 18 | +[azidentity][azure_identity] is used for Azure Active Directory authentication as demonstrated below. |
| 19 | + |
| 20 | +### Prerequisites |
| 21 | + |
| 22 | +* An [Azure subscription][azure_sub] |
| 23 | +* A supported Go version (the Azure SDK supports the two most recent Go releases) |
| 24 | +* A key vault. If you need to create one, see the Key Vault documentation for instructions on doing so in the [Azure Portal][azure_keyvault_portal] or with the [Azure CLI][azure_keyvault_cli]. |
| 25 | + |
| 26 | +### Authentication |
| 27 | + |
| 28 | +This document demonstrates using [azidentity.NewDefaultAzureCredential][default_cred_ref] to authenticate. This credential type works in both local development and production environments. We recommend using a [managed identity][managed_identity] in production. |
| 29 | + |
| 30 | +[Client][client_docs] accepts any [azidentity][azure_identity] credential. See the [azidentity][azure_identity] documentation for more information about other credential types. |
| 31 | + |
| 32 | +#### Create a client |
| 33 | + |
| 34 | +Constructing the client requires your vault's URL, which you can get from the Azure CLI or the Azure Portal. |
| 35 | + |
| 36 | +```go |
| 37 | +import ( |
| 38 | + "github.com/Azure/azure-sdk-for-go/sdk/azidentity" |
| 39 | + "github.com/Azure/azure-sdk-for-go/sdk/security/keyvault/azkeys" |
| 40 | +) |
| 41 | + |
| 42 | +func main() { |
| 43 | + cred, err := azidentity.NewDefaultAzureCredential(nil) |
| 44 | + if err != nil { |
| 45 | + // TODO: handle error |
| 46 | + } |
| 47 | + |
| 48 | + client, err := azkeys.NewClient("https://<TODO: your vault name>.vault.azure.net", cred, nil) |
| 49 | + if err != nil { |
| 50 | + // TODO: handle error |
| 51 | + } |
| 52 | +} |
| 53 | +``` |
| 54 | + |
| 55 | +## Key concepts |
| 56 | + |
| 57 | +### Keys |
| 58 | + |
| 59 | +Azure Key Vault can create and store RSA and elliptic curve keys. Both can optionally be protected by hardware security modules (HSMs). Azure Key Vault can also perform cryptographic operations with them. For more information about keys and supported operations and algorithms, see the [Key Vault documentation](https://docs.microsoft.com/azure/key-vault/keys/about-keys). |
| 60 | + |
| 61 | +[Client][client_docs] can create keys in the vault, get existing keys from the vault, update key metadata, and delete keys, as shown in the examples below. |
| 62 | + |
| 63 | +## Examples |
| 64 | + |
| 65 | +Get started with our [examples][keys_samples]. |
| 66 | + |
| 67 | +## Troubleshooting |
| 68 | + |
| 69 | +### Error Handling |
| 70 | + |
| 71 | +All methods which send HTTP requests return `*azcore.ResponseError` when these requests fail. `ResponseError` has error details and the raw response from Key Vault. |
| 72 | + |
| 73 | +```go |
| 74 | +import "github.com/Azure/azure-sdk-for-go/sdk/azcore" |
| 75 | + |
| 76 | +resp, err := client.GetKey(context.Background(), "keyName", nil) |
| 77 | +if err != nil { |
| 78 | + var httpErr *azcore.ResponseError |
| 79 | + if errors.As(err, &httpErr) { |
| 80 | + // TODO: investigate httpErr |
| 81 | + } else { |
| 82 | + // TODO: not an HTTP error |
| 83 | + } |
| 84 | +} |
| 85 | +``` |
| 86 | + |
| 87 | +### Logging |
| 88 | + |
| 89 | +This module uses the logging implementation in `azcore`. To turn on logging for all Azure SDK modules, set `AZURE_SDK_GO_LOGGING` to `all`. By default the logger writes to stderr. Use the `azcore/log` package to control log output. For example, logging only HTTP request and response events, and printing them to stdout: |
| 90 | + |
| 91 | +```go |
| 92 | +import azlog "github.com/Azure/azure-sdk-for-go/sdk/azcore/log" |
| 93 | + |
| 94 | +// Print log events to stdout |
| 95 | +azlog.SetListener(func(cls azlog.Event, msg string) { |
| 96 | + fmt.Println(msg) |
| 97 | +}) |
| 98 | + |
| 99 | +// Includes only requests and responses in credential logs |
| 100 | +azlog.SetEvents(azlog.EventRequest, azlog.EventResponse) |
| 101 | +``` |
| 102 | + |
| 103 | +### Accessing `http.Response` |
| 104 | + |
| 105 | +You can access the raw `*http.Response` returned by Key Vault using the `runtime.WithCaptureResponse` method and a context passed to any client method. |
| 106 | + |
| 107 | +```go |
| 108 | +import "github.com/Azure/azure-sdk-for-go/sdk/azcore/runtime" |
| 109 | + |
| 110 | +var response *http.Response |
| 111 | +ctx := runtime.WithCaptureResponse(context.TODO(), &response) |
| 112 | +_, err = client.GetKey(ctx, "keyName", nil) |
| 113 | +if err != nil { |
| 114 | + // TODO: handle error |
| 115 | +} |
| 116 | +// TODO: do something with response |
| 117 | +``` |
| 118 | + |
| 119 | +### Additional Documentation |
| 120 | + |
| 121 | +For more extensive documentation on Azure Key Vault, see the [API reference documentation][reference_docs]. |
| 122 | + |
| 123 | +## Contributing |
| 124 | + |
| 125 | +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://cla.microsoft.com. |
| 126 | + |
| 127 | +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. |
| 128 | + |
| 129 | +This project has adopted the [Microsoft Open Source Code of Conduct ][code_of_conduct]. For more information, see the [Code of Conduct FAQ ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [email protected] with any additional questions or comments. |
| 130 | + |
| 131 | + |
| 132 | +[azure_identity]: https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity |
| 133 | +[azure_keyvault_cli]: https://docs.microsoft.com/azure/key-vault/general/quick-create-cli |
| 134 | +[azure_keyvault_portal]: https://docs.microsoft.com/azure/key-vault/general/quick-create-portal |
| 135 | +[azure_sub]: https://azure.microsoft.com/free/ |
| 136 | +[default_cred_ref]: https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity#NewDefaultAzureCredential |
| 137 | +[code_of_conduct]: https://opensource.microsoft.com/codeofconduct/ |
| 138 | +[keyvault_docs]: https://docs.microsoft.com/azure/key-vault/ |
| 139 | +[goget_azkeys]: https://aka.ms/azsdk/go/keyvault-keys/docs |
| 140 | +[reference_docs]: https://aka.ms/azsdk/go/keyvault-keys/docs |
| 141 | +[client_docs]: https://aka.ms/azsdk/go/keyvault-keys/docs#Client |
| 142 | +[key_client_src]: https://github.com/Azure/azure-sdk-for-go/tree/main/sdk/keyvault/azkeys/client.go |
| 143 | +[keys_samples]: https://aka.ms/azsdk/go/keyvault-keys/docs#pkg-examples |
| 144 | +[managed_identity]: https://docs.microsoft.com/azure/active-directory/managed-identities-azure-resources/overview |
| 145 | + |
| 146 | + |
0 commit comments