USER_GROUP_API: typo fixes

.mkosi/mkosi.fedora

@@ -38,10 +38,12 @@ BuildPackages=
         libblkid-devel
         libcap-devel
         libcurl-devel
+        libfdisk-devel
         libgcrypt-devel
         libidn2-devel
         libmicrohttpd-devel
         libmount-devel
+        libpwquality-devel
         libseccomp-devel
         libselinux-devel
         libtool
@@ -51,6 +53,7 @@ BuildPackages=
         lz4-devel
         m4
         meson
+        openssl-devel
         pam-devel
         pcre2-devel
         pkgconfig
@@ -61,6 +64,7 @@ BuildPackages=
         xz-devel
 
 Packages=
+        e2fsprogs
         libidn2
 
 BuildDirectory=mkosi.builddir

CRYPTSETUP

@@ -0,0 +1,63 @@
+# Using a Yubikey for unlocking arbitrary LUKS devices.
+#
+# A few notes on the used parameters:
+#
+# → We use RSA (and not ECC), since Yubikeys support PKCS#11 Decrypt() only for
+#   RSA keys (ECC keys can only be used for signing?)
+# → We use RSA2048, which is the longest key size current Yubikeys support for
+#   RSA
+# → LUKS key size must be << 2048bit due to RSA padding, hence we use 128 bytes
+# → We use Yubikey key slot 9d, since that's apparently the keyslot to use for
+#   decryption purposes, see:
+#   https://developers.yubico.com/PIV/Introduction/Certificate_slots.html
+
+# Make sure noone can read the files we generate, but us
+umask 077
+
+# Clear the Yubikey from any old keys
+ykman piv reset
+
+# Generate a new private/public key pair on th device, store the public key in
+# 'pubkey.pem'.
+ykman piv generate-key -a RSA2048 9d pubkey.pem
+
+# Create a self-signed certificate from this public key, and store it on the
+# device.
+ykman piv generate-certificate --subject "Knobelei" 9d pubkey.pem
+
+# Check if the newly create key on the Yubikey shows up as token in
+# PKCS#11. Have a look at the output, and copy the resulting token URI to the
+# clipboard.
+p11tool --list-tokens
+
+# Generate a (secret) random key to use as LUKS decryption key.
+dd if=/dev/urandom of=plaintext.bin bs=128 count=1
+
+# Encrypt this newly generated LUKS decryption key using the public key whose
+# private key is on the Yubikey, store the result in
+# /etc/encrypted-luks-key.bin, where we'll look for it during boot.
+openssl rsautl -encrypt -pubin -inkey pubkey.pem -in plaintext.bin -out /etc/encrypted-luks-key.bin
+
+# Configure the LUKS decryption key on the LUKS device. We use very low pbkdf
+# settings since the key already has quite a high quality (it comes directly
+# from /dev/urandom after all), and thus we don't need to do much key
+# derivation.
+cryptsetup luksAddKey /dev/sda1 plaintext.bin --pbkdf-memory=32 --pbkdf-parallel=1 --pbkdf-force-iterations=4
+
+# Now securely delete the plain text LUKS key, we don't need it anymore, and
+# since it contains secret key material it should be removed from disk
+# thoroughly.
+shred -u plaintext.bin
+
+# We don't need the public key anymore either, let's remove it too. Since this
+# one is not security sensitive we just do a regular "rm" here.
+rm pubkey.pem
+
+# Test: Let's run systemd-cryptsetup to test if this all worked. The option
+# string should contain the full PKCS#11 URI we have in the clipboard, it tells
+# the tool how to decypher the encrypted LUKS key.
+systemd-cryptsetup attach mytest /dev/sda1 /etc/encrypted-luks-key.bin 'pkcs11-uri=pkcs11:…'
+
+# If that worked, let's now add the same line persistently to /etc/crypttab,
+# for the future.
+echo "mytest /dev/sda1 /etc/encrypted-luks-key 'pkcs11-uri=pkcs11:…' >> /etc/crypttab

TODO

@@ -19,6 +19,14 @@ Janitorial Clean-ups:
 
 Features:
 
+* socket units: allow creating a udev monitor socket with ListenDevices= or so,
+  with matches, then actviate app thorugh that passing socket oveer
+
+* cryptsetup: allow encoding key directly in /etc/crypttab, maybe with a
+  "base64:" prefix. Useful in particular for pkcs11 mode.
+
+* cryptsetup: add logic to wait for pkcs11 token
+
 * coredump: maybe when coredumping read a new xattr from /proc/$PID/exe that
   may be used to mark a whole binary as non-coredumpable. Would fix:
   https://bugs.freedesktop.org/show_bug.cgi?id=69447
@@ -395,15 +403,6 @@ Features:
 
 * maybe introduce gpt auto discovery for /var/tmp?
 
-* maybe add gpt-partition-based user management: each user gets his own
-  LUKS-encrypted GPT partition with a new GPT type. A small nss module
-  enumerates users via udev partition enumeration. UIDs are assigned in a fixed
-  way: the partition index is added as offset to some fixed base uid. User name
-  is stored in GPT partition name. A PAM module authenticates the user via the
-  LUKS partition password. Benefits: strong per-user security, compatibility
-  with stateless/read-only/verity-enabled root. (other idea: do this based on
-  loopback files in /home, without GPT involvement)
-
 * gpt-auto logic: introduce support for discovering /var matching an image. For
   that, use a partition type UUID that is hashed from the OS name (as encoded
   in /etc/os-release), the architecture, and 4 new bits from the gpt flags

TODO-HOME

@@ -0,0 +1,51 @@
+PRIMARILY:
+
+- pkcs11 smart card support: pin certificate in record, then for auth, generate random data, ask smartcard to sign it, then verify signature. For LUKS key store encrypted key in record, decrypt it with smartcard.
+- write fscrypt key into client's keyring
+- don't use argon2 with pkcs#11 cryptsetup mode
+- move the ssh authorized keys stuff from homectl to userdbctl
+- honour passwordChangeNow, and unset it in homectl passwd
+- fix borked yubikey cryptsetup stuff?
+
+Before first release:
+- unit file lockdown (caps, …)
+- extend test case to cover more
+- man pages:
+    cryptsetup pkcs11
+    pam_systemd update
+    nss-systemd update
+- blog story
+- fix userwork and homework paths
+- drop LOG_DEBUG being forced in userdbd and homed
+- drop debug=true being forced in pam_systemd_home
+- performance data
+
+Later:
+- when user tries to log into record signed by unrecognized key, automatically add key to our chain after polkit auth
+- hook up machined/nspawn users with a varlink user query interface
+- rollback when resize fails mid-operation
+- forget key on suspend (requires gnome rework so that lock screen runs outside of uid)
+- resize on login?
+- update LUKS password on login if we find there's a password that unlocks the JSON record but not the LUKS device.
+- always fstrim on logout?
+- compare with accounts daemon
+- create on activate?
+- properties: icon url?, preferred session type?, administrator bool (which translates to 'wheel' membership)?, address?, telephone?, vcard?, samba stuff?, parental controls?
+- communicate clearly when usb stick is safe to remove. probably involves
+  beefing up logind to make pam session close hook synchronous and wait until
+  systemd --user is shut down.
+- logind: maybe keep a "busy fd" as long as there's a non-released session around or the [email protected]
+- fscrypt key mgmt (maybe in xattr?)
+- shrink fs on logout?
+- maybe make automatic, read-only, time-based reflink-copies of LUKS disk images (think: time machine)
+- distuingish destroy / remove (i.e. currently we can unregister a user, unregister+remove their home directory, but not just remove their home directory)
+- in systemd's PAMName= logic: query passwords with ssh-askpassword, so that we can make "loginctl set-linger" mode work
+- fingerprint authentication, pattern authentication, …
+- make sure "classic" user records can also be managed by homed
+- description field for groups
+- make size of $XDG_RUNTIME_DIR configurable in user record
+- reuse pwquality magic in firstboot
+- query password from kernel keyring first
+- update in absence
+- add a "access mode" + "fstype" field to the "status" section of json identity records reflecting the actually used access mode and fstype, even on non-luks backends
+- move acct mgmt stuff from pam_systemd_home to pam_systemd?

docs/GROUP_RECORD.md

@@ -0,0 +1,156 @@
+---
+title: JSON Group Records
+---
+
+# JSON Group Records
+
+Long story short: JSON Group Records are to `struct group` what [JSON User
+Records](https://systemd.io/USER_RECORD.md) are to `struct passwd`.
+
+Conceptually, much of what applies to JSON user records also applies to JSON
+group records. They also consist of seven sections, with similar properties and
+they carry some identical (or at least very similar) fields.
+
+## Fields in the `regular` section
+
+`groupName` → A string with the UNIX group name. Matches the `gr_name` field of
+UNIX/glibc NSS `struct group`, or the shadow structure `struct sgrp`'s
+`sg_namp` field.
+
+`realm` → The "realm" the group belongs to, conceptually identical to the same
+field of user records. A string in DNS domain name syntax.
+
+`disposition` → The disposition of the group, conceptually identical to the
+same field of user records. A string.
+
+`service` → A string, an identifier for the service managing this group record
+(this field is typically in reverse domain name syntax.)
+
+`lastChangeUSec` → An unsigned 64bit integer, a timestamp (in µs since the UNIX
+epoch 1970) of the last time the group record has been modified. (Covers only
+the `regular`, `perMachine` and `privileged` sections).
+
+`gid` → An unsigned integer in the range 0…4294967295: the numeric UNIX group
+ID (GID) to use for the group. This corresponds to the `gr_gid` field of
+`struct group`.
+
+`members` → An array of strings, listing user names that are members of this
+group. Note that JSON user records also contain a `memberOf` field, or in other
+words a group membership can either be denoted in the JSON user record or in
+the JSON record, or in both. The list of memberships should be determined as
+the combination of both lists (plus optionally others). If a user is listed as
+member of a group and doesn't exist it should be ignored. This field
+corresponds to the `gr_mem` field of `struct group` and the `sg_mem` field of
+`struct sgrp`.
+
+`administrators` → Similarly, an array of strings, listing user names that
+shall be considered "administrators" of this group. This field corresponds to
+the `sg_adm` field of `struct sgrp`.
+
+`privileged`/`perMachine`/`binding`/`status`/`signature`/`secret` → The
+objects/arrays for the other six group record sections. These are organized the
+same way as for the JSON user records, and have the same semantics.
+
+## Fields in the `privileged` section
+
+The following fields are defined:
+
+`hashedPassword` → An array of strings with UNIX hashed passwords; see the
+matching field for user records for details. This field corresponds to the
+`sg_passwd` field of `struct sgrp` (and `gr_passwd` of `struct group` in a
+way).
+
+## Fields in the `perMachine` section
+
+`matchMachineId`/`matchHostname` → Strings, match expressions similar as for
+user records, see the user record documentation for details.
+
+The following fields are defined for the `perMachine` section and are defined
+equivalent to the fields of the same name in the `regular` section, and
+override those:
+
+`gid`, `members`, `administrators`
+
+## Fields in the `binding` section
+
+The following fields are defined for the `binding` section, and are equivalent
+to the fields of the same name in the `regular` and `perMachine` sections:
+
+`gid`
+
+## Fields in the `status` section
+
+The following fields are defined in the `status` section, and are mostly
+equivalent to the fields of the same name in the `regular` section, though with
+slightly different conceptual semantics, see the same fields in the user record
+documentation:
+
+`service`
+
+## Fields in the `signature` section
+
+The fields in this section are defined identically to those in the matching
+section in the user record.
+
+## Fields in the `secret` section
+
+Currently no fields are defined in this section for group records.
+
+## Mapping to `struct group` and `struct sgrp`
+
+When mapping classic UNIX group records (i.e. `struct group` and `struct sgrp`)
+to JSON group records the following mappings should be applied:
+
+| Structure      | Field       | Section      | Field            | Condition                  |
+|----------------|-------------|--------------|------------------|----------------------------|
+| `struct group` | `gr_name`   | `regular`    | `groupName`      |                            |
+| `struct group` | `gr_passwd` | `privileged` | `password`       | (See notes below)          |
+| `struct group` | `gr_gid`    | `regular`    | `gid`            |                            |
+| `struct group` | `gr_mem`    | `regular`    | `members`        |                            |
+| `struct sgrp`  | `sg_namp`   | `regular`    | `groupName`      |                            |
+| `struct sgrp`  | `sg_passwd` | `privileged` | `password`       | (See notes below)          |
+| `struct sgrp`  | `sg_adm`    | `regular`    | `administrators` |                            |
+| `struct sgrp`  | `sg_mem`    | `regular`    | `members`        |                            |
+
+At this time almost all Linux machines employ shadow passwords, thus the
+`gr_passwd` field in `struct group` is set to `"x"`, and the actual password
+is stored in the shadow entry `struct sgrp`'s field `sg_passwd`.
+
+## Extending These Records
+
+The same logic and recommendations apply as for JSON user records
+
+## Examples
+
+A reasonable group record for a system group might look like this:
+
+```json
+{
+	"groupName" : "systemd-resolve",
+	"gid" : 193,
+	"status" : {
+		"6b18704270e94aa896b003b4340978f1" : {
+			"service" : "io.systemd.NameServiceSwitch"
+		}
+	}
+}
+```
+
+And here's a more complete one for a regular group:
+
+```json
+{
+	"groupName" : "grobie",
+	"binding" : {
+		"6b18704270e94aa896b003b4340978f1" : {
+			"gid" : 60232
+		}
+	},
+	"disposition" : "regular",
+	"status" : {
+		"6b18704270e94aa896b003b4340978f1" : {
+			"service" : "io.systemd.Home"
+		}
+	}
+}
+```