lkml.org 
[lkml]   [2016]   [Nov]   [4]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    /
    From
    SubjectRevised keyrings(7) man page for review
    Date
    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/
    [unhandled content-type:application/x-troff-man]
    \
     
     \ /
      Last update: 2016-11-04 16:48    [W:3.766 / U:0.204 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site