Add 1.19.x upgrade note around Transit API change for Ed25519ph signa…

…tures (#28847)

website/content/docs/upgrading/upgrade-to-1.19.x.mdx

@@ -0,0 +1,44 @@
+---
+layout: docs
+page_title: Upgrade to Vault 1.19.x - Guides
+description: |-
+  Deprecations, important or breaking changes, and remediation recommendations
+  for anyone upgrading to 1.19.x from Vault 1.18.x.
+---
+
+# Overview
+
+The Vault 1.19.x upgrade guide contains information on deprecations, important
+or breaking changes, and remediation recommendations for anyone upgrading from
+Vault 1.18. **Please read carefully**.
+
+## Important changes
+
+### Transit support for Ed25519ph and Ed25519ctx signatures
+
+**NOTE**: This only applies to Transit Ed25519 keys.
+
+On prior versions of Vault, when the sign and verify API endpoints backed by an Ed25519
+key received the prehashed=true or the hash_algorithm=sha2-512 parameters they were ignored,
+returning back or verifying a Pure Ed25519 signature. As of 1.19.x, setting these values
+on Enterprise editions of Vault will now return an Ed25519ph signature and assume the
+input has been hashed using the SHA-512 algorithm.
+
+If neither prehashed nor hash_algorithm values are provided, the existing default of using
+Pure Ed25519 signatures remains unchanged for both Enterprise and CE Vault editions. The change
+is if those values had been overridden they were previously ignored but now will be enforced
+based on the table below.
+
+| Vault Edition | prehashed | hash_algorithm                | 1.19.x Signature                           | Previous Vault Versions Signature |
+|:--------------|:----------|:------------------------------|:-------------------------------------------|:----------------------------------|
+| Enterprise    | not set   | not set                       | Pure Ed25519                               | Pure Ed25519                      |
+| Enterprise    | false     | any value other than sha2-512 | Pure Ed25519                               | Pure Ed25519                      |
+| Enterprise    | false     | sha2-512                      | An error is returned                       | Pure Ed25519                      |
+| Enterprise    | true      | any value other than sha2-512 | An error is returned                       | Pure Ed25519                      |
+| Enterprise    | true      | sha2-512                      | Ed25519ph                                  | Pure Ed25519                      |
+| CE            | not set   | not set                       | Pure Ed25519                               | Pure Ed25519                      |
+| CE            | false     | any value other than sha2-512 | Pure Ed25519                               | Pure Ed25519                      |
+| CE            | false     | sha2-512                      | An error is returned                       | Pure Ed25519                      |
+| CE            | true      | any value other than sha2-512 | An error is returned                       | Pure Ed25519                      |
+| CE            | true      | sha2-512                      | An error is returned (not supported on CE) | Pure Ed25519                      |
+

website/data/docs-nav-data.json

@@ -2435,6 +2435,10 @@
         "title": "Upgrade to Raft WAL",
         "path": "upgrading/raft-wal"
       },
+      {
+        "title": "Upgrade to 1.19.x",
+        "path": "upgrading/upgrade-to-1.19.x"
+      },
       {
         "title": "Upgrade to 1.18.x",
         "path": "upgrading/upgrade-to-1.18.x"