Update docs to include specifics and caveats around Transit Managed K…

…eys support. (hashicorp#20099)

website/content/api-docs/secret/transit.mdx

@@ -648,7 +648,7 @@ will be returned.
 
 - `batch_input` `(array<object>: nil)` – Specifies a list of items to be
   encrypted in a single batch. When this parameter is set, if the parameters
-  'plaintext', 'context' and 'nonce' are also set, they will be ignored. 
+  'plaintext', 'context' and 'nonce' are also set, they will be ignored.
   Any batch output will preserve the order of the batch input. The
   format for the input is:
 
@@ -679,10 +679,10 @@ will be returned.
   all nonces are unique for a given context. Failing to do so will severely
   impact the ciphertext's security.
 
-- `partial_failure_response_code` `(int: 400)` Ordinarily, if a batch item fails 
-  to encrypt due to a bad input, but other batch items succeed, the HTTP response 
+- `partial_failure_response_code` `(int: 400)` Ordinarily, if a batch item fails
+  to encrypt due to a bad input, but other batch items succeed, the HTTP response
   code is 400 (Bad Request).  Some applications may want to treat partial failures
-  differently.  Providing the parameter returns the given response code integer 
+  differently.  Providing the parameter returns the given response code integer
   instead of a failed status code in this case. If all values fail an error
   code is still returned.  Be warned that some failures (such as failure to
   decrypt) could be indicative of a security breach and should not be
@@ -767,7 +767,7 @@ This endpoint decrypts the provided ciphertext using the named key.
 
 - `batch_input` `(array<object>: nil)` – Specifies a list of items to be
   decrypted in a single batch. When this parameter is set, if the parameters
-  'ciphertext', 'context' and 'nonce' are also set, they will be ignored. 
+  'ciphertext', 'context' and 'nonce' are also set, they will be ignored.
   Any batch output will preserve the order of the batch input. Format
   for the input goes like this:
 
@@ -783,10 +783,10 @@ This endpoint decrypts the provided ciphertext using the named key.
     }
   ]
   ```
-- `partial_failure_response_code` `(int: 400)` Ordinarily, if a batch item fails 
-  to encrypt due to a bad input, but other batch items succeed, the HTTP response 
+- `partial_failure_response_code` `(int: 400)` Ordinarily, if a batch item fails
+  to encrypt due to a bad input, but other batch items succeed, the HTTP response
   code is 400 (Bad Request).  Some applications may want to treat partial failures
-  differently.  Providing the parameter returns the given response code integer 
+  differently.  Providing the parameter returns the given response code integer
   instead of a failed status code in this case. If all values fail an error
   code is still returned.  Be warned that some failures (such as failure to
   decrypt) could be indicative of a security breach and should not be
@@ -1079,7 +1079,7 @@ $ curl \
 ## Generate HMAC
 
 This endpoint returns the digest of given data using the specified hash
-algorithm and the named key. The key can be of any type supported by `transit`, 
+algorithm and the named key. The key can be of any type supported by `transit`,
 as each `transit` key version has an independent, random 256-bit HMAC secret key. If
 the key is of a type that supports rotation, the latest (current) version will
 be used.
@@ -1125,7 +1125,7 @@ be used.
 - `batch_input` `(array<object>: nil)` – Specifies a list of items for processing.
   When this parameter is set, if the parameter 'input' is also set, it will be
   ignored. Responses are returned in the 'batch_results' array component of the
-  'data' element of the response. Any batch output will preserve the order of 
+  'data' element of the response. Any batch output will preserve the order of
   the batch input. If the input data value of an item is invalid, the
   corresponding item in the 'batch_results' will have the key 'error' with a value
   describing the error. The format for batch_input is:
@@ -1279,7 +1279,7 @@ supports signing.
 - `batch_input` `(array<object>: nil)` – Specifies a list of items for processing.
   When this parameter is set, any supplied 'input' or 'context' parameters will be
   ignored. Responses are returned in the 'batch_results' array component of the
-  'data' element of the response. Any batch output will preserve the order of the 
+  'data' element of the response. Any batch output will preserve the order of the
   batch input. If the input data value of an item is invalid, the
   corresponding item in the 'batch_results' will have the key 'error' with a value
   describing the error. The format for batch_input is:
@@ -1472,9 +1472,9 @@ data.
   either an 'hmac' or 'signature' parameter. All items in the batch must consistently
   supply either 'hmac' or 'signature' parameters. It is an error for some items to
   supply 'hmac' while others supply 'signature'. Responses are returned in the
-  'batch_results' array component of the 'data' element of the response. Any batch 
-  output will preserve the order of the batch input. If the input data value of an 
-  item is invalid, the corresponding item in the 'batch_results' will have the key 
+  'batch_results' array component of the 'data' element of the response. Any batch
+  output will preserve the order of the batch input. If the input data value of an
+  item is invalid, the corresponding item in the 'batch_results' will have the key
   'error' with a value describing the error. The format for batch_input is:
 
   ```json
@@ -1765,4 +1765,25 @@ $ curl \
   },
 ```
 
+## Managed Keys
+
+~> **Note**: Managed keys are an Enterprise only feature.
+
+Managed Keys can be used with the Transit Secrets Engine to perform cryptographic operations. Currently
+[Sign Data](#sign-data) and [Verify Signed Data](#verify-signed-data) are well supported, and in certain
+configurations, [Encrypt Data](#encrypt-data) and [Decrypt Data](#decrypt-data) are supported.
+
+When a Transit key is created of type `managed_key`, Transit will lookup the key by name or ID, and will
+attempt to generate the key when key generation is allowed (as specified when the [Create/Update Managed Key](/vault/api-docs/system/managed-keys#create-update-managed-key)
+endpoint is called). Key generation is currently supported for cloud KMSes and for certain PKCS#11 mechanisms
+on HSMs. This is a best effort operation, so certain KMS/HSM/key configurations will require the key to exist
+externally prior to use with Transit.
+
+For key types and mechanisms that require an IV, this value can be provided via the `nonce` parameter of
+the [Encrypt Data](#encrypt-data) and [Decrypt Data](#decrypt-data) endpoints.
+
+Signing and verifying data with a Managed Key through Transit may require pre-hashing of the data. Transit
+can be informed that data is pre-hashed with the `prehashed` parameter of the [Sign Data](#sign-data) and
+[Verify Signed Data](#verify-signed-data) endpoints.
+
 [sys-plugin-reload-backend]: /vault/api-docs/system/plugins-reload-backend#reload-plugins

website/content/api-docs/system/managed-keys.mdx

@@ -121,6 +121,10 @@ $ curl \
     - `0x0009` `CKM_RSA_PKCS_OAEP`
     - `0x0001` `CKM_RSA_PKCS`
 
+  ~> **Note**: It is possible to use unsupported mechanisms with a managed key, however automatic key generation is only
+  possible with the above supported mechanisms. Automatic key generation is also currently a best effort operation and may
+  not function correctly on all HSMs.
+
 - `pin` `(string: <required>)`: The PIN for login.
 
 - `slot` `(string: <slot or token label required>)`: The slot number to use,

website/content/docs/enterprise/managed-keys.mdx

@@ -46,6 +46,11 @@ The [PKI Secrets Engine](/vault/api-docs/secret/pki#managed-keys) has been integ
 with Managed Keys to offer certificate generation, both root and intermediary
 PKI paths, leveraging private keys from an external trusted KMS.
 
+The [Transit Secrets Engine](/vault/api-docs/secret/transit#managed-keys) allows users
+to generate and verify cryptographic signatures with Managed Keys, and in some cases encrypt
+and decrypt data, or generate MACs and HMACs. These operations are performed on the KMS or HSM
+that hosts the Managed Key material.
+
 More engines may leverage managed keys in the future.
 
 ## API