| 1 |
.\" Copyright 2014, Red Hat, Inc. |
| 2 |
.\" Copyright, the authors of the Linux man-pages project |
| 3 |
.\" |
| 4 |
.\" SPDX-License-Identifier: GPL-2.0-or-later |
| 5 |
.\" |
| 6 |
.TH session-keyring 7 2026-02-08 "Linux man-pages 6.18" |
| 7 |
.SH NAME |
| 8 |
session-keyring \- session shared process keyring |
| 9 |
.SH DESCRIPTION |
| 10 |
The session keyring is a keyring used to anchor keys on behalf of a process. |
| 11 |
It is typically created by |
| 12 |
.BR pam_keyinit (8) |
| 13 |
when a user logs in and a link will be added that refers to the |
| 14 |
.BR user\-keyring (7). |
| 15 |
Optionally, |
| 16 |
.BR PAM (7) |
| 17 |
may revoke the session keyring on logout. |
| 18 |
(In typical configurations, PAM does do this revocation.) |
| 19 |
The session keyring has the name (description) |
| 20 |
.IR _ses . |
| 21 |
.P |
| 22 |
A special serial number value, |
| 23 |
.BR KEY_SPEC_SESSION_KEYRING , |
| 24 |
is defined that can be used in lieu of the actual serial number of |
| 25 |
the calling process's session keyring. |
| 26 |
.P |
| 27 |
From the |
| 28 |
.BR keyctl (1) |
| 29 |
utility, |
| 30 |
.RB ' @s ' |
| 31 |
can be used instead of a numeric key ID in much the same way. |
| 32 |
.P |
| 33 |
A process's session keyring is inherited across |
| 34 |
.BR clone (2), |
| 35 |
.BR fork (2), |
| 36 |
and |
| 37 |
.BR vfork (2). |
| 38 |
The session keyring |
| 39 |
is preserved across |
| 40 |
.BR execve (2), |
| 41 |
even when the executable is set-user-ID or set-group-ID or has capabilities. |
| 42 |
The session keyring is destroyed when the last process that |
| 43 |
refers to it exits. |
| 44 |
.P |
| 45 |
If a process doesn't have a session keyring when it is accessed, then, |
| 46 |
under certain circumstances, the |
| 47 |
.BR user\-session\-keyring (7) |
| 48 |
will be attached as the session keyring |
| 49 |
and under others a new session keyring will be created. |
| 50 |
(See |
| 51 |
.BR user\-session\-keyring (7) |
| 52 |
for further details.) |
| 53 |
.SS Special operations |
| 54 |
The |
| 55 |
.I keyutils |
| 56 |
library provides the following special operations for manipulating |
| 57 |
session keyrings: |
| 58 |
.TP |
| 59 |
.BR keyctl_join_session_keyring (3) |
| 60 |
This operation allows the caller to change the session keyring |
| 61 |
that it subscribes to. |
| 62 |
The caller can join an existing keyring with a specified name (description), |
| 63 |
create a new keyring with a given name, |
| 64 |
or ask the kernel to create a new "anonymous" |
| 65 |
session keyring with the name "_ses". |
| 66 |
(This function is an interface to the |
| 67 |
.BR keyctl (2) |
| 68 |
.B KEYCTL_JOIN_SESSION_KEYRING |
| 69 |
operation.) |
| 70 |
.TP |
| 71 |
.BR keyctl_session_to_parent (3) |
| 72 |
This operation allows the caller to make the parent process's |
| 73 |
session keyring to the same as its own. |
| 74 |
For this to succeed, the parent process must have |
| 75 |
identical security attributes and must be single threaded. |
| 76 |
(This function is an interface to the |
| 77 |
.BR keyctl (2) |
| 78 |
.B KEYCTL_SESSION_TO_PARENT |
| 79 |
operation.) |
| 80 |
.P |
| 81 |
These operations are also exposed through the |
| 82 |
.BR keyctl (1) |
| 83 |
utility as: |
| 84 |
.P |
| 85 |
.in +4n |
| 86 |
.EX |
| 87 |
keyctl session |
| 88 |
keyctl session \- [<prog> <arg1> <arg2> ...] |
| 89 |
keyctl session <name> [<prog> <arg1> <arg2> ...] |
| 90 |
.EE |
| 91 |
.in |
| 92 |
.P |
| 93 |
and: |
| 94 |
.P |
| 95 |
.in +4n |
| 96 |
.EX |
| 97 |
keyctl new_session |
| 98 |
.EE |
| 99 |
.in |
| 100 |
.SH SEE ALSO |
| 101 |
.ad l |
| 102 |
.nh |
| 103 |
.BR keyctl (1), |
| 104 |
.BR keyctl (3), |
| 105 |
.BR keyctl_join_session_keyring (3), |
| 106 |
.BR keyctl_session_to_parent (3), |
| 107 |
.BR keyrings (7), |
| 108 |
.BR PAM (7), |
| 109 |
.BR persistent\-keyring (7), |
| 110 |
.BR process\-keyring (7), |
| 111 |
.BR thread\-keyring (7), |
| 112 |
.BR user\-keyring (7), |
| 113 |
.BR user\-session\-keyring (7), |
| 114 |
.BR pam_keyinit (8) |