From 84be0c710d9d562f6d2cf986cc2a8ff4c98a138b Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Wed, 30 Nov 2022 18:43:18 +0100 Subject: tree-wide: hook up image dissection policy logic everywhere --- man/org.freedesktop.systemd1.xml | 72 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) (limited to 'man') diff --git a/man/org.freedesktop.systemd1.xml b/man/org.freedesktop.systemd1.xml index 50680e6b37..05c8b3770e 100644 --- a/man/org.freedesktop.systemd1.xml +++ b/man/org.freedesktop.systemd1.xml @@ -3167,6 +3167,12 @@ node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice { @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s IPCNamespacePath = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s RootImagePolicy = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s MountImagePolicy = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s ExtensionImagePolicy = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s KillMode = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i KillSignal = ...; @@ -3724,6 +3730,12 @@ node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice { + + + + + + @@ -4380,6 +4392,12 @@ node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice { + + + + + + @@ -5147,6 +5165,12 @@ node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2esocket { @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s IPCNamespacePath = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s RootImagePolicy = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s MountImagePolicy = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s ExtensionImagePolicy = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s KillMode = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i KillSignal = ...; @@ -5718,6 +5742,12 @@ node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2esocket { + + + + + + @@ -6356,6 +6386,12 @@ node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2esocket { + + + + + + @@ -7002,6 +7038,12 @@ node /org/freedesktop/systemd1/unit/home_2emount { @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s IPCNamespacePath = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s RootImagePolicy = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s MountImagePolicy = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s ExtensionImagePolicy = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s KillMode = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i KillSignal = ...; @@ -7501,6 +7543,12 @@ node /org/freedesktop/systemd1/unit/home_2emount { + + + + + + @@ -8057,6 +8105,12 @@ node /org/freedesktop/systemd1/unit/home_2emount { + + + + + + @@ -8830,6 +8884,12 @@ node /org/freedesktop/systemd1/unit/dev_2dsda3_2eswap { @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s IPCNamespacePath = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s RootImagePolicy = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s MountImagePolicy = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s ExtensionImagePolicy = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s KillMode = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i KillSignal = ...; @@ -9315,6 +9375,12 @@ node /org/freedesktop/systemd1/unit/dev_2dsda3_2eswap { + + + + + + @@ -9857,6 +9923,12 @@ node /org/freedesktop/systemd1/unit/dev_2dsda3_2eswap { + + + + + + -- cgit v1.2.1 From dee4a6237ab5913a6cac3f2afa5ba6ae1f35080a Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Fri, 2 Dec 2022 15:00:44 +0100 Subject: dissect: add new --validate command This allows unprivileged validation of DDIs. Only superficial structure, i.e. not mounting or so. This becomes particularly handy in the integration tests, and to validate image policies. --- man/systemd-dissect.xml | 14 ++++++++++++++ 1 file changed, 14 insertions(+) (limited to 'man') diff --git a/man/systemd-dissect.xml b/man/systemd-dissect.xml index 06c57a22ec..f388cde3c6 100644 --- a/man/systemd-dissect.xml +++ b/man/systemd-dissect.xml @@ -281,6 +281,20 @@ on. + + + + Validates the partition arrangement of a disk image (DDI), and ensures it matches the + image policy specified via , if one is specified. This parses the + partition table and probes the file systems in the image, but does not attempt to mount them (nor to + set up disk encryption/authentication via LUKS/Verity). It does this taking the configured image + dissection policy into account. Since this operation does not mount file systems, this command – + unlike all other commands implemented by this tool – requires no privileges other than the ability to + access the specified file. Prints "OK" and returns zero if the image appears to be in order and + matches the specified image dissection policy. Otherwise prints an error message and returns + non-zero. + + -- cgit v1.2.1 From 9ea811914fce034c2fe9d5f7d5712d49462ac6a4 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Thu, 1 Dec 2022 22:41:47 +0100 Subject: man: document image policy syntax and semantics, and the hooks in the various components --- man/bootctl.xml | 2 + man/coredumpctl.xml | 2 + man/journalctl.xml | 2 + man/kernel-command-line.xml | 14 ++- man/rules/meson.build | 1 + man/standard-options.xml | 11 +++ man/systemctl.xml | 2 + man/systemd-analyze.xml | 41 ++++++++ man/systemd-dissect.xml | 1 + man/systemd-gpt-auto-generator.xml | 10 ++ man/systemd-machine-id-setup.xml | 2 + man/systemd-nspawn.xml | 11 +++ man/systemd-repart.xml | 2 + man/systemd-sysext.xml | 23 ++++- man/systemd-sysupdate.xml | 2 + man/systemd-sysusers.xml | 2 + man/systemd-tmpfiles.xml | 2 + man/systemd.exec.xml | 24 +++++ man/systemd.image-policy.xml | 191 +++++++++++++++++++++++++++++++++++++ 19 files changed, 341 insertions(+), 4 deletions(-) create mode 100644 man/systemd.image-policy.xml (limited to 'man') diff --git a/man/bootctl.xml b/man/bootctl.xml index a6f1fc1c4c..5f98486343 100644 --- a/man/bootctl.xml +++ b/man/bootctl.xml @@ -305,6 +305,8 @@ switch of the same name. + + When installing binaries with or diff --git a/man/coredumpctl.xml b/man/coredumpctl.xml index 79632eb2d4..0f4a2e83e6 100644 --- a/man/coredumpctl.xml +++ b/man/coredumpctl.xml @@ -268,6 +268,8 @@ switch of the same name. + + diff --git a/man/journalctl.xml b/man/journalctl.xml index ae86c50d62..aa124dd98f 100644 --- a/man/journalctl.xml +++ b/man/journalctl.xml @@ -182,6 +182,8 @@ switch of the same name. + + diff --git a/man/kernel-command-line.xml b/man/kernel-command-line.xml index 6f026318d8..27ef72da36 100644 --- a/man/kernel-command-line.xml +++ b/man/kernel-command-line.xml @@ -396,12 +396,22 @@ rd.systemd.gpt_auto= - Configures whether GPT based partition auto-discovery - shall be attempted. For details, see + Configures whether GPT-based partition auto-discovery shall be attempted. For details, see systemd-gpt-auto-generator8. + + systemd.image_policy= + rd.systemd.image_policy= + + When GPT-based partition auto-discovery is used, configures the image dissection + policy string to apply, as per + systemd.image-policy7. For + details see + systemd-gpt-auto-generator8. + + systemd.default_timeout_start_sec= diff --git a/man/rules/meson.build b/man/rules/meson.build index 63a68c3211..42c546f18d 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -1104,6 +1104,7 @@ manpages = [ ['systemd.environment-generator', '7', [], 'ENABLE_ENVIRONMENT_D'], ['systemd.exec', '5', [], ''], ['systemd.generator', '7', [], ''], + ['systemd.image-policy', '7', [], ''], ['systemd.journal-fields', '7', [], ''], ['systemd.kill', '5', [], ''], ['systemd.link', '5', [], ''], diff --git a/man/standard-options.xml b/man/standard-options.xml index d42f3296ca..71c84958ab 100644 --- a/man/standard-options.xml +++ b/man/standard-options.xml @@ -86,4 +86,15 @@ numerical signal numbers and the program will exit immediately. + + + + + Takes an image policy string as argument, as per + systemd.image-policy7. The + policy is enforced when operating on the disk image specified via , see + above. If not specified defaults to the * policy, i.e. all recognized file systems + in the image are used. + + diff --git a/man/systemctl.xml b/man/systemctl.xml index f930034cb1..1a881d1049 100644 --- a/man/systemctl.xml +++ b/man/systemctl.xml @@ -2276,6 +2276,8 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err switch of the same name. + + diff --git a/man/systemd-analyze.xml b/man/systemd-analyze.xml index 9fd28e6f45..7176e3c046 100644 --- a/man/systemd-analyze.xml +++ b/man/systemd-analyze.xml @@ -162,6 +162,12 @@ fdstore UNIT + + systemd-analyze + OPTIONS + image-policy + POLICY + @@ -840,6 +846,39 @@ stored sock 0:8 4213190 - socket:[4213190] ro "DEVNO". + + <command>systemd-analyze image-policy <optional><replaceable>POLICY</replaceable>…</optional></command> + + This command analyzes the specified image policy string, as per + systemd.image-policy7. The + policy is normalized and simplified. For each currently defined partition identifier (as per the Discoverable + Partitions Specification the effect of the image policy string is shown in tabular form. + + + Example Output + + $ systemd-analyze image-policy swap=encrypted:usr=read-only-on+verity:root=encrypted +Analyzing policy: root=encrypted:usr=verity+read-only-on:swap=encrypted + Long form: root=encrypted:usr=verity+read-only-on:swap=encrypted:=unused+absent + +PARTITION MODE READ-ONLY GROWFS +root encrypted - - +usr verity yes - +home ignore - - +srv ignore - - +esp ignore - - +xbootldr ignore - - +swap encrypted - - +root-verity ignore - - +usr-verity unprotected yes - +root-verity-sig ignore - - +usr-verity-sig ignore - - +tmp ignore - - +var ignore - - +default ignore - - + + @@ -967,6 +1006,8 @@ stored sock 0:8 4213190 - socket:[4213190] ro operate on files inside the specified image path PATH. + + diff --git a/man/systemd-dissect.xml b/man/systemd-dissect.xml index f388cde3c6..2a83477357 100644 --- a/man/systemd-dissect.xml +++ b/man/systemd-dissect.xml @@ -419,6 +419,7 @@ cfdisk /dev/loop/by-ref/quux. + diff --git a/man/systemd-gpt-auto-generator.xml b/man/systemd-gpt-auto-generator.xml index bd542cb7f7..1730039b62 100644 --- a/man/systemd-gpt-auto-generator.xml +++ b/man/systemd-gpt-auto-generator.xml @@ -249,6 +249,16 @@ + + systemd.image_policy= + rd.systemd.image_policy= + + Takes an image dissection policy string as argument (as per + systemd.image-policy7), + and allows enforcing a policy on dissection and use of the automatically discovered GPT partition + table entries. + + root= rootfstype= diff --git a/man/systemd-machine-id-setup.xml b/man/systemd-machine-id-setup.xml index f1695b6ddb..c07a853418 100644 --- a/man/systemd-machine-id-setup.xml +++ b/man/systemd-machine-id-setup.xml @@ -95,6 +95,8 @@ tree. + + Commit a transient machine ID to disk. This diff --git a/man/systemd-nspawn.xml b/man/systemd-nspawn.xml index e2c751692f..39a6febb3c 100644 --- a/man/systemd-nspawn.xml +++ b/man/systemd-nspawn.xml @@ -310,6 +310,17 @@ together with , . + + + + Takes an image policy string as argument, as per + systemd.image-policy7. The + policy is enforced when operating on the disk image specified via , see + above. If not specified defaults to + root=verity+signed+encrypted+unprotected+absent:usr=verity+signed+encrypted+unprotected+absent:home=encrypted+unprotected+absent:srv=encrypted+unprotected+absent:esp=unprotected+absent:xbootldr=unprotected+absent:tmp=encrypted+unprotected+absent:var=encrypted+unprotected+absent, + i.e. all recognized file systems in the image are used, but not the swap partition. + + diff --git a/man/systemd-repart.xml b/man/systemd-repart.xml index 9033ef76d6..98ca1c431a 100644 --- a/man/systemd-repart.xml +++ b/man/systemd-repart.xml @@ -269,6 +269,8 @@ , see above. + + diff --git a/man/systemd-sysext.xml b/man/systemd-sysext.xml index 96e40ddf95..2b7a87f510 100644 --- a/man/systemd-sysext.xml +++ b/man/systemd-sysext.xml @@ -89,7 +89,12 @@ carrying large binary images, however are still useful for carrying symlinks to them. The primary place for installing system extensions is /var/lib/extensions/. Any directories found in these search directories are considered directory based extension images; any files with the - .raw suffix are considered disk image based extension images. + .raw suffix are considered disk image based extension images. When invoked in the + initrd, the additional directory /.extra/sysext/ is included in the directories that + are searched for extension images. Note however, that by default a tighter image policy applies to images + found there, though, see below. This directory is populated by + systemd-stub7 with + extension images found in the system's EFI System Partition. During boot OS extension images are activated automatically, if the systemd-sysext.service is enabled. Note that this service runs only after the @@ -230,6 +235,19 @@ not. + + + + Takes an image policy string as argument, as per + systemd.image-policy7. The + policy is enforced when operating on system extension disk images. If not specified defaults to + root=verity+signed+encrypted+unprotected+absent:usr=verity+signed+encrypted+unprotected+absent, + i.e. only the root and /usr/ file systems in the image are used. When run in the + initrd and operating on a system extension image stored in the /.extra/sysext/ + directory a slightly stricter policy is used by default: + root=signed+absent:usr=signed+absent, see above for details. + + @@ -246,7 +264,8 @@ See Also systemd1, - systemd-nspawn1 + systemd-nspawn1, + systemd-stub7 diff --git a/man/systemd-sysupdate.xml b/man/systemd-sysupdate.xml index 77c1635b9d..409281c19f 100644 --- a/man/systemd-sysupdate.xml +++ b/man/systemd-sysupdate.xml @@ -229,6 +229,8 @@ inside the specified disk image. + + diff --git a/man/systemd-sysusers.xml b/man/systemd-sysusers.xml index aba275024f..f7ee5e79d9 100644 --- a/man/systemd-sysusers.xml +++ b/man/systemd-sysusers.xml @@ -80,6 +80,8 @@ switch of the same name. + + When this option is given, one or more positional arguments diff --git a/man/systemd-tmpfiles.xml b/man/systemd-tmpfiles.xml index 49eda985b4..5612b4803d 100644 --- a/man/systemd-tmpfiles.xml +++ b/man/systemd-tmpfiles.xml @@ -202,6 +202,8 @@ Implies . + + When this option is given, one or more positional arguments diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml index 17be33c56a..1d99c58601 100644 --- a/man/systemd.exec.xml +++ b/man/systemd.exec.xml @@ -260,6 +260,30 @@ + + RootImagePolicy= + MountImagePolicy= + ExtensionImagePolicy= + + Takes an image policy string as per + systemd.image-policy7 + to use when mounting the disk images (DDI) specified in RootImage=, + MountImage=, ExtensionImage=, respectively. If not specified + the following policy string is the default for RootImagePolicy= and MountImagePolicy: + + root=verity+signed+encrypted+unprotected+absent: \ + usr=verity+signed+encrypted+unprotected+absent: \ + home=encrypted+unprotected+absent: \ + srv=encrypted+unprotected+absent: \ + tmp=encrypted+unprotected+absent: \ + var=encrypted+unprotected+absent + + The default policy for ExtensionImagePolicy= is: + + root=verity+signed+encrypted+unprotected+absent: \ + usr=verity+signed+encrypted+unprotected+absent + + MountAPIVFS= diff --git a/man/systemd.image-policy.xml b/man/systemd.image-policy.xml new file mode 100644 index 0000000000..4f7b0986b6 --- /dev/null +++ b/man/systemd.image-policy.xml @@ -0,0 +1,191 @@ + + + + + + + + systemd.image-policy + systemd + + + + systemd.image-policy + 7 + + + + systemd.image-policy + Disk Image Dissection Policy + + + + Description + + In systemd, whenever a disk image (DDI) implementing the Discoverable + Partitions Specification is activated, a policy may be specified controlling which partitions to + mount and what kind of cryptographic protection to require. Such a disk image dissection policy is a + string that contains per-partition-type rules, separated by colons (:). The individual + rules consist of a partition identifier, an equal sign (=), and one or more flags + which may be set per partition. If multiple flags are specified per partition they are separated by a + plus sign (+). + + The partition identifiers currently defined are: , , + , , , , + , , , + , , , + . These identifiers match the relevant partition types in the Discoverable Partitions + Specification, but are agnostic to CPU architectures. If the partition identifier is left empty it + defines the default policy for partitions defined in the Discoverable Parition + Specification for which no policy flags are explicitly listed in the policy string. + + The following partition policy flags are defined that dictate the existence/absence, the use, and + the protection level of partitions: + + + for partitions that shall exist and be used, but shall + come without cryptographic protection, lacking both Verity authentication and LUKS + encryption. + + for partitions that shall exist and be used, with Verity + authentication. (Note: if a DDI image carries a data partition, along with a Verity partition and a + signature partition for it, and only the flag is set – and + is not –, then the image will be set up with Verity, but the signature data will + not be used. Or in other words: any DDI with a set of partitions that qualify for + also implicitly qualifies for , and in fact + ). + + for partitions that shall exist and be used, with Verity + authentication, which are also accompanied by a PKCS#7 signature of the Verity root + hash. + + for partitions which shall exist and be used and are + encrypted with LUKS. + + for partitions that shall exist but shall not be + used. + + for partitions that shall not exist on the + image. + + + By setting a combination of the flags above, alternatives can be declared. For example the + combination unused+absent means: the partition may exist (in which case it shall not + be used) or may be absent. The combination of + unprotected+verity+signed+encrypted+unused+absent may be specified via the special + shortcut open, and indicates that the partition may exist or may be absent, but if it + exists is used, regardless of the protection level. + + As special rule: if none of the flags above are set for a listed partition identifier, the default + policy of is implied, i.e. setting none of these flags listed above means + effectively all flags listed above will be set. + + The following partition policy flags are defined that dictate the state of specific GPT partition + flags: + + + , to require that the + partitions have the read-only partition flag off or on. + + , to require that the + partitions have the growfs partition flag off or on. + + + If both and are set for a partition, + then the state of the read-only flag on the partition is not dictated by the policy. Setting neither flag + is equivalent to setting both, i.e. setting neither of these two flags means effectively both will be + set. A similar logic applies to /. + + If partitions are not listed within an image policy string, the default policy flags are applied + (configurable via an empty partition identifier, see above). If no default policy flags are configured in + the policy string, it is implied to be absent+unused, except for the Verity partition + and their signature partitions where the policy is automatically derived from minimal protection level of + the data partition they protect, as encoded in the policy. + + + + Special Policies + + The special image policy string * is short for "use everything", i.e. is + equivalent to: + + =verity+signed+encrypted+unprotected+unused+absent + + The special image policy string - is short for "use nothing", i.e. is equivalent + to: + + =unused+absent + + The special image policy string ~ is short for "everything must be absent", + i.e. is equivalent to: + + =absent + + + + + Use + + Most systemd components that support operating with disk images support a + command line option to specify the image policy to use, and default to + relatively open policies by default (typically the * policy, as described above), + under the assumption that trust in disk images is established before the images are passed to the program + in question. + + For the host image itself + systemd-gpt-auto-generator8 + is responsible for processing the GPT partition table and making use of the included discoverable + partitions. It accepts an image policy via the kernel command line option + . + + Note that image policies do not dictate how the components will mount and use disk images — they + only dictate which parts to avoid and which protection level and arrangement to require while + mounting/using them. For example, + systemd-sysext8 only + cares for the /usr/ and /opt/ trees inside a disk image, and + thus ignores any /home/ partitions (and similar) in all cases, which might be + included in the image, regardless whether the configured image policy would allow access to it or + not. Similar, + systemd-nspawn1 is not + going to make use of any discovered swap device, regardless if the policy would allow that or not. + + Use the image-policy command of the + systemd-analyze8 tool + to analyze image policy strings, and determine what a specific policy string means for a specific + partition. + + + + Examples + + The following image policy string dictates one read-only Verity-enabled /usr/ + partition must exist, plus encrypted root and swap partitions. All other partitions are ignored: + + usr=verity+read-only-on:root=encrypted:swap=encrypted + + The following image policy string dictates an encrypted, writable root file system, and optional + /srv/ file system that must be encrypted if it exists and no swap partition may + exist: + + root=encrypted+read-only-off:srv=encrypted+absent:swap=absent + + The following image policy string dictates a single root partition that may be encrypted, but + doesn't have to be, and ignores swap partitions, and uses all other partitions if they are available, possibly with encryption. + + root=unprotected+encrypted:swap=absent+unused:=unprotected+encrypted+absent + + + + See Also + + systemd1, + systemd-dissect1, + systemd-gpt-auto-generator8, + systemd-sysext8, + systemd-analyze8 + + + + -- cgit v1.2.1