From e54c13267d479b2add8c13c7dec6b257f8374788 Mon Sep 17 00:00:00 2001 From: gearama <50641385+gearama@users.noreply.github.com> Date: Thu, 5 Sep 2024 13:13:21 -0700 Subject: [PATCH] Kv doc update (#5946) * samples link * certs * keys * secrets * oopsie * az login * oopsie2 * Update sdk/keyvault/azure-security-keyvault-administration/README.md Co-authored-by: Ronnie Geraghty * Update sdk/keyvault/azure-security-keyvault-keys/README.md Co-authored-by: Ronnie Geraghty * Update sdk/keyvault/azure-security-keyvault-administration/README.md Co-authored-by: Ronnie Geraghty * Update sdk/keyvault/azure-security-keyvault-certificates/README.md Co-authored-by: Ronnie Geraghty * links * find package --------- Co-authored-by: Ronnie Geraghty --- .../README.md | 85 ++++++++++---- .../README.md | 111 +++++++++++------- .../azure-security-keyvault-keys/README.md | 89 ++++++++++---- .../azure-security-keyvault-secrets/README.md | 54 +++++++-- 4 files changed, 237 insertions(+), 102 deletions(-) diff --git a/sdk/keyvault/azure-security-keyvault-administration/README.md b/sdk/keyvault/azure-security-keyvault-administration/README.md index 403360922..b04b3ac7d 100644 --- a/sdk/keyvault/azure-security-keyvault-administration/README.md +++ b/sdk/keyvault/azure-security-keyvault-administration/README.md @@ -7,26 +7,21 @@ Azure Security Keyvault Administration Package client library for C++ (`azure-se 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][administration_client_src] | [API reference documentation][api_reference] | [Product documentation][keyvault_docs] +[Source code][administration_client_src] | [Package (vcpkg)](https://vcpkg.io/en/package/azure-security-keyvault-administration-cpp) | [API reference documentation][api_reference] | [Product documentation][keyvault_docs] | [Samples](https://github.com/Azure/azure-sdk-for-cpp/tree/main/sdk/keyvault/azure-security-keyvault-administration/samples) ## Getting started -### Install the package -Install the Azure Key Vault Administration Setting client library for C++ with vcpkg: - -```cmd -vcpkg install azure-security-keyvault-administration-cpp -``` - ### Prerequisites - -* An [Azure subscription][azure_sub]. -* An existing Azure Key Vault. If you need to create an Azure Key Vault, you can use the [Azure CLI][azure_cli]. -* Authorization to an existing Azure Key Vault using either [RBAC][rbac_guide] (recommended) or [access control][access_policy]. +- [vcpkg](https://learn.microsoft.com/vcpkg/get_started/overview) for package acquisition and dependency management +- [CMake](https://cmake.org/download/) for project build +- An [Azure subscription][azure_sub]. +- An existing Azure Key Vault. If you need to create an Azure Key Vault, you can use the [Azure CLI][azure_cli]. +- Authorization to an existing Azure Key Vault using either [RBAC][rbac_guide] (recommended) or [access control][access_policy]. To create a Managed HSM resource, run the following CLI command: ```PowerShell +az login az keyvault create --hsm-name --resource-group --administrators --location ``` @@ -78,6 +73,39 @@ az keyvault role assignment create --hsm-name --role "Ma Please read [best practices][best_practices] for properly securing your managed HSM. +### 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][azsdk_vcpkg_install]. 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: + +```batch +vcpkg new --application +``` + +To install the Azure \ package via vcpkg: +To add the Azure \ package to your vcpkg enter the following command (We'll also add the Azure Identity library for authentication): + +```batch +vcpkg add port azure-security-keyvault-administration-cpp azure-identity-cpp +``` + +Then, add the following in your CMake file: + +```CMake +find_package(azure-identity-cpp CONFIG REQUIRED) +find_package(azure-security-keyvault-administration-cpp CONFIG REQUIRED) +target_link_libraries( PRIVATE Azure::azure-security-keyvault-administration 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: + +```CMake +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][project_set_up_examples]. + ## Key Concepts ### Thread safety We guarantee that all client instance methods are thread-safe and independent of each other ([guideline](https://azure.github.io/azure-sdk/cpp_introduction.html#thread-safety)). This ensures that the recommendation of reusing client instances is always safe, even across threads. @@ -92,8 +120,10 @@ We guarantee that all client instance methods are thread-safe and independent of ## Examples For detailed samples please review the code provided. +### SettingsClient +We'll be using the `DefaultAzureCredential` to authenticate which will pick up the credentials we used when logging in with the Azure CLI earlier. `DefaultAzureCredential` can pick up on a number of Credential types from your environment and is ideal when getting started and developing. Check out our section on [DefaultAzureCredentials](https://github.com/Azure/azure-sdk-for-cpp/tree/main/sdk/identity/azure-identity#defaultazurecredential) to learn more. -### GetSettings +#### GetSettings To get all the available settings present on the Keyvault instance we will first create a client : ```cpp @@ -112,7 +142,7 @@ To get the settings we will call the GetSettings API SettingsListResult settingsList = settingsClient.GetSettings().Value; ``` -### GetSetting +#### GetSetting To get a specific setting we will call the GetSetting API bassing the setting name as a string parameter. @@ -120,7 +150,7 @@ To get a specific setting we will call the GetSetting API bassing the setting na Setting setting = settingsClient.GetSetting(settingsList.Value[0].Name).Value; ``` -### UpdateSetting +#### UpdateSetting To update the value of any of the the available settings, we will call the UpdateSettings API as follows: ```cpp @@ -130,7 +160,8 @@ To update the value of any of the the available settings, we will call the Updat Setting updatedSetting = settingsClient.UpdateSetting(settingsList.Value[0].Name, options).Value; ``` -## Creating a BackupClient + +### BackupClient To create a new `BackupClient` to perform these operations, you need the endpoint to an Azure Key Vault HSM and credentials. @@ -147,7 +178,7 @@ Then, in the sample below, you can set `keyVaultUrl` based on an environment var // create client BackupClient client(std::getenv("AZURE_KEYVAULT_HSM_URL"), credential); ``` -## Create the SasTokenParameter +#### Create the SasTokenParameter Since these operations require a blob storage for the backup/restore operations, a SAS token is required for the connection between the services(Key Vault and Storage). @@ -163,11 +194,11 @@ In this sample we rely on a couple of extra environment variables. = Azure::Core::Url(Azure::Core::_internal::Environment::GetVariable("AZURE_KEYVAULT_BACKUP_URL")); ``` -## The Backup operation +#### The Backup operation Since this is a long running operation the service provides endpoints to determine the status while the opperation is running. -### Starting the backup operation +##### Starting the backup operation ```cpp // Create a full backup using a user-provided SAS token to an Azure blob storage container. @@ -177,7 +208,7 @@ std::cout << "Backup Job Id: " << backupResponse.Value().JobId << std::endl << "Backup Status: " << backupResponse.Value().Status << std::endl; ``` -### Backup operation waiting +##### Backup operation waiting In order to wait for the operation to complete we will call the polling method. @@ -189,11 +220,11 @@ std::cout << "Backup Job Id: " << backupStatus.Value.JobId << std::endl << "Backup Status: " << backupStatus.Value.Status << std::endl; ``` -## The FullRestore operation +#### The FullRestore operation Similar to the backup operation after we initialize the operation we can check the status. -### Starting the restore operation +#### Starting the restore operation the restore operation requires a folder where a backup was previously performed along side the SAS token parameter. ```cpp @@ -204,7 +235,7 @@ std::cout << "Restore Job Id: " << restoreResponse.Value().JobId << std::endl << "Restore Status: " << restoreResponse.Value().Status << std::endl; ``` -### FullRestore operation waiting +##### FullRestore operation waiting ```cpp // Wait for the operation to complete. @@ -213,11 +244,11 @@ std::cout << "Restore Job Id: " << restoreStatus.Value.JobId << std::endl << "Restore Status: " << restoreStatus.Value.Status << std::endl; ``` -## The SelectiveRestore operation +#### The SelectiveRestore operation Similar to the backup operation after we initialize the operation we can check the status. -### Starting the restore operation +##### Starting the restore operation The selective restore operation requires a folder where a backup was previously performed along side the SAS token parameter. @@ -230,7 +261,7 @@ std::cout << "Restore Job Id: " << restoreResponse.Value.JobId << std::endl << "Restore Status: " << restoreResponse.Value.Status << std::endl; ``` -### Selective restore operation completion +##### Selective restore operation completion ```cpp // Wait for the operation to complete. @@ -286,3 +317,5 @@ Azure SDK for C++ is licensed under the [MIT](https://github.com/Azure/azure-sdk [rbac_guide]: https://learn.microsoft.com/azure/key-vault/general/rbac-guide [best_practices]: https://learn.microsoft.com/azure/key-vault/managed-hsm/best-practices [built_in_roles]: https://learn.microsoft.com/azure/key-vault/managed-hsm/built-in-roles +[azsdk_vcpkg_install]: https://github.com/Azure/azure-sdk-for-cpp#getting-started +[project_set_up_examples]: https://github.com/Azure/azure-sdk-for-cpp/tree/main/samples/integration diff --git a/sdk/keyvault/azure-security-keyvault-certificates/README.md b/sdk/keyvault/azure-security-keyvault-certificates/README.md index 2b82d6918..91404c9a9 100644 --- a/sdk/keyvault/azure-security-keyvault-certificates/README.md +++ b/sdk/keyvault/azure-security-keyvault-certificates/README.md @@ -4,52 +4,76 @@ Azure Key Vault is a cloud service that provides secure storage and automated ma The Azure Key Vault certificates client library enables programmatically managing certificates, offering methods to get certificates, policies, issuers, and contacts. -[Source code][certificate_client_src] | [API reference documentation][api_reference] | [Product documentation][keyvault_docs] +[Source code][certificate_client_src] | [Package (vcpkg)](https://vcpkg.io/en/package/azure-security-keyvault-certificates-cpp) | [API reference documentation][api_reference] | [Product documentation][keyvault_docs] | [Samples](https://github.com/Azure/azure-sdk-for-cpp/tree/main/sdk/keyvault/azure-security-keyvault-certificates/samples) ## Getting started -### Install the package -Install the Azure Key Vault certificates client library for C++ with vcpkg: - -```cmd -vcpkg install azure-security-keyvault-certificates-cpp -``` - ### Prerequisites -* An [Azure subscription][azure_sub]. -* An existing Azure Key Vault. If you need to create an Azure Key Vault, you can use the Azure Portal or [Azure CLI][azure_cli]. +- [vcpkg](https://learn.microsoft.com/vcpkg/get_started/overview) for package acquisition and dependency management +- [CMake](https://cmake.org/download/) for project build +- An [Azure subscription][azure_sub]. +- An existing Azure Key Vault. If you need to create an Azure Key Vault, you can use the Azure Portal or [Azure CLI][azure_cli]. If you use the Azure CLI, replace `` and `` with your own, unique names: ```PowerShell +az login az keyvault create --resource-group --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][azsdk_vcpkg_install]. 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: + +```batch +vcpkg new --application +``` + +To install the Azure \ package via vcpkg: +To add the Azure \ package to your vcpkg enter the following command (We'll also add the Azure Identity library for authentication): + +```batch +vcpkg add port azure-security-keyvault-certificates-cpp azure-identity-cpp +``` + +Then, add the following in your CMake file: + +```CMake +find_package(azure-identity-cpp CONFIG REQUIRED) +find_package(azure-security-keyvault-certificates-cpp CONFIG REQUIRED) +target_link_libraries( 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: + +```CMake +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][project_set_up_examples]. ## 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](https://azure.github.io/azure-sdk/cpp_introduction.html#thread-safety)). This ensures that the recommendation of reusing client instances is always safe, even across threads. + +#### Additional concepts + + +[Replaceable HTTP transport adapter](https://github.com/Azure/azure-sdk-for-cpp/blob/main/sdk/core/azure-core#http-transport-adapter) | +[Long-running operations](https://github.com/Azure/azure-sdk-for-cpp/blob/main/sdk/core/azure-core#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. -### Thread safety -We guarantee that all client instance methods are thread-safe and independent of each other ([guideline](https://azure.github.io/azure-sdk/cpp_introduction.html#thread-safety)). This ensures that the recommendation of reusing client instances is always safe, even across threads. - -### Additional concepts - - -[Replaceable HTTP transport adapter](https://github.com/Azure/azure-sdk-for-cpp/blob/main/sdk/core/azure-core#http-transport-adapter) | -[Long-running operations](https://github.com/Azure/azure-sdk-for-cpp/blob/main/sdk/core/azure-core#long-running-operations) | - - -## Examples - -For detailed samples please review the samples provided. - -### Creating a CertificateClient +#### 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. @@ -67,7 +91,7 @@ auto const keyVaultUrl = std::getenv("AZURE_KEYVAULT_URL"); CertificateClient certificateClient(keyVaultUrl, credential); ``` -### Start creating a Certificate +#### Start creating a Certificate Call StartCreateCertificate to start creating a new certificate, with specified properties and policy. @@ -79,7 +103,7 @@ CertificateCreateOptions options; auto response = certificateClient.StartCreateCertificate(certificateName, options); ``` -### Getting a Certificate once completed +#### 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. @@ -95,7 +119,7 @@ std::cout << "Created certificate with policy. Certificate name : " << certifica } ``` -### Updating certificate properties +#### Updating certificate properties Call UpdateCertificateProperties to change one of the certificate properties. @@ -115,7 +139,7 @@ std::cout << "After update certificate is enabled : " << (updatedCertificate.Properties.Enabled.Value() ? "true" : "false"); ``` -### Deleting a Certificate +#### Deleting a Certificate Call StartDeleteCertificate to delete a certificate. This is a long running operation. @@ -124,7 +148,7 @@ auto response = certificateClient.StartDeleteCertificate(certificateName); ``` -### Purging a deleted certificate +#### 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. @@ -133,7 +157,7 @@ auto result = response.PollUntilDone(defaultWait); certificateClient.PurgeDeletedCertificate(certificateName); ``` -### Getting properties of Certificates +#### Getting properties of Certificates Call GetPropertiesOfCertificates to retrieve information about certificates from Key Vault. @@ -155,11 +179,11 @@ for (auto certificates = certificateClient.GetPropertiesOfCertificates(); } ``` -### Creating a new certificate version +#### 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 +#### Getting the versions of a certificate To get information about certificate versions call GetPropertiesOfCertificateVersions. @@ -178,7 +202,7 @@ for (auto certificateVersions << " certificate versions for certificate " << certificateName1; } ``` -### Deleting multiple certificates +#### 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 @@ -190,7 +214,7 @@ response1.PollUntilDone(defaultWait); response2.PollUntilDone(defaultWait); ``` -### Getting the deleted certificates +#### Getting the deleted certificates After the certificates are deleted , but not yet purged we can call GetDeletedCertificates @@ -207,7 +231,7 @@ for (auto deletedCertificates = certificateClient.GetDeletedCertificates(); } ``` -### Importing a PEM certificate +#### 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. @@ -229,7 +253,7 @@ auto imported = certificateClient.ImportCertificate(pemName, options).Value; std::cout << "Imported pem certificate with name " << imported.Name(); ``` -### Importing a PKCS certificate +#### 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. @@ -271,10 +295,15 @@ catch (const Azure::Core::RequestFailedException& ex) 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: -- For more extensive documentation on Azure Key Vault, see the [API reference documentation][keyvault_rest]. +* [What are some good first issues for new contributors to the repo?](https://github.com/azure/azure-sdk-for-cpp/issues?q=is%3Aopen+is%3Aissue+label%3A%22up+for+grabs%22) +* [How to build and test your change][azure_sdk_for_cpp_contributing_developer_guide] +* [How you can make a change happen!][azure_sdk_for_cpp_contributing_pull_requests] +* Frequently Asked Questions (FAQ) and Conceptual Topics in the detailed [Azure SDK for C++ wiki](https://github.com/azure/azure-sdk-for-cpp/wiki). +* For more extensive documentation on Azure Key Vault, see the [API reference documentation][keyvault_rest]. -# Next steps +## 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: @@ -341,4 +370,6 @@ Azure SDK for C++ is licensed under the [MIT](https://github.com/Azure/azure-sdk [azure_sub]: https://azure.microsoft.com/free/ [azure_sdk_for_cpp_contributing]: https://github.com/Azure/azure-sdk-for-cpp/blob/main/CONTRIBUTING.md [azure_sdk_for_cpp_contributing_developer_guide]: https://github.com/Azure/azure-sdk-for-cpp/blob/main/CONTRIBUTING.md#developer-guide -[azure_sdk_for_cpp_contributing_pull_requests]: https://github.com/Azure/azure-sdk-for-cpp/blob/main/CONTRIBUTING.md#pull-requests \ No newline at end of file +[azure_sdk_for_cpp_contributing_pull_requests]: https://github.com/Azure/azure-sdk-for-cpp/blob/main/CONTRIBUTING.md#pull-requests +[azsdk_vcpkg_install]: https://github.com/Azure/azure-sdk-for-cpp#getting-started +[project_set_up_examples]: https://github.com/Azure/azure-sdk-for-cpp/tree/main/samples/integration diff --git a/sdk/keyvault/azure-security-keyvault-keys/README.md b/sdk/keyvault/azure-security-keyvault-keys/README.md index 98c2dd724..6627b3ff8 100644 --- a/sdk/keyvault/azure-security-keyvault-keys/README.md +++ b/sdk/keyvault/azure-security-keyvault-keys/README.md @@ -1,4 +1,4 @@ -# Azure Key Vault key client library for C++ +# Azure Key Vault Key client library for C++ Azure Key Vault is a cloud service that provides secure storage of keys for encrypting your data. Multiple keys, and multiple versions of the same key, can be kept in the Azure Key Vault. @@ -9,11 +9,54 @@ you to safeguard cryptographic keys for your cloud applications using FIPS 140-2 The Azure Key Vault keys library client supports RSA keys and Elliptic Curve (EC) keys, each with corresponding support in hardware security modules (HSM). It offers operations to create, retrieve, update, delete, purge, backup, restore, and list the keys and its versions. -[Source code][key_client_src] | [VCPKG][key_client_vcpkg_package] | [API reference documentation][api_reference] | [Product documentation][keyvault_docs] | [Samples][key_client_samples] +[Source code][key_client_src] | [Package (vcpkg)][key_client_vcpkg_package] | [API reference documentation][api_reference] | [Product documentation][keyvault_docs] | [Samples][key_client_samples] ## Getting started -### Include the package + +### Prerequisites + +- [vcpkg](https://learn.microsoft.com/vcpkg/get_started/overview) for package acquisition and dependency management +- [CMake](https://cmake.org/download/) for project build +- An [Azure subscription][azure_sub]. +- An existing Azure Key Vault. If you need to create an Azure Key Vault, you can use the Azure Portal or [Azure CLI][azure_cli]. + +See the final two steps in the next section for details on creating the Key Vault with the Azure CLI. + +### 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][azsdk_vcpkg_install]. 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: + +```batch +vcpkg new --application +``` + +To install the azure-security-keyvault-keys-cpp package via vcpkg: +To add the azure-security-keyvault-keys-cpp package to your vcpkg enter the following command (We'll also add the Azure Identity library for authentication): + +```batch +vcpkg add port azure-security-keyvault-keys-cpp azure-identity-cpp +``` + +Then, add the following in your CMake file: + +```CMake +find_package(azure-identity-cpp CONFIG REQUIRED) +find_package(azure-security-keyvault-keys-cpp CONFIG REQUIRED) +target_link_libraries( PRIVATE Azure::azure-security-keyvault-keys 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: + +```CMake +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][project_set_up_examples]. + + The easiest way to acquire the C++ SDK is leveraging vcpkg package manager. See the corresponding [Azure SDK for C++ readme section][azsdk_vcpkg_install]. @@ -27,16 +70,10 @@ Then, use in your CMake file: ```CMake find_package(azure-security-keyvault-keys-cpp CONFIG REQUIRED) +find_package(azure-identity-cpp CONFIG REQUIRED) target_link_libraries( PRIVATE Azure::azure-security-keyvault-keys) ``` -### Prerequisites - -- An [Azure subscription][azure_sub]. -- An existing Azure Key Vault. If you need to create an Azure Key Vault, you can use the Azure Portal or [Azure CLI][azure_cli]. - -See the final two steps in the next section for details on creating the Key Vault with the Azure CLI. - ### Authenticate the client In order to interact with the Key Vault service, you'll need to create an instance of the [KeyClient][key_client_class] class. You need a **vault URL**, which you may see as "DNS Name" in the portal, @@ -59,6 +96,7 @@ Use the [Azure CLI][azure_cli] snippet below to create/get client secret credent - Create a service principal and configure its access to Azure resources: ```PowerShell + az login az ad sp create-for-rbac -n --skip-assignment ``` Output: @@ -147,8 +185,21 @@ The example below uses 3 RSA key pairs (only public keys are needed for this com ```PowerShell az keyvault security-domain download --hsm-name --sd-wrapping-keys ./certs/cert_0.cer ./certs/cert_1.cer ./certs/cert_2.cer --sd-quorum 2 --security-domain-file ContosoMHSM-SD.json ``` +## Key concepts -#### Create KeyClient +### KeyVaultKey + +Azure Key Vault supports multiple key types and algorithms, and enables the use of hardware security modules (HSM) for high value keys. + +### KeyClient + +A `KeyClient` providing synchronous operations exists in the SDK. Once you've initialized a `KeyClient`, you can interact with the primary resource types in Azure Key Vault. + +### CryptographyClient + +A `CryptographyClient` providing synchronous operations exists in the SDK. Once you've initialized a `CryptographyClient`, you can use it to perform cryptographic operations with keys stored in Azure Key Vault. + +### KeyClient Once you've replaced **your-vault-url** with the above returned URI, you can create the [KeyClient][key_client_class]: @@ -176,19 +227,7 @@ auto credential = std::make_shared(); CryptographyClient cryptoClient(key.Id, credential); ``` -## Key concepts -### KeyVaultKey - -Azure Key Vault supports multiple key types and algorithms, and enables the use of hardware security modules (HSM) for high value keys. - -### KeyClient - -A `KeyClient` providing synchronous operations exists in the SDK. Once you've initialized a `KeyClient`, you can interact with the primary resource types in Azure Key Vault. - -### CryptographyClient - -A `CryptographyClient` providing synchronous operations exists in the SDK. Once you've initialized a `CryptographyClient`, you can use it to perform cryptographic operations with keys stored in Azure Key Vault. #### Note Microsoft recommends you not use CBC without first ensuring the integrity of the cipher text using an HMAC, for example. See https://docs.microsoft.com/dotnet/standard/security/vulnerabilities-cbc-mode for more information. @@ -213,7 +252,7 @@ We guarantee that all client instance methods are thread-safe and independent of The Azure.Security.KeyVault.Keys package supports synchronous APIs. -The following section provides several code snippets using the `client` [created above](#create-keyclient), covering some of the most common Azure Key Vault key service related tasks: +The following section provides several code snippets using the `client` [created above](#keyclient), covering some of the most common Azure Key Vault key service related tasks: ### Examples @@ -470,3 +509,5 @@ For more information see the [Code of Conduct FAQ][coc_faq] or contact opencode@ [coc_faq]: https://opensource.microsoft.com/codeofconduct/faq/ [access_control]: https://docs.microsoft.com/azure/key-vault/managed-hsm/access-control [rbac_guide]: https://docs.microsoft.com/azure/key-vault/general/rbac-guide +[azsdk_vcpkg_install]: https://github.com/Azure/azure-sdk-for-cpp#getting-started +[project_set_up_examples]: https://github.com/Azure/azure-sdk-for-cpp/tree/main/samples/integration diff --git a/sdk/keyvault/azure-security-keyvault-secrets/README.md b/sdk/keyvault/azure-security-keyvault-secrets/README.md index 1048d0ab4..faed53552 100644 --- a/sdk/keyvault/azure-security-keyvault-secrets/README.md +++ b/sdk/keyvault/azure-security-keyvault-secrets/README.md @@ -4,27 +4,56 @@ Azure Security Keyvault Secrets Package client library for C++ (`azure-security- 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][secrets_client_src] | [API reference documentation][api_reference] | [Product documentation][keyvault_docs] +[Source code][secrets_client_src] | [Package (vcpkg)](https://vcpkg.io/en/package/azure-security-keyvault-secrets-cpp) | [API reference documentation][api_reference] | [Product documentation][keyvault_docs] | [Samples](https://github.com/Azure/azure-sdk-for-cpp/tree/main/sdk/keyvault/azure-security-keyvault-secrets/samples) ## Getting started -### Install the package -Install the Azure Key Vault secrets client library for C++ with vcpkg: - -```cmd -vcpkg install azure-security-keyvault-secrets-cpp -``` - ### Prerequisites -* An [Azure subscription][azure_sub]. -* An existing Azure Key Vault. If you need to create an Azure Key Vault, you can use the Azure Portal or [Azure CLI][azure_cli]. +- [vcpkg](https://learn.microsoft.com/vcpkg/get_started/overview) for package acquisition and dependency management +- [CMake](https://cmake.org/download/) for project build +- An [Azure subscription][azure_sub]. +- An existing Azure Key Vault. If you need to create an Azure Key Vault, you can use the Azure Portal or [Azure CLI][azure_cli]. If you use the Azure CLI, replace `` and `` with your own, unique names: ```PowerShell +az login az keyvault create --resource-group --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][azsdk_vcpkg_install]. 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: + +```batch +vcpkg new --application +``` + +To install the Azure \ package via vcpkg: +To add the Azure \ package to your vcpkg enter the following command (We'll also add the Azure Identity library for authentication): + +```batch +vcpkg add port azure-security-keyvault-secrets-cpp azure-identity-cpp +``` + +Then, add the following in your CMake file: + +```CMake +find_package(azure-security-keyvault-secrets-cpp CONFIG REQUIRED) +find_package(azure-identity-cpp CONFIG REQUIRED) +target_link_libraries( PRIVATE Azure::azure-security-keyvault-secrets 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: + +```CMake +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][project_set_up_examples]. + + ## Key concepts ### KeyVaultSecret @@ -43,7 +72,7 @@ We guarantee that all client instance methods are thread-safe and independent of [Long-running operations](https://github.com/Azure/azure-sdk-for-cpp/blob/main/sdk/core/azure-core#long-running-operations) | -## Examples +## SecretClient For detailed samples please review the samples provided. @@ -236,4 +265,5 @@ Azure SDK for C++ is licensed under the [MIT](https://github.com/Azure/azure-sdk [api_reference]: https://azure.github.io/azure-sdk-for-cpp/keyvault.html [secrets_client_src]: https://github.com/Azure/azure-sdk-for-cpp/tree/main/sdk/keyvault/azure-security-keyvault-secrets [keyvault_docs]: https://docs.microsoft.com/azure/key-vault/ - +[azsdk_vcpkg_install]: https://github.com/Azure/azure-sdk-for-cpp#getting-started +[project_set_up_examples]: https://github.com/Azure/azure-sdk-for-cpp/tree/main/samples/integration