Azure Key Vault Certificates client library for C++

Azure Key Vault is a cloud service that provides secure storage and automated management of certificates used throughout a cloud application. Multiple certificates, and multiple versions of the same certificate, can be kept in the Azure Key Vault. Each certificate in the vault has a policy associated with it which controls the issuance and lifetime of the certificate, along with actions to be taken as certificates near expiry.

The Azure Key Vault certificates client library enables programmatically managing certificates, offering methods to get certificates, policies, issuers, and contacts.

Source code | Package (vcpkg) | API reference documentation | Product documentation | Samples

Getting started

Prerequisites

vcpkg for package acquisition and dependency management
CMake for project build
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 login 
az keyvault create --resource-group <your-resource-group-name> --name <your-key-vault-name>

Install the package

The easiest way to acquire the C++ SDK is leveraging the vcpkg package manager and CMake. See the corresponding Azure SDK for C++ readme section. We'll use vcpkg in manifest mode. To start a vcpkg project in manifest mode use the following command at the root of your project:

vcpkg new --application

To install the Azure <Service-Name> package via vcpkg: To add the Azure <Service-Name> package to your vcpkg enter the following command (We'll also add the Azure Identity library for authentication):

vcpkg add port azure-security-keyvault-certificates-cpp azure-identity-cpp

Then, add the following in your CMake file:

find_package(azure-identity-cpp CONFIG REQUIRED)
find_package(azure-security-keyvault-certificates-cpp CONFIG REQUIRED)
target_link_libraries(<your project name> PRIVATE Azure::azure-security-keyvault-certificates Azure::azure-identity)

Remember to set CMAKE_TOOLCHAIN_FILE to the path to vcpkg.cmake either by adding the following to your CMakeLists.txt file before your project statement:

set(CMAKE_TOOLCHAIN_FILE "vcpkg-root/scripts/buildsystems/vcpkg.cmake")

Or by specifying it in your CMake commands with the -DCMAKE_TOOLCHAIN_FILE argument.

There is more than one way to acquire and install this library. Check out our samples on different ways to set up your Azure C++ project.

Key concepts

KeyVault Certificate

A KeyVaultCertificate is the fundamental resource within Azure Key Vault. You'll use certificates to encrypt and verify encrypted or signed data.

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 |

CertificateClient

With a CertificateClient you can get certificates from the vault, create new certificates and new versions of existing certificates, update certificate metadata, and delete certificates. You can also manage certificate issuers, contacts, and management policies of certificates. This is illustrated in the examples below.

Creating a CertificateClient

To create a new CertificateClient to create, get, update, or delete certificates, you need the endpoint to an Azure Key Vault and credentials.

Key Vault Certificate client for C++ currently supports any TokenCredential for authenticating.

  auto credential = std::make_shared<Azure::Identity::DefaultAzureCredential>();

Then, in the sample below, you can set keyVaultUrl based on an environment variable, configuration setting, or any way that works for your application.

auto const keyVaultUrl = std::getenv("AZURE_KEYVAULT_URL");
...
 CertificateClient certificateClient(keyVaultUrl, credential);

Start creating a Certificate

Call StartCreateCertificate to start creating a new certificate, with specified properties and policy.

std::string certificateName = "Sample1";
CertificateCreateOptions options;
... 
// start the create process
auto response = certificateClient.StartCreateCertificate(certificateName, options);

Getting a Certificate once completed

Call PollUntilDone to poll the status of the creation. Once the opperation has completed we will call GetCertificate to get the newly created certificate.

// wait for complete to get the certificate
auto pollResponse = response.PollUntilDone(defaultWait).Value;
// check the status of the poll response
if (!pollResponse.Error && pollResponse.Status.Value() == "completed")
{
// get the certificate
certificate = certificateClient.GetCertificate(certificateName).Value;
std::cout << "Created certificate with policy. Certificate name : " << certificate.Name();
}

Updating certificate properties

Call UpdateCertificateProperties to change one of the certificate properties.

CertificateUpdateOptions updateOptions;
updateOptions.Properties = certificate.Properties;
updateOptions.Properties.Enabled = false;

 auto updatedCertificate
          = certificateClient
                .UpdateCertificateProperties(
                    certificateName, certificate.Properties.Version, updateOptions)
                .Value;

std::cout << "After update certificate is enabled : "
          << (updatedCertificate.Properties.Enabled.Value() ? "true" : "false");

Deleting a Certificate

Call StartDeleteCertificate to delete a certificate. This is a long running operation.

auto response = certificateClient.StartDeleteCertificate(certificateName);

Purging a deleted certificate

If the Azure Key Vault is soft delete-enabled and you want to permanently delete the certificate before its ScheduledPurgeDate, the certificate needs to be purged.

auto result = response.PollUntilDone(defaultWait);
certificateClient.PurgeDeletedCertificate(certificateName);

Getting properties of Certificates

Call GetPropertiesOfCertificates to retrieve information about certificates from Key Vault.

 // get properties of certificates
for (auto certificates = certificateClient.GetPropertiesOfCertificates();
    certificates.HasPage();
    certificates.MoveToNextPage())
{ 
    // go through every certificate of each page returned
    // the number of results returned for in a  page is not guaranteed
    // it can be anywhere from 0 to 25
    std::cout << "Found " << certificates.Items.size() << " certificates.";
    
    for (auto oneCertificate : certificates.Items)
    {
        std::cout << "Certificate name : " << oneCertificate.Name;
    }
}

Creating a new certificate version

Repeat the create certificate procedure, for an existing certificate it will create a new version of it.

Getting the versions of a certificate

To get information about certificate versions call GetPropertiesOfCertificateVersions.

// get properties of all the versions of a certificate
for (auto certificateVersions
    = certificateClient.GetPropertiesOfCertificateVersions(certificateName1);
    certificateVersions.HasPage();
    certificateVersions.MoveToNextPage())
{ 
    // go through every certificate of each page returned
    // the number of results returned for in a  page is not guaranteed
    // it can be anywhere from 0 to 25

    std::cout << "Found " << certificateVersions.Items.size()
            << " certificate versions for certificate " << certificateName1;
}

Deleting multiple certificates

Now we will delete the certificates. Since this is a long running operation we need to wait for the operation to finish

// delete the certificates
auto response1 = certificateClient.StartDeleteCertificate(certificateName1);
auto response2 = certificateClient.StartDeleteCertificate(certificateName2);
response1.PollUntilDone(defaultWait);
response2.PollUntilDone(defaultWait);

Getting the deleted certificates

After the certificates are deleted , but not yet purged we can call GetDeletedCertificates

// get properties of deleted certificates
for (auto deletedCertificates = certificateClient.GetDeletedCertificates();
    deletedCertificates.HasPage();
    deletedCertificates.MoveToNextPage())
{
    // go through every certificate of each page returned
    // the number of results returned for in a  page is not guaranteed
    // it can be anywhere from 0 to 25
    std::cout << "Found " << deletedCertificates.Items.size() << " deleted certificates.";
}

Importing a PEM certificate

You will need the certificate content in PEM format to perform this operation. One sample is provided in certificate-ImportCertificate sample.

Once the import options are setup we can call Import certificate and get back the newly imported certificate.

// prepare the options
ImportCertificateOptions options;
options.Value = GetPemCertificate();

options.Policy.Enabled = true;
options.Policy.KeyType = CertificateKeyType::Rsa;
options.Policy.KeySize = 2048;
options.Policy.ContentType = CertificateContentType::Pem;
options.Policy.Exportable = true;
// call import API
auto imported = certificateClient.ImportCertificate(pemName, options).Value;
// get some value from the certificate
std::cout << "Imported pem certificate with name " << imported.Name();

Importing a PKCS certificate

You will need the certificate content in PKCS format to perform this operation. One sample is provided in certificate-ImportCertificate sample.

Once the import options are setup we can call Import certificate and get back the newly imported certificate

 // prepare the options
ImportCertificateOptions options;
options.Value = GetPemCertificate();

options.Policy.Enabled = true;
options.Policy.KeyType = CertificateKeyType::Rsa;
options.Policy.KeySize = 2048;
options.Policy.ContentType = CertificateContentType::Pkcs12;
options.Policy.Exportable = true;
// call the import API
auto imported = certificateClient.ImportCertificate(pkcsName, options).Value;
// read something from the certificate
std::cout << "Imported pkcs certificate with name " << imported.Name();

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.

Additional Documentation

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.
For more extensive documentation on Azure Key Vault, see the API reference documentation.

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:

Certificate-Basic-Operations:
- create a certificate
- get a certificate
- update a certificate
- delete a certificate
- purge a certificate
Certificates-Get-Certificates:
- create certificates
- get properties of certificates
- get properties of certificate versions
- delete a certificate
- get deleted certificates
- purge a certificate
Certificates-Import-Certificate:
- Import a PEM certificate
- import a PKCS certificate

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