Section (7) persistent-keyring
persistent-keyring — per-user persistent keyring
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
<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_zsingle_quotesz_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_zsingle_quotesz_s expiration timer is reset to the value in:
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 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_zsingle_quotesz_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 corresponding objects are automatically discarded.
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 persistent keyring corresponding to some other UID in
the same user namespace.
Each user namespace owns a keyring called
contains links to all of the persistent keys in that
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
that keyring, creates the key if it does not exist, and links
it into the keyring.
This page is part of release 5.04 of the Linux
man-pages project. A
description of the project, information about reporting bugs,
and the latest version of this page, can be found at
Copyright (C) 2014 Red Hat, Inc. All Rights Reserved.
Written by David Howells (dhowellsredhat.com)
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version
2 of the License, or (at your option) any later version.