{ "content": [ { "type": "text", "text": "# PERSISTENT-KEYRING(7) (man)\n\n**Summary:** persistent-keyring - per-user persistent keyring\n\n## See Also\n\n- keyctl(1)\n- keyctl(3)\n- keyctlgetpersistent(3)\n- keyrings(7)\n- process-keyring(7)\n- session-keyring(7)\n- thread-keyring(7)\n- user-keyring(7)\n- user-session-keyring(7)\n\n## Section Outline\n\n- **NAME** (2 lines)\n- **DESCRIPTION** (38 lines) — 1 subsections\n - Special operations (6 lines)\n- **NOTES** (6 lines)\n- **SEE ALSO** (3 lines)\n- **COLOPHON** (7 lines)\n\n## Full Content\n\n### NAME\n\npersistent-keyring - per-user persistent keyring\n\n### DESCRIPTION\n\nThe persistent keyring is a keyring used to anchor keys on behalf of a user. Each UID the\nkernel deals with has its own persistent keyring that is shared between all threads owned by\nthat UID. The persistent keyring has a name (description) of the form persistent.\nwhere is the user ID of the corresponding user.\n\nThe persistent keyring may not be accessed directly, even by processes with the appropriate\nUID. Instead, it must first be linked to one of a process's keyrings, before that keyring\ncan access the persistent keyring by virtue of its possessor permits. This linking is done\nwith the keyctlgetpersistent(3) function.\n\nIf a persistent keyring does not exist when it is accessed by the keyctlgetpersistent(3)\noperation, it will be automatically created.\n\nEach time the keyctlgetpersistent(3) operation is performed, the persistent key's expira‐\ntion timer is reset to the value in:\n\n/proc/sys/kernel/keys/persistentkeyringexpiry\n\nShould the timeout be reached, the persistent keyring will be removed and everything it pins\ncan then be garbage collected. The key will then be re-created on a subsequent call to\nkeyctlgetpersistent(3).\n\nThe persistent keyring is not directly searched by requestkey(2); it is searched only if it\nis linked into one of the keyrings that is searched by requestkey(2).\n\nThe persistent keyring is independent of clone(2), fork(2), vfork(2), execve(2), and\nexit(2). It persists until its expiration timer triggers, at which point it is garbage col‐\nlected. This allows the persistent keyring to carry keys beyond the life of the kernel's\nrecord of the corresponding UID (the destruction of which results in the destruction of the\nuser-keyring(7) and the user-session-keyring(7)). The persistent keyring can thus be used to\nhold authentication tokens for processes that run without user interaction, such as programs\nstarted by cron(8).\n\nThe persistent keyring is used to store UID-specific objects that themselves have limited\nlifetimes (e.g., kerberos tokens). If those tokens cease to be used (i.e., the persistent\nkeyring is not accessed), then the timeout of the persistent keyring ensures that the corre‐\nsponding objects are automatically discarded.\n\n#### Special operations\n\nThe keyutils library provides the keyctlgetpersistent(3) function for manipulating persis‐\ntent keyrings. (This function is an interface to the keyctl(2) KEYCTLGETPERSISTENT opera‐\ntion.) This operation allows the calling thread to get the persistent keyring corresponding\nto its own UID or, if the thread has the CAPSETUID capability, the persistent keyring corre‐\nsponding to some other UID in the same user namespace.\n\n### NOTES\n\nEach user namespace owns a keyring called .persistentregister that contains links to all of\nthe persistent keys in that namespace. (The .persistentregister keyring can be seen when\nreading the contents of the /proc/keys file for the UID 0 in the namespace.) The\nkeyctlgetpersistent(3) operation looks for a key with a name of the form persistent.\nin that keyring, creates the key if it does not exist, and links it into the keyring.\n\n### SEE ALSO\n\nkeyctl(1), keyctl(3), keyctlgetpersistent(3), keyrings(7), process-keyring(7),\nsession-keyring(7), thread-keyring(7), user-keyring(7), user-session-keyring(7)\n\n### COLOPHON\n\nThis page is part of release 5.10 of the Linux man-pages project. A description of the\nproject, information about reporting bugs, and the latest version of this page, can be found\nat https://www.kernel.org/doc/man-pages/.\n\n\n\nLinux 2020-08-13 PERSISTENT-KEYRING(7)\n\n" } ], "structuredContent": { "command": "PERSISTENT-KEYRING", "section": "7", "mode": "man", "summary": "persistent-keyring - per-user persistent keyring", "synopsis": null, "flags": [], "examples": [], "see_also": [ { "name": "keyctl", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/keyctl/1/json" }, { "name": "keyctl", "section": "3", "url": "https://www.chedong.com/phpMan.php/man/keyctl/3/json" }, { "name": "keyctlgetpersistent", "section": "3", "url": "https://www.chedong.com/phpMan.php/man/keyctlgetpersistent/3/json" }, { "name": "keyrings", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/keyrings/7/json" }, { "name": "process-keyring", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/process-keyring/7/json" }, { "name": "session-keyring", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/session-keyring/7/json" }, { "name": "thread-keyring", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/thread-keyring/7/json" }, { "name": "user-keyring", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/user-keyring/7/json" }, { "name": "user-session-keyring", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/user-session-keyring/7/json" } ], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "DESCRIPTION", "lines": 38, "subsections": [ { "name": "Special operations", "lines": 6 } ] }, { "name": "NOTES", "lines": 6, "subsections": [] }, { "name": "SEE ALSO", "lines": 3, "subsections": [] }, { "name": "COLOPHON", "lines": 7, "subsections": [] } ] } }