HALF ECHO LEARN / REFERENCE COLLECTION
v262.2docs/USER_RECORD.md
Git blob: a0e4f4d55da48ab7f404343c63a7e8c702099671
Lines 1001–1227 of 1,227
Before signing the user record should be brought into "normalized" form,
i.e. the keys in all objects should be sorted alphabetically.
All redundant white-space and newlines should be removed and the JSON text then signed.
The signatures only cover the `regular`, `perMachine` and `privileged` sections
of the user records, all other sections (include `signature` itself), are
removed before the signature is calculated.
Rationale for signing and threat model: while a multi-user operating system
like Linux strives for being sufficiently secure even after a user acquired a
local login session reality tells us this is not the case.
Hence it is essential to restrict carefully which users may gain access to a system and which ones shall not.
A minimal level of trust must be established between system,
user record and the user themselves before a log-in request may be permitted.
In particular if the home directory is provided in its own LUKS2 encapsulated file system
it is essential this trust is established before the user logs in (and hence the file system mounted),
since file system implementations on Linux are well known to be relatively vulnerable to rogue disk images.
User records and home directories in many context are expected to be something shareable between multiple systems,
and the transfer between them might not happen via exclusively trusted channels.
Hence it's essential that the user record is not manipulated between uses.
Finally, resource management (which may be done by the various fields of the user record) is security
sensitive, since it should forcefully lock the user into the assigned resource usage and not allow them to use more.
The requirement of being able to trust the user record data combined with the potential transfer over untrusted
channels suggest a cryptographic signature mechanism where only user records
signed by a recognized key are permitted to log in locally.
Note that other mechanisms for establishing sufficient trust exist too, and are perfectly valid as well.
For example, systems like LDAP/ActiveDirectory generally insist on user record transfer from trusted servers via encrypted TLS channels only.
Or traditional UNIX users created locally in `/etc/passwd` never exist outside of the local trusted system,
hence transfer and trust in the source are not an issue.
The major benefit of operating with signed user records is that they are self-sufficiently trusted,
not relying on a secure channel for transfer, and thus being compatible with a more distributed model
of home directory transfer, including on USB sticks and such.
## Fields in the `secret` section
As mentioned, the `secret` section of the user record should never be persisted
nor transferred across machines.
It is only defined in short-lived operations, for example when a user record is first created or registered, as the secret
key data needs to be available to derive encryption keys from and similar.
The `secret` field of the top-level user record contains the following fields:
`password` → an array of strings, each containing a plain text password.
`tokenPin` → an array of strings, each containing a plain text PIN, suitable
for unlocking security tokens that require that.
(The field `pkcs11Pin` should be considered a compatibility alias for this field, and merged with `tokenPin`
in case both are set.)
`pkcs11ProtectedAuthenticationPathPermitted` → a boolean.
If set to true allows the receiver to use the PKCS#11 "protected authentication path" (i.e. a
physical button/touch element on the security token) for authenticating the user.
If false or unset, authentication this way shall not be attempted.
`fido2UserPresencePermitted` → a boolean.
If set to true allows the receiver to use the FIDO2 "user presence" flag.
This is similar to the concept of `pkcs11ProtectedAuthenticationPathPermitted`,
but exposes the FIDO2 "up" concept behind it.
If false or unset authentication this way shall not be attempted.
`fido2UserVerificationPermitted` → a boolean. If set to true allows the
receiver to use the FIDO2 "user verification" flag.
This is similar to the concept of `pkcs11ProtectedAuthenticationPathPermitted`,
but exposes the FIDO2 "uv" concept behind it.
If false or unset authentication this way shall not be attempted.
## Mapping to `struct passwd` and `struct spwd`
When mapping classic UNIX user records (i.e. `struct passwd` and `struct spwd`)
to JSON user records the following mappings should be applied:
| Structure | Field | Section | Field | Condition |
|-----------------|-------------|--------------|------------------------------|----------------------------|
| `struct passwd` | `pw_name` | `regular` | `userName` | |
| `struct passwd` | `pw_passwd` | `privileged` | `password` | (See notes below) |
| `struct passwd` | `pw_uid` | `regular` | `uid` | |
| `struct passwd` | `pw_gid` | `regular` | `gid` | |
| `struct passwd` | `pw_gecos` | `regular` | `realName` | |
| `struct passwd` | `pw_dir` | `regular` | `homeDirectory` | |
| `struct passwd` | `pw_shell` | `regular` | `shell` | |
| `struct spwd` | `sp_namp` | `regular` | `userName` | |
| `struct spwd` | `sp_pwdp` | `privileged` | `password` | (See notes below) |
| `struct spwd` | `sp_lstchg` | `regular` | `lastPasswordChangeUSec` | (if `sp_lstchg` > 0) |
| `struct spwd` | `sp_lstchg` | `regular` | `passwordChangeNow` | (if `sp_lstchg` == 0) |
| `struct spwd` | `sp_min` | `regular` | `passwordChangeMinUSec` | |
| `struct spwd` | `sp_max` | `regular` | `passwordChangeMaxUSec` | |
| `struct spwd` | `sp_warn` | `regular` | `passwordChangeWarnUSec` | |
| `struct spwd` | `sp_inact` | `regular` | `passwordChangeInactiveUSec` | |
| `struct spwd` | `sp_expire` | `regular` | `locked` | (if `sp_expire` in [0, 1]) |
| `struct spwd` | `sp_expire` | `regular` | `notAfterUSec` | (if `sp_expire` > 1) |
At this time almost all Linux machines employ shadow passwords, thus the
`pw_passwd` field in `struct passwd` is set to `"x"`, and the actual password
is stored in the shadow entry `struct spwd`'s field `sp_pwdp`.
## Extending These Records
User records following this specifications are supposed to be extendable for various applications.
In general, subsystems are free to introduce their own keys, as long as:
* Care should be taken to place the keys in the right section, i.e. the most
appropriate for the data field.
* Care should be taken to avoid namespace clashes.
Please prefix your fields with a short identifier of your project to avoid ambiguities and
incompatibilities.
* This specification is supposed to be a living specification.
If you need additional fields, please consider submitting them upstream for inclusion in this specification.
If they are reasonably universally useful, it would be best to list them here.
## Examples
The shortest valid user record looks like this:
```json
{
"userName" : "u"
}
```
A reasonable user record for a system user might look like this:
```json
{
"userName" : "httpd",
"uid" : 473,
"gid" : 473,
"disposition" : "system",
"locked" : true
}
```
A fully featured user record associated with a home directory managed by
`systemd-homed.service` might look like this:
```json
{
"autoLogin" : true,
"binding" : {
"15e19cf24e004b949ddaac60c74aa165" : {
"fileSystemType" : "ext4",
"fileSystemUuid" : "758e88c8-5851-4a2a-b88f-e7474279c111",
"gid" : 60232,
"homeDirectory" : "/home/grobie",
"blobDirectory" : "/var/cache/systemd/homed/grobie/",
"imagePath" : "/home/grobie.home",
"luksCipher" : "aes",
"luksCipherMode" : "xts-plain64",
"luksUuid" : "e63581ba-79fb-4226-b9de-1888393f7573",
"luksVolumeKeySize" : 32,
"partitionUuid" : "41f9ce04-c827-4b74-a981-c669f93eb4dc",
"storage" : "luks",
"uid" : 60232
}
},
"blobManifest" : {
"avatar" : "c0636851d25a62d817ff7da4e081d1e646e42c74d0ecb53425f75fcf1ba43b52",
"login-background" : "da7ad0222a6edbc6cd095149c72d38d92fd3114f606e4b57469857ef47fade18"
},
"disposition" : "regular",
"enforcePasswordPolicy" : false,
"lastChangeUSec" : 1565950024279735,
"memberOf" : [
"wheel"
],
"privileged" : {
"hashedPassword" : [
"$6$WHBKvAFFT9jKPA4k$OPY4D4TczKN/jOnJzy54DDuOOagCcvxxybrwMbe1SVdm.Bbr.zOmBdATp.QrwZmvqyr8/SafbbQu.QZ2rRvDs/"
]
},
"signature" : [
{
"data" : "LU/HeVrPZSzi3MJ0PVHwD5m/xf51XDYCrSpbDRNBdtF4fDVhrN0t2I2OqH/1yXiBidXlV0ptMuQVq8KVICdEDw==",
"key" : "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA/QT6kQWOAMhDJf56jBmszEQQpJHqDsGDMZOdiptBgRk=\n-----END PUBLIC KEY-----\n"
}
],
"userName" : "grobie",
"status" : {
"15e19cf24e004b949ddaac60c74aa165" : {
"goodAuthenticationCounter" : 16,
"lastGoodAuthenticationUSec" : 1566309343044322,
"rateLimitBeginUSec" : 1566309342340723,
"rateLimitCount" : 1,
"state" : "inactive",
"service" : "io.systemd.Home",
"diskSize" : 161118667776,
"diskCeiling" : 190371729408,
"diskFloor" : 5242880,
"signedLocally" : true
}
}
}
```
When `systemd-homed.service` manages a home directory it will also include a
version of the user record in the home directory itself in the `~/.identity` file.
This version lacks the `binding` and `status` sections which are used for
local management of the user, but are not intended to be portable between
systems. It would hence look like this:
```json
{
"autoLogin" : true,
"disposition" : "regular",
"enforcePasswordPolicy" : false,
"lastChangeUSec" : 1565950024279735,
"memberOf" : [
"wheel"
],
"privileged" : {
"hashedPassword" : [
"$6$WHBKvAFFT9jKPA4k$OPY4D4TczKN/jOnJzy54DDuOOagCcvxxybrwMbe1SVdm.Bbr.zOmBdATp.QrwZmvqyr8/SafbbQu.QZ2rRvDs/"
]
},
"signature" : [
{
"data" : "LU/HeVrPZSzi3MJ0PVHwD5m/xf51XDYCrSpbDRNBdtF4fDVhrN0t2I2OqH/1yXiBidXlV0ptMuQVq8KVICdEDw==",
"key" : "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA/QT6kQWOAMhDJf56jBmszEQQpJHqDsGDMZOdiptBgRk=\n-----END PUBLIC KEY-----\n"
}
],
"userName" : "grobie"
}
```