mirror of https://github.com/mkerrisk/man-pages
keyrings.7, persistent-keyring.7, process-keyring.7, session-keyring.7, thread-keyring.7, user-keyring.7, user-session-keyring.7: ffix + pages xref fixes
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
parent
a44454bc1b
commit
f437df79f2
|
@ -27,7 +27,7 @@ A library and some userspace utilities are provided to allow access to the
|
|||
facility.
|
||||
See
|
||||
.BR keyutils (7)
|
||||
manual page for more information.
|
||||
for more information.
|
||||
.P
|
||||
This document contains the following sections:
|
||||
.P
|
||||
|
@ -94,11 +94,12 @@ memory and the owning user ID specifies whose quota is to be debited.
|
|||
Each key can have an expiration time set.
|
||||
When that time is reached,
|
||||
the key is marked as being expired and accesses to it fail with
|
||||
\fIEKEYEXPIRED\fR.
|
||||
.BR EKEYEXPIRED .
|
||||
If not deleted, updated or replaced, after a set amount of time,
|
||||
expired keys are
|
||||
automatically removed along with all links to them and \fIENOKEY\fR will be
|
||||
reported.
|
||||
automatically removed along with all links to them and
|
||||
.B ENOKEY
|
||||
will be reported.
|
||||
.IP "\fBReference count\fR"
|
||||
Each key has a reference count.
|
||||
Keys are referenced by keyrings, by current active users
|
||||
|
@ -190,17 +191,28 @@ These keyrings are pinned as long as the set of credentials exists - which is
|
|||
usually as long as the process does.
|
||||
.IP
|
||||
There are three keyrings with different inheritance/sharing rules:
|
||||
The \fBsession keyring\fR (inherited and shared by all child processes),
|
||||
the \fBprocess keyring\fR (shared by all threads in a process) and
|
||||
the \fBthread keyring\fR (specific to a particular thread).
|
||||
The
|
||||
.BR session-keyring (7)
|
||||
(inherited and shared by all child processes),
|
||||
the
|
||||
.BR process-keyring (7)
|
||||
(shared by all threads in a process) and
|
||||
the
|
||||
.BR thread-keyring (7)
|
||||
(specific to a particular thread).
|
||||
.IP "\fBUser keyrings\fR"
|
||||
Each UID known to the kernel has a record that contains two keyrings: The
|
||||
\fBuser keyring\fR and the \fBuser session keyring\fR.
|
||||
.BR user-keyring (7)
|
||||
and the
|
||||
.BR user-session-keyring (7).
|
||||
These exist for as long as the UID record in the kernel exists.
|
||||
A link to the user keyring is placed in a new session keyring by
|
||||
\fBpam_keyinit\fR when a new login session is initiated.
|
||||
.BR pam_keyinit (8)
|
||||
when a new login session is initiated.
|
||||
.IP "\fBPersistent keyrings\fR"
|
||||
There is a \fBpersistent keyring\fR available to each UID known to the system.
|
||||
There is a
|
||||
.BR persistent-keyring (7)
|
||||
available to each UID known to the system.
|
||||
It may persist beyond the life of the UID record previously mentioned,
|
||||
but has an expiration time set such that it is automatically cleaned up
|
||||
after a set time.
|
||||
|
@ -256,9 +268,10 @@ to access the user's keys.
|
|||
It also allows the prevention of access to keys
|
||||
just on the basis of UID and GID matches.
|
||||
.P
|
||||
When it creates the session keyring, the \fBpam_keyinit\fR module adds a link
|
||||
to the user keyring, thus making the user keyring and anything it contains
|
||||
possessed by default.
|
||||
When it creates the session keyring,
|
||||
.BR pam_keyinit (8)
|
||||
adds a link to the user keyring,
|
||||
thus making the user keyring and anything it contains possessed by default.
|
||||
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
||||
.SH ACCESS RIGHTS
|
||||
.P
|
||||
|
@ -338,7 +351,9 @@ manual pages for more information.
|
|||
.P
|
||||
One of the key features of this facility is the ability to find a key that it
|
||||
is retaining.
|
||||
The \fBrequest_key\fR() system call is the primary point of
|
||||
The
|
||||
.BR request_key (2)
|
||||
system call is the primary point of
|
||||
access for userspace to find a key to use
|
||||
(the kernel has something similar available).
|
||||
.P
|
||||
|
@ -346,7 +361,10 @@ The search algorithm works as follows:
|
|||
.IP (1)
|
||||
The three process keyrings are searched in the following order: the thread
|
||||
keyring if it exists, the process keyring if it exists and then either the
|
||||
session keyring if it exists or the user session keyring if that exists.
|
||||
.BR session-keyring (7)
|
||||
if it exists or the
|
||||
.BR user-session-keyring (7)
|
||||
if that exists.
|
||||
.IP (2)
|
||||
If the caller was a process that was invoked by the \fBrequest_key\fR() upcall
|
||||
mechanism then the keyrings of the original caller of that \fBrequest_key\fR()
|
||||
|
@ -367,20 +385,24 @@ then the first noted error state is returned or else \fBENOKEY\fR is returned.
|
|||
It is also possible to search a specific keyring, in which case only steps (3)
|
||||
to (6) apply.
|
||||
.P
|
||||
See the
|
||||
See
|
||||
.BR request_key (2)
|
||||
and
|
||||
.BR keyctl_search (3)
|
||||
manual pages for more information.
|
||||
for more information.
|
||||
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
||||
.SH ON-DEMAND KEY CREATION
|
||||
.P
|
||||
If a key cannot be found, the \fBrequest_key\fR() system call will, if given a
|
||||
\fIcallout_info\fR argument, create a new key and then upcall to userspace to
|
||||
If a key cannot be found,
|
||||
.BR request_key (2)
|
||||
will, if given a
|
||||
.I callout_info
|
||||
argument, create a new key and then upcall to userspace to
|
||||
instantiate the key.
|
||||
This allows keys to be created on an as-needed basis.
|
||||
.P
|
||||
Typically, this will involve the kernel forking and exec'ing \fBrequest-key\fR
|
||||
Typically, this will involve the kernel forking and exec'ing
|
||||
.BR request-key (8)
|
||||
program, which will then execute the appopriate handler based on its
|
||||
configuration.
|
||||
.P
|
||||
|
|
|
@ -14,9 +14,7 @@
|
|||
.SH NAME
|
||||
persistent-keyring \- per-user persistent keyring
|
||||
.SH DESCRIPTION
|
||||
The
|
||||
.B persistent keyring
|
||||
is a keyring used to anchor keys on behalf of a user.
|
||||
The persistent keyring is a keyring used to anchor keys on behalf of a user.
|
||||
Each UID the kernel deals with has its own persistent keyring that
|
||||
is shared between all threads owned by that UID.
|
||||
.P
|
||||
|
@ -36,8 +34,12 @@ first before that keyring can access it by virtue of its possessor permits.
|
|||
This is done with \fBkeyctl_get_persistent\fP().
|
||||
.P
|
||||
Persistent keyrings are independent of
|
||||
clone(), fork(), vfork(), execve() and
|
||||
exit().
|
||||
.BR clone (2),
|
||||
.BR fork (2),
|
||||
.BR vfork (2),
|
||||
.BR execve (2),
|
||||
and
|
||||
.BR exit (2).
|
||||
They persist until their expiration timers trigger - at which point
|
||||
they are garbage collected.
|
||||
This allows them to carry keys beyond the life of
|
||||
|
@ -51,7 +53,9 @@ The keyutils library provides a special operation for manipulating persistent
|
|||
keyrings:
|
||||
.IP \fBkeyctl_get_persistent\fP()
|
||||
This operation allows the caller to get the persistent keyring corresponding
|
||||
to their own UID or, if they have \fBCAP_SETUID\fR, the persistent keyring
|
||||
to their own UID or, if they have
|
||||
.BR CAP_SETUID ,
|
||||
the persistent keyring
|
||||
corresponding to some other UID in the same user namespace.
|
||||
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
||||
.SH SEE ALSO
|
||||
|
|
|
@ -14,12 +14,12 @@
|
|||
.SH NAME
|
||||
process-keyring \- per-process shared keyring
|
||||
.SH DESCRIPTION
|
||||
The
|
||||
.B process keyring
|
||||
is a keyring used to anchor keys on behalf of a process.
|
||||
The process keyring is a keyring used to anchor keys on behalf of a process.
|
||||
It is only created when a process requests it.
|
||||
.P
|
||||
A special serial number value, \fBKEY_SPEC_PROCESS_KEYRING\fP, is defined that
|
||||
A special serial number value,
|
||||
.BR KEY_SPEC_PROCESS_KEYRING ,
|
||||
is defined that
|
||||
can be used in lieu of the calling process's process keyring's actual serial
|
||||
number.
|
||||
.P
|
||||
|
@ -27,14 +27,20 @@ From the keyctl utility, '\fB@p\fP' can be used instead of a numeric key ID in
|
|||
much the same way, but as keyctl is a program run after forking, this is of no
|
||||
utility.
|
||||
.P
|
||||
A process's process keyring is inherited across clone() with CLONE_THREAD and
|
||||
is cleared by execve().
|
||||
A process's process keyring is inherited across
|
||||
.BR clone (2)
|
||||
with
|
||||
.B CLONE_THREAD
|
||||
and is cleared by
|
||||
.BR execve (2).
|
||||
The process keyring will be destroyed when the last
|
||||
thread that refers to it exits.
|
||||
.P
|
||||
If a process doesn't have a process keyring when it is accessed, then the
|
||||
process keyring will be created if the keyring is to be modified, otherwise
|
||||
error ENOKEY will be issued.
|
||||
error
|
||||
.B ENOKEY
|
||||
will be issued.
|
||||
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
||||
.SH SEE ALSO
|
||||
.ad l
|
||||
|
|
|
@ -14,12 +14,12 @@
|
|||
.SH NAME
|
||||
session-keyring \- session shared process keyring
|
||||
.SH DESCRIPTION
|
||||
The
|
||||
.B session keyring
|
||||
is a keyring used to anchor keys on behalf of a process.
|
||||
It is typically created by the \fBpam_keyinit\fP module
|
||||
The session keyring is a keyring used to anchor keys on behalf of a process.
|
||||
It is typically created by
|
||||
.BR pam_keyinit (8)
|
||||
when a user logs in and a link will be
|
||||
added that refers to the \fBuser keyring\fP.
|
||||
added that refers to the
|
||||
.BR user-keyring (7).
|
||||
.P
|
||||
A special serial number value, \fBKEY_SPEC_SESSION_KEYRING\fP, is defined that
|
||||
can be used in lieu of the calling process's session keyring's actual serial
|
||||
|
@ -28,8 +28,15 @@ number.
|
|||
From the keyctl utility, '\fB@s\fP' can be used instead of a numeric key ID in
|
||||
much the same way.
|
||||
.P
|
||||
A process's session keyring is inherited across clone(), fork() and vfork() and
|
||||
is retained across execve() - even when the target executable is setuid or
|
||||
A process's session keyring is inherited across
|
||||
.BR clone (2),
|
||||
.BR fork (2),
|
||||
and
|
||||
.BR vfork (2)
|
||||
and
|
||||
is retained across
|
||||
.BR execve (2)
|
||||
- even when the target executable is setuid or
|
||||
setgid.
|
||||
The session keyring will be destroyed when the last process that
|
||||
refers to it exits.
|
||||
|
|
|
@ -14,12 +14,12 @@
|
|||
.SH NAME
|
||||
thread-keyring \- per-thread keyring
|
||||
.SH DESCRIPTION
|
||||
The
|
||||
.B thread keyring
|
||||
is a keyring used to anchor keys on behalf of a process.
|
||||
The thread keyring is a keyring used to anchor keys on behalf of a process.
|
||||
It is only created when a thread requests it.
|
||||
.P
|
||||
A special serial number value, \fBKEY_SPEC_THREAD_KEYRING\fP, is defined that
|
||||
A special serial number value,
|
||||
.BR KEY_SPEC_THREAD_KEYRING ,
|
||||
is defined that
|
||||
can be used in lieu of the calling thread's thread keyring's actual serial
|
||||
number.
|
||||
.P
|
||||
|
@ -27,12 +27,16 @@ From the keyctl utility, '\fB@t\fP' can be used instead of a numeric key ID in
|
|||
much the same way, but as keyctl is a program run after forking, this is of no
|
||||
utility.
|
||||
.P
|
||||
Thread keyrings are not inherited across clone() and are cleared by execve().
|
||||
Thread keyrings are not inherited across
|
||||
.BR clone (2)
|
||||
and are cleared by
|
||||
.BR execve (2).
|
||||
A thread keyring is destroyed when the thread that refers to it exits.
|
||||
.P
|
||||
If a thread doesn't have a thread keyring when it is accessed, then the thread
|
||||
keyring will be created if the keyring is to be modified, otherwise error
|
||||
ENOKEY will be issued.
|
||||
.B ENOKEY
|
||||
will be issued.
|
||||
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
||||
.SH SEE ALSO
|
||||
.ad l
|
||||
|
|
|
@ -14,9 +14,7 @@
|
|||
.SH NAME
|
||||
user-keyring \- per-user keyring
|
||||
.SH DESCRIPTION
|
||||
The
|
||||
.B user keyring
|
||||
is a keyring used to anchor keys on behalf of a user.
|
||||
The user keyring is a keyring used to anchor keys on behalf of a user.
|
||||
Each UID the kernel deals with has its own user keyring.
|
||||
This keyring is associated with the record that the kernel maintains
|
||||
for the UID and, once created, is retained as long as that record persists.
|
||||
|
@ -24,27 +22,40 @@ It is shared amongst all processes of that UID.
|
|||
.P
|
||||
The user keyring is created on demand when a thread requests it.
|
||||
Normally,
|
||||
this happens when \fBpam_keyinit\fP is invoked when a user logs in.
|
||||
this happens when
|
||||
.BR pam_keyinit (8)
|
||||
is invoked when a user logs in.
|
||||
.P
|
||||
The user keyring is not searched by default by \fBrequest_key\fP().
|
||||
When the
|
||||
pam_keyinit module creates a session keyring, it adds to it a link to the user
|
||||
When
|
||||
.BR pam_keyinit (8)
|
||||
creates a session keyring, it adds to it a link to the user
|
||||
keyring so that the user keyring will be searched when the session keyring is.
|
||||
.P
|
||||
A special serial number value, \fBKEY_SPEC_USER_KEYRING\fP, is defined that
|
||||
A special serial number value,
|
||||
.BR KEY_SPEC_USER_KEYRING ,
|
||||
is defined that
|
||||
can be used in lieu of the calling process's user keyring's actual serial
|
||||
number.
|
||||
.P
|
||||
From the keyctl utility, '\fB@u\fP' can be used instead of a numeric key ID in
|
||||
much the same way.
|
||||
.P
|
||||
User keyrings are independent of clone(), fork(), vfork(), execve() and exit()
|
||||
User keyrings are independent of
|
||||
.BR clone (2),
|
||||
.BR fork (2),
|
||||
.BR vfork (2),
|
||||
.BR execve (2),
|
||||
and
|
||||
.BR exit (2)
|
||||
excepting that the keyring is destroyed when the UID record is destroyed when
|
||||
the last process pinning it exits.
|
||||
.P
|
||||
If it necessary to for a key associated with a user to exist beyond the UID
|
||||
record being garbage collected - for example for use by a cron script - then
|
||||
the \fBpersistent keyring\fP should be used instead.
|
||||
the
|
||||
.BR persistent-keyring (7)
|
||||
should be used instead.
|
||||
.P
|
||||
If a user keyring does not exist when it is accessed, it will be created.
|
||||
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
||||
|
|
|
@ -14,9 +14,7 @@
|
|||
.SH NAME
|
||||
user-session-keyring \- per-user default session keyring
|
||||
.SH DESCRIPTION
|
||||
The
|
||||
.B user session keyring
|
||||
is a keyring used to anchor keys on behalf of a user.
|
||||
The user session keyring is a keyring used to anchor keys on behalf of a user.
|
||||
Each UID the kernel
|
||||
deals with has its own user session keyring.
|
||||
This keyring is associated with
|
||||
|
@ -26,7 +24,9 @@ It is shared amongst all processes of that
|
|||
UID.
|
||||
.P
|
||||
The user session keyring is created on demand when a thread requests it
|
||||
or when a thread asks for its \fBsession keyring\fP and that doesn't exist.
|
||||
or when a thread asks for its
|
||||
.BR session-keyring (7)
|
||||
and that doesn't exist.
|
||||
In the latter case,
|
||||
a user session keyring will be created and, if the session keyring
|
||||
wasn't to be created, the user session keyring will be set as the process's
|
||||
|
@ -35,22 +35,34 @@ actual session keyring.
|
|||
The user session keyring is searched by \fBrequest_key\fP() if the actual
|
||||
session keyring does not exist and is ignored otherwise.
|
||||
.P
|
||||
A special serial number value, \fBKEY_SPEC_USER_SESSION_KEYRING\fP, is defined
|
||||
A special serial number value,
|
||||
.BR KEY_SPEC_USER_SESSION_KEYRING ,
|
||||
is defined
|
||||
that can be used in lieu of the calling process's user session keyring's actual
|
||||
serial number.
|
||||
.P
|
||||
From the keyctl utility, '\fB@us\fP' can be used instead of a numeric key ID in
|
||||
much the same way.
|
||||
.P
|
||||
User session keyrings are independent of clone(), fork(), vfork(), execve() and
|
||||
exit() excepting that the keyring is destroyed when the UID record is destroyed
|
||||
User session keyrings are independent of
|
||||
.BR clone (2),
|
||||
.BR fork (2),
|
||||
.BR vfork (2),
|
||||
.BR execve (2),
|
||||
and
|
||||
.BR exit (2)
|
||||
excepting that the keyring is destroyed when the UID record is destroyed
|
||||
when the last process pinning it exits.
|
||||
.P
|
||||
If a user session keyring does not exist when it is accessed, it will be
|
||||
created.
|
||||
.P
|
||||
It is strongly recommended that a \fBsession keyring\fP be set explicitly, for
|
||||
example by \fBpam_keyinit\fP, rather than relying on the user session keyring -
|
||||
It is strongly recommended that a
|
||||
.BR session-keyring (7)
|
||||
be set explicitly, for
|
||||
example by
|
||||
.BR pam_keyinit (8),
|
||||
rather than relying on the user session keyring -
|
||||
particularly if a process is running as root.
|
||||
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
||||
.SH SEE ALSO
|
||||
|
|
Loading…
Reference in New Issue