From e193475265a8cc080283ca0fc00600839b90ad83 Mon Sep 17 00:00:00 2001 From: divyapola5 <87338962+divyapola5@users.noreply.github.com> Date: Mon, 21 Mar 2022 10:26:46 -0500 Subject: [PATCH] Documentation changes in /sys/managed-keys (#14377) (#14611) * update sample request in create managed keys * Update documentation for curve param * Add period at end of sentence * Update key_bits documentation for aws and azure --- .../content/api-docs/system/managed-keys.mdx | 60 +++++++++++++++---- 1 file changed, 50 insertions(+), 10 deletions(-) diff --git a/website/content/api-docs/system/managed-keys.mdx b/website/content/api-docs/system/managed-keys.mdx index 51aba92c87ab7..3a0162b29a4ce 100644 --- a/website/content/api-docs/system/managed-keys.mdx +++ b/website/content/api-docs/system/managed-keys.mdx @@ -1,12 +1,12 @@ --- layout: api page_title: /sys/managed-keys - HTTP API -description: The `/sys/managed-keys` endpoint is used manage the managed keys in Vault. +description: The `/sys/managed-keys` endpoint is used to manage the managed keys in Vault. --- # `/sys/managed-keys` -The `/sys/managed-keys` endpoint is used manage the Managed Key configuration within Vault. +The `/sys/managed-keys` endpoint is used to manage the Managed Key configuration within Vault. See the [Managed Keys](/docs/enterprise/managed-keys) section for further details on the Managed Keys system. ## List managed keys. @@ -51,12 +51,25 @@ the namespace. |:-------|:--------------------------------| | `POST` | `/sys/managed-keys/:type/:name` | +### Sample Payload + +```json +{ + "library": "softhsm", + "slot": "693149389", + "pin": "12345", + "key_label": "hsm-key1", + "mechanism": "0x0001" +} +``` + ### Sample Request ```shell-session $ curl \ --request POST \ --header "X-Vault-Token: ..." \ + --data @payload.json \ http://127.0.0.1:8200/v1/sys/managed-keys/pkcs11/hsm-key1 ``` @@ -85,7 +98,7 @@ $ curl \ ~> NOTE: The `pkcs11` backend is only available with Vault Enterprise Plus (HSMs) edition -- `type` `(string: "pkcs11")` - To select a PKCS#11 backend, the type parameter must be set to `pkcs11` +- `type` `(string: "pkcs11")` - To select a PKCS#11 backend, the type parameter must be set to `pkcs11`. - `library` `(string: )` - The name of the `kms_library` stanza to use from Vault's config to lookup the local library path. See [kms_library stanza](/docs/configuration/kms-library) for further details. @@ -119,13 +132,13 @@ $ curl \ - `token_label` `(string: )`: The slot token label to use. -- `curve` `(string: "")` - supplies the curve value when using the `CKM_ECDSA mechanism`. +- `curve` `(string: "" )` - supplies the curve value when using the `CKM_ECDSA mechanism`. The supported values are - `P384` - `P521` - `P256` -- `key_bits` `(int: 0)` - supplies the size in bits of the key when using `CKM_RSA_PKCS_PSS`, +- `key_bits` `(int: 0 )` - supplies the size in bits of the key when using `CKM_RSA_PKCS_PSS`, `CKM_RSA_PKCS_OAEP` or `CKM_RSA_PKCS` as a value for `mechanism`. The supported values are - 2048 @@ -138,12 +151,14 @@ $ curl \ pkcs11 implementation. #### AWS KMS Parameters +- `type` `(string: "awskms")` - To select an AWS KMS backend, the type parameter must be set to `awskms`. + - `access_key` `(string: )`: The AWS access key to use. This may also be provided in the `AWS_ACCESS_KEY_ID` environment variable or as part of the AWS profile from the AWS CLI or instance profile. -- `curve` `(string: "")`: The curve to use for an ECDSA key. This field is used when - `key_type` is `ECDSA`. Supported options are `P256`, `P384`, or `P521`. +- `curve` `(string: "" )`: The curve to use for an ECDSA key. + This field is used when `key_type` is `ECDSA`. Supported options are `P256`, `P384`, or `P521`. - `endpoint` `(string: "")`: Used to specify a custom AWS endpoint. If not set, Vault will use the default API endpoint for your region. @@ -173,6 +188,31 @@ $ curl \ the `AWS_SECRET_ACCESS_KEY` environment variable or as part of the AWS profile from the AWS CLI or instance profile. +#### Azure Key Vault Parameters +- `type` `(string: "azurekeyvault")` - To select an Azure Key Vault backend, the type parameter must be set to `azurekeyvault`. + +- `tenant_id` `(string: )`: The tenant id for the Azure Active Directory organization. + +- `client_id` `(string: )`: The client id for credentials to query the Azure APIs. + +- `client_secret` `(string: )`: The client secret for credentials to query the + Azure APIs. + +- `environment` `(string: "AZUREPUBLICCLOUD")`: The Azure Cloud environment API endpoints to use. + +- `vault_name` `(string: )`: The Key Vault vault to use the encryption keys for + encryption and decryption. + +- `key_name` `(string: )`: The Key Vault key to use for encryption and decryption. + +- `resource` `(string: "vault.azure.net")`: The Azure Key Vault resource's DNS Suffix to connect + to. Needs to be changed to connect to Azure's Managed HSM KeyVault instance type. + +- `key_bits` `(string: )`: The size in bits for an RSA key. + This field is required when `key_type` is `RSA`. Supported values are `2048`, `3072`, and `4096`. + +- `key_type` `(string: )`: The type of key to use. At this time only supported value is `RSA`. + ## Read managed key This endpoint returns the managed key configuration at the given path. @@ -184,7 +224,7 @@ This endpoint returns the managed key configuration at the given path. ### Parameters - `name` `(string: )` - The lowercase name identifying the key. -- `type` `(string: )` – The backend type for the managed key. +- `type` `(string: )` – The backend type for the managed key. Supported options are `pkcs11`, `awskms` and `azurekeyvault`. ### Sample Request @@ -233,7 +273,7 @@ status code, the configuration can be considered valid. ### Parameters - `name` `(string: )` - The lowercase name identifying the key. -- `type` `(string: )` – The backend type for the managed key. +- `type` `(string: )` – The backend type for the managed key. Supported options are `pkcs11`, `awskms` and `azurekeyvault`. ### Sample Request @@ -257,7 +297,7 @@ listed within any mount point's `allowed_managed_keys`. ### Parameters - `name` `(string: )` - The lowercase name identifying the key. -- `type` `(string: )` – The backend type for the managed key. +- `type` `(string: )` – The backend type for the managed key. Supported options are `pkcs11`, `awskms` and `azurekeyvault`. ### Sample Request