Addressed review comments and added docs for 1.19.x and 1.20.x

Author: Adit Shah

content/vault/v1.19.x/content/docs/enterprise/managed-keys.mdx renamed to content/vault/v1.19.x/content/docs/enterprise/managed-keys/managed-keys.mdx

@@ -0,0 +1,237 @@
+---
+layout: docs
+page_title: Configure transit secret engine to use HSM managed keys
+description: >-
+  Understand how to configure vault to use keys present in PKCS #11 based HSM for crypto-operations.
+---
+
+# Configure transit secrets engine to use PKCS 11 HSM using managed keys
+
+@include 'alerts/enterprise-only.mdx'
+
+Transit secrets engine can be pluged into Vault's centralised abstraction layer called [managed keys](/vault/docs/enterprise/managed-keys) to delegate 
+crypto-operations operations to a trusted external KMS or HSM.
+This allows users to leverage key management systems external to Vault for handling, storing, and interacting 
+with private key material. 
+
+## Requirements
+
+To setup transit secrets engine backed by PKCS 11 based HSM, you need: 
+
+- A Vault Enterprise server running. 
+- A PKCS 11 based HSM.
+
+## Vault setup
+
+1. Configure managed key.
+    
+    A PKCS#11 HSM requires a shared library to configure Vault to communication with the HSM. 
+    To declare this library, edit the Vault server configuration to add a [`kms_library` stanza](/vault/docs/configuration/kms-library)
+
+    <CodeBlockConfig filename="config-vault.hcl">
+
+    ```hcl
+    kms_library "pkcs11" {
+        name = "myhsm"
+        library = "/usr/vault/lib/libCryptoki2_64.so"
+    }
+    ```
+
+    </CodeBlockConfig>
+
+1. Use PKCS 11 with IBM EP11 tokens.
+
+    <Note> 
+
+    User needs to have Crypto Express adapters enabled in the LinuxOne and Linux on IBM Z instances as well as configure to use EP11 token. 
+    User also needs to install opencryptoki which can then talk to EP11 token. For more details, refer to the [IBM EP11 Token](https://www.ibm.com/docs/en/linux-on-systems?topic=support-exploiting-enterprise-pkcs-11-using-opencryptoki) page.
+
+    </Note>
+
+    ```hcl
+    kms_library "pkcs11" {
+        name = "myhsm"
+        library = "/usr/local/lib/opencryptoki/libopencryptoki.so"
+    }
+    ```
+
+1.  Restart or reload Vault's configuration with `SIGHUP`.
+
+    ```shell-session
+    $ kill -HUP $(pidof vault)
+    ```  
+1.  Each managed key requires type-specific configuration. You must identify the location of a key and PIN to access the HSM. This is very similar to Vault's PKCS#11 auto-unseal mechanism. Configure the managed key.
+   
+    ```shell-session
+    $ vault write sys/managed-keys/pkcs11/transit-rsa-key \
+        library=myhsm \
+        slot=4 \
+        pin=12345678 \
+        key_label="vault-rsa-key" \
+        allow_generate_key=true \
+        mechanism=0x0001 \
+        allow_store_key=true \
+        key_bits=2048 \
+        any_mount=false
+    ```
+
+    The PKCS#11 specific parameters are `library`, referring to the previously
+    configured `kms_library` stanza, `slot`, `pin`, `key_label`, and `mechanism`,
+    which identifies the object in the HSM which will hold the key. Its
+    mechanism is `CKM_RSA_PKCS` (RSA with PKCS#11 v1.5 signatures), and that will
+    require a 2048 bit key. The `allow_generate_key` flag indicates that Vault is
+    allowed to request that the HSM generate a key. The `allow_store_key` parameter
+    indicates that a new key may be stored in the backend. Without this flag, you
+    may configure the key yourself in the HSM and just point Vault at the result.
+    The `any_mount` means any mount in the namespace may access the managed
+    key. For this example, it is set to false so that you can demonstrate how to
+    lock managed key access down to a specific mount.
+
+    **Example output:**
+
+    <CodeBlockConfig hideClipboard>
+
+    ```plaintext
+    Success! Data written to: sys/managed-keys/pkcs11/transit-rsa-key
+    ```
+
+    </CodeBlockConfig>
+
+1.  Read the key back to verify if named managed key was created successfully. 
+
+    ```shell-session
+    $ vault read sys/managed-keys/pkcs11/transit-rsa-key
+
+    Key                   Value
+    ---                   -----
+    UUID                  fe8f3c8c-8f11-571d-b4ce-411314fcaf98
+    allow_generate_key    true
+    allow_replace_key     false
+    allow_store_key       true
+    any_mount             false
+    key_bits              2048
+    key_label             vault-rsa-key
+    library               myhsm
+    mechanism             1
+    name                  transit-rsa-key
+    pin                   redacted
+    slot                  4
+    type                  pkcs11
+    usages                [3 4]
+    ```
+
+##  Configure transit secrets engine
+
+1.  Enable the `transit` secrets engine at the `transit` path.
+
+    ```shell-session
+    $ vault secrets enable transit
+    Success! Enabled the transit secrets engine at: transit/
+    ```
+
+1.  Tune the secrets engine to use managed keys.
+
+    ```shell-session
+    $ vault secrets tune --allowed-managed-keys=transit-rsa-key transit
+    Success! Tuned the secrets engine at: transit/
+    ```
+
+    You configured the managed key with `any_mount=false` in the previous step.
+    This command grants access to the `transit-rsa-key` to the Transit secrets
+    engine's mount.
+
+1.  Create a transit key.
+
+    ```shell-session
+    $ vault write transit/keys/hsm-transit-key \
+        type=managed_key \
+        managed_key_name=transit-rsa-key \
+        allow_plaintext_backup=false \
+        exportable=false
+    ```
+   
+    **Example output:**
+
+    <CodeBlockConfig hideClipboard>
+   
+    ```text
+    Key                       Value
+    ---                       -----
+    allow_plaintext_backup    false
+    auto_rotate_period        0s
+    deletion_allowed          false
+    derived                   false
+    exportable                false
+    imported_key              false
+    latest_version            1
+    min_available_version     0
+    min_decryption_version    1
+    min_encryption_version    0
+    name                      hsm-transit-key
+    supports_decryption       true
+    supports_derivation       false
+    supports_encryption       true
+    supports_signing          true
+    type                      managed_key
+    ```
+
+    </CodeBlockConfig>
+
+    At this step while creating transit key, RSA 2048 public private key pair also gets created in the HSM. The key label is `vault-rsa-key`.
+
+##  Perform crypto-operation
+
+1.  Perform the sign data operation.
+
+    ```shell-session
+    $ vault write transit/sign/hsm-transit-key \
+        input=$(echo -n "data to sign" | base64) \
+        hash_algorithm=sha2-256
+    ```
+
+    **Example output:**
+
+    <CodeBlockConfig hideClipboard>
+
+    ```text
+    Key            Value
+    ---            -----
+    key_version    1
+    signature      vault:v1:bqLeknlTuvrPt99ubS0CZyDs5iG8q9n+7kLG+2qHmg1xcHxUdKYCvtIUO5ZpCjJ6SUA/cTJgeFqdhK5rOcSfTzhU5B+HABEYeVb+H7yQ4+sLWrJQ5fNAQZCly+AiXM4q2lAvMW651oq0D4R86f0tOUHVjsaQyqhrrtaA1GQoIcNikx4llTXiGRmc3A1dZmpFCpG7ejQuUF8mGj1tFmY/dyrV0V9o58rmqGe/ddfg+bAfpewNcqWPoWtB+o9QuFhw3L8eqxVCbF8lGfZlqJmudep13So4bC03bWdlZBET8nYpX51Bi5yz0C9wth666IiqE61JnPBlmcJFEyd3FCJ4yQ==
+    ```
+
+    </CodeBlockConfig>
+
+2.  Verify signed data.
+
+    ```shell-session
+    $ vault write transit/verify/hsm-transit-key \
+        input=$(echo -n "data to sign" | base64) \
+        hash_algorithm=sha2-256 \
+        signature="vault:v1:..."
+    ```
+
+    The signature is the output of the sign command.
+
+    **Example output:**
+
+    <CodeBlockConfig hideClipboard>
+
+    ```shell-session
+    Key      Value
+    ---      -----
+    valid    true
+    ```
+
+    </CodeBlockConfig>
+
+
+## Reference
+
+- [Encrypt data in transit with Vault](/vault/tutorials/encryption-as-a-service/eaas-transit)
+- [Transit secrets engine](/vault/docs/secrets/transit)
+
+## API 
+
+- [Transit secrets engine (API)](/vault/api-docs/secret/transit)
+- [`/sys/managed-keys`](/vault/api-docs/system/managed-keys) endpoint

content/vault/v1.19.x/content/docs/enterprise/managed-keys/transit-secret-engine.mdx

@@ -2896,7 +2896,16 @@
       },
       {
         "title": "3rd party key management",
-        "path": "enterprise/managed-keys"
+        "routes": [
+          {
+            "title": "3rd party key management in Vault",
+             "path": "enterprise/managed-keys"
+          },
+          {
+            "title": "Transit secret engine with pkcs11 HSM",
+            "path": "enterprise/managed-keys/transit-secret-engine"
+          }
+        ]
       },
       {
         "title": "Multi-factor authN",