diff --git a/man7/session-keyring.7 b/man7/session-keyring.7 new file mode 100644 index 000000000..9dc4cdfc9 --- /dev/null +++ b/man7/session-keyring.7 @@ -0,0 +1,85 @@ +.\" +.\" Copyright (C) 2014 Red Hat, Inc. All Rights Reserved. +.\" Written by David Howells (dhowells@redhat.com) +.\" +.\" This program is free software; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public Licence +.\" as published by the Free Software Foundation; either version +.\" 2 of the Licence, or (at your option) any later version. +.\" +.TH "SESSION KEYRING" 7 "19 Feb 2014" Linux "Kernel key management" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.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 when a user logs in and a link will be +added that refers to the \fBuser keyring\fP. +.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 +number. +.P +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 +setgid. The session keyring will be destroyed when the last process that +refers to it exits. +.P +If a process doesn't have a session keyring when it is accessed, then, under +certain circumstances, the \fBuser session keyring\fR will be attached as the +session keyring and under others a new session keyring will be created. +.SH SPECIAL OPERATIONS +The keyutils library provides a number of special operations for manipulating +session keyrings: +.IP \fBkeyctl_join_session_keyring\fP() +This operation allows the caller to change their session keyring. The caller +can join an existing keyring by name, create a new keyring of the name given or +ask the kernel to create a new session keyring with the name "_ses". +.IP \fBkeyctl_session_to_parent\fP() +This operation allows the caller to set the parent process's session keyring to +the same as their own. For this to succeed, the parent process must have +identical security attributes and must be single threaded. +.P +These operations are also exposed through the keyctl utility as: +.P +.RS +\fBkeyctl\fP session +.br +\fBkeyctl\fP session - [ ...] +.br +\fBkeyctl\fP session [ ...] +.RE +.P +and: +.P +.RS +\fBkeyctl\fP new_session +.RE +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SEE ALSO +.BR keyctl (1), +.br +.BR keyctl (3), +.br +.BR keyctl_join_session_keyring (3), +.br +.BR keyctl_session_to_parent (3), +.br +.BR pam_keyinit (8), +.br +.BR keyrings (7), +.br +.BR thread-keyring (7), +.br +.BR process-keyring (7), +.br +.BR user-keyring (7), +.br +.BR user-session-keyring (7) +.br +.BR persistent-keyring (7)