Transit engine named key upsert behavior is not consistently documented and highlighted.

[andersonm-1]

https://www.vaultproject.io/docs/secrets/transit#usage describes key usage flow as:

1. Enable transit engine
2. Create a named key
3. Use the key for encryption/decryption

However, and as documented in https://www.vaultproject.io/api-docs/secret/transit#encrypt-data , when encrypt endpoint is called, "if the user has the create capability for this endpoint in their policies, and the key does not exist, it will be upserted with default values (whether the key requires derivation depends on whether the context parameter is empty or not)."
This behavior is dangerous. If an authorized user is trying to encrypt with an existing key and by mistake sends a name of a non-existent key, then his data is encrypted with a key different from the one he expects. When the user later tries to decrypt, he isn't able to unless he recreates the same mistaken name.

If this is the accepted behavior, then at least it should be very well documented and highlighted.

[sgmiller]

Not to disparage this issue, this indeed may need some thought. But I wanted to point out this is only if the user has "create" on the path. You can assign only "update" to your policies to prevent this from happening.

[aphorise]

I think the current documentation calls this out:

This endpoint encrypts the provided plaintext using the named key. This path supports the create and update policy capabilities as follows: if the user has the create capability for this endpoint in their policies, and the key does not exist, it will be upserted with default values (whether the key requires derivation depends on whether the context parameter is empty or not). If the user only has update capability and the key does not exist, an error will be returned.

Hey @andersonm-1 do you agree & ok to close?
PS - relates to #9235

[andersonm-1]

Hi @aphorise . I would prefer to have an explicit mention in the Usage section under the "Encrypt some plaintext data using the /encrypt endpoint with a named key" item, something like:
NOTE: if the named key doesn't exist and the user has the create capability for this endpoint in their policies, then it is created with default values!

[aphorise]

I hear your preference but the only issue with adding it in the CLI documentation area speficially for tranist is that it would then make it an exception among the other sections which do not detail policy capabilities - those are all done in the API. The Docs tend to give you a quick guide / access via CLI using a prividilged token (like an admin / root token).

What's more the policy section is also calling attention to this for all mounts in the concepts:

create (POST/PUT) - Allows creating data at the given path. Very few parts of Vault distinguish between create and update, so most operations require both create and update capabilities. Parts of Vault that provide such a distinction are noted in documentation.

@andersonm-1 - please consider closing if you agree.

PS - there's also been -output-policy parameter since 1.11.0:

Print minimum required policy for any command: The global CLI flag -output-policy can now be used with any command to print out the minimum required policy HCL for that operation, including whether the given path requires the "sudo" capability. [https://github.com//pull/14899]