Linux and UNIX Man Pages

Linux & Unix Commands - Search Man Pages

persistent-keyring(7) [linux man page]

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

NAME
persistent-keyring - per-user persistent keyring DESCRIPTION
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. The persistent keyring has a name (description) of the form _persistent.<UID> where <UID> is the user ID of the corresponding user. The persistent keyring may not be accessed directly, even by processes with the appropriate UID. Instead, it must first be linked to one of a process's keyrings, before that keyring can access the persistent keyring by virtue of its possessor permits. This linking is done with the keyctl_get_persistent(3) function. If a persistent keyring does not exist when it is accessed by the keyctl_get_persistent(3) operation, it will be automatically created. Each time the keyctl_get_persistent(3) operation is performed, the persistent key's expiration timer is reset to the value in: /proc/sys/kernel/keys/persistent_keyring_expiry Should the timeout be reached, the persistent keyring will be removed and everything it pins can then be garbage collected. The key will then be re-created on a subsequent call to keyctl_get_persistent(3). The persistent keyring is not directly searched by request_key(2); it is searched only if it is linked into one of the keyrings that is searched by request_key(2). The persistent keyring is independent of clone(2), fork(2), vfork(2), execve(2), and _exit(2). It persists until its expiration timer triggers, at which point it is garbage collected. This allows the persistent keyring to carry keys beyond the life of the kernel's record of the corresponding UID (the destruction of which results in the destruction of the user-keyring(7) and the user-session-keyring(7)). The persistent keyring can thus be used to hold authentication tokens for processes that run without user interaction, such as programs started by cron(8). The persistent keyring is used to store UID-specific objects that themselves have limited lifetimes (e.g., kerberos tokens). If those tokens cease to be used (i.e., the persistent keyring is not accessed), then the timeout of the persistent keyring ensures that the corre- sponding objects are automatically discarded. Special operations The keyutils library provides the keyctl_get_persistent(3) function for manipulating persistent keyrings. (This function is an interface to the keyctl(2) KEYCTL_GET_PERSISTENT operation.) This operation allows the calling thread to get the persistent keyring corresponding to its own UID or, if the thread has the CAP_SETUID capability, the persistent keyring corresponding to some other UID in the same user names- pace. NOTES
Each user namespace owns a keyring called .persistent_register that contains links to all of the persistent keys in that namespace. (The .persistent_register keyring can be seen when reading the contents of the /proc/keys file for the UID 0 in the namespace.) The keyctl_get_persistent(3) operation looks for a key with a name of the form _persistent.<UID> in that keyring, creates the key if it does not exist, and links it into the keyring. SEE ALSO
keyctl(1), keyctl(3), keyctl_get_persistent(3), keyrings(7), process-keyring(7), session-keyring(7), thread-keyring(7), user-keyring(7), user-session-keyring(7) Linux 2017-03-13 PERSISTENT-KEYRING(7)

Check Out this Related Man Page

KEYCTL_SET_REQKEY_KEYRING(3)				    Linux Key Management Calls				      KEYCTL_SET_REQKEY_KEYRING(3)

NAME
keyctl_set_reqkey_keyring - Set the implicit destination keyring SYNOPSIS
#include <keyutils.h> long keyctl_set_reqkey_keyring(int reqkey_defl); DESCRIPTION
keyctl_set_reqkey_keyring() sets the default destination for implicit key requests for the current thread and returns the old setting. After this operation has been issued, keys acquired by implicit key requests, such as might be performed by open() on an AFS or NFS filesystem, will be linked by default to the specified keyring by this function. The valid values of reqkey_defl are: KEY_REQKEY_DEFL_NO_CHANGE This makes no change to the current setting. KEY_REQKEY_DEFL_THREAD_KEYRING This makes the thread-specific keyring the default destination. KEY_REQKEY_DEFL_PROCESS_KEYRING This makes the process-specific keyring the default destination. KEY_REQKEY_DEFL_SESSION_KEYRING This makes the session keyring the default destination. KEY_REQKEY_DEFL_USER_KEYRING This makes the UID-specific keyring the default destination. KEY_REQKEY_DEFL_USER_SESSION_KEYRING This makes the UID-specific session keyring the default destination. KEY_REQKEY_DEFL_DEFAULT This selects the default behaviour which is to use the thread-specific keyring if there is one, otherwise the process-specific keyring if there is one, otherwise the session keyring if there is one, otherwise the UID-specific session keyring. This setting is inherited across fork() and exec(). RETURN VALUE
On success keyctl_set_reqkey_keyring() returns 0. On error, the value -1 will be returned and errno will have been set to an appropriate error. ERRORS
EINVAL The value of reqkey_defl is invalid. 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_join_session_keyring(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_timeout(3), keyctl_assume_authority(3), keyctl_describe_alloc(3), keyctl_read_alloc(3), request-key(8) Linux 4 May 2006 KEYCTL_SET_REQKEY_KEYRING(3)
Man Page