Debian Codegraph @

upstream/debian-unstable/man8/pam_keyinit.8

raw
1 '\" t
2 .\" Title: pam_keyinit
3 .\" Author: [see the "AUTHOR" section]
4 .\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
5 .\" Date: 06/29/2025
6 .\" Manual: Linux-PAM Manual
7 .\" Source: Linux-PAM
8 .\" Language: English
9 .\"
10 .TH "PAM_KEYINIT" "8" "06/29/2025" "Linux\-PAM" "Linux\-PAM Manual"
11 .\" -----------------------------------------------------------------
12 .\" * Define some portability stuff
13 .\" -----------------------------------------------------------------
14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
15 .\" http://bugs.debian.org/507673
16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18 .ie \n(.g .ds Aq \(aq
19 .el .ds Aq '
20 .\" -----------------------------------------------------------------
21 .\" * set default formatting
22 .\" -----------------------------------------------------------------
23 .\" disable hyphenation
24 .nh
25 .\" disable justification (adjust text to left margin only)
26 .ad l
27 .\" -----------------------------------------------------------------
28 .\" * MAIN CONTENT STARTS HERE *
29 .\" -----------------------------------------------------------------
30 .SH "NAME"
31 pam_keyinit \- Kernel session keyring initialiser module
32 .SH "SYNOPSIS"
33 .HP \w'\fBpam_keyinit\&.so\fR\ 'u
34 \fBpam_keyinit\&.so\fR [debug] [force] [revoke]
35 .SH "DESCRIPTION"
36 .PP
37 The pam_keyinit PAM module ensures that the invoking process has a session keyring other than the user default session keyring\&.
38 .PP
39 The module checks to see if the process\*(Aqs session keyring is the
40 \fBuser-session-keyring\fR(7), and, if it is, creates a new
41 \fBsession-keyring\fR(7)
42 with which to replace it\&. If a new session keyring is created, it will install a link to the
43 \fBuser-keyring\fR(7)
44 in the session keyring so that keys common to the user will be automatically accessible through it\&. The session keyring of the invoking process will thenceforth be inherited by all its children unless they override it\&.
45 .PP
46 In order to allow other PAM modules to attach tokens to the keyring, this module provides both an
47 \fIauth\fR
48 (limited to
49 \fBpam_setcred\fR(3)
50 and a
51 \fIsession\fR
52 component\&. The session keyring is created in the module called\&. Moreover this module should be included as early as possible in a PAM configuration\&.
53 .PP
54 This module is intended primarily for use by login processes\&. Be aware that after the session keyring has been replaced, the old session keyring and the keys it contains will no longer be accessible\&.
55 .PP
56 This module should not, generally, be invoked by programs like
57 \fBsu\fR, since it is usually desirable for the key set to percolate through to the alternate context\&. The keys have their own permissions system to manage this\&.
58 .PP
59 The keyutils package is used to manipulate keys more directly\&. This can be obtained from:
60 .PP
61 \m[blue]\fBKeyutils\fR\m[]\&\s-2\u[1]\d\s+2
62 .SH "OPTIONS"
63 .PP
64 debug
65 .RS 4
66 Log debug information with
67 \fBsyslog\fR(3)\&.
68 .RE
69 .PP
70 force
71 .RS 4
72 Causes the session keyring of the invoking process to be replaced unconditionally\&.
73 .RE
74 .PP
75 revoke
76 .RS 4
77 Causes the session keyring of the invoking process to be revoked when the invoking process exits if the session keyring was created for this process in the first place\&.
78 .RE
79 .SH "MODULE TYPES PROVIDED"
80 .PP
81 Only the
82 \fBsession\fR
83 module type is provided\&.
84 .SH "RETURN VALUES"
85 .PP
86 PAM_SUCCESS
87 .RS 4
88 This module will usually return this value
89 .RE
90 .PP
91 PAM_AUTH_ERR
92 .RS 4
93 Authentication failure\&.
94 .RE
95 .PP
96 PAM_BUF_ERR
97 .RS 4
98 Memory buffer error\&.
99 .RE
100 .PP
101 PAM_IGNORE
102 .RS 4
103 The return value should be ignored by PAM dispatch\&.
104 .RE
105 .PP
106 PAM_SERVICE_ERR
107 .RS 4
108 Cannot determine the user name\&.
109 .RE
110 .PP
111 PAM_SESSION_ERR
112 .RS 4
113 This module will return this value if its arguments are invalid or if a system error such as ENOMEM occurs\&.
114 .RE
115 .PP
116 PAM_USER_UNKNOWN
117 .RS 4
118 User not known\&.
119 .RE
120 .SH "EXAMPLES"
121 .PP
122 Add this line to your login entries to start each login session with its own session keyring:
123 .sp
124 .if n \{\
125 .RS 4
126 .\}
127 .nf
128 session required pam_keyinit\&.so
129
130 .fi
131 .if n \{\
132 .RE
133 .\}
134 .PP
135 This will prevent keys from one session leaking into another session for the same user\&.
136 .SH "SEE ALSO"
137 .PP
138 \fBpam.conf\fR(5),
139 \fBpam.d\fR(5),
140 \fBpam\fR(7),
141 \fBkeyctl\fR(1)
142 .SH "AUTHOR"
143 .PP
144 pam_keyinit was written by David Howells, <dhowells@redhat\&.com>\&.
145 .SH "NOTES"
146 .IP " 1." 4
147 Keyutils
148 .RS 4
149 \%http://people.redhat.com/~dhowells/keyutils/
150 .RE