doc: build: signing: document signing key file resolution

doc/build/signing/index.rst

@@ -36,9 +36,10 @@ Notes on the above commands:
 
 For more information on these and other related configuration options, see:
 
-- ``SB_CONFIG_BOOTLOADER_MCUBOOT``: build the application for loading by MCUboot
-- ``SB_CONFIG_BOOT_SIGNATURE_KEY_FILE``: the key file to use when signing images. If you have
-  your own key, change this appropriately
+- :kconfig:option:`SB_CONFIG_BOOTLOADER_MCUBOOT`: build the application for loading by MCUboot
+- :kconfig:option:`SB_CONFIG_BOOT_SIGNATURE_KEY_FILE`: the key file to use when signing images. If
+  you have your own key, change this appropriately; see :ref:`build-signing-keys` for using an
+  absolute path or a CMake variable such as ``${APP_DIR}``
 - :kconfig:option:`CONFIG_MCUBOOT_EXTRA_IMGTOOL_ARGS`: optional additional command line arguments
   for ``imgtool``
 - :kconfig:option:`CONFIG_MCUBOOT_GENERATE_CONFIRMED_IMAGE`: also generate a confirmed image,
@@ -66,6 +67,64 @@ Whether ``west flash`` supports this feature depends on your runner. The ``nrfjp
 ``pyocd`` runners work with the above flow. If your runner does not support this flow and you
 would like it to, please send a patch or file an issue for adding support.
 
+.. _build-signing-keys:
+
+Signing key files
+*****************
+
+When building with sysbuild, :kconfig:option:`SB_CONFIG_BOOT_SIGNATURE_KEY_FILE` selects the key
+used to sign images. Its value is propagated to two images:
+
+- the application image, as :kconfig:option:`CONFIG_MCUBOOT_SIGNATURE_KEY_FILE`, which ``imgtool``
+  uses to sign the application; and
+- the MCUboot image, as ``CONFIG_BOOT_SIGNATURE_KEY_FILE``, whose public part is built into the
+  bootloader so it can verify that signature.
+
+.. warning::
+
+   The default value points at one of the insecure development keys bundled with MCUboot (for
+   example :file:`root-ec-p256.pem`). These keys are public — they ship with every Zephyr and
+   MCUboot checkout — so they are only suitable for development and testing. For anything else,
+   generate your own key and keep the private key out of any repository or build directory that
+   you do not control.
+
+How sysbuild resolves the key file path
+=======================================
+
+The value of :kconfig:option:`SB_CONFIG_BOOT_SIGNATURE_KEY_FILE` is processed with CMake's
+``string(CONFIGURE)`` command, so any ``${VARIABLE}`` reference it contains is expanded as a CMake
+variable before the path is used. After expansion, an absolute path is used as-is; a relative path
+is resolved by each image independently:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 35 65
+
+   * - Image
+     - Search order for a relative path
+   * - Application (:kconfig:option:`CONFIG_MCUBOOT_SIGNATURE_KEY_FILE`)
+     - ``APPLICATION_CONFIG_DIR``, then the west workspace topdir (``WEST_TOPDIR``)
+   * - MCUboot (``CONFIG_BOOT_SIGNATURE_KEY_FILE``)
+     - ``APPLICATION_CONFIG_DIR``, then the MCUboot module directory
+
+.. warning::
+
+   Each image resolves a relative path against a different base, so a bare relative path points at
+   a different file for each image and usually fails to build. Do not use one: give an absolute
+   path, or anchor the path with a CMake variable.
+
+``${APP_DIR}`` (the main application's source directory) is the recommended anchor: it keeps the
+key inside your own application, and both images resolve it to the same file. Any CMake variable
+available when the value is expanded may be used:
+
+.. code-block:: cfg
+
+   # sysbuild.conf
+   SB_CONFIG_BOOT_SIGNATURE_KEY_FILE="${APP_DIR}/keys/my-signing-key.pem"
+
+The same resolution rules apply to the optional encryption key file
+(:kconfig:option:`CONFIG_MCUBOOT_ENCRYPTION_KEY_FILE`).
+
 .. _west-extending-signing:
 
 Extending signing externally

doc/build/sysbuild/images.rst

@@ -283,7 +283,8 @@ configuration values, multiple can be used per image, the configuration should b
 different images to correctly configure them based upon options set in sysbuild. MCUboot
 configuration options are configured in both the application the MCUboot image using this method
 which allows sysbuild to be the central location for things like the signing key which are then
-kept in-sync in the main application bootloader images.
+kept in-sync in the main application bootloader images. See :ref:`build-signing-keys` for setting
+the key to an absolute path or a CMake variable such as ``${APP_DIR}``.
 
 Inside image configuration scripts, the ``ZCMAKE_APPLICATION`` variable is set to the name of the
 application being configured, the ``set_config_*`` sysbuild CMake functions can be used to set