Regenerate Key Vault with renames, update READMEs (#2459)

* Regenerate Key Vault with renames, update READMEs

* Update release information

* Fix typo

* Set VCPKG_ROOT

Also includes instructions in the root `CONTRIBUTING.md`.

The unsetting of `VCPKG_ROOT` was intentional:
<actions/runner-images#6376>

Still, that was done a while ago and our pipelines had been working.
We're still investigating *what* changed.

* Remove dev-dependency on openssl

Need to build openssl on Windows, but we'll tackle that post-beta.2.

Author: heaths

.vscode/cspell.json

@@ -69,6 +69,7 @@
     "undelete",
     "upvote",
     "userdelegationkey",
+    "vcpkg",
     "versionid",
     "virtualmachine",
     "worktree"

CONTRIBUTING.md

@@ -30,6 +30,38 @@ Alternatively, you can build any one or more crates by passing their crate names
 You can also build the entire workspace by either building from the root source directory or running `cargo build --workspace`, but unless you're making changes to `azure_core`
 or its dependencies, this is generally unnecessary nor recommended. It will take considerable time and drive space.
 
+### Building on Windows
+
+By default we use the [`openssl`](https://crates.io/crates/openssl) crate and, indirectly, the [`openssl-sys`](https://crates.io/crates/openssl-sys) crate. On Windows, you may need to download and build openssl before you can successfully compile.
+Since `openssl-sys` supports [vcpkg](https://learn.microsoft.com/vcpkg/), you can bootstrap OpenSSL:
+
+1. Clone `vcpkg` somewhere in your development environment:
+
+   ```pwsh
+   git clone --depth=1 https://github.com/microsoft/vcpkg.git
+   ```
+
+2. Run the bootstrap script to download a prebuilt binary:
+
+   ```pwsh
+   cd vcpkg; .\bootstrap-vcpkg.bat
+   ```
+
+3. Set up environment variables:
+
+   ```pwsh
+   $env:VCPKG_ROOT = "C:\path\to\vcpkg" # from step 1
+   $env:PATH = "${env:VCPKG_ROOT};${env:PATH}"
+   ```
+
+   To persist these variables for future sessions, remember to set them in the Windows System Environment Variables panel.
+
+4. In the root of this repo, run:
+
+   ```pwsh
+   vcpkg install
+   ```
+
 ### Linting
 
 You can run `cargo clippy` to check for common issues. Like `cargo build`, you can pass one or more crate names to `--package`.

eng/emitter-package-lock.json

@@ -1,7 +1,7 @@
 {
   "main": "dist/src/index.js",
   "dependencies": {
-    "@azure-tools/typespec-rust": "0.13.2"
+    "@azure-tools/typespec-rust": "0.13.3"
   },
   "devDependencies": {
     "@azure-tools/typespec-azure-core": "0.54.0",
@@ -14,4 +14,4 @@
     "@typespec/versioning": "0.68.0",
     "@typespec/xml": "0.68.0"
   }
-}
+}

eng/emitter-package.json

@@ -2,5 +2,5 @@
   "AssetsRepo": "Azure/azure-sdk-assets",
   "AssetsRepoPrefixPath": "rust",
   "TagPrefix": "rust/keyvault",
-  "Tag": "rust/keyvault_4acaa30551"
+  "Tag": "rust/keyvault_59ae61e2f7"
 }

sdk/keyvault/assets.json

@@ -1,6 +1,6 @@
 # Release History
 
-## 0.1.0 (Unreleased)
+## 0.1.0 (2025-04-09)
 
 ### Features Added
 

sdk/keyvault/azure_security_keyvault_certificates/CHANGELOG.md

@@ -52,9 +52,9 @@ Instantiate a `DefaultAzureCredential` to pass to the client. The same instance
 
 ## Key concepts
 
-### CertificateBundle
+### Certificate
 
-A Azure Key Vault certificate public key. The private key is never included when retrieving a `CertificateBundle`.
+A Azure Key Vault certificate public key. The private key is never included when retrieving a `Certificate`.
 
 ### CertificateClient
 
@@ -66,7 +66,222 @@ We guarantee that all client instance methods are thread-safe and independent of
 
 ## Examples
 
-> TODO
+The following section provides several code snippets using the `CertificateClient`, covering some of the most common Azure Key Vault certificates service related tasks:
+
+* [Create a certificate](#create-a-certificate)
+* [Retrieve a certificate](#retrieve-a-certificate)
+* [Update an existing certificate](#update-an-existing-certificate)
+* [Delete a certificate](#delete-a-certificate)
+* [List certificates](#list-certificates)
+
+### Create a certificate
+
+`create_certificate` creates a Key Vault certificate to be stored in the Azure Key Vault. If a certificate with the same name already exists, then a new version of the certificate is created.
+Before we can create a new certificate, though, we need to define a certificate policy. This is used for the first certificate version and all subsequent versions of that certificate until changed.
+
+```rust no_run
+use azure_identity::DefaultAzureCredential;
+use azure_security_keyvault_certificates::{
+    models::{CertificatePolicy, CreateCertificateParameters, IssuerParameters, X509CertificateProperties},
+    ResourceExt, CertificateClient,
+};
+use std::{sync::LazyLock, time::Duration};
+use tokio::time::sleep;
+
+static DEFAULT_POLICY: LazyLock<CertificatePolicy> = LazyLock::new(|| CertificatePolicy {
+    x509_certificate_properties: Some(X509CertificateProperties {
+        subject: Some("CN=DefaultPolicy".into()),
+        ..Default::default()
+    }),
+    issuer_parameters: Some(IssuerParameters {
+        name: Some("Self".into()),
+        ..Default::default()
+    }),
+    ..Default::default()
+});
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let credential = DefaultAzureCredential::new()?;
+    let client = CertificateClient::new(
+        "https://your-key-vault-name.vault.azure.net/",
+        credential.clone(),
+        None,
+    )?;
+
+    // Create a self-signed certificate.
+    let body = CreateCertificateParameters {
+        certificate_policy: Some(DEFAULT_POLICY.clone()),
+        ..Default::default()
+    };
+
+    let mut operation = client
+        .create_certificate("certificate-name", body.try_into()?, None)
+        .await?
+        .into_body()
+        .await?;
+    let name = operation.resource_id()?.name;
+
+    // Wait for the certificate operation to complete.
+    loop {
+        if matches!(operation.status, Some(ref status) if status == "completed") {
+            break;
+        }
+
+        if let Some(err) = operation.error {
+            return Err(azure_core::Error::new(
+                azure_core::error::ErrorKind::Other,
+                err.message
+                    .unwrap_or_else(|| "failed to create certificate".into()),
+            ))?;
+        }
+
+        sleep(Duration::from_secs(3)).await;
+
+        operation = client
+            .get_certificate_operation(&name, None)
+            .await?
+            .into_body()
+            .await?;
+    }
+
+    Ok(())
+}
+```
+
+### Retrieve a certificate
+
+`get_certificate` retrieves a certificate that was created or even still in progress in Key Vault.
+Setting the `certificate-version` to an empty string will return the latest version.
+
+```rust no_run
+use azure_core::base64;
+use azure_identity::DefaultAzureCredential;
+use azure_security_keyvault_certificates::CertificateClient;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let credential = DefaultAzureCredential::new()?;
+    let client = CertificateClient::new(
+        "https://your-key-vault-name.vault.azure.net/",
+        credential.clone(),
+        None,
+    )?;
+
+    let certificate = client
+        .get_certificate("certificate-name", "certificate-version", None)
+        .await?
+        .into_body()
+        .await?;
+
+    println!(
+        "Certificate thumbprint: {:?}",
+        certificate.x509_thumbprint.map(base64::encode)
+    );
+
+    Ok(())
+}
+```
+
+### Update an existing certificate
+
+`update_certificate_properties` updates a certificate previously stored in the Azure Key Vault.
+Only the attributes of the certificate are updated. To regenerate the certificate, call `CertificateClient::create_certificate` on a certificate with the same name.
+
+```rust no_run
+use azure_identity::DefaultAzureCredential;
+use azure_security_keyvault_certificates::{
+    models::UpdateCertificatePropertiesParameters, CertificateClient,
+};
+use std::collections::HashMap;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let credential = DefaultAzureCredential::new()?;
+    let client = CertificateClient::new(
+        "https://your-key-vault-name.vault.azure.net/",
+        credential.clone(),
+        None,
+    )?;
+
+    // Update a certificate using the certificate client.
+    let certificate_update_parameters = UpdateCertificatePropertiesParameters {
+        tags: HashMap::from_iter(vec![("tag-name".into(), "tag-value".into())]),
+        ..Default::default()
+    };
+
+    client
+        .update_certificate_properties(
+            "certificate-name",
+            "",
+            certificate_update_parameters.try_into()?,
+            None,
+        )
+        .await?
+        .into_body()
+        .await?;
+
+    Ok(())
+}
+```
+
+### Delete a certificate
+
+`delete_certificate` will tell Key Vault to delete a certificate but it is not deleted immediately.
+It will not be deleted until the service-configured data retention period - the default is 90 days - or until you call `purge_certificate` on the returned `DeletedCertificate.id`.
+
+```rust no_run
+use azure_identity::DefaultAzureCredential;
+use azure_security_keyvault_certificates::CertificateClient;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let credential = DefaultAzureCredential::new()?;
+    let client = CertificateClient::new(
+        "https://your-key-vault-name.vault.azure.net/",
+        credential.clone(),
+        None,
+    )?;
+
+    // Delete a certificate using the certificate client.
+    client.delete_certificate("certificate-name", None).await?;
+
+    Ok(())
+}
+```
+
+### List certificates
+
+This example lists all the certificates in the specified Azure Key Vault.
+
+```rust no_run
+use azure_identity::DefaultAzureCredential;
+use azure_security_keyvault_certificates::{CertificateClient, ResourceExt};
+use futures::TryStreamExt;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    // Create a new certificate client
+    let credential = DefaultAzureCredential::new()?;
+    let client = CertificateClient::new(
+        "https://your-key-vault-name.vault.azure.net/",
+        credential.clone(),
+        None,
+    )?;
+
+    let mut pager = client.list_certificate_properties(None)?.into_stream();
+    while let Some(certificates) = pager.try_next().await? {
+        let certificates = certificates.into_body().await?.value;
+        for certificate in certificates {
+            // Get the certificate name from the ID.
+            let name = certificate.resource_id()?.name;
+            println!("Found Certificate with Name: {}", name);
+        }
+    }
+
+    Ok(())
+}
+```
 
 ## Troubleshooting