Login or Register to Ask a Question and Join Our Community

Linux and UNIX Man Pages

Linux & Unix Commands - Search Man Pages

session-keyring(7) [linux man page]

SESSION-KEYRING(7)					     Linux Programmer's Manual						SESSION-KEYRING(7)

NAME

       session-keyring - session shared process keyring

DESCRIPTION

       The session keyring is a keyring used to anchor keys on behalf of a process.  It is typically created by pam_keyinit(8) when a user logs in
       and a link will be added that refers to the user-keyring(7).  Optionally, PAM may revoke the session keyring on logout.	(In  typical  con-
       figurations, PAM does do this revocation.)  The session keyring has the name (description) _ses.

       A  special  serial  number  value, KEY_SPEC_SESSION_KEYRING, is defined that can be used in lieu of the actual serial number of the calling
       process's session keyring.

       From the keyctl(1) utility, '@s' can be used instead of a numeric key ID in much the same way.

       A process's session keyring is inherited across clone(2), fork(2), and vfork(2).  The session keyring is preserved across  execve(2),  even
       when the executable is set-user-ID or set-group-ID or has capabilities.	The session keyring is destroyed when the last process that refers
       to it exits.

       If a process doesn't have a session keyring when it is accessed, then, under certain circumstances,  the  user-session-keyring(7)  will	be
       attached as the session keyring and under others a new session keyring will be created.	(See user-session-keyring(7) for further details.)

   Special operations
       The keyutils library provides the following special operations for manipulating session keyrings:

       keyctl_join_session_keyring(3)
	      This  operation allows the caller to change the session keyring that it subscribes to.  The caller can join an existing keyring with
	      a specified name (description), create a new keyring with a given name, or ask the  kernel  to  create  a  new  "anonymous"  session
	      keyring with the name "_ses".  (This function is an interface to the keyctl(2) KEYCTL_JOIN_SESSION_KEYRING operation.)

       keyctl_session_to_parent(3)
	      This operation allows the caller to make the parent process's session keyring to the same as its own.  For this to succeed, the par-
	      ent process must have identical security attributes and must be single threaded.	(This function is an interface	to  the  keyctl(2)
	      KEYCTL_SESSION_TO_PARENT operation.)

       These operations are also exposed through the keyctl(1) utility as:

	   keyctl session
	   keyctl session - [<prog> <arg1> <arg2> ...]
	   keyctl session <name> [<prog> <arg1> <arg2> ...]

       and:

	   keyctl new_session

SEE ALSO

       keyctl(1), keyctl(3), keyctl_join_session_keyring(3), keyctl_session_to_parent(3), keyrings(7), persistent-keyring(7), process-keyring(7),
       thread-keyring(7), user-keyring(7), user-session-keyring(7), pam_keyinit(8)

Linux								    2017-09-15							SESSION-KEYRING(7)

Check Out this Related Man Page

KEYCTL_JOIN_SESSION_KEYRING(3)				    Linux Key Management Calls				    KEYCTL_JOIN_SESSION_KEYRING(3)

NAME

       keyctl_join_session_keyring - Join a different session keyring

SYNOPSIS

       #include <keyutils.h>

       key_serial_t keyctl_join_session_keyring(const char *name);

DESCRIPTION

       keyctl_join_session_keyring() changes the session keyring to which a process is subscribed.

       If name is NULL then a new anonymous keyring will be created, and the process will be subscribed to that.

       If  name  points to a string, then if a keyring of that name is available, the process will attempt to subscribe to that keyring, giving an
       error if that is not permitted; otherwise a new keyring of that name is created and attached as the session keyring.

       To attach to an extant named keyring, the keyring must have search permission available to the calling process.

RETURN VALUE

       On success keyctl_join_session_keyring() returns the serial number of the key it found or created.  On error, the value -1 will be returned
       and errno will have been set to an appropriate error.

ERRORS

       ENOMEM Insufficient memory to create a key.

       EDQUOT The key quota for this user would be exceeded by creating this key or linking it to the keyring.

       EACCES The named keyring exists, but is not searchable by the calling process.

LINKING

       This is a library function that can be found in libkeyutils.  When linking, -lkeyutils should be specified to the linker.

SEE ALSO

       keyctl(1),
       add_key(2),
       keyctl(2),
       request_key(2),
       keyctl_get_keyring_ID(3),
       keyctl_update(3),
       keyctl_revoke(3),
       keyctl_chown(3),
       keyctl_setperm(3),
       keyctl_describe(3),
       keyctl_clear(3),
       keyctl_link(3),
       keyctl_unlink(3),
       keyctl_search(3),
       keyctl_read(3),
       keyctl_instantiate(3),
       keyctl_negate(3),
       keyctl_set_reqkey_keyring(3),
       keyctl_set_timeout(3),
       keyctl_assume_authority(3),
       keyctl_describe_alloc(3),
       keyctl_read_alloc(3),
       request-key(8)

Linux								    4 May 2006					    KEYCTL_JOIN_SESSION_KEYRING(3)
Man Page