Merge 9f026bfd96 into 9bf6ffe166

man: split cryptenroll man page into sections (#35297 )
cryptenroll: it's called PKCS#11, not PKCS11
2024-11-22 13:01:34 +01:00 · 2024-11-22 12:01:07 +00:00 · 2024-11-22 10:42:37 +01:00 · 2024-11-22 10:42:37 +01:00 · 2024-11-22 10:38:19 +01:00 · 2024-11-12 15:38:46 +05:30
8 changed files with 100 additions and 48 deletions
--- a/man/systemd-cryptenroll.xml
+++ b/man/systemd-cryptenroll.xml
@ -265,32 +265,11 @@
  </refsect1>

  <refsect1>
-    <title>Options</title>
+    <title>Unlocking</title>

-    <para>The following options are understood:</para>
+    <para>The following options are understood that may be used to unlock the device in preparation of the enrollment operations:</para>

    <variablelist>
-      <varlistentry>
-        <term><option>--password</option></term>
-
-        <listitem><para>Enroll a regular password/passphrase. This command is mostly equivalent to
-        <command>cryptsetup luksAddKey</command>, however may be combined with
-        <option>--wipe-slot=</option> in one call, see below.</para>
-
-        <xi:include href="version-info.xml" xpointer="v248"/></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><option>--recovery-key</option></term>
-
-        <listitem><para>Enroll a recovery key. Recovery keys are mostly identical to passphrases, but are
-        computer-generated instead of being chosen by a human, and thus have a guaranteed high entropy. The
-        key uses a character set that is easy to type in, and may be scanned off screen via a QR code.
-        </para>
-
-        <xi:include href="version-info.xml" xpointer="v248"/></listitem>
-      </varlistentry>
-
      <varlistentry>
        <term><option>--unlock-key-file=<replaceable>PATH</replaceable></option></term>

@ -328,7 +307,45 @@

        <xi:include href="version-info.xml" xpointer="v256"/></listitem>
      </varlistentry>
+    </variablelist>
+  </refsect1>

+  <refsect1>
+    <title>Simple Enrollment</title>
+
+    <para>The following options are understood that may be used to enroll simple user input based
+    unlocking:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term><option>--password</option></term>
+
+        <listitem><para>Enroll a regular password/passphrase. This command is mostly equivalent to
+        <command>cryptsetup luksAddKey</command>, however may be combined with
+        <option>--wipe-slot=</option> in one call, see below.</para>
+
+        <xi:include href="version-info.xml" xpointer="v248"/></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--recovery-key</option></term>
+
+        <listitem><para>Enroll a recovery key. Recovery keys are mostly identical to passphrases, but are
+        computer-generated instead of being chosen by a human, and thus have a guaranteed high entropy. The
+        key uses a character set that is easy to type in, and may be scanned off screen via a QR code.
+        </para>
+
+        <xi:include href="version-info.xml" xpointer="v248"/></listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
+  <refsect1>
+    <title>PKCS#11 Enrollment</title>
+
+    <para>The following option is understood that may be used to enroll PKCS#11 tokens:</para>
+
+    <variablelist>
      <varlistentry>
        <term><option>--pkcs11-token-uri=<replaceable>URI</replaceable></option></term>

@ -361,7 +378,15 @@

        <xi:include href="version-info.xml" xpointer="v248"/></listitem>
      </varlistentry>
+    </variablelist>
+  </refsect1>

+  <refsect1>
+    <title>FIDO2 Enrollment</title>
+
+    <para>The following options are understood that may be used to enroll PKCS#11 tokens:</para>
+
+    <variablelist>
      <varlistentry>
        <term><option>--fido2-credential-algorithm=<replaceable>STRING</replaceable></option></term>
        <listitem><para>Specify COSE algorithm used in credential generation. The default value is
@ -461,7 +486,15 @@

        <xi:include href="version-info.xml" xpointer="v249"/></listitem>
      </varlistentry>
+    </variablelist>
+  </refsect1>

+  <refsect1>
+    <title>TPM2 Enrollment</title>
+
+    <para>The following options are understood that may be used to enroll TPM2 devices:</para>
+
+    <variablelist>
      <varlistentry>
        <term><option>--tpm2-device=<replaceable>PATH</replaceable></option></term>

@ -636,7 +669,15 @@

        <xi:include href="version-info.xml" xpointer="v255"/></listitem>
      </varlistentry>
+    </variablelist>
+  </refsect1>

+  <refsect1>
+    <title>Other Options</title>
+
+    <para>The following additional options are understood:</para>
+
+    <variablelist>
      <varlistentry>
        <term><option>--wipe-slot=<replaceable>SLOT<optional>,SLOT...</optional></replaceable></option></term>

--- a/man/systemd-stub.xml
+++ b/man/systemd-stub.xml
@ -75,6 +75,9 @@
      <listitem><para>An optional <literal>.ucode</literal> section with an initrd containing microcode, to
      be handed to the kernel before any other initrd. This initrd must not be compressed.</para></listitem>

+      <listitem><para>An optional <literal>.fmw</literal> section with the firmware image.
+      </para></listitem>
+
      <listitem><para>An optional <literal>.splash</literal> section with an image (in the Windows
      <filename>.BMP</filename> format) to show on screen before invoking the kernel.</para></listitem>

--- a/shell-completion/bash/systemd-cryptenroll
+++ b/shell-completion/bash/systemd-cryptenroll
@ -38,19 +38,12 @@ __get_tpm2_devices() {
    done
 }

-__get_block_devices() {
-    local i
-    for i in /dev/*; do
-        [ -b "$i" ] && printf '%s\n' "$i"
-    done
-}
-
 _systemd_cryptenroll() {
    local comps
    local cur=${COMP_WORDS[COMP_CWORD]} prev=${COMP_WORDS[COMP_CWORD-1]} words cword
    local -A OPTS=(
        [STANDALONE]='-h --help --version
-                     --password --recovery-key'
+                     --password --recovery-key --list-devices'
        [ARG]='--unlock-key-file
               --unlock-fido2-device
               --unlock-tpm2-device
@ -116,7 +109,7 @@ _systemd_cryptenroll() {
        return 0
    fi

-    comps=$(__get_block_devices)
+    comps=$(systemd-cryptenroll --list-devices)
    COMPREPLY=( $(compgen -W '$comps' -- "$cur") )
    return 0
 }
--- a/src/cryptenroll/cryptenroll.c
+++ b/src/cryptenroll/cryptenroll.c
@ -193,7 +193,7 @@ static int help(void) {
               "\n%3$sSimple Enrollment:%4$s\n"
               "     --password        Enroll a user-supplied password\n"
               "     --recovery-key    Enroll a recovery key\n"
-               "\n%3$sPKCS11 Enrollment:%4$s\n"
+               "\n%3$sPKCS#11 Enrollment:%4$s\n"
               "     --pkcs11-token-uri=URI\n"
               "                       Specify PKCS#11 security token URI\n"
               "\n%3$sFIDO2 Enrollment:%4$s\n"
--- a/src/fundamental/uki.c
+++ b/src/fundamental/uki.c
@ -9,19 +9,20 @@ const char* const unified_sections[_UNIFIED_SECTION_MAX + 1] = {
         * https://learn.microsoft.com/en-us/windows/win32/debug/pe-format#section-table-section-headers
         * (Note that PE *object* files may have longer section names (via indirection in the string table) but
         * this is not allowed for PE *executables*, which UKIs are.) */
-        [UNIFIED_SECTION_LINUX]   = ".linux",
-        [UNIFIED_SECTION_OSREL]   = ".osrel",
-        [UNIFIED_SECTION_CMDLINE] = ".cmdline",
-        [UNIFIED_SECTION_INITRD]  = ".initrd",
-        [UNIFIED_SECTION_UCODE]   = ".ucode",
-        [UNIFIED_SECTION_SPLASH]  = ".splash",
-        [UNIFIED_SECTION_DTB]     = ".dtb",
-        [UNIFIED_SECTION_UNAME]   = ".uname",
-        [UNIFIED_SECTION_SBAT]    = ".sbat",
-        [UNIFIED_SECTION_PCRSIG]  = ".pcrsig",
-        [UNIFIED_SECTION_PCRPKEY] = ".pcrpkey",
-        [UNIFIED_SECTION_PROFILE] = ".profile",
-        [UNIFIED_SECTION_DTBAUTO] = ".dtbauto",
-        [UNIFIED_SECTION_HWIDS]   = ".hwids",
+        [UNIFIED_SECTION_LINUX]      = ".linux",
+        [UNIFIED_SECTION_OSREL]      = ".osrel",
+        [UNIFIED_SECTION_CMDLINE]    = ".cmdline",
+        [UNIFIED_SECTION_INITRD]     = ".initrd",
+        [UNIFIED_SECTION_UCODE]      = ".ucode",
+        [UNIFIED_SECTION_SPLASH]     = ".splash",
+        [UNIFIED_SECTION_DTB]        = ".dtb",
+        [UNIFIED_SECTION_UNAME]      = ".uname",
+        [UNIFIED_SECTION_SBAT]       = ".sbat",
+        [UNIFIED_SECTION_PCRSIG]     = ".pcrsig",
+        [UNIFIED_SECTION_PCRPKEY]    = ".pcrpkey",
+        [UNIFIED_SECTION_PROFILE]    = ".profile",
+        [UNIFIED_SECTION_DTBAUTO]    = ".dtbauto",
+        [UNIFIED_SECTION_HWIDS]      = ".hwids",
+        [UNIFIED_SECTION_FIRMWARE]   = ".fmw",
        NULL,
 };
--- a/src/fundamental/uki.h
+++ b/src/fundamental/uki.h
@ -20,6 +20,7 @@ typedef enum UnifiedSection {
        UNIFIED_SECTION_PROFILE,
        UNIFIED_SECTION_DTBAUTO,
        UNIFIED_SECTION_HWIDS,
+        UNIFIED_SECTION_FIRMWARE,
        _UNIFIED_SECTION_MAX,
 } UnifiedSection;

--- a/src/measure/measure.c
+++ b/src/measure/measure.c
@ -104,6 +104,7 @@ static int help(int argc, char *argv[], void *userdata) {
               "     --linux=PATH        Path to Linux kernel image file        %7$s .linux\n"
               "     --osrel=PATH        Path to os-release file                %7$s .osrel\n"
               "     --cmdline=PATH      Path to file with kernel command line  %7$s .cmdline\n"
+               "     --firmware=PATH     Path to firmware image file            %7$s .fmw\n"
               "     --initrd=PATH       Path to initrd image file              %7$s .initrd\n"
               "     --ucode=PATH        Path to microcode image file           %7$s .ucode\n"
               "     --splash=PATH       Path to splash bitmap file             %7$s .splash\n"
@ -158,8 +159,9 @@ static int parse_argv(int argc, char *argv[]) {
                ARG_PCRPKEY,
                ARG_PROFILE,
                ARG_HWIDS,
+                ARG_DTBAUTO,
                _ARG_SECTION_LAST,
-                ARG_DTBAUTO = _ARG_SECTION_LAST,
+                ARG_FIRMWARE = _ARG_SECTION_LAST,
                ARG_BANK,
                ARG_PRIVATE_KEY,
                ARG_PRIVATE_KEY_SOURCE,
@ -180,6 +182,7 @@ static int parse_argv(int argc, char *argv[]) {
                { "osrel",              required_argument, NULL, ARG_OSREL              },
                { "cmdline",            required_argument, NULL, ARG_CMDLINE            },
                { "initrd",             required_argument, NULL, ARG_INITRD             },
+                { "firmware",           required_argument, NULL, ARG_FIRMWARE           },
                { "ucode",              required_argument, NULL, ARG_UCODE              },
                { "splash",             required_argument, NULL, ARG_SPLASH             },
                { "dtb",                required_argument, NULL, ARG_DTB                },
--- a/src/ukify/ukify.py
+++ b/src/ukify/ukify.py
@ -242,6 +242,7 @@ class UkifyConfig:
    efi_arch: str
    hwids: Path
    initrd: list[Path]
+    firmware: Path
    join_profiles: list[Path]
    json: Union[Literal['pretty'], Literal['short'], Literal['off']]
    linux: Optional[Path]
@ -364,6 +365,7 @@ class Uname:
 DEFAULT_SECTIONS_TO_SHOW = {
    '.linux':   'binary',
    '.initrd':  'binary',
+    '.fmw':     'binary',
    '.ucode':   'binary',
    '.splash':  'binary',
    '.dtb':     'binary',
@ -1213,6 +1215,7 @@ def make_uki(opts: UkifyConfig) -> None:
        ('.splash',  opts.splash,     True),
        ('.pcrpkey', pcrpkey,         True),
        ('.initrd',  initrd,          True),
+        ('.fmw',     opts.firmware,   True),
        ('.ucode',   opts.microcode,  True),
    ]  # fmt: skip

@ -1269,6 +1272,7 @@ def make_uki(opts: UkifyConfig) -> None:
        '.osrel',
        '.cmdline',
        '.initrd',
+        '.fmw',
        '.ucode',
        '.splash',
        '.dtb',
@ -1729,6 +1733,12 @@ CONFIG_ITEMS = [
        config_key='UKI/Initrd',
        config_push=ConfigItem.config_list_prepend,
    ),
+    ConfigItem(
+        '--firmware',
+        type=Path,
+        help='firmware file [.fmw section]',
+        config_key='UKI/Firmware',
+    ),
    ConfigItem(
        '--microcode',
        metavar='UCODE',
Author	SHA1	Message	Date
Ani Sinha	34a4eff47c	Merge `9f026bfd96` into `9bf6ffe166`	2024-11-22 13:01:34 +01:00
Luca Boccassi	9bf6ffe166	man: split cryptenroll man page into sections (#35297 )	2024-11-22 12:01:07 +00:00
Lennart Poettering	cc6baba720	cryptenroll: it's called PKCS#11, not PKCS11 In the --help text we really should use the official spelling, just like in the man page.	2024-11-22 10:42:37 +01:00
Lennart Poettering	3ae48d071c	man: add enrollment type sections to cryptenroll man page We have the same sections in the --help text, hence we even more so should have them in the man page.	2024-11-22 10:42:37 +01:00
Antonio Alvarez Feijoo	2ccacdd57c	bash-completion: add --list-devices to systemd-cryptenroll And also use it to list suitable block devices.	2024-11-22 10:38:19 +01:00
Ani Sinha	9f026bfd96	measure: introduce support for a .fmw section UKIs container can be used to bundle a firmware image that can be measured and used on a confidential computing environment. Add support to introduce a .fmw section in UKI that can be used for a firmware image. ukify tool has been also changed to support addition of a firmware image in UKI. For example: ukify.py build \ --stub ./build/src/boot/efi/linuxx64.efi.stub \ --linux bzImage \ --cmdline='blah blah debug' \ --firmware ~/OVMF.fd \ --output=root/efi/boot/bootx64.efi Co-authored-by: harald.hoyer@gmail.com	2024-11-12 15:38:46 +05:30