Debian Codegraph @

upstream/debian-unstable/man8/pam_systemd_loadkey.8

raw
1 '\" t
2 .TH "PAM_SYSTEMD_LOADKEY" "8" "" "systemd 261~rc3" "pam_systemd_loadkey"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 pam_systemd_loadkey \- Read password from kernel keyring and set it as PAM authtok
24 .SH "SYNOPSIS"
25 .PP
26 pam_systemd_loadkey\&.so
27 .SH "DESCRIPTION"
28 .PP
29 \fBpam_systemd_loadkey\fR
30 reads a NUL\-separated password list from the kernel keyring, and sets the last password in the list as the PAM authtok, which can be used by e\&.g\&.
31 \fBpam_get_authtok\fR(3)\&.
32 .PP
33 The password list is supposed to be stored in the "user" keyring of the root user, by an earlier call to
34 \fBsystemd-ask-password\fR(1)
35 with
36 \fB\-\-keyname=\fR\&. You can pass the keyname to
37 \fBpam_systemd_loadkey\fR
38 via the
39 \fBkeyname=\fR
40 option\&.
41 .SH "OPTIONS"
42 .PP
43 The following options are understood:
44 .PP
45 \fIkeyname=\fR
46 .RS 4
47 Takes a string argument which sets the keyname to read\&. The default is
48 "cryptsetup"\&. During boot,
49 \[email protected]\fR(8)
50 stores a passphrase or PIN in the keyring\&. The LUKS2 volume key can also be used, via the
51 \fBlink\-volume\-key\fR
52 option in
53 \fBcrypttab\fR(5)\&.
54 .sp
55 .it 1 an-trap
56 .nr an-no-space-flag 1
57 .nr an-break-flag 1
58 .br
59 .B Table\ \&1.\ \& Possible values for \fIkeyname\fR\&.
60 .TS
61 allbox tab(:);
62 lB lB.
63 T{
64 Value
65 T}:T{
66 Description
67 T}
68 .T&
69 l l
70 l l
71 l l
72 l l.
73 T{
74 cryptsetup
75 T}:T{
76 Passphrase or recovery key
77 T}
78 T{
79 fido2\-pin
80 T}:T{
81 Security token PIN
82 T}
83 T{
84 luks2\-pin
85 T}:T{
86 LUKS2 token PIN
87 T}
88 T{
89 tpm2\-pin
90 T}:T{
91 TPM2 PIN
92 T}
93 .TE
94 .sp 1
95 Added in version 255\&.
96 .RE
97 .PP
98 \fIdebug\fR
99 .RS 4
100 The module will log debugging information as it operates\&.
101 .sp
102 Added in version 255\&.
103 .RE
104 .SH "EXAMPLE"
105 .PP
106 This module is intended to be used when you use LUKS with a passphrase, enable autologin in the display manager, and want to unlock Gnome Keyring / KDE KWallet automatically\&. So in total, you only enter one password during boot\&.
107 .PP
108 You need to set the password of your Gnome Keyring/KWallet to the same as your LUKS passphrase\&. Then add the following lines to your display manager\*(Aqs PAM config under
109 /etc/pam\&.d/
110 (e\&.g\&.
111 sddm\-autologin):
112 .sp
113 .if n \{\
114 .RS 4
115 .\}
116 .nf
117 \-auth optional pam_systemd_loadkey\&.so
118 \-auth optional pam_gnome_keyring\&.so
119 \-session optional pam_gnome_keyring\&.so auto_start
120 \-session optional pam_kwallet5\&.so auto_start
121 .fi
122 .if n \{\
123 .RE
124 .\}
125 .PP
126 And add the following lines to your display manager\*(Aqs systemd service file, so it can access root\*(Aqs keyring:
127 .sp
128 .if n \{\
129 .RS 4
130 .\}
131 .nf
132 [Service]
133 KeyringMode=inherit
134 .fi
135 .if n \{\
136 .RE
137 .\}
138 .PP
139 In this setup, early during the boot process,
140 \[email protected]\fR(8)
141 will ask for the passphrase and store it in the kernel keyring with the keyname
142 "cryptsetup"\&. Then when the display manager does the autologin,
143 \fBpam_systemd_loadkey\fR
144 will read the passphrase from the kernel keyring, set it as the PAM authtok, and then
145 \fBpam_gnome_keyring\fR
146 and
147 \fBpam_kwallet5\fR
148 will unlock with the same passphrase\&.