[PATCH 15/15] Documentation: migration-2025.11.0: List changes to CONFIG_CRYPTO_PUBLIC_KEYS

[Jonas Rebmann <jre@pengutronix.de>]

As part of the introduction of TLV signature in public key keyrings,
there is a new interpreter for CONFIG_CRYPTO_PUBLIC_KEYS in
scripts/keytoc.c. All users should update to the new syntax and are
presented with a warning. Users with invalid characters in the legacy
syntax must change the fit-hint and will be presented with an error.

Signed-off-by: Jonas Rebmann <jre@pengutronix.de>
---
 Documentation/migration-guides/migration-2025.11.0.rst | 17 +++++++++++++++++
 Documentation/user/barebox-tlv.rst                     | 16 ++++++++--------
 2 files changed, 25 insertions(+), 8 deletions(-)

diff --git a/Documentation/migration-guides/migration-2025.11.0.rst b/Documentation/migration-guides/migration-2025.11.0.rst
new file mode 100644
index 0000000000..87b1486fda
--- /dev/null
+++ b/Documentation/migration-guides/migration-2025.11.0.rst
@@ -0,0 +1,17 @@
+Release v2025.11.0
+==================
+
+Configuration options
+---------------------
+
+* The syntax of ``CONFIG_CRYPTO_PUBLIC_KEYS`` was updated with the introduction
+  of the keyring feature. Previously, keys selected via
+  ``CONFIG_CRYPTO_PUBLIC_KEYS`` were only used for fitimage verification. Now,
+  fitimage verification uses the "fit" keyring. "fit" will be selected as the
+  default keyring for transition but a warning will be emitted when no keyring
+  is explicitly provided. Existing users should update their keyspec for
+  fitimage public keys to ``keyring=fit[,fit-hint=<fit_hint>]:<crt>``
+* The fit-hints in ``CONFIG_CRYPTO_PUBLIC_KEYS`` are now limited to identifiers
+  matching the regular expression ``[a-zA-Z][a-zA-Z0-9_-]*``. Public keys with
+  a ``fit-hint`` not conforming to this results in an error, affected key-hints
+  must be changed. Please reach out to the mailing list if this causes issues.
diff --git a/Documentation/user/barebox-tlv.rst b/Documentation/user/barebox-tlv.rst
index 46d1f7a006..1c1abfb43a 100644
--- a/Documentation/user/barebox-tlv.rst
+++ b/Documentation/user/barebox-tlv.rst
@@ -31,8 +31,8 @@ The TLV binary has the following format:
      };
 
      struct sig {
-       u8 spki_hash_prefix[4];
-       u8 signature[];
+         u8 spki_hash_prefix[4];
+         u8 signature[];
      };
 
      struct tlv_format {
@@ -67,12 +67,12 @@ Parsing must be handled by board-specific extensions.
 Signature
 ---------
 
-If ``length_sig`` is zero, signature is disabled.
-The ``signature`` section of the file is exactly ``length_sig`` bytes long.
-This includes the ``spki_hash_prefix``, followed by the signature itself.
-``spki_hash_prefix`` is the first bytes of the sha256 hash of the *Subject
-Public Key Info* and its purpose is to allow for quicker matching of a signed
-TLV with its corresponding public key during signature verification.
+If ``length_sig`` is zero, signature is disabled.  The ``signature`` section of
+the file is exactly ``length_sig`` bytes long.  This includes the
+``spki_hash_prefix``, followed by the signature itself.  ``spki_hash_prefix``
+is the first four bytes of the sha256 hash of the *Subject Public Key Info* and
+its purpose is to allow for quicker matching of a signed TLV with its
+corresponding public key during signature verification.
 
 The ``signature`` shall be verified on all fields before the ``signature`` field,
 but with ``length_sig`` overwritten with 0,

-- 
2.51.0.297.gca2559c1d6