* Revised keyrings(7) man page for review
@ 2016-11-04 15:47 ` Michael Kerrisk
0 siblings, 0 replies; 36+ messages in thread
From: Michael Kerrisk @ 2016-11-04 15:47 UTC (permalink / raw)
To: David Howells; +Cc: lkml, Eugene Syromyatnikov, keyrings, linux-man
[-- Attachment #1: Type: text/plain, Size: 30719 bytes --]
Hi David,
As part of the process of adopting the *.7 pages from
keyutils into man-pages, I've made some significant
extensions to the keyrings(7) page. Among the more notable
changes:
* Expanded the detail in "Key types"
* Addition of a section on the various /proc files
* Various other minor reworkings elsewhere in the text
Would you would be willing to review the new page, please?
(The page source file is attached, in case you want to
see all the formatting.)
Cheers,
Michael
====
NAME
keyrings - in-kernel key management and retention facility
DESCRIPTION
The Linux key-management facility is primarily a way for driv‐
ers to retain or cache security data, authentication keys,
encryption keys, and other data in the kernel.
System call interfaces are provided so that user-space programs
can manage those objects and also use the facility for their
own purposes.
A library and some user-space utilities are provided to allow
access to the facility. See keyctl(1), keyctl(3), and keyu‐
tils(7) for more information.
Keys
A key has the following attributes:
Serial number (ID)
This is a unique integer handle by which a key is
referred to in system call arguments. The serial number
is sometimes synonymously referred as the key ID. Pro‐
grammatically, key serial numbers are represented using
the type key_serial_t.
Type A key's type defines what sort of data can be held in
the key, how the proposed content of the key will be
parsed, and how the payload will be used.
There are a number of general purpose types available,
plus some specialist types defined by specific drivers.
Description (name)
The key description is a printable string that is used
as the search term for the key (in conjunction with the
key type) as well as a display name. During searches,
the description may be partially matched or exactly
matched.
Payload (data)
The payload is the actual content of a key. This is
usually set when a key is created, but it is possible
for the kernel to upcall to user space to finish the
instantiation of a key if that key wasn't already known
to the kernel when it was requested. (Details can be
found in request_key(2).)
A key's payload can be read and updated if the key type
supports it and if suitable permission is granted to the
caller.
Access rights
Much as files do, each key has an owning user ID, an
owning group ID, and a security label. They also have a
set of permissions, though there are more than for a
normal UNIX file, and there is an additional category
beyond the usual user, group, and other (see below).
Note that keys are quota controlled since they represent
unswappable kernel memory and the owning user ID speci‐
fies whose quota is to be debited.
Expiration time
Each key can have an expiration time set. When that
time is reached, the key is marked as being expired and
accesses to it fail with EKEYEXPIRED. If not deleted,
updated, or replaced, after a set amount of time,
expired keys are automatically removed along with all
links to them, and attempts to access the key will fail
with the error ENOKEY.
Reference count
Each key has a reference count. Keys are referenced by
keyrings, by currently active users, and by a process's
credentials. When the reference count reaches zero, the
key is scheduled for garbage collection.
Key types
The facility provides several basic types of key:
"user" This is a general purpose key type. The key is kept
entirely within kernel memory. The payload may be read
and updated by user-space applications.
The payload for keys of this type is a blob of arbitrary
data of up to 32,767 bytes.
The description may be any valid string, though it is
preferred that it start with a colon-delimited prefix
representing the service to which the key is of interest
(for instance "afs:mykey").
"keyring"
Keyrings are special keys whose payload consists of a
set of links to other keys (including other keyrings),
analogous to a directory holding links to files. The
main purpose of a keyring is to prevent other keys from
being garbage collected because nothing refers to them.
"logon" (since Linux 3.3)
This key type is essentially the same as "user", but it
does not provide reading (i.e., the keyctl(2)
KEYCTL_READ operation), meaning that the key payload is
never visible from user space. This is suitable for
storing username-password pairs that you do not want to
be readable from user space.
"big_key" (since Linux 3.13)
This key type is similar to the "user" key type, but it
may hold a payload of up to 1MiB in size. The data may
be stored in the swap space rather than in kernel memory
if the data size exceeds the overhead of storing the
data in swap space (a tmpfs file is used, which requires
filesystem structures to be allocated in the kernel).
This key type is useful for tasks such as holding Ker‐
beros ticket caches.
There are more specialized key types available also, but
they're not discussed here as they're not intended for normal
user-space use.
Keyrings
As previously mentioned, keyrings are a special type of key
that contain links to other keys (which may include other
keyrings). Keys may be linked to by multiple keyrings.
Keyrings may be considered as analogous to UNIX directories
where each directory contains a set of hard links to files.
Various operations (system calls) may be applied only to
keyrings:
Adding A key may be added to a keyring by system calls that
create keys. This prevents the new key from being imme‐
diately deleted when the system call driver releases its
last reference to the key.
Linking
A link may be added to a keyring pointing to a key that
is already known, provided this does not create a self-
referential cycle.
Unlinking
A link may be removed from a keyring. When the last
link to a key is removed, that key will be scheduled for
deletion by the garbage collector.
Clearing
All the links may be removed from a keyring.
Searching
A keyring may be considered the root of a tree or sub‐
tree in which keyrings form the branches and non-
keyrings the leaves. This tree may be searched for a
leaf matching a particular type and description.
See keyctl_clear(3), keyctl_link(3), keyctl_search(3), and
keyctl_unlink(3) for more information.
Anchoring keys
To prevent a key from being prematurely garbage collected, it
must anchored to keep its reference count elevated when it is
not in active use by the kernel.
Keyrings are used to anchor other keys - each link is a refer‐
ence on a key - but whilst keyrings are available to link to
keys, keyrings themselves are just keys and are also subject to
the same anchoring necessity.
The kernel makes available a number of anchor keyrings. Note
that some of these keyrings will be created only when first
accessed.
Process keyrings
Process credentials themselves reference keyrings with
specific semantics. These keyrings are pinned as long
as the set of credentials exists, which is usually as
long as the process exists.
There are three keyrings with different inheri‐
tance/sharing rules: The session-keyring(7) (inherited
and shared by all child processes), the process-
keyring(7) (shared by all threads in a process) and the
thread-keyring(7) (specific to a particular thread).
User keyrings
Each UID known to the kernel has a record that contains
two keyrings: the user-keyring(7) and the user-session-
keyring(7). These exist for as long as the UID record
in the kernel exists. A link to the user keyring is
placed in a new session keyring by pam_keyinit(8) when a
new login session is initiated.
Persistent keyrings
There is a persistent-keyring(7) available to each UID
known to the system. It may persist beyond the life of
the UID record previously mentioned, but has an expira‐
tion time set such that it is automatically cleaned up
after a set time. This, for example, permits cron
scripts to use credentials left when the user logs out.
Note that the expiration time is reset every time the
persistent key is requested.
Special keyrings
There are special keyrings owned by the kernel that can
anchor keys for special purposes. An example of this is
the system keyring used for holding encryption keys for
module signature verification.
These special keyrings are usually closed to direct
alteration by user space.
See thread-keyring(7), process-keyring(7), session-keyring(7),
user-keyring(7), user-session-keyring(7), and persistent-
keyring(7) for more information.
Possession
The concept of possession is important to understanding the
keyrings security model. Whether a thread possesses a key is
determined by the following rules:
(1) Any key or keyring that does not grant search permission to
the caller is ignored in all the following rules.
(2) A thread possesses its session, process, and thread
keyrings directly because those are pointed to by its cre‐
dentials.
(3) If a keyring is possessed, then any key it links to is also
possessed.
(4) If any key a keyring links to is itself a keyring, then
rule (3) applies recursively.
(5) If a process is upcalled from the kernel to instantiate a
key, then it also possesses the requester's keyrings as in
rule (1) as if it were the requester.
Note that possession is not a fundamental property of a key,
but must rather be calculated each time the key is needed.
Possession is designed to allow set-user-ID programs run from,
say a user's shell to access the user's keys. It also allows
the prevention of access to keys just on the basis of UID and
GID matches.
When it creates the session keyring, pam_keyinit(8) adds a link
to the user-keyring(7), thus making the user keyring and any‐
thing it contains possessed by default.
Access rights
Each key has the following security-related attributes:
* The owning user ID
* The ID of a group that is permitted to access the key
* A security label
* A permissions mask
The permissions mask contains four sets of rights. The first
three sets are mutually exclusive. One and only one will be in
force for a particular access check. In order of descending
priority, these three sets are:
user The set specifies the rights granted if the key's user
ID matches the caller's filesystem user ID.
group The set specifies the rights granted if the user ID
didn't match and the key's group ID matches the caller's
filesystem GID or one of the caller's supplementary
group IDs.
other The set specifies the rights granted if neither the
key's user ID nor group ID matched.
The fourth set of rights is:
possessor
The set specifies the rights granted if a key is deter‐
mined to be possessed by the caller.
The complete set of rights for a key is the union of whichever
of the first three sets is applicable plus the fourth set if
the key is possessed.
The set of rights that may be granted in each of the four masks
is as follows:
view The attributes of the key may be read. This includes
the type, description, and access rights (excluding the
security label).
read For a key: the payload of the key may be read. For a
keyring: the list of serial numbers (keys) to which the
keyring has links may be read.
write The payload of the key may be updated. For a keyring,
links may be added to or removed from the keyring, the
keyring may be cleared completely (all links are
removed), and the key may be revoked.
search For a key (or a keyring): the key may be found by a
search. For a keyring: keys and keyrings that are
linked to by the keyring may be searched.
link Links may be created from keyrings to the key. The ini‐
tial link to a key that is established when the key is
created doesn't require this permission.
setattr
The ownership details and security label of the key may
be changed, the key's expiration time may be set, and
the key may be revoked.
If any right is granted to a thread for a key,
┌─────────────────────────────────────────────────────┐
│FIXME │
├─────────────────────────────────────────────────────┤
│This seems to contradict the text below, which says │
│that 'view' permission is what is significant. │
│Which is correct? │
└─────────────────────────────────────────────────────┘
then that thread will see the key listed in /proc/keys. If no
rights at all are granted, then that thread can't even tell
that the key exists.
In addition to access rights, any active Linux Security Module
(LSM) may prevent access to a key if its policy so dictates. A
key may be given a security label or other attribute by the LSM
which can be retrieved.
See keyctl_chown(3), keyctl_describe(3), keyctl_get_secu‐
rity(3), keyctl_setperm(3), and selinux(8) for more informa‐
tion.
Searching for keys
One of the key features of the Linux key-management facility is
the ability to find a key that a process is retaining. The
request_key(2) system call is the primary point of access for
user-space applications to find a key. (internally, the kernel
has something similar available for use by internal components
that make use of keys.)
The search algorithm works as follows:
(1) The three process keyrings are searched in the following
order: the thread thread-keyring(7) if it exists, the
process-keyring(7) if it exists, and then either the ses‐
sion-keyring(7) if it exists or the user-session-keyring(7)
if that exists.
(2) If the caller was a process that was invoked by the
request_key(2) upcall mechanism then the keyrings of the
original caller of that request_key(2) will be searched as
well.
(3) The search of the keyring tree is in preorder: each keyring
is searched first for a match, then the keyrings referred
to by that keyring are searched.
(4) If a matching key is found that is valid, then the search
terminates and that key is returned.
(5) If a matching key is found that has an error state
attached, that error state is noted and the search contin‐
ues.
(6) If valid matching key is found, then the first noted error
state is returned; otherwise, an ENOKEY error is returned.
It is also possible to search a specific keyring, in which case
only steps (3) to (6) apply.
See request_key(2) and keyctl_search(3) for more information.
On-demand key creation
If a key cannot be found, request_key(2) will, if given a call‐
out_info argument, create a new key and then upcall to user
space to instantiate the key. This allows keys to be created
on an as-needed basis.
Typically, this will involve the kernel forking and exec'ing
the request-key(8) program, which will then execute the appro‐
priate handler based on its configuration.
The handler is passed a special authorization key that allows
it and only it to instantiate the new key. This is also used
to permit searches performed by the handler program to also
search the requester's keyrings.
See request_key(2), keyctl_assume_authority(3), keyctl_instan‐
tiate(3), keyctl_negate(3), keyctl_reject(3), request-key(8)
and request-key.conf(5) for more information.
/proc files
The kernel provides various /proc files that expose information
about keys or define limits on key usage.
/proc/keys (since Linux 2.6.10)
This file exposes a list of the keys that are viewable
by the reading process, providing various information
about each key.
The only keys included in the list are those that grant
view permission to the reading process, regardless of
whether or not it possesses them. LSM security checks
are still performed, and may filter out further keys
that the process is not authorized to view.
An example of the data that one might see in this file
is the following:
009a2028 I--Q--- 1 perm 3f010000 1000 1000 user krb_ccache:primary: 12
1806c4ba I--Q--- 1 perm 3f010000 1000 1000 keyring _pid: 2
25d3a08f I--Q--- 1 perm 1f3f0000 1000 65534 keyring _uid_ses.1000: 1
28576bd8 I--Q--- 3 perm 3f010000 1000 1000 keyring _krb: 1
2c546d21 I--Q--- 190 perm 3f030000 1000 1000 keyring _ses: 2
30a4e0be I------ 4 2d 1f030000 1000 65534 keyring _persistent.1000: 1
32100fab I--Q--- 4 perm 1f3f0000 1000 65534 keyring _uid.1000: 2
32a387ea I--Q--- 1 perm 3f010000 1000 1000 keyring _pid: 2
3ce56aea I--Q--- 5 perm 3f030000 1000 1000 keyring _ses: 1
The fields shown in each line of this file are as fol‐
lows:
ID The ID (serial number) of the key, expressed in
hexadecimal.
Flags A set of flags describing the state of the key:
I The key has been instantiated.
R The key has been revoked.
D The key is dead (i.e., has been deleted). (A
key may be briefly in this state during
garbage collection.)
Q The key contributes to the user's quota.
U The key is under construction via a callback
to user space; see request-key(2).
N The key is negatively instantiated.
i The key has been invalidated.
Usage This is a count of the number of kernel creden‐
tial structures that are pinning the key (approx‐
imately: the number of threads and open file ref‐
erences that refer to this key).
Timeout
The amount of time until the key will expire,
expressed in human-readable form (weeks, days,
hours, minutes, and seconds). The string perm
here means that the key is permanent (no time‐
out). The string expd means that the key has
already expired, but has not yet been garbage
collected.
Permissions
The key permissions, expressed as four hexadeci‐
mal bytes containing, from left to right, the
possessor, user, group, and other permissions.
UID The user ID of the key owner.
GID The group ID of the key. The value -1 here means
that the key as no group ID; this can occur in
certain circumstances for keys created by the
kernel.
Type The key type (user, keyring, etc.)
Description
The key description (name).
Description
This field contains descriptive information about
the key. For most key tpes, it has the form
desc[: extra-info]
The name subfield is the the key's description
(name). The optional extra-info field provides
some further information about the key. The
information that appears here depends on the key
type, as follows:
"user" and "logon"
The size in bytes of the key payload
(expressed in decimal).
"keyring"
The number of keys linked to the keyring, or
the string empty if there are no keys linked
to the keyring.
"big_key"
The payload size in bytes, followed either by
the string [file], if the key payload exceeds
the threshold that means that the payload is
stored in a (swappable) tmpfs filesystem, or
otherwise the string [buff], indicating that
the key is small enough to reside in kernel
memory.
For the ".request_key_auth" key type (authoriza‐
tion key; see request_key(2)), the description
field has the form shown in the following exam‐
ple:
key:c9a9b19 pid:28880 ci:10
The three subfields are as follows:
key The hexadecimal ID of the key being instan‐
tiated in the requesting program.
pid The PID of the requesting program.
ci The length of the callout data with which
the requested key should be instantiated
(i.e., the length of the payload associated
with the authorization key).
/proc/key-users (since Linux 2.6.10)
This file lists various information for each user ID
that has at least one key on the system. An example of
the data that one might see in this file is the follow‐
ing:
0: 10 9/9 2/1000000 22/25000000
42: 9 9/9 8/200 106/20000
1000: 11 11/11 10/200 271/20000
The fields shown in each line are as follows:
uid The user ID.
usage This is a kernel-internal usage count for the
kernel structure used to record key users.
nkeys/nikeys
The total number of keys owned by the user, and
the number of those keys that have been instanti‐
ated.
qnkeys/maxkeys
The number of keys owned by the user, and the
maximum keys that the user may own.
qnbytes/maxbytes
The number of bytes consumed in payloads of the
keys owned by this user, and the upper limit on
the number of bytes in key payloads for that
user.
/proc/sys/kernel/keys/gc_delay (since Linux 2.6.32)
The value in this file specifies the interval, in sec‐
onds, after which revoked and expired keys will be
garbage collected. The purpose of having such an inter‐
val is so that there is a window of time where user
space can see an error (respectively EKEYREVOKED and
EKEYEXPIRED) that indicates what happened to the key.
The default value in this file is 300 (i.e., 5 minutes).
/proc/sys/kernel/keys/persistent_keyring_expiry (since Linux
3.13)
This file defines an interval, in seconds, to which the
persistent keyring's expiration timer is reset each time
the keyring is accessed (via keyctl_get_persistent(3) or
the keyctl(2) KEYCTL_GET_PERSISTENT operation.)
The default value in this file is 259200 (i.e., 3 days).
The following files (which are writable by privileged pro‐
cesses) are used to enforce quotas on the number of keys and
number of bytes of data that can be stored in key payloads:
/proc/sys/kernel/keys/maxbytes (since Linux 2.6.26)
This is the maximum number of bytes of data that a non‐
root user can hold in the payloads of the keys owned by
the user.
The default value in this file is 20,000.
/proc/sys/kernel/keys/maxkeys (since Linux 2.6.26)
This is the maximum number of keys that a nonroot user
may own.
The default value in this file is 200.
/proc/sys/kernel/keys/root_maxbytes (since Linux 2.6.26)
This is the maximum number of bytes of data that the
root user (UID 0 in the root user namespace) can hold in
the payloads of the keys owned by root.
The default value in this file is 25,000,000.
/proc/sys/kernel/keys/root_maxkeys (since Linux 2.6.26)
This is the maximum number of keys that the root user
(UID 0 in the root user namespace) may own.
The default value in this file is 1,000,000.
With respect to keyrings, note that each link in a keyring con‐
sumes 4 bytes of the keyring payload.
Users
The Linux key-management facility has a number of users and
usages, but is not limited to those that already exist.
In-kernel users of this facility include:
Network filesystems - DNS
The kernel uses the upcall mechanism provided by the
keys to upcall to user space to do DNS lookups and then
to cache the results.
AF_RXRPC and kAFS - Authentication
The AF_RXRPC network protocol and the in-kernel AFS
filesystem use keys to store the ticket needed to do
secured or encrypted traffic. These are then looked up
by network operations on AF_RXRPC and filesystem opera‐
tions on kAFS.
NFS - User ID mapping
The NFS filesystem uses keys to store mappings of for‐
eign user IDs to local user IDs.
CIFS - Password
The CIFS filesystem uses keys to store passwords for
accessing remote shares.
Module verification
The kernel build process can be made to cryptographi‐
cally sign modules. That signature is then checked when
a module is loaded.
User-space users of this facility include:
Kerberos key storage
The MIT Kerberos 5 facility (libkrb5) can use keys to
store authentication tokens which can be made to be
automatically cleaned up a set time after the user last
uses them, but until then permits them to hang around
after the user has logged out so that cron scripts can
use them.
SEE ALSO
keyutils(7), persistent-keyring(7), process-keyring(7),
session-keyring(7), thread-keyring(7), user-keyring(7),
user-session-keyring(7), pam_keyinit(8)
Linux 2016-11-01 KEYRINGS(7)
--
Michael Kerrisk, man7.org Training and Consulting
mtk@man7.org, http://man7.org/training/
"The Linux Programming Interface" -- http://man7.org/tlpi/
[-- Attachment #2: keyrings.7 --]
[-- Type: application/x-troff-man, Size: 25373 bytes --]
^ permalink raw reply [flat|nested] 36+ messages in thread
* Revised keyrings(7) man page for review
@ 2016-11-04 15:47 ` Michael Kerrisk
0 siblings, 0 replies; 36+ messages in thread
From: Michael Kerrisk @ 2016-11-04 15:47 UTC (permalink / raw)
To: David Howells
Cc: lkml, Eugene Syromyatnikov, keyrings-u79uwXL29TY76Z2rM5mHXA, linux-man
[-- Attachment #1: Type: text/plain, Size: 30739 bytes --]
Hi David,
As part of the process of adopting the *.7 pages from
keyutils into man-pages, I've made some significant
extensions to the keyrings(7) page. Among the more notable
changes:
* Expanded the detail in "Key types"
* Addition of a section on the various /proc files
* Various other minor reworkings elsewhere in the text
Would you would be willing to review the new page, please?
(The page source file is attached, in case you want to
see all the formatting.)
Cheers,
Michael
====
NAME
keyrings - in-kernel key management and retention facility
DESCRIPTION
The Linux key-management facility is primarily a way for driv‐
ers to retain or cache security data, authentication keys,
encryption keys, and other data in the kernel.
System call interfaces are provided so that user-space programs
can manage those objects and also use the facility for their
own purposes.
A library and some user-space utilities are provided to allow
access to the facility. See keyctl(1), keyctl(3), and keyu‐
tils(7) for more information.
Keys
A key has the following attributes:
Serial number (ID)
This is a unique integer handle by which a key is
referred to in system call arguments. The serial number
is sometimes synonymously referred as the key ID. Pro‐
grammatically, key serial numbers are represented using
the type key_serial_t.
Type A key's type defines what sort of data can be held in
the key, how the proposed content of the key will be
parsed, and how the payload will be used.
There are a number of general purpose types available,
plus some specialist types defined by specific drivers.
Description (name)
The key description is a printable string that is used
as the search term for the key (in conjunction with the
key type) as well as a display name. During searches,
the description may be partially matched or exactly
matched.
Payload (data)
The payload is the actual content of a key. This is
usually set when a key is created, but it is possible
for the kernel to upcall to user space to finish the
instantiation of a key if that key wasn't already known
to the kernel when it was requested. (Details can be
found in request_key(2).)
A key's payload can be read and updated if the key type
supports it and if suitable permission is granted to the
caller.
Access rights
Much as files do, each key has an owning user ID, an
owning group ID, and a security label. They also have a
set of permissions, though there are more than for a
normal UNIX file, and there is an additional category
beyond the usual user, group, and other (see below).
Note that keys are quota controlled since they represent
unswappable kernel memory and the owning user ID speci‐
fies whose quota is to be debited.
Expiration time
Each key can have an expiration time set. When that
time is reached, the key is marked as being expired and
accesses to it fail with EKEYEXPIRED. If not deleted,
updated, or replaced, after a set amount of time,
expired keys are automatically removed along with all
links to them, and attempts to access the key will fail
with the error ENOKEY.
Reference count
Each key has a reference count. Keys are referenced by
keyrings, by currently active users, and by a process's
credentials. When the reference count reaches zero, the
key is scheduled for garbage collection.
Key types
The facility provides several basic types of key:
"user" This is a general purpose key type. The key is kept
entirely within kernel memory. The payload may be read
and updated by user-space applications.
The payload for keys of this type is a blob of arbitrary
data of up to 32,767 bytes.
The description may be any valid string, though it is
preferred that it start with a colon-delimited prefix
representing the service to which the key is of interest
(for instance "afs:mykey").
"keyring"
Keyrings are special keys whose payload consists of a
set of links to other keys (including other keyrings),
analogous to a directory holding links to files. The
main purpose of a keyring is to prevent other keys from
being garbage collected because nothing refers to them.
"logon" (since Linux 3.3)
This key type is essentially the same as "user", but it
does not provide reading (i.e., the keyctl(2)
KEYCTL_READ operation), meaning that the key payload is
never visible from user space. This is suitable for
storing username-password pairs that you do not want to
be readable from user space.
"big_key" (since Linux 3.13)
This key type is similar to the "user" key type, but it
may hold a payload of up to 1MiB in size. The data may
be stored in the swap space rather than in kernel memory
if the data size exceeds the overhead of storing the
data in swap space (a tmpfs file is used, which requires
filesystem structures to be allocated in the kernel).
This key type is useful for tasks such as holding Ker‐
beros ticket caches.
There are more specialized key types available also, but
they're not discussed here as they're not intended for normal
user-space use.
Keyrings
As previously mentioned, keyrings are a special type of key
that contain links to other keys (which may include other
keyrings). Keys may be linked to by multiple keyrings.
Keyrings may be considered as analogous to UNIX directories
where each directory contains a set of hard links to files.
Various operations (system calls) may be applied only to
keyrings:
Adding A key may be added to a keyring by system calls that
create keys. This prevents the new key from being imme‐
diately deleted when the system call driver releases its
last reference to the key.
Linking
A link may be added to a keyring pointing to a key that
is already known, provided this does not create a self-
referential cycle.
Unlinking
A link may be removed from a keyring. When the last
link to a key is removed, that key will be scheduled for
deletion by the garbage collector.
Clearing
All the links may be removed from a keyring.
Searching
A keyring may be considered the root of a tree or sub‐
tree in which keyrings form the branches and non-
keyrings the leaves. This tree may be searched for a
leaf matching a particular type and description.
See keyctl_clear(3), keyctl_link(3), keyctl_search(3), and
keyctl_unlink(3) for more information.
Anchoring keys
To prevent a key from being prematurely garbage collected, it
must anchored to keep its reference count elevated when it is
not in active use by the kernel.
Keyrings are used to anchor other keys - each link is a refer‐
ence on a key - but whilst keyrings are available to link to
keys, keyrings themselves are just keys and are also subject to
the same anchoring necessity.
The kernel makes available a number of anchor keyrings. Note
that some of these keyrings will be created only when first
accessed.
Process keyrings
Process credentials themselves reference keyrings with
specific semantics. These keyrings are pinned as long
as the set of credentials exists, which is usually as
long as the process exists.
There are three keyrings with different inheri‐
tance/sharing rules: The session-keyring(7) (inherited
and shared by all child processes), the process-
keyring(7) (shared by all threads in a process) and the
thread-keyring(7) (specific to a particular thread).
User keyrings
Each UID known to the kernel has a record that contains
two keyrings: the user-keyring(7) and the user-session-
keyring(7). These exist for as long as the UID record
in the kernel exists. A link to the user keyring is
placed in a new session keyring by pam_keyinit(8) when a
new login session is initiated.
Persistent keyrings
There is a persistent-keyring(7) available to each UID
known to the system. It may persist beyond the life of
the UID record previously mentioned, but has an expira‐
tion time set such that it is automatically cleaned up
after a set time. This, for example, permits cron
scripts to use credentials left when the user logs out.
Note that the expiration time is reset every time the
persistent key is requested.
Special keyrings
There are special keyrings owned by the kernel that can
anchor keys for special purposes. An example of this is
the system keyring used for holding encryption keys for
module signature verification.
These special keyrings are usually closed to direct
alteration by user space.
See thread-keyring(7), process-keyring(7), session-keyring(7),
user-keyring(7), user-session-keyring(7), and persistent-
keyring(7) for more information.
Possession
The concept of possession is important to understanding the
keyrings security model. Whether a thread possesses a key is
determined by the following rules:
(1) Any key or keyring that does not grant search permission to
the caller is ignored in all the following rules.
(2) A thread possesses its session, process, and thread
keyrings directly because those are pointed to by its cre‐
dentials.
(3) If a keyring is possessed, then any key it links to is also
possessed.
(4) If any key a keyring links to is itself a keyring, then
rule (3) applies recursively.
(5) If a process is upcalled from the kernel to instantiate a
key, then it also possesses the requester's keyrings as in
rule (1) as if it were the requester.
Note that possession is not a fundamental property of a key,
but must rather be calculated each time the key is needed.
Possession is designed to allow set-user-ID programs run from,
say a user's shell to access the user's keys. It also allows
the prevention of access to keys just on the basis of UID and
GID matches.
When it creates the session keyring, pam_keyinit(8) adds a link
to the user-keyring(7), thus making the user keyring and any‐
thing it contains possessed by default.
Access rights
Each key has the following security-related attributes:
* The owning user ID
* The ID of a group that is permitted to access the key
* A security label
* A permissions mask
The permissions mask contains four sets of rights. The first
three sets are mutually exclusive. One and only one will be in
force for a particular access check. In order of descending
priority, these three sets are:
user The set specifies the rights granted if the key's user
ID matches the caller's filesystem user ID.
group The set specifies the rights granted if the user ID
didn't match and the key's group ID matches the caller's
filesystem GID or one of the caller's supplementary
group IDs.
other The set specifies the rights granted if neither the
key's user ID nor group ID matched.
The fourth set of rights is:
possessor
The set specifies the rights granted if a key is deter‐
mined to be possessed by the caller.
The complete set of rights for a key is the union of whichever
of the first three sets is applicable plus the fourth set if
the key is possessed.
The set of rights that may be granted in each of the four masks
is as follows:
view The attributes of the key may be read. This includes
the type, description, and access rights (excluding the
security label).
read For a key: the payload of the key may be read. For a
keyring: the list of serial numbers (keys) to which the
keyring has links may be read.
write The payload of the key may be updated. For a keyring,
links may be added to or removed from the keyring, the
keyring may be cleared completely (all links are
removed), and the key may be revoked.
search For a key (or a keyring): the key may be found by a
search. For a keyring: keys and keyrings that are
linked to by the keyring may be searched.
link Links may be created from keyrings to the key. The ini‐
tial link to a key that is established when the key is
created doesn't require this permission.
setattr
The ownership details and security label of the key may
be changed, the key's expiration time may be set, and
the key may be revoked.
If any right is granted to a thread for a key,
┌─────────────────────────────────────────────────────┐
│FIXME │
├─────────────────────────────────────────────────────┤
│This seems to contradict the text below, which says │
│that 'view' permission is what is significant. │
│Which is correct? │
└─────────────────────────────────────────────────────┘
then that thread will see the key listed in /proc/keys. If no
rights at all are granted, then that thread can't even tell
that the key exists.
In addition to access rights, any active Linux Security Module
(LSM) may prevent access to a key if its policy so dictates. A
key may be given a security label or other attribute by the LSM
which can be retrieved.
See keyctl_chown(3), keyctl_describe(3), keyctl_get_secu‐
rity(3), keyctl_setperm(3), and selinux(8) for more informa‐
tion.
Searching for keys
One of the key features of the Linux key-management facility is
the ability to find a key that a process is retaining. The
request_key(2) system call is the primary point of access for
user-space applications to find a key. (internally, the kernel
has something similar available for use by internal components
that make use of keys.)
The search algorithm works as follows:
(1) The three process keyrings are searched in the following
order: the thread thread-keyring(7) if it exists, the
process-keyring(7) if it exists, and then either the ses‐
sion-keyring(7) if it exists or the user-session-keyring(7)
if that exists.
(2) If the caller was a process that was invoked by the
request_key(2) upcall mechanism then the keyrings of the
original caller of that request_key(2) will be searched as
well.
(3) The search of the keyring tree is in preorder: each keyring
is searched first for a match, then the keyrings referred
to by that keyring are searched.
(4) If a matching key is found that is valid, then the search
terminates and that key is returned.
(5) If a matching key is found that has an error state
attached, that error state is noted and the search contin‐
ues.
(6) If valid matching key is found, then the first noted error
state is returned; otherwise, an ENOKEY error is returned.
It is also possible to search a specific keyring, in which case
only steps (3) to (6) apply.
See request_key(2) and keyctl_search(3) for more information.
On-demand key creation
If a key cannot be found, request_key(2) will, if given a call‐
out_info argument, create a new key and then upcall to user
space to instantiate the key. This allows keys to be created
on an as-needed basis.
Typically, this will involve the kernel forking and exec'ing
the request-key(8) program, which will then execute the appro‐
priate handler based on its configuration.
The handler is passed a special authorization key that allows
it and only it to instantiate the new key. This is also used
to permit searches performed by the handler program to also
search the requester's keyrings.
See request_key(2), keyctl_assume_authority(3), keyctl_instan‐
tiate(3), keyctl_negate(3), keyctl_reject(3), request-key(8)
and request-key.conf(5) for more information.
/proc files
The kernel provides various /proc files that expose information
about keys or define limits on key usage.
/proc/keys (since Linux 2.6.10)
This file exposes a list of the keys that are viewable
by the reading process, providing various information
about each key.
The only keys included in the list are those that grant
view permission to the reading process, regardless of
whether or not it possesses them. LSM security checks
are still performed, and may filter out further keys
that the process is not authorized to view.
An example of the data that one might see in this file
is the following:
009a2028 I--Q--- 1 perm 3f010000 1000 1000 user krb_ccache:primary: 12
1806c4ba I--Q--- 1 perm 3f010000 1000 1000 keyring _pid: 2
25d3a08f I--Q--- 1 perm 1f3f0000 1000 65534 keyring _uid_ses.1000: 1
28576bd8 I--Q--- 3 perm 3f010000 1000 1000 keyring _krb: 1
2c546d21 I--Q--- 190 perm 3f030000 1000 1000 keyring _ses: 2
30a4e0be I------ 4 2d 1f030000 1000 65534 keyring _persistent.1000: 1
32100fab I--Q--- 4 perm 1f3f0000 1000 65534 keyring _uid.1000: 2
32a387ea I--Q--- 1 perm 3f010000 1000 1000 keyring _pid: 2
3ce56aea I--Q--- 5 perm 3f030000 1000 1000 keyring _ses: 1
The fields shown in each line of this file are as fol‐
lows:
ID The ID (serial number) of the key, expressed in
hexadecimal.
Flags A set of flags describing the state of the key:
I The key has been instantiated.
R The key has been revoked.
D The key is dead (i.e., has been deleted). (A
key may be briefly in this state during
garbage collection.)
Q The key contributes to the user's quota.
U The key is under construction via a callback
to user space; see request-key(2).
N The key is negatively instantiated.
i The key has been invalidated.
Usage This is a count of the number of kernel creden‐
tial structures that are pinning the key (approx‐
imately: the number of threads and open file ref‐
erences that refer to this key).
Timeout
The amount of time until the key will expire,
expressed in human-readable form (weeks, days,
hours, minutes, and seconds). The string perm
here means that the key is permanent (no time‐
out). The string expd means that the key has
already expired, but has not yet been garbage
collected.
Permissions
The key permissions, expressed as four hexadeci‐
mal bytes containing, from left to right, the
possessor, user, group, and other permissions.
UID The user ID of the key owner.
GID The group ID of the key. The value -1 here means
that the key as no group ID; this can occur in
certain circumstances for keys created by the
kernel.
Type The key type (user, keyring, etc.)
Description
The key description (name).
Description
This field contains descriptive information about
the key. For most key tpes, it has the form
desc[: extra-info]
The name subfield is the the key's description
(name). The optional extra-info field provides
some further information about the key. The
information that appears here depends on the key
type, as follows:
"user" and "logon"
The size in bytes of the key payload
(expressed in decimal).
"keyring"
The number of keys linked to the keyring, or
the string empty if there are no keys linked
to the keyring.
"big_key"
The payload size in bytes, followed either by
the string [file], if the key payload exceeds
the threshold that means that the payload is
stored in a (swappable) tmpfs filesystem, or
otherwise the string [buff], indicating that
the key is small enough to reside in kernel
memory.
For the ".request_key_auth" key type (authoriza‐
tion key; see request_key(2)), the description
field has the form shown in the following exam‐
ple:
key:c9a9b19 pid:28880 ci:10
The three subfields are as follows:
key The hexadecimal ID of the key being instan‐
tiated in the requesting program.
pid The PID of the requesting program.
ci The length of the callout data with which
the requested key should be instantiated
(i.e., the length of the payload associated
with the authorization key).
/proc/key-users (since Linux 2.6.10)
This file lists various information for each user ID
that has at least one key on the system. An example of
the data that one might see in this file is the follow‐
ing:
0: 10 9/9 2/1000000 22/25000000
42: 9 9/9 8/200 106/20000
1000: 11 11/11 10/200 271/20000
The fields shown in each line are as follows:
uid The user ID.
usage This is a kernel-internal usage count for the
kernel structure used to record key users.
nkeys/nikeys
The total number of keys owned by the user, and
the number of those keys that have been instanti‐
ated.
qnkeys/maxkeys
The number of keys owned by the user, and the
maximum keys that the user may own.
qnbytes/maxbytes
The number of bytes consumed in payloads of the
keys owned by this user, and the upper limit on
the number of bytes in key payloads for that
user.
/proc/sys/kernel/keys/gc_delay (since Linux 2.6.32)
The value in this file specifies the interval, in sec‐
onds, after which revoked and expired keys will be
garbage collected. The purpose of having such an inter‐
val is so that there is a window of time where user
space can see an error (respectively EKEYREVOKED and
EKEYEXPIRED) that indicates what happened to the key.
The default value in this file is 300 (i.e., 5 minutes).
/proc/sys/kernel/keys/persistent_keyring_expiry (since Linux
3.13)
This file defines an interval, in seconds, to which the
persistent keyring's expiration timer is reset each time
the keyring is accessed (via keyctl_get_persistent(3) or
the keyctl(2) KEYCTL_GET_PERSISTENT operation.)
The default value in this file is 259200 (i.e., 3 days).
The following files (which are writable by privileged pro‐
cesses) are used to enforce quotas on the number of keys and
number of bytes of data that can be stored in key payloads:
/proc/sys/kernel/keys/maxbytes (since Linux 2.6.26)
This is the maximum number of bytes of data that a non‐
root user can hold in the payloads of the keys owned by
the user.
The default value in this file is 20,000.
/proc/sys/kernel/keys/maxkeys (since Linux 2.6.26)
This is the maximum number of keys that a nonroot user
may own.
The default value in this file is 200.
/proc/sys/kernel/keys/root_maxbytes (since Linux 2.6.26)
This is the maximum number of bytes of data that the
root user (UID 0 in the root user namespace) can hold in
the payloads of the keys owned by root.
The default value in this file is 25,000,000.
/proc/sys/kernel/keys/root_maxkeys (since Linux 2.6.26)
This is the maximum number of keys that the root user
(UID 0 in the root user namespace) may own.
The default value in this file is 1,000,000.
With respect to keyrings, note that each link in a keyring con‐
sumes 4 bytes of the keyring payload.
Users
The Linux key-management facility has a number of users and
usages, but is not limited to those that already exist.
In-kernel users of this facility include:
Network filesystems - DNS
The kernel uses the upcall mechanism provided by the
keys to upcall to user space to do DNS lookups and then
to cache the results.
AF_RXRPC and kAFS - Authentication
The AF_RXRPC network protocol and the in-kernel AFS
filesystem use keys to store the ticket needed to do
secured or encrypted traffic. These are then looked up
by network operations on AF_RXRPC and filesystem opera‐
tions on kAFS.
NFS - User ID mapping
The NFS filesystem uses keys to store mappings of for‐
eign user IDs to local user IDs.
CIFS - Password
The CIFS filesystem uses keys to store passwords for
accessing remote shares.
Module verification
The kernel build process can be made to cryptographi‐
cally sign modules. That signature is then checked when
a module is loaded.
User-space users of this facility include:
Kerberos key storage
The MIT Kerberos 5 facility (libkrb5) can use keys to
store authentication tokens which can be made to be
automatically cleaned up a set time after the user last
uses them, but until then permits them to hang around
after the user has logged out so that cron scripts can
use them.
SEE ALSO
keyutils(7), persistent-keyring(7), process-keyring(7),
session-keyring(7), thread-keyring(7), user-keyring(7),
user-session-keyring(7), pam_keyinit(8)
Linux 2016-11-01 KEYRINGS(7)
--
Michael Kerrisk, man7.org Training and Consulting
mtk-ASgREoAs3yw@public.gmane.org, http://man7.org/training/
"The Linux Programming Interface" -- http://man7.org/tlpi/
[-- Attachment #2: keyrings.7 --]
[-- Type: application/x-troff-man, Size: 25432 bytes --]
^ permalink raw reply [flat|nested] 36+ messages in thread
* [PATCH draft_keys 0/7] Minor edits
[not found] ` <51643019-bb42-4066-c824-c55b9e668ac6-ASgREoAs3yw@public.gmane.org>
@ 2016-11-25 1:00 ` Eugene Syromyatnikov
2016-11-25 10:01 ` Michael Kerrisk (man-pages)
2016-11-25 1:00 ` [PATCH draft_keys 1/7] keyctl.2: tfix Eugene Syromyatnikov
` (6 subsequent siblings)
7 siblings, 1 reply; 36+ messages in thread
From: Eugene Syromyatnikov @ 2016-11-25 1:00 UTC (permalink / raw)
To: mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w; +Cc: linux-man-u79uwXL29TY76Z2rM5mHXA
Hello.
There are some minor edits to keyrings(7) (and one minor typo fix for
keyctl(2)).
One additional idea: add_key(2) and request_key(2) have some duplication
regarding special keyrings (as already noted in comments there), maybe
add overview information regarding them (along with constant names)
to the Keyrings section of the keyrings(7) and then reference it from
add_key/request_key (with the notes regarding non-applicability of
requestor keyring in add_key and such).
Another thought is to document group keyring (that it is present since
beginning but has never been implemented), since it has a constant
definition and one may think (upon possible discovery in headers) that
it is just some undocumented feature.
Eugene Syromyatnikov (7):
keyctl.2: tfix
keyrings.7: minor clarification rearding storage method used in
keyrings
keyrings.7: spacing fix
keyrings.7: minor clarification regarding decision whether to store
big_key in tmpfs or not
keyrings.7: tfix
keyrings.7: tfix
keyrings.7: information regarding pre-3.17 limits on
root_maxbytes/root_maxkeys
man2/keyctl.2 | 1 -
man7/keyrings.7 | 20 ++++++++++++--------
2 files changed, 12 insertions(+), 9 deletions(-)
--
2.10.2
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply [flat|nested] 36+ messages in thread
* [PATCH draft_keys 1/7] keyctl.2: tfix
[not found] ` <51643019-bb42-4066-c824-c55b9e668ac6-ASgREoAs3yw@public.gmane.org>
2016-11-25 1:00 ` [PATCH draft_keys 0/7] Minor edits Eugene Syromyatnikov
@ 2016-11-25 1:00 ` Eugene Syromyatnikov
2016-11-25 8:35 ` Michael Kerrisk (man-pages)
2016-11-25 1:00 ` [PATCH draft_keys 2/7] keyrings.7: minor clarification rearding storage method used in keyrings Eugene Syromyatnikov
` (5 subsequent siblings)
7 siblings, 1 reply; 36+ messages in thread
From: Eugene Syromyatnikov @ 2016-11-25 1:00 UTC (permalink / raw)
To: mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w; +Cc: linux-man-u79uwXL29TY76Z2rM5mHXA
---
man2/keyctl.2 | 1 -
1 file changed, 1 deletion(-)
diff --git a/man2/keyctl.2 b/man2/keyctl.2
index d723b9a..cf2c991 100644
--- a/man2/keyctl.2
+++ b/man2/keyctl.2
@@ -931,7 +931,6 @@ Use the process-specific keyring
.RB ( process-keyring (7))
as the new default keyring.
.TP
-.TP
.BR KEY_REQKEY_DEFL_SESSION_KEYRING
Use the session-specific keyring
.RB ( session-keyring (7))
--
2.10.2
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply related [flat|nested] 36+ messages in thread
* [PATCH draft_keys 2/7] keyrings.7: minor clarification rearding storage method used in keyrings
[not found] ` <51643019-bb42-4066-c824-c55b9e668ac6-ASgREoAs3yw@public.gmane.org>
2016-11-25 1:00 ` [PATCH draft_keys 0/7] Minor edits Eugene Syromyatnikov
2016-11-25 1:00 ` [PATCH draft_keys 1/7] keyctl.2: tfix Eugene Syromyatnikov
@ 2016-11-25 1:00 ` Eugene Syromyatnikov
2016-11-25 8:37 ` Michael Kerrisk (man-pages)
2016-11-25 1:01 ` [PATCH draft_keys 3/7] keyrings.7: spacing fix Eugene Syromyatnikov
` (4 subsequent siblings)
7 siblings, 1 reply; 36+ messages in thread
From: Eugene Syromyatnikov @ 2016-11-25 1:00 UTC (permalink / raw)
To: mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w; +Cc: linux-man-u79uwXL29TY76Z2rM5mHXA
---
man7/keyrings.7 | 5 ++++-
1 file changed, 4 insertions(+), 1 deletion(-)
diff --git a/man7/keyrings.7 b/man7/keyrings.7
index 81de084..ed3bbee 100644
--- a/man7/keyrings.7
+++ b/man7/keyrings.7
@@ -117,7 +117,10 @@ to which the key is of interest
.IR """afs:mykey""" ).
.TP
.I """keyring"""
-Keyrings are special keys whose payload consists of a set of links
+'\" Note that keyrings use different fields in struct key in order to store
+'\" their data - index_key instead of type/description and name_link/keys
+'\" instead of payload.
+Keyrings are special keys which store a set of links
to other keys (including other keyrings),
analogous to a directory holding links to files.
The main purpose of a keyring is to prevent other keys from
--
2.10.2
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply related [flat|nested] 36+ messages in thread
* [PATCH draft_keys 3/7] keyrings.7: spacing fix
[not found] ` <51643019-bb42-4066-c824-c55b9e668ac6-ASgREoAs3yw@public.gmane.org>
` (2 preceding siblings ...)
2016-11-25 1:00 ` [PATCH draft_keys 2/7] keyrings.7: minor clarification rearding storage method used in keyrings Eugene Syromyatnikov
@ 2016-11-25 1:01 ` Eugene Syromyatnikov
2016-11-25 8:39 ` Michael Kerrisk (man-pages)
2016-11-25 1:01 ` [PATCH draft_keys 4/7] keyrings.7: minor clarification regarding decision whether to store big_key in tmpfs or not Eugene Syromyatnikov
` (3 subsequent siblings)
7 siblings, 1 reply; 36+ messages in thread
From: Eugene Syromyatnikov @ 2016-11-25 1:01 UTC (permalink / raw)
To: mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w; +Cc: linux-man-u79uwXL29TY76Z2rM5mHXA
---
man7/keyrings.7 | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/man7/keyrings.7 b/man7/keyrings.7
index ed3bbee..c15a273 100644
--- a/man7/keyrings.7
+++ b/man7/keyrings.7
@@ -145,7 +145,7 @@ that should not be readable from user space.
.\" commit ab3c3587f8cda9083209a61dbe3a4407d3cada10
This key type is similar to the
.I """user"""
-key type, but it may hold a payload of up to 1MiB in size.
+key type, but it may hold a payload of up to 1 MiB in size.
The data may be stored in the swap space rather than in kernel memory
if the data size exceeds the overhead of storing the data in swap space
(a tmpfs file is used, which requires filesystem structures
--
2.10.2
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply related [flat|nested] 36+ messages in thread
* [PATCH draft_keys 4/7] keyrings.7: minor clarification regarding decision whether to store big_key in tmpfs or not
[not found] ` <51643019-bb42-4066-c824-c55b9e668ac6-ASgREoAs3yw@public.gmane.org>
` (3 preceding siblings ...)
2016-11-25 1:01 ` [PATCH draft_keys 3/7] keyrings.7: spacing fix Eugene Syromyatnikov
@ 2016-11-25 1:01 ` Eugene Syromyatnikov
2016-11-25 8:40 ` Michael Kerrisk (man-pages)
2016-11-25 1:01 ` [PATCH draft_keys 5/7] keyrings.7: tfix Eugene Syromyatnikov
` (2 subsequent siblings)
7 siblings, 1 reply; 36+ messages in thread
From: Eugene Syromyatnikov @ 2016-11-25 1:01 UTC (permalink / raw)
To: mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w; +Cc: linux-man-u79uwXL29TY76Z2rM5mHXA
---
man7/keyrings.7 | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/man7/keyrings.7 b/man7/keyrings.7
index c15a273..2f452c6 100644
--- a/man7/keyrings.7
+++ b/man7/keyrings.7
@@ -149,7 +149,8 @@ key type, but it may hold a payload of up to 1 MiB in size.
The data may be stored in the swap space rather than in kernel memory
if the data size exceeds the overhead of storing the data in swap space
(a tmpfs file is used, which requires filesystem structures
-to be allocated in the kernel).
+to be allocated in the kernel; the size of these determines size threshold
+above which tmpfs storage method is used).
This key type is useful for tasks such as holding Kerberos ticket caches.
.PP
There are more specialized key types available also,
--
2.10.2
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply related [flat|nested] 36+ messages in thread
* [PATCH draft_keys 5/7] keyrings.7: tfix
[not found] ` <51643019-bb42-4066-c824-c55b9e668ac6-ASgREoAs3yw@public.gmane.org>
` (4 preceding siblings ...)
2016-11-25 1:01 ` [PATCH draft_keys 4/7] keyrings.7: minor clarification regarding decision whether to store big_key in tmpfs or not Eugene Syromyatnikov
@ 2016-11-25 1:01 ` Eugene Syromyatnikov
2016-11-25 8:42 ` Michael Kerrisk (man-pages)
2016-11-25 1:01 ` [PATCH draft_keys 6/7] " Eugene Syromyatnikov
2016-11-25 1:01 ` [PATCH draft_keys 7/7] keyrings.7: information regarding pre-3.17 limits on root_maxbytes/root_maxkeys Eugene Syromyatnikov
7 siblings, 1 reply; 36+ messages in thread
From: Eugene Syromyatnikov @ 2016-11-25 1:01 UTC (permalink / raw)
To: mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w; +Cc: linux-man-u79uwXL29TY76Z2rM5mHXA
---
man7/keyrings.7 | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/man7/keyrings.7 b/man7/keyrings.7
index 2f452c6..2da882c 100644
--- a/man7/keyrings.7
+++ b/man7/keyrings.7
@@ -489,7 +489,7 @@ and may filter out further keys that the process is not authorized to view.
An example of the data that one might see in this file is the following:
.nf
-.in 0n
+.in +4n
009a2028 I--Q--- 1 perm 3f010000 1000 1000 user krb_ccache:primary: 12
1806c4ba I--Q--- 1 perm 3f010000 1000 1000 keyring _pid: 2
25d3a08f I--Q--- 1 perm 1f3f0000 1000 65534 keyring _uid_ses.1000: 1
--
2.10.2
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply related [flat|nested] 36+ messages in thread
* [PATCH draft_keys 6/7] keyrings.7: tfix
[not found] ` <51643019-bb42-4066-c824-c55b9e668ac6-ASgREoAs3yw@public.gmane.org>
` (5 preceding siblings ...)
2016-11-25 1:01 ` [PATCH draft_keys 5/7] keyrings.7: tfix Eugene Syromyatnikov
@ 2016-11-25 1:01 ` Eugene Syromyatnikov
2016-11-25 8:43 ` Michael Kerrisk (man-pages)
2016-11-25 1:01 ` [PATCH draft_keys 7/7] keyrings.7: information regarding pre-3.17 limits on root_maxbytes/root_maxkeys Eugene Syromyatnikov
7 siblings, 1 reply; 36+ messages in thread
From: Eugene Syromyatnikov @ 2016-11-25 1:01 UTC (permalink / raw)
To: mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w; +Cc: linux-man-u79uwXL29TY76Z2rM5mHXA
---
man7/keyrings.7 | 2 --
1 file changed, 2 deletions(-)
diff --git a/man7/keyrings.7 b/man7/keyrings.7
index 2da882c..9dac4db 100644
--- a/man7/keyrings.7
+++ b/man7/keyrings.7
@@ -588,8 +588,6 @@ The key type (user, keyring, etc.)
.TP
Description
The key description (name).
-.TP
-Description
This field contains descriptive information about the key.
For most key types, it has the form
--
2.10.2
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply related [flat|nested] 36+ messages in thread
* [PATCH draft_keys 7/7] keyrings.7: information regarding pre-3.17 limits on root_maxbytes/root_maxkeys
[not found] ` <51643019-bb42-4066-c824-c55b9e668ac6-ASgREoAs3yw@public.gmane.org>
` (6 preceding siblings ...)
2016-11-25 1:01 ` [PATCH draft_keys 6/7] " Eugene Syromyatnikov
@ 2016-11-25 1:01 ` Eugene Syromyatnikov
2016-11-25 8:54 ` Michael Kerrisk (man-pages)
7 siblings, 1 reply; 36+ messages in thread
From: Eugene Syromyatnikov @ 2016-11-25 1:01 UTC (permalink / raw)
To: mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w; +Cc: linux-man-u79uwXL29TY76Z2rM5mHXA
---
man7/keyrings.7 | 6 ++++--
1 file changed, 4 insertions(+), 2 deletions(-)
diff --git a/man7/keyrings.7 b/man7/keyrings.7
index 9dac4db..12853e8 100644
--- a/man7/keyrings.7
+++ b/man7/keyrings.7
@@ -734,7 +734,8 @@ This is the maximum number of bytes of data that the root user
(UID 0 in the root user namespace)
can hold in the payloads of the keys owned by root.
-The default value in this file is 25,000,000.
+.\"738c5d190f6540539a04baf36ce21d46b5da04bd
+The default value in this file is 25,000,000 (was 20,000 before Linux 3.17).
.\" commit 0b77f5bfb45c13e1e5142374f9d6ca75292252a4
.TP
.IR /proc/sys/kernel/keys/root_maxkeys " (since Linux 2.6.26)"
@@ -743,7 +744,8 @@ This is the maximum number of keys that the root user
(UID 0 in the root user namespace)
may own.
-The default value in this file is 1,000,000.
+.\"738c5d190f6540539a04baf36ce21d46b5da04bd
+The default value in this file is 1,000,000 (was 200 before Linux 3.17).
.PP
With respect to keyrings,
note that each link in a keyring consumes 4 bytes of the keyring payload.
--
2.10.2
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply related [flat|nested] 36+ messages in thread
* Re: [PATCH draft_keys 1/7] keyctl.2: tfix
2016-11-25 1:00 ` [PATCH draft_keys 1/7] keyctl.2: tfix Eugene Syromyatnikov
@ 2016-11-25 8:35 ` Michael Kerrisk (man-pages)
0 siblings, 0 replies; 36+ messages in thread
From: Michael Kerrisk (man-pages) @ 2016-11-25 8:35 UTC (permalink / raw)
To: Eugene Syromyatnikov
Cc: mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w, linux-man-u79uwXL29TY76Z2rM5mHXA
On 11/25/2016 02:00 AM, Eugene Syromyatnikov wrote:
> ---
> man2/keyctl.2 | 1 -
> 1 file changed, 1 deletion(-)
Applied. Thanks, Eugene.
Cheers,
Michael
> diff --git a/man2/keyctl.2 b/man2/keyctl.2
> index d723b9a..cf2c991 100644
> --- a/man2/keyctl.2
> +++ b/man2/keyctl.2
> @@ -931,7 +931,6 @@ Use the process-specific keyring
> .RB ( process-keyring (7))
> as the new default keyring.
> .TP
> -.TP
> .BR KEY_REQKEY_DEFL_SESSION_KEYRING
> Use the session-specific keyring
> .RB ( session-keyring (7))
>
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply [flat|nested] 36+ messages in thread
* Re: [PATCH draft_keys 2/7] keyrings.7: minor clarification rearding storage method used in keyrings
2016-11-25 1:00 ` [PATCH draft_keys 2/7] keyrings.7: minor clarification rearding storage method used in keyrings Eugene Syromyatnikov
@ 2016-11-25 8:37 ` Michael Kerrisk (man-pages)
0 siblings, 0 replies; 36+ messages in thread
From: Michael Kerrisk (man-pages) @ 2016-11-25 8:37 UTC (permalink / raw)
To: Eugene Syromyatnikov
Cc: mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w, linux-man-u79uwXL29TY76Z2rM5mHXA
On 11/25/2016 02:00 AM, Eugene Syromyatnikov wrote:
> ---
> man7/keyrings.7 | 5 ++++-
> 1 file changed, 4 insertions(+), 1 deletion(-)
Ahh -- good catch! Applied. Thanks, Eugene.
There was one typo in the title of the patch, but a more general
point: when the patch subject isn't tfix/wfix/etc., the first
word of the subject should have an initial capital
(i.e., s/minor/Minor/).
Cheers,
Michael
> diff --git a/man7/keyrings.7 b/man7/keyrings.7
> index 81de084..ed3bbee 100644
> --- a/man7/keyrings.7
> +++ b/man7/keyrings.7
> @@ -117,7 +117,10 @@ to which the key is of interest
> .IR """afs:mykey""" ).
> .TP
> .I """keyring"""
> -Keyrings are special keys whose payload consists of a set of links
> +'\" Note that keyrings use different fields in struct key in order to store
> +'\" their data - index_key instead of type/description and name_link/keys
> +'\" instead of payload.
> +Keyrings are special keys which store a set of links
> to other keys (including other keyrings),
> analogous to a directory holding links to files.
> The main purpose of a keyring is to prevent other keys from
>
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply [flat|nested] 36+ messages in thread
* Re: [PATCH draft_keys 3/7] keyrings.7: spacing fix
2016-11-25 1:01 ` [PATCH draft_keys 3/7] keyrings.7: spacing fix Eugene Syromyatnikov
@ 2016-11-25 8:39 ` Michael Kerrisk (man-pages)
0 siblings, 0 replies; 36+ messages in thread
From: Michael Kerrisk (man-pages) @ 2016-11-25 8:39 UTC (permalink / raw)
To: Eugene Syromyatnikov
Cc: mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w, linux-man-u79uwXL29TY76Z2rM5mHXA
On 11/25/2016 02:01 AM, Eugene Syromyatnikov wrote:
> ---
> man7/keyrings.7 | 2 +-
> 1 file changed, 1 insertion(+), 1 deletion(-)
Applied. Thanks, Eugene.
Cheers,
Michael
> diff --git a/man7/keyrings.7 b/man7/keyrings.7
> index ed3bbee..c15a273 100644
> --- a/man7/keyrings.7
> +++ b/man7/keyrings.7
> @@ -145,7 +145,7 @@ that should not be readable from user space.
> .\" commit ab3c3587f8cda9083209a61dbe3a4407d3cada10
> This key type is similar to the
> .I """user"""
> -key type, but it may hold a payload of up to 1MiB in size.
> +key type, but it may hold a payload of up to 1 MiB in size.
> The data may be stored in the swap space rather than in kernel memory
> if the data size exceeds the overhead of storing the data in swap space
> (a tmpfs file is used, which requires filesystem structures
>
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply [flat|nested] 36+ messages in thread
* Re: [PATCH draft_keys 4/7] keyrings.7: minor clarification regarding decision whether to store big_key in tmpfs or not
2016-11-25 1:01 ` [PATCH draft_keys 4/7] keyrings.7: minor clarification regarding decision whether to store big_key in tmpfs or not Eugene Syromyatnikov
@ 2016-11-25 8:40 ` Michael Kerrisk (man-pages)
0 siblings, 0 replies; 36+ messages in thread
From: Michael Kerrisk (man-pages) @ 2016-11-25 8:40 UTC (permalink / raw)
To: Eugene Syromyatnikov
Cc: mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w, linux-man-u79uwXL29TY76Z2rM5mHXA
On 11/25/2016 02:01 AM, Eugene Syromyatnikov wrote:
> ---
> man7/keyrings.7 | 3 ++-
> 1 file changed, 2 insertions(+), 1 deletion(-)
Applied. Thanks, Eugene.
Cheers,
Michael
> diff --git a/man7/keyrings.7 b/man7/keyrings.7
> index c15a273..2f452c6 100644
> --- a/man7/keyrings.7
> +++ b/man7/keyrings.7
> @@ -149,7 +149,8 @@ key type, but it may hold a payload of up to 1 MiB in size.
> The data may be stored in the swap space rather than in kernel memory
> if the data size exceeds the overhead of storing the data in swap space
> (a tmpfs file is used, which requires filesystem structures
> -to be allocated in the kernel).
> +to be allocated in the kernel; the size of these determines size threshold
> +above which tmpfs storage method is used).
> This key type is useful for tasks such as holding Kerberos ticket caches.
> .PP
> There are more specialized key types available also,
>
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply [flat|nested] 36+ messages in thread
* Re: [PATCH draft_keys 5/7] keyrings.7: tfix
2016-11-25 1:01 ` [PATCH draft_keys 5/7] keyrings.7: tfix Eugene Syromyatnikov
@ 2016-11-25 8:42 ` Michael Kerrisk (man-pages)
0 siblings, 0 replies; 36+ messages in thread
From: Michael Kerrisk (man-pages) @ 2016-11-25 8:42 UTC (permalink / raw)
To: Eugene Syromyatnikov
Cc: mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w, linux-man-u79uwXL29TY76Z2rM5mHXA
Hi Eugene,
On 11/25/2016 02:01 AM, Eugene Syromyatnikov wrote:
> ---
> man7/keyrings.7 | 2 +-
> 1 file changed, 1 insertion(+), 1 deletion(-)
Not applied! The indentation choice here was deliberate,
to prevent the rendered text going over 80 columns.
Cheers,
Michael
>
> diff --git a/man7/keyrings.7 b/man7/keyrings.7
> index 2f452c6..2da882c 100644
> --- a/man7/keyrings.7
> +++ b/man7/keyrings.7
> @@ -489,7 +489,7 @@ and may filter out further keys that the process is not authorized to view.
> An example of the data that one might see in this file is the following:
>
> .nf
> -.in 0n
> +.in +4n
> 009a2028 I--Q--- 1 perm 3f010000 1000 1000 user krb_ccache:primary: 12
> 1806c4ba I--Q--- 1 perm 3f010000 1000 1000 keyring _pid: 2
> 25d3a08f I--Q--- 1 perm 1f3f0000 1000 65534 keyring _uid_ses.1000: 1
>
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply [flat|nested] 36+ messages in thread
* Re: [PATCH draft_keys 6/7] keyrings.7: tfix
2016-11-25 1:01 ` [PATCH draft_keys 6/7] " Eugene Syromyatnikov
@ 2016-11-25 8:43 ` Michael Kerrisk (man-pages)
0 siblings, 0 replies; 36+ messages in thread
From: Michael Kerrisk (man-pages) @ 2016-11-25 8:43 UTC (permalink / raw)
To: Eugene Syromyatnikov
Cc: mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w, linux-man-u79uwXL29TY76Z2rM5mHXA
On 11/25/2016 02:01 AM, Eugene Syromyatnikov wrote:
> ---
> man7/keyrings.7 | 2 --
> 1 file changed, 2 deletions(-)
Applied. Thanks, Eugene.
Cheers,
Michael
> diff --git a/man7/keyrings.7 b/man7/keyrings.7
> index 2da882c..9dac4db 100644
> --- a/man7/keyrings.7
> +++ b/man7/keyrings.7
> @@ -588,8 +588,6 @@ The key type (user, keyring, etc.)
> .TP
> Description
> The key description (name).
> -.TP
> -Description
> This field contains descriptive information about the key.
> For most key types, it has the form
>
>
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply [flat|nested] 36+ messages in thread
* Re: [PATCH draft_keys 7/7] keyrings.7: information regarding pre-3.17 limits on root_maxbytes/root_maxkeys
2016-11-25 1:01 ` [PATCH draft_keys 7/7] keyrings.7: information regarding pre-3.17 limits on root_maxbytes/root_maxkeys Eugene Syromyatnikov
@ 2016-11-25 8:54 ` Michael Kerrisk (man-pages)
0 siblings, 0 replies; 36+ messages in thread
From: Michael Kerrisk (man-pages) @ 2016-11-25 8:54 UTC (permalink / raw)
To: Eugene Syromyatnikov
Cc: mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w, linux-man-u79uwXL29TY76Z2rM5mHXA
On 11/25/2016 02:01 AM, Eugene Syromyatnikov wrote:
> ---
> man7/keyrings.7 | 6 ++++--
> 1 file changed, 4 insertions(+), 2 deletions(-)
Applied. Thanks, Eugene.
Cheers,
Michael
> diff --git a/man7/keyrings.7 b/man7/keyrings.7
> index 9dac4db..12853e8 100644
> --- a/man7/keyrings.7
> +++ b/man7/keyrings.7
> @@ -734,7 +734,8 @@ This is the maximum number of bytes of data that the root user
> (UID 0 in the root user namespace)
> can hold in the payloads of the keys owned by root.
>
> -The default value in this file is 25,000,000.
> +.\"738c5d190f6540539a04baf36ce21d46b5da04bd
> +The default value in this file is 25,000,000 (was 20,000 before Linux 3.17).
> .\" commit 0b77f5bfb45c13e1e5142374f9d6ca75292252a4
> .TP
> .IR /proc/sys/kernel/keys/root_maxkeys " (since Linux 2.6.26)"
> @@ -743,7 +744,8 @@ This is the maximum number of keys that the root user
> (UID 0 in the root user namespace)
> may own.
>
> -The default value in this file is 1,000,000.
> +.\"738c5d190f6540539a04baf36ce21d46b5da04bd
> +The default value in this file is 1,000,000 (was 200 before Linux 3.17).
> .PP
> With respect to keyrings,
> note that each link in a keyring consumes 4 bytes of the keyring payload.
>
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply [flat|nested] 36+ messages in thread
* Re: [PATCH draft_keys 0/7] Minor edits
2016-11-25 1:00 ` [PATCH draft_keys 0/7] Minor edits Eugene Syromyatnikov
@ 2016-11-25 10:01 ` Michael Kerrisk (man-pages)
0 siblings, 0 replies; 36+ messages in thread
From: Michael Kerrisk (man-pages) @ 2016-11-25 10:01 UTC (permalink / raw)
To: Eugene Syromyatnikov
Cc: mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w, linux-man-u79uwXL29TY76Z2rM5mHXA
Hi Eugene,
On 11/25/2016 02:00 AM, Eugene Syromyatnikov wrote:
> Hello.
>
> There are some minor edits to keyrings(7) (and one minor typo fix for
> keyctl(2)).
Thanks for this series!
> One additional idea: add_key(2) and request_key(2) have some duplication
> regarding special keyrings (as already noted in comments there),
(yes.)
> maybe
> add overview information regarding them (along with constant names)
> to the Keyrings section of the keyrings(7) and then reference it from
> add_key/request_key (with the notes regarding non-applicability of
> requestor keyring in add_key and such).
Yes, I'd wondered about doing something like that. But, I'm
balancing that against inconvenience to the reader, by forcing
them to look at another page. So far, it seems best to leave
things as they are, but I'm still thinking about it.
> Another thought is to document group keyring (that it is present since
> beginning but has never been implemented), since it has a constant
> definition and one may think (upon possible discovery in headers) that
> it is just some undocumented feature.
I've added a few words on this to keyrings(7).
Everything is now pushed to Git.
Cheers,
Michael
> Eugene Syromyatnikov (7):
> keyctl.2: tfix
> keyrings.7: minor clarification rearding storage method used in
> keyrings
> keyrings.7: spacing fix
> keyrings.7: minor clarification regarding decision whether to store
> big_key in tmpfs or not
> keyrings.7: tfix
> keyrings.7: tfix
> keyrings.7: information regarding pre-3.17 limits on
> root_maxbytes/root_maxkeys
>
> man2/keyctl.2 | 1 -
> man7/keyrings.7 | 20 ++++++++++++--------
> 2 files changed, 12 insertions(+), 9 deletions(-)
>
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply [flat|nested] 36+ messages in thread
* Re: Revised keyrings(7) man page for review
[not found] ` <51643019-bb42-4066-c824-c55b9e668ac6-ASgREoAs3yw@public.gmane.org>
@ 2016-11-26 12:51 ` Michael Kerrisk (man-pages)
2016-11-25 1:00 ` [PATCH draft_keys 1/7] keyctl.2: tfix Eugene Syromyatnikov
` (6 subsequent siblings)
7 siblings, 0 replies; 36+ messages in thread
From: Michael Kerrisk (man-pages) @ 2016-11-26 12:51 UTC (permalink / raw)
To: Michael Kerrisk, David Howells
Cc: mtk.manpages, lkml, Eugene Syromyatnikov, keyrings, linux-man
Hi David,
Would you have a chance to look at this page?
Cheers
Michael
On 11/04/2016 04:47 PM, Michael Kerrisk wrote:
> Hi David,
>
> As part of the process of adopting the *.7 pages from
> keyutils into man-pages, I've made some significant
> extensions to the keyrings(7) page. Among the more notable
> changes:
>
> * Expanded the detail in "Key types"
> * Addition of a section on the various /proc files
> * Various other minor reworkings elsewhere in the text
>
> Would you would be willing to review the new page, please?
> (The page source file is attached, in case you want to
> see all the formatting.)
>
> Cheers,
>
> Michael
>
>
> ====
>
> NAME
> keyrings - in-kernel key management and retention facility
>
> DESCRIPTION
> The Linux key-management facility is primarily a way for driv‐
> ers to retain or cache security data, authentication keys,
> encryption keys, and other data in the kernel.
>
> System call interfaces are provided so that user-space programs
> can manage those objects and also use the facility for their
> own purposes.
>
> A library and some user-space utilities are provided to allow
> access to the facility. See keyctl(1), keyctl(3), and keyu‐
> tils(7) for more information.
>
> Keys
> A key has the following attributes:
>
> Serial number (ID)
> This is a unique integer handle by which a key is
> referred to in system call arguments. The serial number
> is sometimes synonymously referred as the key ID. Pro‐
> grammatically, key serial numbers are represented using
> the type key_serial_t.
>
> Type A key's type defines what sort of data can be held in
> the key, how the proposed content of the key will be
> parsed, and how the payload will be used.
>
> There are a number of general purpose types available,
> plus some specialist types defined by specific drivers.
>
> Description (name)
> The key description is a printable string that is used
> as the search term for the key (in conjunction with the
> key type) as well as a display name. During searches,
> the description may be partially matched or exactly
> matched.
>
> Payload (data)
> The payload is the actual content of a key. This is
> usually set when a key is created, but it is possible
> for the kernel to upcall to user space to finish the
> instantiation of a key if that key wasn't already known
> to the kernel when it was requested. (Details can be
> found in request_key(2).)
>
> A key's payload can be read and updated if the key type
> supports it and if suitable permission is granted to the
> caller.
>
> Access rights
> Much as files do, each key has an owning user ID, an
> owning group ID, and a security label. They also have a
> set of permissions, though there are more than for a
> normal UNIX file, and there is an additional category
> beyond the usual user, group, and other (see below).
>
> Note that keys are quota controlled since they represent
> unswappable kernel memory and the owning user ID speci‐
> fies whose quota is to be debited.
>
> Expiration time
> Each key can have an expiration time set. When that
> time is reached, the key is marked as being expired and
> accesses to it fail with EKEYEXPIRED. If not deleted,
> updated, or replaced, after a set amount of time,
> expired keys are automatically removed along with all
> links to them, and attempts to access the key will fail
> with the error ENOKEY.
>
> Reference count
> Each key has a reference count. Keys are referenced by
> keyrings, by currently active users, and by a process's
> credentials. When the reference count reaches zero, the
> key is scheduled for garbage collection.
>
> Key types
> The facility provides several basic types of key:
>
> "user" This is a general purpose key type. The key is kept
> entirely within kernel memory. The payload may be read
> and updated by user-space applications.
>
> The payload for keys of this type is a blob of arbitrary
> data of up to 32,767 bytes.
>
> The description may be any valid string, though it is
> preferred that it start with a colon-delimited prefix
> representing the service to which the key is of interest
> (for instance "afs:mykey").
>
> "keyring"
> Keyrings are special keys whose payload consists of a
> set of links to other keys (including other keyrings),
> analogous to a directory holding links to files. The
> main purpose of a keyring is to prevent other keys from
> being garbage collected because nothing refers to them.
>
> "logon" (since Linux 3.3)
> This key type is essentially the same as "user", but it
> does not provide reading (i.e., the keyctl(2)
> KEYCTL_READ operation), meaning that the key payload is
> never visible from user space. This is suitable for
> storing username-password pairs that you do not want to
> be readable from user space.
>
> "big_key" (since Linux 3.13)
> This key type is similar to the "user" key type, but it
> may hold a payload of up to 1MiB in size. The data may
> be stored in the swap space rather than in kernel memory
> if the data size exceeds the overhead of storing the
> data in swap space (a tmpfs file is used, which requires
> filesystem structures to be allocated in the kernel).
> This key type is useful for tasks such as holding Ker‐
> beros ticket caches.
>
> There are more specialized key types available also, but
> they're not discussed here as they're not intended for normal
> user-space use.
>
> Keyrings
> As previously mentioned, keyrings are a special type of key
> that contain links to other keys (which may include other
> keyrings). Keys may be linked to by multiple keyrings.
> Keyrings may be considered as analogous to UNIX directories
> where each directory contains a set of hard links to files.
>
> Various operations (system calls) may be applied only to
> keyrings:
>
> Adding A key may be added to a keyring by system calls that
> create keys. This prevents the new key from being imme‐
> diately deleted when the system call driver releases its
> last reference to the key.
>
> Linking
> A link may be added to a keyring pointing to a key that
> is already known, provided this does not create a self-
> referential cycle.
>
> Unlinking
> A link may be removed from a keyring. When the last
> link to a key is removed, that key will be scheduled for
> deletion by the garbage collector.
>
> Clearing
> All the links may be removed from a keyring.
>
> Searching
> A keyring may be considered the root of a tree or sub‐
> tree in which keyrings form the branches and non-
> keyrings the leaves. This tree may be searched for a
> leaf matching a particular type and description.
>
> See keyctl_clear(3), keyctl_link(3), keyctl_search(3), and
> keyctl_unlink(3) for more information.
>
> Anchoring keys
> To prevent a key from being prematurely garbage collected, it
> must anchored to keep its reference count elevated when it is
> not in active use by the kernel.
>
> Keyrings are used to anchor other keys - each link is a refer‐
> ence on a key - but whilst keyrings are available to link to
> keys, keyrings themselves are just keys and are also subject to
> the same anchoring necessity.
>
> The kernel makes available a number of anchor keyrings. Note
> that some of these keyrings will be created only when first
> accessed.
>
> Process keyrings
> Process credentials themselves reference keyrings with
> specific semantics. These keyrings are pinned as long
> as the set of credentials exists, which is usually as
> long as the process exists.
>
> There are three keyrings with different inheri‐
> tance/sharing rules: The session-keyring(7) (inherited
> and shared by all child processes), the process-
> keyring(7) (shared by all threads in a process) and the
> thread-keyring(7) (specific to a particular thread).
>
> User keyrings
> Each UID known to the kernel has a record that contains
> two keyrings: the user-keyring(7) and the user-session-
> keyring(7). These exist for as long as the UID record
> in the kernel exists. A link to the user keyring is
> placed in a new session keyring by pam_keyinit(8) when a
> new login session is initiated.
>
> Persistent keyrings
> There is a persistent-keyring(7) available to each UID
> known to the system. It may persist beyond the life of
> the UID record previously mentioned, but has an expira‐
> tion time set such that it is automatically cleaned up
> after a set time. This, for example, permits cron
> scripts to use credentials left when the user logs out.
>
> Note that the expiration time is reset every time the
> persistent key is requested.
>
> Special keyrings
> There are special keyrings owned by the kernel that can
> anchor keys for special purposes. An example of this is
> the system keyring used for holding encryption keys for
> module signature verification.
>
> These special keyrings are usually closed to direct
> alteration by user space.
>
> See thread-keyring(7), process-keyring(7), session-keyring(7),
> user-keyring(7), user-session-keyring(7), and persistent-
> keyring(7) for more information.
>
> Possession
> The concept of possession is important to understanding the
> keyrings security model. Whether a thread possesses a key is
> determined by the following rules:
>
> (1) Any key or keyring that does not grant search permission to
> the caller is ignored in all the following rules.
>
> (2) A thread possesses its session, process, and thread
> keyrings directly because those are pointed to by its cre‐
> dentials.
>
> (3) If a keyring is possessed, then any key it links to is also
> possessed.
>
> (4) If any key a keyring links to is itself a keyring, then
> rule (3) applies recursively.
>
> (5) If a process is upcalled from the kernel to instantiate a
> key, then it also possesses the requester's keyrings as in
> rule (1) as if it were the requester.
>
> Note that possession is not a fundamental property of a key,
> but must rather be calculated each time the key is needed.
>
> Possession is designed to allow set-user-ID programs run from,
> say a user's shell to access the user's keys. It also allows
> the prevention of access to keys just on the basis of UID and
> GID matches.
>
> When it creates the session keyring, pam_keyinit(8) adds a link
> to the user-keyring(7), thus making the user keyring and any‐
> thing it contains possessed by default.
>
> Access rights
> Each key has the following security-related attributes:
>
> * The owning user ID
>
> * The ID of a group that is permitted to access the key
>
> * A security label
>
> * A permissions mask
>
> The permissions mask contains four sets of rights. The first
> three sets are mutually exclusive. One and only one will be in
> force for a particular access check. In order of descending
> priority, these three sets are:
>
> user The set specifies the rights granted if the key's user
> ID matches the caller's filesystem user ID.
>
> group The set specifies the rights granted if the user ID
> didn't match and the key's group ID matches the caller's
> filesystem GID or one of the caller's supplementary
> group IDs.
>
> other The set specifies the rights granted if neither the
> key's user ID nor group ID matched.
>
> The fourth set of rights is:
>
> possessor
> The set specifies the rights granted if a key is deter‐
> mined to be possessed by the caller.
>
> The complete set of rights for a key is the union of whichever
> of the first three sets is applicable plus the fourth set if
> the key is possessed.
>
> The set of rights that may be granted in each of the four masks
> is as follows:
>
> view The attributes of the key may be read. This includes
> the type, description, and access rights (excluding the
> security label).
>
> read For a key: the payload of the key may be read. For a
> keyring: the list of serial numbers (keys) to which the
> keyring has links may be read.
>
> write The payload of the key may be updated. For a keyring,
> links may be added to or removed from the keyring, the
> keyring may be cleared completely (all links are
> removed), and the key may be revoked.
>
> search For a key (or a keyring): the key may be found by a
> search. For a keyring: keys and keyrings that are
> linked to by the keyring may be searched.
>
> link Links may be created from keyrings to the key. The ini‐
> tial link to a key that is established when the key is
> created doesn't require this permission.
>
> setattr
> The ownership details and security label of the key may
> be changed, the key's expiration time may be set, and
> the key may be revoked.
>
> If any right is granted to a thread for a key,
>
>
> ┌─────────────────────────────────────────────────────┐
> │FIXME │
> ├─────────────────────────────────────────────────────┤
> │This seems to contradict the text below, which says │
> │that 'view' permission is what is significant. │
> │Which is correct? │
> └─────────────────────────────────────────────────────┘
> then that thread will see the key listed in /proc/keys. If no
> rights at all are granted, then that thread can't even tell
> that the key exists.
>
> In addition to access rights, any active Linux Security Module
> (LSM) may prevent access to a key if its policy so dictates. A
> key may be given a security label or other attribute by the LSM
> which can be retrieved.
>
> See keyctl_chown(3), keyctl_describe(3), keyctl_get_secu‐
> rity(3), keyctl_setperm(3), and selinux(8) for more informa‐
> tion.
>
> Searching for keys
> One of the key features of the Linux key-management facility is
> the ability to find a key that a process is retaining. The
> request_key(2) system call is the primary point of access for
> user-space applications to find a key. (internally, the kernel
> has something similar available for use by internal components
> that make use of keys.)
>
> The search algorithm works as follows:
>
> (1) The three process keyrings are searched in the following
> order: the thread thread-keyring(7) if it exists, the
> process-keyring(7) if it exists, and then either the ses‐
> sion-keyring(7) if it exists or the user-session-keyring(7)
> if that exists.
>
> (2) If the caller was a process that was invoked by the
> request_key(2) upcall mechanism then the keyrings of the
> original caller of that request_key(2) will be searched as
> well.
>
> (3) The search of the keyring tree is in preorder: each keyring
> is searched first for a match, then the keyrings referred
> to by that keyring are searched.
>
> (4) If a matching key is found that is valid, then the search
> terminates and that key is returned.
>
> (5) If a matching key is found that has an error state
> attached, that error state is noted and the search contin‐
> ues.
>
> (6) If valid matching key is found, then the first noted error
> state is returned; otherwise, an ENOKEY error is returned.
>
> It is also possible to search a specific keyring, in which case
> only steps (3) to (6) apply.
>
> See request_key(2) and keyctl_search(3) for more information.
>
> On-demand key creation
> If a key cannot be found, request_key(2) will, if given a call‐
> out_info argument, create a new key and then upcall to user
> space to instantiate the key. This allows keys to be created
> on an as-needed basis.
>
> Typically, this will involve the kernel forking and exec'ing
> the request-key(8) program, which will then execute the appro‐
> priate handler based on its configuration.
>
> The handler is passed a special authorization key that allows
> it and only it to instantiate the new key. This is also used
> to permit searches performed by the handler program to also
> search the requester's keyrings.
>
> See request_key(2), keyctl_assume_authority(3), keyctl_instan‐
> tiate(3), keyctl_negate(3), keyctl_reject(3), request-key(8)
> and request-key.conf(5) for more information.
>
> /proc files
> The kernel provides various /proc files that expose information
> about keys or define limits on key usage.
>
> /proc/keys (since Linux 2.6.10)
> This file exposes a list of the keys that are viewable
> by the reading process, providing various information
> about each key.
>
> The only keys included in the list are those that grant
> view permission to the reading process, regardless of
> whether or not it possesses them. LSM security checks
> are still performed, and may filter out further keys
> that the process is not authorized to view.
>
> An example of the data that one might see in this file
> is the following:
>
> 009a2028 I--Q--- 1 perm 3f010000 1000 1000 user krb_ccache:primary: 12
> 1806c4ba I--Q--- 1 perm 3f010000 1000 1000 keyring _pid: 2
> 25d3a08f I--Q--- 1 perm 1f3f0000 1000 65534 keyring _uid_ses.1000: 1
> 28576bd8 I--Q--- 3 perm 3f010000 1000 1000 keyring _krb: 1
> 2c546d21 I--Q--- 190 perm 3f030000 1000 1000 keyring _ses: 2
> 30a4e0be I------ 4 2d 1f030000 1000 65534 keyring _persistent.1000: 1
> 32100fab I--Q--- 4 perm 1f3f0000 1000 65534 keyring _uid.1000: 2
> 32a387ea I--Q--- 1 perm 3f010000 1000 1000 keyring _pid: 2
> 3ce56aea I--Q--- 5 perm 3f030000 1000 1000 keyring _ses: 1
>
> The fields shown in each line of this file are as fol‐
> lows:
>
> ID The ID (serial number) of the key, expressed in
> hexadecimal.
>
> Flags A set of flags describing the state of the key:
>
> I The key has been instantiated.
>
> R The key has been revoked.
>
> D The key is dead (i.e., has been deleted). (A
> key may be briefly in this state during
> garbage collection.)
>
> Q The key contributes to the user's quota.
>
> U The key is under construction via a callback
> to user space; see request-key(2).
>
> N The key is negatively instantiated.
>
> i The key has been invalidated.
>
> Usage This is a count of the number of kernel creden‐
> tial structures that are pinning the key (approx‐
> imately: the number of threads and open file ref‐
> erences that refer to this key).
>
> Timeout
> The amount of time until the key will expire,
> expressed in human-readable form (weeks, days,
> hours, minutes, and seconds). The string perm
> here means that the key is permanent (no time‐
> out). The string expd means that the key has
> already expired, but has not yet been garbage
> collected.
>
> Permissions
> The key permissions, expressed as four hexadeci‐
> mal bytes containing, from left to right, the
> possessor, user, group, and other permissions.
>
> UID The user ID of the key owner.
>
> GID The group ID of the key. The value -1 here means
> that the key as no group ID; this can occur in
> certain circumstances for keys created by the
> kernel.
>
> Type The key type (user, keyring, etc.)
>
> Description
> The key description (name).
>
> Description
> This field contains descriptive information about
> the key. For most key tpes, it has the form
>
> desc[: extra-info]
>
> The name subfield is the the key's description
> (name). The optional extra-info field provides
> some further information about the key. The
> information that appears here depends on the key
> type, as follows:
>
> "user" and "logon"
> The size in bytes of the key payload
> (expressed in decimal).
>
> "keyring"
> The number of keys linked to the keyring, or
> the string empty if there are no keys linked
> to the keyring.
>
> "big_key"
> The payload size in bytes, followed either by
> the string [file], if the key payload exceeds
> the threshold that means that the payload is
> stored in a (swappable) tmpfs filesystem, or
> otherwise the string [buff], indicating that
> the key is small enough to reside in kernel
> memory.
>
> For the ".request_key_auth" key type (authoriza‐
> tion key; see request_key(2)), the description
> field has the form shown in the following exam‐
> ple:
>
> key:c9a9b19 pid:28880 ci:10
>
> The three subfields are as follows:
>
> key The hexadecimal ID of the key being instan‐
> tiated in the requesting program.
>
> pid The PID of the requesting program.
>
> ci The length of the callout data with which
> the requested key should be instantiated
> (i.e., the length of the payload associated
> with the authorization key).
>
> /proc/key-users (since Linux 2.6.10)
> This file lists various information for each user ID
> that has at least one key on the system. An example of
> the data that one might see in this file is the follow‐
> ing:
>
> 0: 10 9/9 2/1000000 22/25000000
> 42: 9 9/9 8/200 106/20000
> 1000: 11 11/11 10/200 271/20000
>
> The fields shown in each line are as follows:
>
> uid The user ID.
>
> usage This is a kernel-internal usage count for the
> kernel structure used to record key users.
>
> nkeys/nikeys
> The total number of keys owned by the user, and
> the number of those keys that have been instanti‐
> ated.
>
> qnkeys/maxkeys
> The number of keys owned by the user, and the
> maximum keys that the user may own.
>
> qnbytes/maxbytes
> The number of bytes consumed in payloads of the
> keys owned by this user, and the upper limit on
> the number of bytes in key payloads for that
> user.
>
> /proc/sys/kernel/keys/gc_delay (since Linux 2.6.32)
> The value in this file specifies the interval, in sec‐
> onds, after which revoked and expired keys will be
> garbage collected. The purpose of having such an inter‐
> val is so that there is a window of time where user
> space can see an error (respectively EKEYREVOKED and
> EKEYEXPIRED) that indicates what happened to the key.
>
> The default value in this file is 300 (i.e., 5 minutes).
>
> /proc/sys/kernel/keys/persistent_keyring_expiry (since Linux
> 3.13)
> This file defines an interval, in seconds, to which the
> persistent keyring's expiration timer is reset each time
> the keyring is accessed (via keyctl_get_persistent(3) or
> the keyctl(2) KEYCTL_GET_PERSISTENT operation.)
>
> The default value in this file is 259200 (i.e., 3 days).
>
> The following files (which are writable by privileged pro‐
> cesses) are used to enforce quotas on the number of keys and
> number of bytes of data that can be stored in key payloads:
>
> /proc/sys/kernel/keys/maxbytes (since Linux 2.6.26)
> This is the maximum number of bytes of data that a non‐
> root user can hold in the payloads of the keys owned by
> the user.
>
> The default value in this file is 20,000.
>
> /proc/sys/kernel/keys/maxkeys (since Linux 2.6.26)
> This is the maximum number of keys that a nonroot user
> may own.
>
> The default value in this file is 200.
>
> /proc/sys/kernel/keys/root_maxbytes (since Linux 2.6.26)
> This is the maximum number of bytes of data that the
> root user (UID 0 in the root user namespace) can hold in
> the payloads of the keys owned by root.
>
> The default value in this file is 25,000,000.
>
> /proc/sys/kernel/keys/root_maxkeys (since Linux 2.6.26)
> This is the maximum number of keys that the root user
> (UID 0 in the root user namespace) may own.
>
> The default value in this file is 1,000,000.
>
> With respect to keyrings, note that each link in a keyring con‐
> sumes 4 bytes of the keyring payload.
>
> Users
> The Linux key-management facility has a number of users and
> usages, but is not limited to those that already exist.
>
> In-kernel users of this facility include:
>
> Network filesystems - DNS
> The kernel uses the upcall mechanism provided by the
> keys to upcall to user space to do DNS lookups and then
> to cache the results.
>
> AF_RXRPC and kAFS - Authentication
> The AF_RXRPC network protocol and the in-kernel AFS
> filesystem use keys to store the ticket needed to do
> secured or encrypted traffic. These are then looked up
> by network operations on AF_RXRPC and filesystem opera‐
> tions on kAFS.
>
> NFS - User ID mapping
> The NFS filesystem uses keys to store mappings of for‐
> eign user IDs to local user IDs.
>
> CIFS - Password
> The CIFS filesystem uses keys to store passwords for
> accessing remote shares.
>
> Module verification
> The kernel build process can be made to cryptographi‐
> cally sign modules. That signature is then checked when
> a module is loaded.
>
> User-space users of this facility include:
>
> Kerberos key storage
> The MIT Kerberos 5 facility (libkrb5) can use keys to
> store authentication tokens which can be made to be
> automatically cleaned up a set time after the user last
> uses them, but until then permits them to hang around
> after the user has logged out so that cron scripts can
> use them.
>
> SEE ALSO
> keyutils(7), persistent-keyring(7), process-keyring(7),
> session-keyring(7), thread-keyring(7), user-keyring(7),
> user-session-keyring(7), pam_keyinit(8)
>
>
>
> Linux 2016-11-01 KEYRINGS(7)
>
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
^ permalink raw reply [flat|nested] 36+ messages in thread
* Re: Revised keyrings(7) man page for review
@ 2016-11-26 12:51 ` Michael Kerrisk (man-pages)
0 siblings, 0 replies; 36+ messages in thread
From: Michael Kerrisk (man-pages) @ 2016-11-26 12:51 UTC (permalink / raw)
To: Michael Kerrisk, David Howells
Cc: mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w, lkml, Eugene Syromyatnikov,
keyrings-u79uwXL29TY76Z2rM5mHXA, linux-man
Hi David,
Would you have a chance to look at this page?
Cheers
Michael
On 11/04/2016 04:47 PM, Michael Kerrisk wrote:
> Hi David,
>
> As part of the process of adopting the *.7 pages from
> keyutils into man-pages, I've made some significant
> extensions to the keyrings(7) page. Among the more notable
> changes:
>
> * Expanded the detail in "Key types"
> * Addition of a section on the various /proc files
> * Various other minor reworkings elsewhere in the text
>
> Would you would be willing to review the new page, please?
> (The page source file is attached, in case you want to
> see all the formatting.)
>
> Cheers,
>
> Michael
>
>
> ====
>
> NAME
> keyrings - in-kernel key management and retention facility
>
> DESCRIPTION
> The Linux key-management facility is primarily a way for driv‐
> ers to retain or cache security data, authentication keys,
> encryption keys, and other data in the kernel.
>
> System call interfaces are provided so that user-space programs
> can manage those objects and also use the facility for their
> own purposes.
>
> A library and some user-space utilities are provided to allow
> access to the facility. See keyctl(1), keyctl(3), and keyu‐
> tils(7) for more information.
>
> Keys
> A key has the following attributes:
>
> Serial number (ID)
> This is a unique integer handle by which a key is
> referred to in system call arguments. The serial number
> is sometimes synonymously referred as the key ID. Pro‐
> grammatically, key serial numbers are represented using
> the type key_serial_t.
>
> Type A key's type defines what sort of data can be held in
> the key, how the proposed content of the key will be
> parsed, and how the payload will be used.
>
> There are a number of general purpose types available,
> plus some specialist types defined by specific drivers.
>
> Description (name)
> The key description is a printable string that is used
> as the search term for the key (in conjunction with the
> key type) as well as a display name. During searches,
> the description may be partially matched or exactly
> matched.
>
> Payload (data)
> The payload is the actual content of a key. This is
> usually set when a key is created, but it is possible
> for the kernel to upcall to user space to finish the
> instantiation of a key if that key wasn't already known
> to the kernel when it was requested. (Details can be
> found in request_key(2).)
>
> A key's payload can be read and updated if the key type
> supports it and if suitable permission is granted to the
> caller.
>
> Access rights
> Much as files do, each key has an owning user ID, an
> owning group ID, and a security label. They also have a
> set of permissions, though there are more than for a
> normal UNIX file, and there is an additional category
> beyond the usual user, group, and other (see below).
>
> Note that keys are quota controlled since they represent
> unswappable kernel memory and the owning user ID speci‐
> fies whose quota is to be debited.
>
> Expiration time
> Each key can have an expiration time set. When that
> time is reached, the key is marked as being expired and
> accesses to it fail with EKEYEXPIRED. If not deleted,
> updated, or replaced, after a set amount of time,
> expired keys are automatically removed along with all
> links to them, and attempts to access the key will fail
> with the error ENOKEY.
>
> Reference count
> Each key has a reference count. Keys are referenced by
> keyrings, by currently active users, and by a process's
> credentials. When the reference count reaches zero, the
> key is scheduled for garbage collection.
>
> Key types
> The facility provides several basic types of key:
>
> "user" This is a general purpose key type. The key is kept
> entirely within kernel memory. The payload may be read
> and updated by user-space applications.
>
> The payload for keys of this type is a blob of arbitrary
> data of up to 32,767 bytes.
>
> The description may be any valid string, though it is
> preferred that it start with a colon-delimited prefix
> representing the service to which the key is of interest
> (for instance "afs:mykey").
>
> "keyring"
> Keyrings are special keys whose payload consists of a
> set of links to other keys (including other keyrings),
> analogous to a directory holding links to files. The
> main purpose of a keyring is to prevent other keys from
> being garbage collected because nothing refers to them.
>
> "logon" (since Linux 3.3)
> This key type is essentially the same as "user", but it
> does not provide reading (i.e., the keyctl(2)
> KEYCTL_READ operation), meaning that the key payload is
> never visible from user space. This is suitable for
> storing username-password pairs that you do not want to
> be readable from user space.
>
> "big_key" (since Linux 3.13)
> This key type is similar to the "user" key type, but it
> may hold a payload of up to 1MiB in size. The data may
> be stored in the swap space rather than in kernel memory
> if the data size exceeds the overhead of storing the
> data in swap space (a tmpfs file is used, which requires
> filesystem structures to be allocated in the kernel).
> This key type is useful for tasks such as holding Ker‐
> beros ticket caches.
>
> There are more specialized key types available also, but
> they're not discussed here as they're not intended for normal
> user-space use.
>
> Keyrings
> As previously mentioned, keyrings are a special type of key
> that contain links to other keys (which may include other
> keyrings). Keys may be linked to by multiple keyrings.
> Keyrings may be considered as analogous to UNIX directories
> where each directory contains a set of hard links to files.
>
> Various operations (system calls) may be applied only to
> keyrings:
>
> Adding A key may be added to a keyring by system calls that
> create keys. This prevents the new key from being imme‐
> diately deleted when the system call driver releases its
> last reference to the key.
>
> Linking
> A link may be added to a keyring pointing to a key that
> is already known, provided this does not create a self-
> referential cycle.
>
> Unlinking
> A link may be removed from a keyring. When the last
> link to a key is removed, that key will be scheduled for
> deletion by the garbage collector.
>
> Clearing
> All the links may be removed from a keyring.
>
> Searching
> A keyring may be considered the root of a tree or sub‐
> tree in which keyrings form the branches and non-
> keyrings the leaves. This tree may be searched for a
> leaf matching a particular type and description.
>
> See keyctl_clear(3), keyctl_link(3), keyctl_search(3), and
> keyctl_unlink(3) for more information.
>
> Anchoring keys
> To prevent a key from being prematurely garbage collected, it
> must anchored to keep its reference count elevated when it is
> not in active use by the kernel.
>
> Keyrings are used to anchor other keys - each link is a refer‐
> ence on a key - but whilst keyrings are available to link to
> keys, keyrings themselves are just keys and are also subject to
> the same anchoring necessity.
>
> The kernel makes available a number of anchor keyrings. Note
> that some of these keyrings will be created only when first
> accessed.
>
> Process keyrings
> Process credentials themselves reference keyrings with
> specific semantics. These keyrings are pinned as long
> as the set of credentials exists, which is usually as
> long as the process exists.
>
> There are three keyrings with different inheri‐
> tance/sharing rules: The session-keyring(7) (inherited
> and shared by all child processes), the process-
> keyring(7) (shared by all threads in a process) and the
> thread-keyring(7) (specific to a particular thread).
>
> User keyrings
> Each UID known to the kernel has a record that contains
> two keyrings: the user-keyring(7) and the user-session-
> keyring(7). These exist for as long as the UID record
> in the kernel exists. A link to the user keyring is
> placed in a new session keyring by pam_keyinit(8) when a
> new login session is initiated.
>
> Persistent keyrings
> There is a persistent-keyring(7) available to each UID
> known to the system. It may persist beyond the life of
> the UID record previously mentioned, but has an expira‐
> tion time set such that it is automatically cleaned up
> after a set time. This, for example, permits cron
> scripts to use credentials left when the user logs out.
>
> Note that the expiration time is reset every time the
> persistent key is requested.
>
> Special keyrings
> There are special keyrings owned by the kernel that can
> anchor keys for special purposes. An example of this is
> the system keyring used for holding encryption keys for
> module signature verification.
>
> These special keyrings are usually closed to direct
> alteration by user space.
>
> See thread-keyring(7), process-keyring(7), session-keyring(7),
> user-keyring(7), user-session-keyring(7), and persistent-
> keyring(7) for more information.
>
> Possession
> The concept of possession is important to understanding the
> keyrings security model. Whether a thread possesses a key is
> determined by the following rules:
>
> (1) Any key or keyring that does not grant search permission to
> the caller is ignored in all the following rules.
>
> (2) A thread possesses its session, process, and thread
> keyrings directly because those are pointed to by its cre‐
> dentials.
>
> (3) If a keyring is possessed, then any key it links to is also
> possessed.
>
> (4) If any key a keyring links to is itself a keyring, then
> rule (3) applies recursively.
>
> (5) If a process is upcalled from the kernel to instantiate a
> key, then it also possesses the requester's keyrings as in
> rule (1) as if it were the requester.
>
> Note that possession is not a fundamental property of a key,
> but must rather be calculated each time the key is needed.
>
> Possession is designed to allow set-user-ID programs run from,
> say a user's shell to access the user's keys. It also allows
> the prevention of access to keys just on the basis of UID and
> GID matches.
>
> When it creates the session keyring, pam_keyinit(8) adds a link
> to the user-keyring(7), thus making the user keyring and any‐
> thing it contains possessed by default.
>
> Access rights
> Each key has the following security-related attributes:
>
> * The owning user ID
>
> * The ID of a group that is permitted to access the key
>
> * A security label
>
> * A permissions mask
>
> The permissions mask contains four sets of rights. The first
> three sets are mutually exclusive. One and only one will be in
> force for a particular access check. In order of descending
> priority, these three sets are:
>
> user The set specifies the rights granted if the key's user
> ID matches the caller's filesystem user ID.
>
> group The set specifies the rights granted if the user ID
> didn't match and the key's group ID matches the caller's
> filesystem GID or one of the caller's supplementary
> group IDs.
>
> other The set specifies the rights granted if neither the
> key's user ID nor group ID matched.
>
> The fourth set of rights is:
>
> possessor
> The set specifies the rights granted if a key is deter‐
> mined to be possessed by the caller.
>
> The complete set of rights for a key is the union of whichever
> of the first three sets is applicable plus the fourth set if
> the key is possessed.
>
> The set of rights that may be granted in each of the four masks
> is as follows:
>
> view The attributes of the key may be read. This includes
> the type, description, and access rights (excluding the
> security label).
>
> read For a key: the payload of the key may be read. For a
> keyring: the list of serial numbers (keys) to which the
> keyring has links may be read.
>
> write The payload of the key may be updated. For a keyring,
> links may be added to or removed from the keyring, the
> keyring may be cleared completely (all links are
> removed), and the key may be revoked.
>
> search For a key (or a keyring): the key may be found by a
> search. For a keyring: keys and keyrings that are
> linked to by the keyring may be searched.
>
> link Links may be created from keyrings to the key. The ini‐
> tial link to a key that is established when the key is
> created doesn't require this permission.
>
> setattr
> The ownership details and security label of the key may
> be changed, the key's expiration time may be set, and
> the key may be revoked.
>
> If any right is granted to a thread for a key,
>
>
> ┌─────────────────────────────────────────────────────┐
> │FIXME │
> ├─────────────────────────────────────────────────────┤
> │This seems to contradict the text below, which says │
> │that 'view' permission is what is significant. │
> │Which is correct? │
> └─────────────────────────────────────────────────────┘
> then that thread will see the key listed in /proc/keys. If no
> rights at all are granted, then that thread can't even tell
> that the key exists.
>
> In addition to access rights, any active Linux Security Module
> (LSM) may prevent access to a key if its policy so dictates. A
> key may be given a security label or other attribute by the LSM
> which can be retrieved.
>
> See keyctl_chown(3), keyctl_describe(3), keyctl_get_secu‐
> rity(3), keyctl_setperm(3), and selinux(8) for more informa‐
> tion.
>
> Searching for keys
> One of the key features of the Linux key-management facility is
> the ability to find a key that a process is retaining. The
> request_key(2) system call is the primary point of access for
> user-space applications to find a key. (internally, the kernel
> has something similar available for use by internal components
> that make use of keys.)
>
> The search algorithm works as follows:
>
> (1) The three process keyrings are searched in the following
> order: the thread thread-keyring(7) if it exists, the
> process-keyring(7) if it exists, and then either the ses‐
> sion-keyring(7) if it exists or the user-session-keyring(7)
> if that exists.
>
> (2) If the caller was a process that was invoked by the
> request_key(2) upcall mechanism then the keyrings of the
> original caller of that request_key(2) will be searched as
> well.
>
> (3) The search of the keyring tree is in preorder: each keyring
> is searched first for a match, then the keyrings referred
> to by that keyring are searched.
>
> (4) If a matching key is found that is valid, then the search
> terminates and that key is returned.
>
> (5) If a matching key is found that has an error state
> attached, that error state is noted and the search contin‐
> ues.
>
> (6) If valid matching key is found, then the first noted error
> state is returned; otherwise, an ENOKEY error is returned.
>
> It is also possible to search a specific keyring, in which case
> only steps (3) to (6) apply.
>
> See request_key(2) and keyctl_search(3) for more information.
>
> On-demand key creation
> If a key cannot be found, request_key(2) will, if given a call‐
> out_info argument, create a new key and then upcall to user
> space to instantiate the key. This allows keys to be created
> on an as-needed basis.
>
> Typically, this will involve the kernel forking and exec'ing
> the request-key(8) program, which will then execute the appro‐
> priate handler based on its configuration.
>
> The handler is passed a special authorization key that allows
> it and only it to instantiate the new key. This is also used
> to permit searches performed by the handler program to also
> search the requester's keyrings.
>
> See request_key(2), keyctl_assume_authority(3), keyctl_instan‐
> tiate(3), keyctl_negate(3), keyctl_reject(3), request-key(8)
> and request-key.conf(5) for more information.
>
> /proc files
> The kernel provides various /proc files that expose information
> about keys or define limits on key usage.
>
> /proc/keys (since Linux 2.6.10)
> This file exposes a list of the keys that are viewable
> by the reading process, providing various information
> about each key.
>
> The only keys included in the list are those that grant
> view permission to the reading process, regardless of
> whether or not it possesses them. LSM security checks
> are still performed, and may filter out further keys
> that the process is not authorized to view.
>
> An example of the data that one might see in this file
> is the following:
>
> 009a2028 I--Q--- 1 perm 3f010000 1000 1000 user krb_ccache:primary: 12
> 1806c4ba I--Q--- 1 perm 3f010000 1000 1000 keyring _pid: 2
> 25d3a08f I--Q--- 1 perm 1f3f0000 1000 65534 keyring _uid_ses.1000: 1
> 28576bd8 I--Q--- 3 perm 3f010000 1000 1000 keyring _krb: 1
> 2c546d21 I--Q--- 190 perm 3f030000 1000 1000 keyring _ses: 2
> 30a4e0be I------ 4 2d 1f030000 1000 65534 keyring _persistent.1000: 1
> 32100fab I--Q--- 4 perm 1f3f0000 1000 65534 keyring _uid.1000: 2
> 32a387ea I--Q--- 1 perm 3f010000 1000 1000 keyring _pid: 2
> 3ce56aea I--Q--- 5 perm 3f030000 1000 1000 keyring _ses: 1
>
> The fields shown in each line of this file are as fol‐
> lows:
>
> ID The ID (serial number) of the key, expressed in
> hexadecimal.
>
> Flags A set of flags describing the state of the key:
>
> I The key has been instantiated.
>
> R The key has been revoked.
>
> D The key is dead (i.e., has been deleted). (A
> key may be briefly in this state during
> garbage collection.)
>
> Q The key contributes to the user's quota.
>
> U The key is under construction via a callback
> to user space; see request-key(2).
>
> N The key is negatively instantiated.
>
> i The key has been invalidated.
>
> Usage This is a count of the number of kernel creden‐
> tial structures that are pinning the key (approx‐
> imately: the number of threads and open file ref‐
> erences that refer to this key).
>
> Timeout
> The amount of time until the key will expire,
> expressed in human-readable form (weeks, days,
> hours, minutes, and seconds). The string perm
> here means that the key is permanent (no time‐
> out). The string expd means that the key has
> already expired, but has not yet been garbage
> collected.
>
> Permissions
> The key permissions, expressed as four hexadeci‐
> mal bytes containing, from left to right, the
> possessor, user, group, and other permissions.
>
> UID The user ID of the key owner.
>
> GID The group ID of the key. The value -1 here means
> that the key as no group ID; this can occur in
> certain circumstances for keys created by the
> kernel.
>
> Type The key type (user, keyring, etc.)
>
> Description
> The key description (name).
>
> Description
> This field contains descriptive information about
> the key. For most key tpes, it has the form
>
> desc[: extra-info]
>
> The name subfield is the the key's description
> (name). The optional extra-info field provides
> some further information about the key. The
> information that appears here depends on the key
> type, as follows:
>
> "user" and "logon"
> The size in bytes of the key payload
> (expressed in decimal).
>
> "keyring"
> The number of keys linked to the keyring, or
> the string empty if there are no keys linked
> to the keyring.
>
> "big_key"
> The payload size in bytes, followed either by
> the string [file], if the key payload exceeds
> the threshold that means that the payload is
> stored in a (swappable) tmpfs filesystem, or
> otherwise the string [buff], indicating that
> the key is small enough to reside in kernel
> memory.
>
> For the ".request_key_auth" key type (authoriza‐
> tion key; see request_key(2)), the description
> field has the form shown in the following exam‐
> ple:
>
> key:c9a9b19 pid:28880 ci:10
>
> The three subfields are as follows:
>
> key The hexadecimal ID of the key being instan‐
> tiated in the requesting program.
>
> pid The PID of the requesting program.
>
> ci The length of the callout data with which
> the requested key should be instantiated
> (i.e., the length of the payload associated
> with the authorization key).
>
> /proc/key-users (since Linux 2.6.10)
> This file lists various information for each user ID
> that has at least one key on the system. An example of
> the data that one might see in this file is the follow‐
> ing:
>
> 0: 10 9/9 2/1000000 22/25000000
> 42: 9 9/9 8/200 106/20000
> 1000: 11 11/11 10/200 271/20000
>
> The fields shown in each line are as follows:
>
> uid The user ID.
>
> usage This is a kernel-internal usage count for the
> kernel structure used to record key users.
>
> nkeys/nikeys
> The total number of keys owned by the user, and
> the number of those keys that have been instanti‐
> ated.
>
> qnkeys/maxkeys
> The number of keys owned by the user, and the
> maximum keys that the user may own.
>
> qnbytes/maxbytes
> The number of bytes consumed in payloads of the
> keys owned by this user, and the upper limit on
> the number of bytes in key payloads for that
> user.
>
> /proc/sys/kernel/keys/gc_delay (since Linux 2.6.32)
> The value in this file specifies the interval, in sec‐
> onds, after which revoked and expired keys will be
> garbage collected. The purpose of having such an inter‐
> val is so that there is a window of time where user
> space can see an error (respectively EKEYREVOKED and
> EKEYEXPIRED) that indicates what happened to the key.
>
> The default value in this file is 300 (i.e., 5 minutes).
>
> /proc/sys/kernel/keys/persistent_keyring_expiry (since Linux
> 3.13)
> This file defines an interval, in seconds, to which the
> persistent keyring's expiration timer is reset each time
> the keyring is accessed (via keyctl_get_persistent(3) or
> the keyctl(2) KEYCTL_GET_PERSISTENT operation.)
>
> The default value in this file is 259200 (i.e., 3 days).
>
> The following files (which are writable by privileged pro‐
> cesses) are used to enforce quotas on the number of keys and
> number of bytes of data that can be stored in key payloads:
>
> /proc/sys/kernel/keys/maxbytes (since Linux 2.6.26)
> This is the maximum number of bytes of data that a non‐
> root user can hold in the payloads of the keys owned by
> the user.
>
> The default value in this file is 20,000.
>
> /proc/sys/kernel/keys/maxkeys (since Linux 2.6.26)
> This is the maximum number of keys that a nonroot user
> may own.
>
> The default value in this file is 200.
>
> /proc/sys/kernel/keys/root_maxbytes (since Linux 2.6.26)
> This is the maximum number of bytes of data that the
> root user (UID 0 in the root user namespace) can hold in
> the payloads of the keys owned by root.
>
> The default value in this file is 25,000,000.
>
> /proc/sys/kernel/keys/root_maxkeys (since Linux 2.6.26)
> This is the maximum number of keys that the root user
> (UID 0 in the root user namespace) may own.
>
> The default value in this file is 1,000,000.
>
> With respect to keyrings, note that each link in a keyring con‐
> sumes 4 bytes of the keyring payload.
>
> Users
> The Linux key-management facility has a number of users and
> usages, but is not limited to those that already exist.
>
> In-kernel users of this facility include:
>
> Network filesystems - DNS
> The kernel uses the upcall mechanism provided by the
> keys to upcall to user space to do DNS lookups and then
> to cache the results.
>
> AF_RXRPC and kAFS - Authentication
> The AF_RXRPC network protocol and the in-kernel AFS
> filesystem use keys to store the ticket needed to do
> secured or encrypted traffic. These are then looked up
> by network operations on AF_RXRPC and filesystem opera‐
> tions on kAFS.
>
> NFS - User ID mapping
> The NFS filesystem uses keys to store mappings of for‐
> eign user IDs to local user IDs.
>
> CIFS - Password
> The CIFS filesystem uses keys to store passwords for
> accessing remote shares.
>
> Module verification
> The kernel build process can be made to cryptographi‐
> cally sign modules. That signature is then checked when
> a module is loaded.
>
> User-space users of this facility include:
>
> Kerberos key storage
> The MIT Kerberos 5 facility (libkrb5) can use keys to
> store authentication tokens which can be made to be
> automatically cleaned up a set time after the user last
> uses them, but until then permits them to hang around
> after the user has logged out so that cron scripts can
> use them.
>
> SEE ALSO
> keyutils(7), persistent-keyring(7), process-keyring(7),
> session-keyring(7), thread-keyring(7), user-keyring(7),
> user-session-keyring(7), pam_keyinit(8)
>
>
>
> Linux 2016-11-01 KEYRINGS(7)
>
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply [flat|nested] 36+ messages in thread
* Re: Revised keyrings(7) man page for review
[not found] ` <51643019-bb42-4066-c824-c55b9e668ac6-ASgREoAs3yw@public.gmane.org>
@ 2016-12-13 11:35 ` David Howells
2016-11-25 1:00 ` [PATCH draft_keys 1/7] keyctl.2: tfix Eugene Syromyatnikov
` (6 subsequent siblings)
7 siblings, 0 replies; 36+ messages in thread
From: David Howells @ 2016-12-13 11:35 UTC (permalink / raw)
To: Michael Kerrisk; +Cc: dhowells, lkml, Eugene Syromyatnikov, keyrings, linux-man
Michael Kerrisk <mtk@man7.org> wrote:
> The Linux key-management facility is primarily a way for driv‐
> ers to retain or cache security data, authentication keys,
> encryption keys, and other data in the kernel.
No comma before "and".
> access to the facility. See keyctl(1), keyctl(3), and keyu‐
Ditto. (And some other dittos).
> to the kernel when it was requested. (Details can be
> found in request_key(2).)
How about dropping the brackets and making that last sentence "For further
details, see request_key(2)."
> beyond the usual user, group, and other (see below).
I think this needs to say what below one is supposed to see:
"beyond the usual User, Group and Other (see 'Possession' below)."
> Key types
> The facility provides several basic types of key:
Again, I think the keyring type needs to go either first or last.
> "big_key" (since Linux 3.13)
> This key type is similar to the "user" key type, but it
> may hold a payload of up to 1MiB in size. The data may
> be stored in the swap space rather than in kernel memory
stored encrypted (as of 4.8).
> Anchoring keys
> To prevent a key from being prematurely garbage collected, it
> must anchored to keep its reference count elevated when it is
> not in active use by the kernel.
I think "prematurely" is unnecessary here.
> (3) The search of the keyring tree is in preorder: each keyring
> is searched first for a match, then the keyrings referred
> to by that keyring are searched.
"preorder"? How about "breadth-first order"?
> The only keys included in the list are those that grant
> view permission to the reading process, regardless of
> whether or not it possesses them. LSM security checks
> are still performed, and may filter out further keys
> that the process is not authorized to view.
This is correct. See proc_keys_show() in security/keys/proc.c:
rc = key_task_permission(key_ref, ctx.cred, KEY_NEED_VIEW);
if (rc < 0)
return 0;
Possibly it shouldn't be, but for now it is.
> D The key is dead (i.e., has been deleted). (A
> key may be briefly in this state during
> garbage collection.)
No - "dead" in this context means that the key type was unregistered.
> Description
> The key description (name).
>
> Description
> This field contains descriptive information about
Merge?
David
^ permalink raw reply [flat|nested] 36+ messages in thread
* Re: Revised keyrings(7) man page for review
@ 2016-12-13 11:35 ` David Howells
0 siblings, 0 replies; 36+ messages in thread
From: David Howells @ 2016-12-13 11:35 UTC (permalink / raw)
To: Michael Kerrisk
Cc: dhowells-H+wXaHxf7aLQT0dZR+AlfA, lkml, Eugene Syromyatnikov,
keyrings-u79uwXL29TY76Z2rM5mHXA, linux-man
Michael Kerrisk <mtk-ASgREoAs3yw@public.gmane.org> wrote:
> The Linux key-management facility is primarily a way for driv‐
> ers to retain or cache security data, authentication keys,
> encryption keys, and other data in the kernel.
No comma before "and".
> access to the facility. See keyctl(1), keyctl(3), and keyu‐
Ditto. (And some other dittos).
> to the kernel when it was requested. (Details can be
> found in request_key(2).)
How about dropping the brackets and making that last sentence "For further
details, see request_key(2)."
> beyond the usual user, group, and other (see below).
I think this needs to say what below one is supposed to see:
"beyond the usual User, Group and Other (see 'Possession' below)."
> Key types
> The facility provides several basic types of key:
Again, I think the keyring type needs to go either first or last.
> "big_key" (since Linux 3.13)
> This key type is similar to the "user" key type, but it
> may hold a payload of up to 1MiB in size. The data may
> be stored in the swap space rather than in kernel memory
stored encrypted (as of 4.8).
> Anchoring keys
> To prevent a key from being prematurely garbage collected, it
> must anchored to keep its reference count elevated when it is
> not in active use by the kernel.
I think "prematurely" is unnecessary here.
> (3) The search of the keyring tree is in preorder: each keyring
> is searched first for a match, then the keyrings referred
> to by that keyring are searched.
"preorder"? How about "breadth-first order"?
> The only keys included in the list are those that grant
> view permission to the reading process, regardless of
> whether or not it possesses them. LSM security checks
> are still performed, and may filter out further keys
> that the process is not authorized to view.
This is correct. See proc_keys_show() in security/keys/proc.c:
rc = key_task_permission(key_ref, ctx.cred, KEY_NEED_VIEW);
if (rc < 0)
return 0;
Possibly it shouldn't be, but for now it is.
> D The key is dead (i.e., has been deleted). (A
> key may be briefly in this state during
> garbage collection.)
No - "dead" in this context means that the key type was unregistered.
> Description
> The key description (name).
>
> Description
> This field contains descriptive information about
Merge?
David
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply [flat|nested] 36+ messages in thread
* Re: Revised keyrings(7) man page for review
@ 2016-12-13 12:43 ` Michael Kerrisk (man-pages)
0 siblings, 0 replies; 36+ messages in thread
From: Michael Kerrisk (man-pages) @ 2016-12-13 12:43 UTC (permalink / raw)
To: David Howells, Michael Kerrisk
Cc: mtk.manpages, lkml, Eugene Syromyatnikov, keyrings, linux-man
Hi David,
On 12/13/2016 12:35 PM, David Howells wrote:
> Michael Kerrisk <mtk@man7.org> wrote:
>
>> The Linux key-management facility is primarily a way for driv‐
>> ers to retain or cache security data, authentication keys,
>> encryption keys, and other data in the kernel.
>
> No comma before "and".
I use/Linux man-pages uses the "Oxford comma" convention.
>
>> access to the facility. See keyctl(1), keyctl(3), and keyu‐
>
> Ditto. (And some other dittos).
See above.
>> to the kernel when it was requested. (Details can be
>> found in request_key(2).)
>
> How about dropping the brackets and making that last sentence "For further
> details, see request_key(2)."
Done.
>> beyond the usual user, group, and other (see below).
>
> I think this needs to say what below one is supposed to see:
>
> "beyond the usual User, Group and Other (see 'Possession' below)."
Fixed.
>> Key types
>> The facility provides several basic types of key:
>
> Again, I think the keyring type needs to go either first or last.
Fixed.
>> "big_key" (since Linux 3.13)
>> This key type is similar to the "user" key type, but it
>> may hold a payload of up to 1MiB in size. The data may
>> be stored in the swap space rather than in kernel memory
>
> stored encrypted (as of 4.8).
Added "encrypted".
>
>> Anchoring keys
>> To prevent a key from being prematurely garbage collected, it
>> must anchored to keep its reference count elevated when it is
>> not in active use by the kernel.
>
> I think "prematurely" is unnecessary here.
Fixed.
>> (3) The search of the keyring tree is in preorder: each keyring
>> is searched first for a match, then the keyrings referred
>> to by that keyring are searched.
>
> "preorder"? How about "breadth-first order"?
Fixed.
>> The only keys included in the list are those that grant
>> view permission to the reading process, regardless of
>> whether or not it possesses them. LSM security checks
>> are still performed, and may filter out further keys
>> that the process is not authorized to view.
>
> This is correct. See proc_keys_show() in security/keys/proc.c:
>
> rc = key_task_permission(key_ref, ctx.cred, KEY_NEED_VIEW);
> if (rc < 0)
> return 0;
>
> Possibly it shouldn't be, but for now it is.
Okay -- thanks.
>> D The key is dead (i.e., has been deleted). (A
>> key may be briefly in this state during
>> garbage collection.)
>
> No - "dead" in this context means that the key type was unregistered.
Okay, so the text should read as:
D The key is dead (i.e., the key has been unregis‐
tered). (A key may be briefly in this state
during garbage collection.)
Right?
>
>> Description
>> The key description (name).
>>
>> Description
>> This field contains descriptive information about
>
> Merge?
Yup. Already found and fixed that one.
Cheers,
Michael
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
^ permalink raw reply [flat|nested] 36+ messages in thread
* Re: Revised keyrings(7) man page for review
@ 2016-12-13 12:43 ` Michael Kerrisk (man-pages)
0 siblings, 0 replies; 36+ messages in thread
From: Michael Kerrisk (man-pages) @ 2016-12-13 12:43 UTC (permalink / raw)
To: David Howells, Michael Kerrisk
Cc: mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w, lkml, Eugene Syromyatnikov,
keyrings-u79uwXL29TY76Z2rM5mHXA, linux-man
Hi David,
On 12/13/2016 12:35 PM, David Howells wrote:
> Michael Kerrisk <mtk-ASgREoAs3yw@public.gmane.org> wrote:
>
>> The Linux key-management facility is primarily a way for driv‐
>> ers to retain or cache security data, authentication keys,
>> encryption keys, and other data in the kernel.
>
> No comma before "and".
I use/Linux man-pages uses the "Oxford comma" convention.
>
>> access to the facility. See keyctl(1), keyctl(3), and keyu‐
>
> Ditto. (And some other dittos).
See above.
>> to the kernel when it was requested. (Details can be
>> found in request_key(2).)
>
> How about dropping the brackets and making that last sentence "For further
> details, see request_key(2)."
Done.
>> beyond the usual user, group, and other (see below).
>
> I think this needs to say what below one is supposed to see:
>
> "beyond the usual User, Group and Other (see 'Possession' below)."
Fixed.
>> Key types
>> The facility provides several basic types of key:
>
> Again, I think the keyring type needs to go either first or last.
Fixed.
>> "big_key" (since Linux 3.13)
>> This key type is similar to the "user" key type, but it
>> may hold a payload of up to 1MiB in size. The data may
>> be stored in the swap space rather than in kernel memory
>
> stored encrypted (as of 4.8).
Added "encrypted".
>
>> Anchoring keys
>> To prevent a key from being prematurely garbage collected, it
>> must anchored to keep its reference count elevated when it is
>> not in active use by the kernel.
>
> I think "prematurely" is unnecessary here.
Fixed.
>> (3) The search of the keyring tree is in preorder: each keyring
>> is searched first for a match, then the keyrings referred
>> to by that keyring are searched.
>
> "preorder"? How about "breadth-first order"?
Fixed.
>> The only keys included in the list are those that grant
>> view permission to the reading process, regardless of
>> whether or not it possesses them. LSM security checks
>> are still performed, and may filter out further keys
>> that the process is not authorized to view.
>
> This is correct. See proc_keys_show() in security/keys/proc.c:
>
> rc = key_task_permission(key_ref, ctx.cred, KEY_NEED_VIEW);
> if (rc < 0)
> return 0;
>
> Possibly it shouldn't be, but for now it is.
Okay -- thanks.
>> D The key is dead (i.e., has been deleted). (A
>> key may be briefly in this state during
>> garbage collection.)
>
> No - "dead" in this context means that the key type was unregistered.
Okay, so the text should read as:
D The key is dead (i.e., the key has been unregis‐
tered). (A key may be briefly in this state
during garbage collection.)
Right?
>
>> Description
>> The key description (name).
>>
>> Description
>> This field contains descriptive information about
>
> Merge?
Yup. Already found and fixed that one.
Cheers,
Michael
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply [flat|nested] 36+ messages in thread
* Re: Revised keyrings(7) man page for review
@ 2016-12-13 12:57 ` Michael Kerrisk (man-pages)
0 siblings, 0 replies; 36+ messages in thread
From: Michael Kerrisk (man-pages) @ 2016-12-13 12:57 UTC (permalink / raw)
To: David Howells, Michael Kerrisk
Cc: Michael Kerrisk, lkml, Eugene Syromyatnikov, keyrings, linux-man
Hello David,
Amended a piece here after Eugene's note about encrypted keys.
On 13 December 2016 at 13:43, Michael Kerrisk (man-pages)
<mtk.manpages@gmail.com> wrote:
> Hi David,
>
> On 12/13/2016 12:35 PM, David Howells wrote:
>> Michael Kerrisk <mtk@man7.org> wrote:
>>
>>> "big_key" (since Linux 3.13)
>>> This key type is similar to the "user" key type, but it
>>> may hold a payload of up to 1MiB in size. The data may
>>> be stored in the swap space rather than in kernel memory
>>
>> stored encrypted (as of 4.8).
>
> Added "encrypted".
So, I've updated this piece a couple of times since the draft that you
reviewed, and by now it reads:
"big_key" (since Linux 3.13)
This key type is similar to the "user" key type, but it may
hold a payload of up to 1 MiB in size. This key type is
useful for tasks such as holding Kerberos ticket caches.
The payload data may be stored in the swap space rather
than in kernel memory if the data size exceeds the overhead
of storing the data encrypted in swap space. (A tmpfs file
is used, which requires filesystem structures to be allo‐
cated in the kernel; The size of these structures deter‐
mines the size threshold above which the tmpfs storage
method is used.) Since Linux 4.8, payload data is
encrypted, to prevent it being written unencrypted into
swap space.
Okay?
Thanks,
Michael
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
^ permalink raw reply [flat|nested] 36+ messages in thread
* Re: Revised keyrings(7) man page for review
@ 2016-12-13 12:57 ` Michael Kerrisk (man-pages)
0 siblings, 0 replies; 36+ messages in thread
From: Michael Kerrisk (man-pages) @ 2016-12-13 12:57 UTC (permalink / raw)
To: David Howells, Michael Kerrisk
Cc: Michael Kerrisk, lkml, Eugene Syromyatnikov,
keyrings-u79uwXL29TY76Z2rM5mHXA, linux-man
Hello David,
Amended a piece here after Eugene's note about encrypted keys.
On 13 December 2016 at 13:43, Michael Kerrisk (man-pages)
<mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> Hi David,
>
> On 12/13/2016 12:35 PM, David Howells wrote:
>> Michael Kerrisk <mtk-ASgREoAs3yw@public.gmane.org> wrote:
>>
>>> "big_key" (since Linux 3.13)
>>> This key type is similar to the "user" key type, but it
>>> may hold a payload of up to 1MiB in size. The data may
>>> be stored in the swap space rather than in kernel memory
>>
>> stored encrypted (as of 4.8).
>
> Added "encrypted".
So, I've updated this piece a couple of times since the draft that you
reviewed, and by now it reads:
"big_key" (since Linux 3.13)
This key type is similar to the "user" key type, but it may
hold a payload of up to 1 MiB in size. This key type is
useful for tasks such as holding Kerberos ticket caches.
The payload data may be stored in the swap space rather
than in kernel memory if the data size exceeds the overhead
of storing the data encrypted in swap space. (A tmpfs file
is used, which requires filesystem structures to be allo‐
cated in the kernel; The size of these structures deter‐
mines the size threshold above which the tmpfs storage
method is used.) Since Linux 4.8, payload data is
encrypted, to prevent it being written unencrypted into
swap space.
Okay?
Thanks,
Michael
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply [flat|nested] 36+ messages in thread
* Re: Revised keyrings(7) man page for review
2016-12-13 11:35 ` David Howells
@ 2016-12-13 13:31 ` David Howells
-1 siblings, 0 replies; 36+ messages in thread
From: David Howells @ 2016-12-13 13:31 UTC (permalink / raw)
To: Michael Kerrisk (man-pages)
Cc: dhowells, Michael Kerrisk, lkml, Eugene Syromyatnikov, keyrings,
linux-man
Michael Kerrisk (man-pages) <mtk.manpages@gmail.com> wrote:
> I use/Linux man-pages uses the "Oxford comma" convention.
"... an optional comma ..." ;-)
There's also:
... LSM security checks are still performed, and may filter out
further keys that the process is not authorized to view.
but has two parts and isn't a list... ;-P
> >> D The key is dead (i.e., has been deleted). (A
> >> key may be briefly in this state during
> >> garbage collection.)
> >
> > No - "dead" in this context means that the key type was unregistered.
>
> Okay, so the text should read as:
>
> D The key is dead (i.e., the key has been unregis‐
> tered). (A key may be briefly in this state
> during garbage collection.)
>
> Right?
Not quite. The driver for the key type has been unregistered, not the key.
David
^ permalink raw reply [flat|nested] 36+ messages in thread
* Re: Revised keyrings(7) man page for review
@ 2016-12-13 13:31 ` David Howells
0 siblings, 0 replies; 36+ messages in thread
From: David Howells @ 2016-12-13 13:31 UTC (permalink / raw)
To: Michael Kerrisk (man-pages)
Cc: dhowells, Michael Kerrisk, lkml, Eugene Syromyatnikov, keyrings,
linux-man
Michael Kerrisk (man-pages) <mtk.manpages@gmail.com> wrote:
> I use/Linux man-pages uses the "Oxford comma" convention.
"... an optional comma ..." ;-)
There's also:
... LSM security checks are still performed, and may filter out
further keys that the process is not authorized to view.
but has two parts and isn't a list... ;-P
> >> D The key is dead (i.e., has been deleted). (A
> >> key may be briefly in this state during
> >> garbage collection.)
> >
> > No - "dead" in this context means that the key type was unregistered.
>
> Okay, so the text should read as:
>
> D The key is dead (i.e., the key has been unregis‐
> tered). (A key may be briefly in this state
> during garbage collection.)
>
> Right?
Not quite. The driver for the key type has been unregistered, not the key.
David
^ permalink raw reply [flat|nested] 36+ messages in thread
* Re: Revised keyrings(7) man page for review
@ 2016-12-13 13:38 ` David Howells
0 siblings, 0 replies; 36+ messages in thread
From: David Howells @ 2016-12-13 13:38 UTC (permalink / raw)
To: mtk.manpages
Cc: dhowells, Michael Kerrisk, lkml, Eugene Syromyatnikov, keyrings,
linux-man
Michael Kerrisk (man-pages) <mtk.manpages@gmail.com> wrote:
> So, I've updated this piece a couple of times since the draft that you
> reviewed, and by now it reads:
>
> "big_key" (since Linux 3.13)
> This key type is similar to the "user" key type, but it may
> hold a payload of up to 1 MiB in size. This key type is
> useful for tasks such as holding Kerberos ticket caches.
I'm not sure that "tasks" is quite the word I'd use here (it's overloaded).
Perhaps "purposes"?
> The payload data may be stored in the swap space rather
> than in kernel memory if the data size exceeds the overhead
> of storing the data encrypted in swap space. (A tmpfs file
> is used, which requires filesystem structures to be allo‐
> cated in the kernel; The size of these structures deter‐
> mines the size threshold above which the tmpfs storage
> method is used.) Since Linux 4.8, payload data is
> encrypted, to prevent it being written unencrypted into
> swap space.
I would either drop the first "encrypted" ("storing the data encrypted") since
you mention this later or move it earlier to be after the word "stored" ("may
be stored encrypted").
Note that with the "Since Linux 4.8 ..." sentence, the encryption is only
applied if it is stored into tmpfs.
Also, the payload isn't directly stored into swapspace, but is rather stored
into tmpfs, from where it can be swapped. This is important since you can use
this type of key without any swapspace available to your system.
David
^ permalink raw reply [flat|nested] 36+ messages in thread
* Re: Revised keyrings(7) man page for review
@ 2016-12-13 13:38 ` David Howells
0 siblings, 0 replies; 36+ messages in thread
From: David Howells @ 2016-12-13 13:38 UTC (permalink / raw)
To: mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w
Cc: dhowells-H+wXaHxf7aLQT0dZR+AlfA, Michael Kerrisk, lkml,
Eugene Syromyatnikov, keyrings-u79uwXL29TY76Z2rM5mHXA, linux-man
Michael Kerrisk (man-pages) <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> So, I've updated this piece a couple of times since the draft that you
> reviewed, and by now it reads:
>
> "big_key" (since Linux 3.13)
> This key type is similar to the "user" key type, but it may
> hold a payload of up to 1 MiB in size. This key type is
> useful for tasks such as holding Kerberos ticket caches.
I'm not sure that "tasks" is quite the word I'd use here (it's overloaded).
Perhaps "purposes"?
> The payload data may be stored in the swap space rather
> than in kernel memory if the data size exceeds the overhead
> of storing the data encrypted in swap space. (A tmpfs file
> is used, which requires filesystem structures to be allo‐
> cated in the kernel; The size of these structures deter‐
> mines the size threshold above which the tmpfs storage
> method is used.) Since Linux 4.8, payload data is
> encrypted, to prevent it being written unencrypted into
> swap space.
I would either drop the first "encrypted" ("storing the data encrypted") since
you mention this later or move it earlier to be after the word "stored" ("may
be stored encrypted").
Note that with the "Since Linux 4.8 ..." sentence, the encryption is only
applied if it is stored into tmpfs.
Also, the payload isn't directly stored into swapspace, but is rather stored
into tmpfs, from where it can be swapped. This is important since you can use
this type of key without any swapspace available to your system.
David
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply [flat|nested] 36+ messages in thread
* Re: Revised keyrings(7) man page for review
2016-12-13 13:31 ` David Howells
(?)
@ 2016-12-13 13:41 ` Michael Kerrisk (man-pages)
-1 siblings, 0 replies; 36+ messages in thread
From: Michael Kerrisk (man-pages) @ 2016-12-13 13:41 UTC (permalink / raw)
To: David Howells
Cc: mtk.manpages, lkml, Eugene Syromyatnikov, keyrings, linux-man
Hi David,
On 12/13/2016 02:31 PM, David Howells wrote:
> Michael Kerrisk (man-pages) <mtk.manpages@gmail.com> wrote:
>
>> I use/Linux man-pages uses the "Oxford comma" convention.
>
> "... an optional comma ..." ;-)
>
> There's also:
>
> ... LSM security checks are still performed, and may filter out
> further keys that the process is not authorized to view.
>
> but has two parts and isn't a list... ;-P
Oxford comma doesn't apply there... But, to me, it depends how
you read the text aloud. I'd read it with a pause where the comma is,
and so added a comma there.
>
>>>> D The key is dead (i.e., has been deleted). (A
>>>> key may be briefly in this state during
>>>> garbage collection.)
>>>
>>> No - "dead" in this context means that the key type was unregistered.
>>
>> Okay, so the text should read as:
>>
>> D The key is dead (i.e., the key has been unregis‐
>> tered). (A key may be briefly in this state
>> during garbage collection.)
>>
>> Right?
>
> Not quite. The driver for the key type has been unregistered, not the key.
Bother. I meant to write "key type"! Fixed.
Cheers,
Michael
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
^ permalink raw reply [flat|nested] 36+ messages in thread
* Re: Revised keyrings(7) man page for review
@ 2016-12-13 13:52 ` Michael Kerrisk (man-pages)
0 siblings, 0 replies; 36+ messages in thread
From: Michael Kerrisk (man-pages) @ 2016-12-13 13:52 UTC (permalink / raw)
To: David Howells
Cc: mtk.manpages, lkml, Eugene Syromyatnikov, keyrings, linux-man
On 12/13/2016 02:38 PM, David Howells wrote:
> Michael Kerrisk (man-pages) <mtk.manpages@gmail.com> wrote:
>
>> So, I've updated this piece a couple of times since the draft that you
>> reviewed, and by now it reads:
>>
>> "big_key" (since Linux 3.13)
>> This key type is similar to the "user" key type, but it may
>> hold a payload of up to 1 MiB in size. This key type is
>> useful for tasks such as holding Kerberos ticket caches.
>
> I'm not sure that "tasks" is quite the word I'd use here (it's overloaded).
> Perhaps "purposes"?
Fixed.
>> The payload data may be stored in the swap space rather
>> than in kernel memory if the data size exceeds the overhead
>> of storing the data encrypted in swap space. (A tmpfs file
>> is used, which requires filesystem structures to be allo‐
>> cated in the kernel; The size of these structures deter‐
>> mines the size threshold above which the tmpfs storage
>> method is used.) Since Linux 4.8, payload data is
>> encrypted, to prevent it being written unencrypted into
>> swap space.
>
> I would either drop the first "encrypted" ("storing the data encrypted") since
I already dropped that first "encrypted".
> you mention this later or move it earlier to be after the word "stored" ("may
> be stored encrypted").
>
> Note that with the "Since Linux 4.8 ..." sentence, the encryption is only
> applied if it is stored into tmpfs.
Thanks for that tip.
> Also, the payload isn't directly stored into swapspace, but is rather stored
> into tmpfs, from where it can be swapped. This is important since you can use
> this type of key without any swapspace available to your system.
Yes, the text still needs some work... How about:
"big_key" (since Linux 3.13)
This key type is similar to the "user" key type, but it may
hold a payload of up to 1 MiB in size. This key type is
useful for purposes such as holding Kerberos ticket caches.
The payload data may be stored in a tmpfs filesystem,
rather than in kernel memory, if the data size exceeds the
overhead of storing the data in the filesystem. (Storing
the data in a filesystem requires filesystem structures to
be allocated in the kernel. The size of these structures
determines the size threshold above which the tmpfs storage
method is used.) Since Linux 4.8, the payload data is
encrypted when stored in tmpfs, to prevent it being written
unencrypted into swap space.
?
Thanks,
Michael
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
^ permalink raw reply [flat|nested] 36+ messages in thread
* Re: Revised keyrings(7) man page for review
@ 2016-12-13 13:52 ` Michael Kerrisk (man-pages)
0 siblings, 0 replies; 36+ messages in thread
From: Michael Kerrisk (man-pages) @ 2016-12-13 13:52 UTC (permalink / raw)
To: David Howells
Cc: mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w, lkml, Eugene Syromyatnikov,
keyrings-u79uwXL29TY76Z2rM5mHXA, linux-man
On 12/13/2016 02:38 PM, David Howells wrote:
> Michael Kerrisk (man-pages) <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
>
>> So, I've updated this piece a couple of times since the draft that you
>> reviewed, and by now it reads:
>>
>> "big_key" (since Linux 3.13)
>> This key type is similar to the "user" key type, but it may
>> hold a payload of up to 1 MiB in size. This key type is
>> useful for tasks such as holding Kerberos ticket caches.
>
> I'm not sure that "tasks" is quite the word I'd use here (it's overloaded).
> Perhaps "purposes"?
Fixed.
>> The payload data may be stored in the swap space rather
>> than in kernel memory if the data size exceeds the overhead
>> of storing the data encrypted in swap space. (A tmpfs file
>> is used, which requires filesystem structures to be allo‐
>> cated in the kernel; The size of these structures deter‐
>> mines the size threshold above which the tmpfs storage
>> method is used.) Since Linux 4.8, payload data is
>> encrypted, to prevent it being written unencrypted into
>> swap space.
>
> I would either drop the first "encrypted" ("storing the data encrypted") since
I already dropped that first "encrypted".
> you mention this later or move it earlier to be after the word "stored" ("may
> be stored encrypted").
>
> Note that with the "Since Linux 4.8 ..." sentence, the encryption is only
> applied if it is stored into tmpfs.
Thanks for that tip.
> Also, the payload isn't directly stored into swapspace, but is rather stored
> into tmpfs, from where it can be swapped. This is important since you can use
> this type of key without any swapspace available to your system.
Yes, the text still needs some work... How about:
"big_key" (since Linux 3.13)
This key type is similar to the "user" key type, but it may
hold a payload of up to 1 MiB in size. This key type is
useful for purposes such as holding Kerberos ticket caches.
The payload data may be stored in a tmpfs filesystem,
rather than in kernel memory, if the data size exceeds the
overhead of storing the data in the filesystem. (Storing
the data in a filesystem requires filesystem structures to
be allocated in the kernel. The size of these structures
determines the size threshold above which the tmpfs storage
method is used.) Since Linux 4.8, the payload data is
encrypted when stored in tmpfs, to prevent it being written
unencrypted into swap space.
?
Thanks,
Michael
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply [flat|nested] 36+ messages in thread
* Re: Revised keyrings(7) man page for review
@ 2016-12-13 14:20 ` David Howells
0 siblings, 0 replies; 36+ messages in thread
From: David Howells @ 2016-12-13 14:20 UTC (permalink / raw)
To: Michael Kerrisk (man-pages)
Cc: dhowells, lkml, Eugene Syromyatnikov, keyrings, linux-man
Michael Kerrisk (man-pages) <mtk.manpages@gmail.com> wrote:
> The payload data may be stored in a tmpfs filesystem,
> rather than in kernel memory, if the data size exceeds the
> overhead of storing the data in the filesystem. (Storing
> the data in a filesystem requires filesystem structures to
> be allocated in the kernel. The size of these structures
> determines the size threshold above which the tmpfs storage
> method is used.) Since Linux 4.8, the payload data is
> encrypted when stored in tmpfs, to prevent it being written
> unencrypted into swap space.
"... thereby preventing it from being written unencrypted into the swapspace"?
David
^ permalink raw reply [flat|nested] 36+ messages in thread
* Re: Revised keyrings(7) man page for review
@ 2016-12-13 14:20 ` David Howells
0 siblings, 0 replies; 36+ messages in thread
From: David Howells @ 2016-12-13 14:20 UTC (permalink / raw)
To: Michael Kerrisk (man-pages)
Cc: dhowells-H+wXaHxf7aLQT0dZR+AlfA, lkml, Eugene Syromyatnikov,
keyrings-u79uwXL29TY76Z2rM5mHXA, linux-man
Michael Kerrisk (man-pages) <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> The payload data may be stored in a tmpfs filesystem,
> rather than in kernel memory, if the data size exceeds the
> overhead of storing the data in the filesystem. (Storing
> the data in a filesystem requires filesystem structures to
> be allocated in the kernel. The size of these structures
> determines the size threshold above which the tmpfs storage
> method is used.) Since Linux 4.8, the payload data is
> encrypted when stored in tmpfs, to prevent it being written
> unencrypted into swap space.
"... thereby preventing it from being written unencrypted into the swapspace"?
David
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply [flat|nested] 36+ messages in thread
* Re: Revised keyrings(7) man page for review
2016-12-13 14:20 ` David Howells
(?)
@ 2016-12-14 7:27 ` Michael Kerrisk (man-pages)
-1 siblings, 0 replies; 36+ messages in thread
From: Michael Kerrisk (man-pages) @ 2016-12-14 7:27 UTC (permalink / raw)
To: David Howells
Cc: mtk.manpages, lkml, Eugene Syromyatnikov, keyrings, linux-man
On 12/13/2016 03:20 PM, David Howells wrote:
> Michael Kerrisk (man-pages) <mtk.manpages@gmail.com> wrote:
>
>> The payload data may be stored in a tmpfs filesystem,
>> rather than in kernel memory, if the data size exceeds the
>> overhead of storing the data in the filesystem. (Storing
>> the data in a filesystem requires filesystem structures to
>> be allocated in the kernel. The size of these structures
>> determines the size threshold above which the tmpfs storage
>> method is used.) Since Linux 4.8, the payload data is
>> encrypted when stored in tmpfs, to prevent it being written
>> unencrypted into swap space.
>
> "... thereby preventing it from being written unencrypted into the swapspace"?
Fixed.
Thanks,
Michael
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
^ permalink raw reply [flat|nested] 36+ messages in thread
end of thread, other threads:[~2016-12-14 7:28 UTC | newest]
Thread overview: 36+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2016-11-04 15:47 Revised keyrings(7) man page for review Michael Kerrisk
2016-11-04 15:47 ` Michael Kerrisk
[not found] ` <51643019-bb42-4066-c824-c55b9e668ac6-ASgREoAs3yw@public.gmane.org>
2016-11-25 1:00 ` [PATCH draft_keys 0/7] Minor edits Eugene Syromyatnikov
2016-11-25 10:01 ` Michael Kerrisk (man-pages)
2016-11-25 1:00 ` [PATCH draft_keys 1/7] keyctl.2: tfix Eugene Syromyatnikov
2016-11-25 8:35 ` Michael Kerrisk (man-pages)
2016-11-25 1:00 ` [PATCH draft_keys 2/7] keyrings.7: minor clarification rearding storage method used in keyrings Eugene Syromyatnikov
2016-11-25 8:37 ` Michael Kerrisk (man-pages)
2016-11-25 1:01 ` [PATCH draft_keys 3/7] keyrings.7: spacing fix Eugene Syromyatnikov
2016-11-25 8:39 ` Michael Kerrisk (man-pages)
2016-11-25 1:01 ` [PATCH draft_keys 4/7] keyrings.7: minor clarification regarding decision whether to store big_key in tmpfs or not Eugene Syromyatnikov
2016-11-25 8:40 ` Michael Kerrisk (man-pages)
2016-11-25 1:01 ` [PATCH draft_keys 5/7] keyrings.7: tfix Eugene Syromyatnikov
2016-11-25 8:42 ` Michael Kerrisk (man-pages)
2016-11-25 1:01 ` [PATCH draft_keys 6/7] " Eugene Syromyatnikov
2016-11-25 8:43 ` Michael Kerrisk (man-pages)
2016-11-25 1:01 ` [PATCH draft_keys 7/7] keyrings.7: information regarding pre-3.17 limits on root_maxbytes/root_maxkeys Eugene Syromyatnikov
2016-11-25 8:54 ` Michael Kerrisk (man-pages)
2016-11-26 12:51 ` Revised keyrings(7) man page for review Michael Kerrisk (man-pages)
2016-11-26 12:51 ` Michael Kerrisk (man-pages)
2016-12-13 11:35 ` David Howells
2016-12-13 11:35 ` David Howells
2016-12-13 12:43 ` Michael Kerrisk (man-pages)
2016-12-13 12:43 ` Michael Kerrisk (man-pages)
2016-12-13 12:57 ` Michael Kerrisk (man-pages)
2016-12-13 12:57 ` Michael Kerrisk (man-pages)
2016-12-13 13:38 ` David Howells
2016-12-13 13:38 ` David Howells
2016-12-13 13:52 ` Michael Kerrisk (man-pages)
2016-12-13 13:52 ` Michael Kerrisk (man-pages)
2016-12-13 14:20 ` David Howells
2016-12-13 14:20 ` David Howells
2016-12-14 7:27 ` Michael Kerrisk (man-pages)
2016-12-13 13:31 ` David Howells
2016-12-13 13:31 ` David Howells
2016-12-13 13:41 ` Michael Kerrisk (man-pages)
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.