Azure Security Keyvault Secrets Package client library for C++

Azure Security Keyvault Secrets Package client library for C++ (azure-security-keyvault-secrets) matches necessary patterns that the development team has established to create a unified SDK written in the C++ programming language. These libraries follow the Azure SDK Design Guidelines for C++.

The library allows client libraries to expose common functionality in a consistent fashion. Once you learn how to use these APIs in one client library, you will know how to use them in other client libraries.

Source code | API reference documentation | Product documentation

Getting started

Install the package

Install the Azure Key Vault secrets client library for C++ with vcpkg:

vcpkg install azure-security-keyvault-secrets-cpp

Prerequisites

• An Azure subscription.
• An existing Azure Key Vault. If you need to create an Azure Key Vault, you can use the Azure Portal or Azure CLI.

If you use the Azure CLI, replace <your-resource-group-name> and <your-key-vault-name> with your own, unique names:

az keyvault create --resource-group <your-resource-group-name> --name <your-key-vault-name>

Key concepts

KeyVaultSecret

A Secret is the fundamental resource within Azure Key Vault. From a developer's perspective, Azure Key Vault APIs accept and return secret values as strings.

SecretClient

SecretClient provides synchronous operations exists in the SDK. Once you've initialized a SecretClient, you can interact with the primary resource types in Azure Key Vault.

Thread safety

We guarantee that all client instance methods are thread-safe and independent of each other (guideline). This ensures that the recommendation of reusing client instances is always safe, even across threads.

Additional concepts

Replaceable HTTP transport adapter | Long-running operations |

Examples

For detailed samples please review the samples provided.

Create a client

First step is to create a SecretClient.

auto credential = std::make_shared<Azure::Identity::DefaultAzureCredential>();
 
// create client
SecretClient secretClient(std::getenv("AZURE_KEYVAULT_URL"), credential);

Create a secret

We call the secret client to create a secret.

std::string secretName("MySampleSecret");
std::string secretValue("my secret value");
 
secretClient.SetSecret(secretName, secretValue);

Get a secret

We retrieve a secret by name.

// get secret
KeyVaultSecret secret = secretClient.GetSecret(secretName).Value;
 
std::cout << "Secret is returned with name " << secret.Name << " and value "
          << secret.Value.Value() << std::endl;

Update a secret

Updating an existing secret

// change one of the properties
secret.Properties.ContentType = "my content";
// update the secret
KeyVaultSecret updatedSecret = secretClient.UpdateSecretProperties(secret.Properties).Value;
std::cout << "Secret's content type is now " << updatedSecret.Properties.ContentType.Value()
          << std::endl;

Delete a secret

Delete an existing secret.

// start deleting the secret
DeleteSecretOperation operation = secretClient.StartDeleteSecret(secret.Name);
 
// You only need to wait for completion if you want to purge or recover the secret.
// The duration of the delete operation might vary
// in case returns too fast increase the timeout value
operation.PollUntilDone(20s);
 
// purge the deleted secret
secretClient.PurgeDeletedSecret(secret.Name);

Delete and purge a secret

Delete and Purge a secret.

// start deleting the secret
DeleteSecretOperation operation = secretClient.StartDeleteSecret(secret.Name);
 
// You only need to wait for completion if you want to purge or recover the secret.
// The duration of the delete operation might vary
// in case returns too fast increase the timeout value
operation.PollUntilDone(20s);
 
// purge the deleted secret
secretClient.PurgeDeletedSecret(secret.Name);

List Secrets

List all the secrets in keyvault.

// get all the versions of a secret
for (auto secretsVersion = secretClient.GetPropertiesOfSecretsVersions(secret1.Name);
     secretsVersion.HasPage();
     secretsVersion.MoveToNextPage())
{ // go through each version of the secret
  // the number of results returned for in a page is not guaranteed
  // it can be anywhere from 0 to 25
  for (auto const& secret : secretsVersion.Items)
  {
    std::cout << "Found Secret with name: " << secret.Name
              << " and with version: " << secret.Version << std::endl;
  }
}

Troubleshooting

When you interact with the Azure Key Vault Secrets client library using the C++ SDK, errors returned by the service correspond to the same HTTP status codes returned for requests.

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".

try
{
  Secret secret = client.GetSecret("some_secret").Value;
}
catch (const Azure::Core::RequestFailedException& ex)
{
  std::cout << std::underlying_type<Azure::Core::Http::HttpStatusCode>::type(ex.StatusCode);
}

You will notice that additional information is logged, like the client request ID of the operation.

Next steps

Several Azure Key Vault secrets client library samples are available to you in this GitHub repository. These samples provide example code for additional scenarios commonly encountered while working with Azure Key Vault:

• Sample1-Basic-Operations:
  • Create a secret
  • Get a secret
  • Update a secret
  • Delete and Purge a secret
• Sample2-Backup-Restore:
  • Backup a secret
  • Restore a deleted secret
• Sample3-Delete-Recover:
  • Delete a secret
  • Recover a deleted Secret
• Sample4-Get-Secrets-Deleted:
  • List all secrets
  • List all of a secrets versions
  • List all deletes secrets
  • Get properties of a deleted secret

Contributing

For details on contributing to this repository, see the contributing guide.

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 the Contributor License Agreement.

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.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Additional Helpful Links for Contributors

Many people all over the world have helped make this project better. You'll want to check out:

• What are some good first issues for new contributors to the repo?
• How to build and test your change
• How you can make a change happen!
• Frequently Asked Questions (FAQ) and Conceptual Topics in the detailed Azure SDK for C++ wiki.

Reporting security issues and security bugs

Security issues and bugs should be reported privately, via email, to the Microsoft Security Response Center (MSRC) secur.nosp@m.e@mi.nosp@m.croso.nosp@m.ft.c.nosp@m.om. You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Further information, including the MSRC PGP key, can be found in the Security TechCenter.

License

Azure SDK for C++ is licensed under the MIT license.