diff --git a/man/systemd-homed.service.xml b/man/systemd-homed.service.xml
index e4c520ff2f..a51bd36d41 100644
--- a/man/systemd-homed.service.xml
+++ b/man/systemd-homed.service.xml
@@ -47,6 +47,55 @@
userdbctl1.
+
+ Key Management
+
+ User records are cryptographically signed with a public/private key pair (the signature is part of
+ the JSON record itself). For a user to be permitted to log in locally the public key matching the
+ signature of their user record must be installed. For a user record to be modified locally the private
+ key matching the signature must be installed locally, too. The keys are stored in the
+ /var/lib/systemd/home/ directory:
+
+
+
+
+ /var/lib/systemd/home/local.private
+
+ The private key of the public/private key pair used for local records. Currently,
+ only a single such key may be installed.
+
+
+
+ /var/lib/systemd/home/local.public
+
+ The public key of the public/private key pair used for local records. Currently,
+ only a single such key may be installed.
+
+
+
+ /var/lib/systemd/home/*.public
+
+ Additional public keys. Any users whose user records are signed with any of these keys
+ are permitted to log in locally. An arbitrary number of keys may be installed this
+ way.
+
+
+
+ All key files listed above are in PEM format.
+
+ In order to migrate a home directory from a host foobar to another host
+ quux it is hence sufficient to copy
+ /var/lib/systemd/home/local.public from the host foobar to
+ quux, maybe calling the file on the destination
+ /var/lib/systemd/home/foobar.public, reflecting the origin of the key. If the user
+ record should be modifiable on quux the pair
+ /var/lib/systemd/home/local.public and
+ /var/lib/systemd/home/local.private need to be copied from foobar
+ to quux, and placed under the identical paths there, as currently only a single
+ private key is supported per host. Note of course that the latter means that user records
+ generated/signed before the key pair is copied in, lose their validity.
+
+
See Also