# keyctl

## NAME



           keyctl - key management facility control
    


## SYNOPSIS



           **keyctl** --version
           **keyctl** supports [<cap> | --raw]
           **keyctl** id [<keyring>]
           **keyctl** show [-x] [<keyring>]
           **keyctl** add [-x] <type> <desc> <data> <keyring>
           **keyctl** padd [-x] <type> <desc> <keyring>
           **keyctl** request <type> <desc> [<dest_keyring>]
           **keyctl** request2 <type> <desc> <info> [<dest_keyring>]
           **keyctl** prequest2 <type> <desc> [<dest_keyring>]
           **keyctl** update [-x] <key> <data>
           **keyctl** pupdate [-x] <key>
           **keyctl** newring <name> <keyring>
           **keyctl** revoke <key>
           **keyctl** clear <keyring>
           **keyctl** link <key> <keyring>
           **keyctl** unlink <key> [<keyring>]
           **keyctl** move [-f] <key> <from_keyring> <to_keyring>
           **keyctl** search <keyring> <type> <desc> [<dest_keyring>]
           **keyctl** restrict_keyring <keyring> [<type> [<restriction>]]
           **keyctl** read <key>
           **keyctl** pipe <key>
           **keyctl** print <key>
           **keyctl** list <keyring>
           **keyctl** rlist <keyring>
           **keyctl** describe <keyring>
           **keyctl** rdescribe <keyring> [sep]
           **keyctl** chown <key> <uid>
           **keyctl** chgrp <key> <gid>
           **keyctl** setperm <key> <mask>
           **keyctl** new_session [<name>]
           **keyctl** session
           **keyctl** session - [<prog> <arg1> <arg2> ...]
           **keyctl** session <name> [<prog> <arg1> <arg2> ...]
           **keyctl** instantiate [-x] <key> <data> <keyring>
           **keyctl** pinstantiate [-x] <key> <keyring>
           **keyctl** negate <key> <timeout> <keyring>
           **keyctl** reject <key> <timeout> <error> <keyring>
           **keyctl** timeout <key> <timeout>
           **keyctl** security <key>
           **keyctl** reap [-v]
           **keyctl** purge <type>
           **keyctl** purge [-i] [-p] <type> <desc>
           **keyctl** purge -s <type> <desc>
           **keyctl** get_persistent <keyring> [<uid>]
           **keyctl** dh_compute <private> <prime> <base>
           **keyctl** dh_compute_kdf <private> <prime> <base> <output_length>
           <hash_type>
           **keyctl** dh_compute_kdf_oi [-x] <private> <prime> <base>
           <output_length> <hash_type>
           **keyctl** pkey_query <key> <pass> [k=v]*
           **keyctl** pkey_encrypt <key> <pass> <datafile> [k=v]* ><encfile>
           **keyctl** pkey_decrypt <key> <pass> <encfile> [k=v]* ><datafile>
           **keyctl** pkey_sign <key> <pass> <datafile> [k=v]* ><sigfile>
           **keyctl** pkey_decrypt <key> <pass> <datafile> <sigfile> [k=v]*
           **keyctl** watch [-f<filters>] <key>
           **keyctl** watch_add <fd> <key>
           **keyctl** watch_rm <fd> <key>
           **keyctl** watch_session [-f <filters>] [-n <name>] \
                           <notifylog> <gclog> <fd> <prog> [<arg1> <arg2>
           ...]
    


## DESCRIPTION



           This program is used to control the key management facility in
           various ways using a variety of subcommands.
    


## KEY IDENTIFIERS



           The key identifiers passed to or returned from keyctl are, in
           general, positive integers. There are, however, some special
           values with special meanings that can be passed as arguments:
    
           No key: **0**
    
           Thread keyring: **@t** or **-1**
                  Each thread may have its own keyring. This is searched
                  first, before all others. The thread keyring is replaced by
                  (v)fork, exec and clone.
    
           Process keyring: **@p** or **-2**
                  Each process (thread group) may have its own keyring. This
                  is shared between all members of a group and will be
                  searched after the thread keyring. The process keyring is
                  replaced by (v)fork and exec.
    
           Session keyring: **@s** or **-3**
                  Each process subscribes to a session keyring that is
                  inherited across (v)fork, exec and clone. This is searched
                  after the process keyring. Session keyrings can be named
                  and an extant keyring can be joined in place of a process's
                  current session keyring.
    
           User specific keyring: **@u** or **-4**
                  This keyring is shared between all the processes owned by a
                  particular user. It isn't searched directly, but is
                  normally linked to from the session keyring.
    
           User default session keyring: **@us** or **-5**
                  This is the default session keyring for a particular user.
                  Login processes that change to a particular user will bind
                  to this session until another session is set.
    
           Group specific keyring: **@g** or **-6**
                  This is a place holder for a group specific keyring, but is
                  not actually implemented yet in the kernel.
    
           Assumed request_key authorisation key: **@a** or **-7**
                  This selects the authorisation key provided to the
                  **request_key**() helper to permit it to access the callers
                  keyrings and instantiate the target key.
    
           Keyring by name: **%: <name>**
                  A named keyring.  This will be searched for in the
                  process's keyrings and in _/proc/keys_.
    
           Key by name: **% <type>:<name>**
                  A named key of the given type.  This will be searched for
                  in the process's keyrings and in _/proc/keys_.
    


## COMMAND SYNTAX



           Any non-ambiguous shortening of a command name may be used in lieu
           of the full command name. This facility should not be used in
           scripting as new commands may be added in future that then cause
           ambiguity.
    
       **Display the package version number**
           **keyctl --version**
    
           This command prints the package version number and build date and
           exits:
    
                  $ keyctl --version
                  keyctl from keyutils-1.5.3 (Built 2011-08-24)
    
       **Query subsystem capabilities**
           **keyctl** supports
           **keyctl** supports --raw
           **keyctl** supports <cap>
    
           This command can list the available capabilities:
    
                  $ keyctl supports
                  have_capabilities=0
                  have_persistent_keyrings=1
                  have_dh_compute=1
                  have_public_key=1
    
           produce a raw hex dump of the capabilities list:
    
                  $ keyctl supports --raw
                  ff0f
    
           or query a specific capability:
    
                  $ keyctl supports pkey
                  echo $?
                  0
    
           which exits 0 if the capability is supported, 1 if it isn't and 3
           if the name is not recognised.  The capabilities supported are:
    
           **capabilities**
                  The kernel supports capability querying.  If not, the other
                  capabilities will be queried as best libkeyutils can
                  manage.
    
           **persistent_keyrings**
                  The kernel supports persistent keyrings.
    
           **dh_compute**
                  The kernel supports Diffie-Hellman computation operations.
    
           **public_key**
                  The kernel supports public key operations.
    
           **big_key_type**
                  The kernel supports the big_key key type.
    
           **key_invalidate**
                  The kernel supports the invalidate key operaiton.
    
           **restrict_keyring**
                  The kernel supports the restrict_keyring operation.
    
           **move_key**
                  The kernel supports the move key operation.
    
           **ns_keyring_name**
                  Keyring names are segregated according to the user-
                  namespace in which the keyrings are created.
    
           **ns_key_tag**
                  Keys can get tagged with namespace tags, allowing keys with
                  the same type and description, but different namespaces to
                  coexist in the same keyring.  Tagging is done automatically
                  according to the key type.
    
       **Show actual key or keyring ID**
           **keyctl id [ <key>]**
    
           This command looks up the real ID of a key or keyring from the
           identifier given, which is typically a symbolic ID such as "@s"
           indicating the session keyring, but can also be a numeric ID or
           "%type:desc" notation.  If a special keyring is specified that
           isn't created yet, an error will be given rather than causing that
           keyring to be created.
    
       **Show process keyrings**
           **keyctl show [-x] [ <keyring>]**
    
           By default this command recursively shows what keyrings a process
           is subscribed to and what keys and keyrings they contain.  If a
           keyring is specified then that keyring will be dumped instead.  If
           **-x** is specified then the keyring IDs will be dumped in hex instead
           of decimal.
    
       **Add a key to a keyring**
           **keyctl add**[-x] <type> <desc> <data> <keyring>
           **keyctl padd**[-x] <type> <desc> <keyring>
    
           This command creates a key of the specified type and description;
           instantiates it with the given data and attaches it to the
           specified keyring. It then prints the new key's ID on stdout:
    
                  $ keyctl add user mykey stuff @u
                  26
    
           The **padd** variant of the command reads the data from stdin rather
           than taking it from the command line:
    
                  $ echo -n stuff | keyctl padd user mykey @u
                  26
    
           If **-x** is given, then the data is hex-decoded with whitespace being
           discarded.
    
       **Request a key**
           **keyctl request** <type> <desc> [<dest_keyring>]
           **keyctl request2** <type> <desc> <info> [<dest_keyring>]
           **keyctl prequest2** <type> <desc> [<dest_keyring>]
    
           These three commands request the lookup of a key of the given type
           and description. The process's keyrings will be searched, and if a
           match is found the matching key's ID will be printed to stdout;
           and if a destination keyring is given, the key will be added to
           that keyring also.
    
           If there is no key, the first command will simply return the error
           ENOKEY and fail. The second and third commands will create a
           partial key with the type and description, and call out to
           _/sbin/request-key_ with that key and the extra information
           supplied. This will then attempt to instantiate the key in some
           manner, such that a valid key is obtained.
    
           The third command is like the second, except that the callout
           information is read from stdin rather than being passed on the
           command line.
    
           If a valid key is obtained, the ID will be printed and the key
           attached as if the original search had succeeded.
    
           If there wasn't a valid key obtained, a temporary negative key
           will be attached to the destination keyring if given and the error
           "Requested key not available" will be given.
    
                  $ keyctl request2 user debug:hello wibble
                  23
                  $ echo -n wibble | keyctl prequest2 user debug:hello
                  23
                  $ keyctl request user debug:hello
                  23
    
       **Update a key**
           **keyctl update**[-x] <key> <data>
           **keyctl pupdate**[-x] <key>
    
           This command replaces the data attached to a key with a new set of
           data. If the type of the key doesn't support update then error
           "Operation not supported" will be returned.
    
                  $ keyctl update 23 zebra
    
           The **pupdate** variant of the command reads the data from stdin
           rather than taking it from the command line:
    
                  $ echo -n zebra | keyctl pupdate 23
                  $ echo 616263313233 | keyctl pupdate -x 23
    
           If **-x** is given, then the data is hex-decoded with whitespace being
           discarded.
    
       **Create a keyring**
           **keyctl newring** <name> <keyring>
    
           This command creates a new keyring of the specified name and
           attaches it to the specified keyring. The ID of the new keyring
           will be printed to stdout if successful.
    
                  $ keyctl newring squelch @us
                  27
    
       **Revoke a key**
           **keyctl revoke** <key>
    
           This command marks a key as being revoked. Any further operations
           on that key (apart from unlinking it) will return error "Key has
           been revoked".
    
                  $ keyctl revoke 26
                  $ keyctl describe 26
                  keyctl_describe: Key has been revoked
    
       **Clear a keyring**
           **keyctl clear** <keyring>
    
           This command unlinks all the keys attached to the specified
           keyring. Error "Not a directory" will be returned if the key
           specified is not a keyring.
    
                  $ keyctl clear 27
    
       **Link a key to a keyring**
           **keyctl link** <key> <keyring>
    
           This command makes a link from the key to the keyring if there's
           enough capacity to do so. Error "Not a directory" will be returned
           if the destination is not a keyring. Error "Permission denied"
           will be returned if the key doesn't have link permission or the
           keyring doesn't have write permission. Error "File table overflow"
           will be returned if the keyring is full. Error "Resource deadlock
           avoided" will be returned if an attempt was made to introduce a
           recursive link.
    
                  $ keyctl link 23 27
                  $ keyctl link 27 27
                  keyctl_link: Resource deadlock avoided
    
       **Unlink a key from a keyring or the session keyring tree**
           **keyctl unlink** <key> [<keyring>]
    
           If the keyring is specified, this command removes a link to the
           key from the keyring. Error "Not a directory" will be returned if
           the destination is not a keyring. Error "Permission denied" will
           be returned if the keyring doesn't have write permission. Error
           "No such file or directory" will be returned if the key is not
           linked to by the keyring.
    
           If the keyring is not specified, this command performs a depth-
           first search of the session keyring tree and removes all the links
           to the nominated key that it finds (and that it is permitted to
           remove).  It prints the number of successful unlinks before
           exiting.
    
                  $ keyctl unlink 23 27
    
       **Move a key between keyrings.**
           **keyctl move**[-f] <key> <from_keyring> <to_keyring>
    
           This command moves a key from one keyring to another, atomically
           combining "keyctl unlink <key> <from_keyring>" and "keyctl link
           <key> <to_keyring>".
    
           If the "-f" flag is present, any matching key will be displaced
           from "to_keyring"; if not present, the command will fail with the
           error message "File exists" if the key would otherwise displace
           another key from "to_keyring".
    
                  $ keyctl move 23 27 29
                  $ keyctl move -f 71 @u @s
    
       **Search a keyring**
           **keyctl search** <keyring> <type> <desc> [<dest_keyring>]
    
           This command non-recursively searches a keyring for a key of a
           particular type and description. If found, the ID of the key will
           be printed on stdout and the key will be attached to the
           destination keyring if present. Error "Requested key not
           available" will be returned if the key is not found.
    
                  $ keyctl search @us user debug:hello
                  23
                  $ keyctl search @us user debug:bye
                  keyctl_search: Requested key not available
    
       **Restrict a keyring**
           **keyctl restrict_keyring** <keyring> [<type> [<restriction>]]
    
           This command limits the linkage of keys to the given keyring using
           a provided restriction scheme. The scheme is associated with a
           given key type, with further details provided in the restriction
           option string.  Options typically contain a restriction name
           possibly followed by key ids or other data relevant to the
           restriction. If no restriction scheme is provided, the keyring
           will reject all links.
    
                  $ keyctl restrict_keyring $1 asymmetric builtin_trusted
    
       **Read a key**
           **keyctl read** <key>
           **keyctl pipe** <key>
           **keyctl print** <key>
    
           These commands read the payload of a key. "read" prints it on
           stdout as a hex dump, "pipe" dumps the raw data to stdout and
           "print" dumps it to stdout directly if it's entirely printable or
           as a hexdump preceded by ":hex:" if not.
    
           If the key type does not support reading of the payload, then
           error "Operation not supported" will be returned.
    
                  $ keyctl read 26
                  1 bytes of data in key:
                  62
                  $ keyctl print 26
                  b
                  $ keyctl pipe 26
                  b$
    
       **List a keyring**
           **keyctl list** <keyring>
           **keyctl rlist** <keyring>
    
           These commands list the contents of a key as a keyring. "list"
           pretty prints the contents and "rlist" just produces a space-
           separated list of key IDs.
    
           No attempt is made to check that the specified keyring is a
           keyring.
    
                  $ keyctl list @us
                  2 keys in keyring:
                         22: vrwsl----------  4043    -1 keyring: _uid.4043
                         23: vrwsl----------  4043  4043 user: debug:hello
                  $ keyctl rlist @us
                  22 23
    
       **Describe a key**
           **keyctl describe** <keyring>
           **keyctl rdescribe** <keyring> [sep]
    
           These commands fetch a description of a keyring. "describe" pretty
           prints the description in the same fashion as the "list" command;
           "rdescribe" prints the raw data returned from the kernel.
    
                  $ keyctl describe @us
                         -5: vrwsl----------  4043    -1 keyring: _uid_ses.4043
                  $ keyctl rdescribe @us
                  keyring;4043;-1;3f1f0000;_uid_ses.4043
    
           The raw string is "<type>;<uid>;<gid>;<perms>;<description>",
           where _uid_ and _gid_ are the decimal user and group IDs, _perms_ is the
           permissions mask in hex, _type_ and _description_ are the type name
           and description strings (neither of which will contain
           semicolons).
    
       **Change the access controls on a key**
           **keyctl chown** <key> <uid>
           **keyctl chgrp** <key> <gid>
    
           These two commands change the UID and GID associated with
           evaluating a key's permissions mask. The UID also governs which
           quota a key is taken out of.
    
           The chown command is not currently supported; attempting it will
           earn the error "Operation not supported" at best.
    
           For non-superuser users, the GID may only be set to the process's
           GID or a GID in the process's groups list. The superuser may set
           any GID it likes.
    
                  $ sudo keyctl chown 27 0
                  keyctl_chown: Operation not supported
                  $ sudo keyctl chgrp 27 0
    
       **Set the permissions mask on a key**
           **keyctl setperm** <key> <mask>
    
           This command changes the permission control mask on a key. The
           mask may be specified as a hex number if it begins "0x", an octal
           number if it begins "0" or a decimal number otherwise.
    
           The hex numbers are a combination of:
    
                  Possessor UID       GID       Other     Permission Granted
                  ========  ========  ========  ========  ==================
                  01000000  00010000  00000100  00000001  View
                  02000000  00020000  00000200  00000002  Read
                  04000000  00040000  00000400  00000004  Write
                  08000000  00080000  00000800  00000008  Search
                  10000000  00100000  00001000  00000010  Link
                  20000000  00200000  00002000  00000020  Set Attribute
                  3f000000  003f0000  00003f00  0000003f  All
    
           _View_ permits the type, description and other parameters of a key
           to be viewed.
    
           _Read_ permits the payload (or keyring list) to be read if supported
           by the type.
    
           _Write_ permits the payload (or keyring list) to be modified or
           updated.
    
           _Search_ on a key permits it to be found when a keyring to which it
           is linked is searched.
    
           _Link_ permits a key to be linked to a keyring.
    
           _Set Attribute_ permits a key to have its owner, group membership,
           permissions mask and timeout changed.
    
                  $ keyctl setperm 27 0x1f1f1f00
    
       **Start a new session with fresh keyrings**
           **keyctl session**
           **keyctl session** - [<prog> <arg1> <arg2> ...]
           **keyctl session** <name> [<prog> <arg1> <arg2> ...]
    
           These commands join or create a new keyring and then run a shell
           or other program with that keyring as the session key.
    
           The variation with no arguments just creates an anonymous session
           keyring and attaches that as the session keyring; it then exec's
           $SHELL.
    
           The variation with a dash in place of a name creates an anonymous
           session keyring and attaches that as the session keyring; it then
           exec's the supplied command, or $SHELL if one isn't supplied.
    
           The variation with a name supplied creates or joins the named
           keyring and attaches that as the session keyring; it then exec's
           the supplied command, or $SHELL if one isn't supplied.
    
                  $ keyctl rdescribe @s
                  keyring;4043;-1;3f1f0000;_uid_ses.4043
    
                  $ keyctl session
                  Joined session keyring: 28
    
                  $ keyctl rdescribe @s
                  keyring;4043;4043;3f1f0000;_ses.24082
    
                  $ keyctl session -
                  Joined session keyring: 29
                  $ keyctl rdescribe @s
                  keyring;4043;4043;3f1f0000;_ses.24139
    
                  $ keyctl session - keyctl rdescribe @s
                  Joined session keyring: 30
                  keyring;4043;4043;3f1f0000;_ses.24185
    
                  $ keyctl session fish
                  Joined session keyring: 34
                  $ keyctl rdescribe @s
                  keyring;4043;4043;3f1f0000;fish
    
                  $ keyctl session fish keyctl rdesc @s
                  Joined session keyring: 35
                  keyring;4043;4043;3f1f0000;fish
    
       **Instantiate a key**
           **keyctl instantiate**[-x] <key> <data> <keyring>
           **keyctl pinstantiate**[-x] <key> <keyring>
           **keyctl negate** <key> <timeout> <keyring>
           **keyctl reject** <key> <timeout> <error> <keyring>
    
           These commands are used to attach data to a partially set up key
           (as created by the kernel and passed to _/sbin/request-key_).
           "instantiate" marks a key as being valid and attaches the data as
           the payload.  "negate" and "reject" mark a key as invalid and sets
           a timeout on it so that it'll go away after a while.  This
           prevents a lot of quickly sequential requests from slowing the
           system down overmuch when they all fail, as all subsequent
           requests will then fail with error "Requested key not found" (if
           negated) or the specified error (if rejected) until the negative
           key has expired.
    
           Reject's error argument can either be a UNIX error number or one
           of '**rejected** ', '**expired** ' or '**revoked** '.
    
           The newly instantiated key will be attached to the specified
           keyring.
    
           These commands may only be run from the program run by request-key
           - a special authorisation key is set up by the kernel and attached
           to the request-key's session keyring. This special key is revoked
           once the key to which it refers has been instantiated one way or
           another.
    
                  $ keyctl instantiate $1 "Debug $3" $4
                  $ keyctl negate $1 30 $4
                  $ keyctl reject $1 30 64 $4
    
           The **pinstantiate** variant of the command reads the data from stdin
           rather than taking it from the command line:
    
                  $ echo -n "Debug $3" | keyctl pinstantiate $1 $4
    
           If **-x** is given, then the data is hex-decoded with whitespace being
           discarded:
    
                  $ echo 01 02 03 04 | keyctl pinstantiate -x $1 $4
    
       **Set the expiry time on a key**
           **keyctl timeout** <key> <timeout>
    
           This command is used to set the timeout on a key, or clear an
           existing timeout if the value specified is zero. The timeout is
           given as a number of seconds into the future.
    
                  $ keyctl timeout $1 45
    
       **Retrieve a key's security context**
           **keyctl security** <key>
    
           This command is used to retrieve a key's LSM security context.
           The label is printed on stdout.
    
                  $ keyctl security @s
                  unconfined_u:unconfined_r:unconfined_t:s0-s0:c0.c1023
    
       **Give the parent process a new session keyring**
           **keyctl new_session [ <name>]**
    
           This command is used to give the invoking process (typically a
           shell) a new session keyring, discarding its old session keyring.
           If a name is given, the keyring is given that name, otherwise it
           will be given a name of "_ses" and will not be manually joinable.
    
                  $  keyctl session foo
                  Joined session keyring: 723488146
                  $  keyctl show
                  Session Keyring
                         -3 --alswrv      0     0  keyring: foo
                  $  keyctl new_session
                  490511412
                  $  keyctl show
                  Session Keyring
                         -3 --alswrv      0     0  keyring: _ses
    
           Note that this affects the _parent_ of the process that invokes the
           system call, and so may only affect processes with matching
           credentials.  Furthermore, the change does not take effect till
           the parent process next transitions from kernel space to user
           space - typically when the **wait**() system call returns.
    
       **Remove dead keys from the session keyring tree**
           **keyctl reap**
    
           This command performs a depth-first search of the caller's session
           keyring tree and attempts to unlink any key that it finds that is
           inaccessible due to expiry, revocation, rejection or negation.  It
           does not attempt to remove live keys that are unavailable simply
           due to a lack of granted permission.
    
           A key that is designated reapable will only be removed from a
           keyring if the caller has Write permission on that keyring, and
           only keyrings that grant Search permission to the caller will be
           searched.
    
           The command prints the number of keys reaped before it exits.  If
           the **-v** flag is passed then the reaped keys are listed as they're
           being reaped, together with the success or failure of the unlink.
    
       **Remove matching keys from the session keyring tree**
           **keyctl** purge <type>
           **keyctl** purge [-i] [-p] <type> <desc>
           **keyctl** purge -s <type> <desc>
    
           These commands perform a depth-first search to find matching keys
           in the caller's session keyring tree and attempts to unlink them.
           The number of keys successfully unlinked is printed at the end.
    
           The keyrings must grant Read and View permission to the caller to
           be searched, and the keys to be removed must also grant View
           permission.  Keys can only be removed from keyrings that grant
           Write permission.
    
           The first variant purges all keys of the specified type.
    
           The second variant purges all keys of the specified type that also
           match the given description literally.  The -i flag allows a case-
           independent match and the -p flag allows a prefix match.
    
           The third variant purges all keys of the specified type and
           matching description using the key type's comparator in the kernel
           to match the description.  This permits the key type to match a
           key with a variety of descriptions.
    
       **Get persistent keyring**
           **keyctl** get_persistent <keyring> [<uid>]
    
           This command gets the persistent keyring for either the current
           UID or the specified UID and attaches it to the nominated keyring.
           The persistent keyring's ID will be printed on stdout.
    
           The kernel will create the keyring if it doesn't exist and every
           time this command is called, will reset the expiration timeout on
           the keyring to the value in:
    
                  /proc/sys/kernel/keys/persistent_keyring_expiry
    
           (by default three days).  Should the timeout be reached, the
           persistent keyring will be removed and everything it pins can then
           be garbage collected.
    
           If a UID other than the process's real or effective UIDs is
           specified, then an error will be given if the process does not
           have the CAP_SETUID capability.
    
       **Compute a Diffie-Hellman shared secret or public key**
           **keyctl** dh_compute <private> <prime> <base>
    
           This command computes either a Diffie-Hellman shared secret or the
           public key corresponding to the provided private key using the
           payloads of three keys. The computation is:
    
                  base ^ private (mod prime)
    
           The three inputs must be user keys with read permission. If the
           provided base key contains the shared generator value, the public
           key will be computed.  If the provided base key contains the
           remote public key value, the shared secret will be computed.
    
           The result is printed to stdout as a hex dump.
    
                  $ keyctl dh_compute $1 $2 $3
                  8 bytes of data in result:
                  00010203 04050607
    
       **Compute a Diffie-Hellman shared secret and derive key material**
           **keyctl** dh_compute_kdf <private> <prime> <base> <output_length>
           <hash_type>
    
           This command computes a Diffie-Hellman shared secret and derives
           key material from the shared secret using a key derivation
           function (KDF).  The shared secret is derived as outlined above
           and is input to the KDF using the specified hash type. The hash
           type must point to a hash name known to the kernel crypto API.
    
           The operation derives key material of the length specified by the
           caller.
    
           The operation is compliant to the specification of SP800-56A.
    
           The result is printed to stdout as hex dump.
    
       **Compute a Diffie-Hellman shared secret and apply KDF with other input**
           **keyctl** dh_compute_kdf_oi [-x] <private> <prime> <base>
           <output_length> <hash_type>
    
           This command is identical to the command _dh_compute_kdf_ to
           generate a Diffie-Hellman shared secret followed by a key
           derivation operation. This command allows the caller to provide
           the other input data (OI data) compliant to SP800-56A via stdin.
    
           If **-x** is given, then the data passed to stdin is hex-decoded with
           whitespace being discarded.
    
       **Perform public-key operations with an asymmetric key**
           **keyctl** pkey_query <key> <pass> [k=v]*
           **keyctl** pkey_encrypt <key> <pass> <datafile> [k=v]* > <encfile>
           **keyctl** pkey_decrypt <key> <pass> <encfile> [k=v]* > <datafile>
           **keyctl** pkey_sign <key> <pass> <datafile> [k=v]* > <sigfile>
           **keyctl** pkey_verify <key> <pass> <datafile> <sigfile> [k=v]*
    
           These commands query an asymmetric key, encrypt data with it,
           decrypt the encrypted data, generate a signature over some data
           and verify that signature.  For encrypt, decrypt and sign, the
           resulting data is written to stdout; verify reads the data and the
           signature files and compares them.
    
           [**!**] NOTE that the data is of very limited capacity, with no more
           bits than the size of the key.  For signatures, the caller is
           expected to digest the actual data and pass in the result of the
           digest as the datafile.  The name of the digest should be
           specified on the end of the command line as "hash=<name>".
    
           The _key_ ID indicates the key to use; _pass_ is a placeholder for
           future password provision and should be "0" for the moment;
           _datafile_ is the unencrypted data to be encrypted, signed or to
           have its signature checked; _encfile_ is a file containing encrypted
           data; and _sigfile_ is a file containing a signature.
    
           A list of parameters in "key[=val]" form can be included on the
           end of the command line.  These specify things like the digest
           algorithm used ("hash=<name>") or the encoding form
           ("enc=<type>").
    
                  k=`keyctl padd asymmetric "" @s <key.pkcs8.der`
                  keyctl pkey_query $k 0 enc=pkcs1 hash=sha256
                  keyctl pkey_encrypt $k 0 foo.hash enc=pkcs1 >foo.enc
                  keyctl pkey_decrypt $k 0 foo.enc enc=pkcs1 >foo.hash
                  keyctl pkey_sign $k 0 foo.hash enc=pkcs1 hash=sha256 >foo.sig
                  keyctl pkey_verify $k 0 foo.hash foo.sig enc=pkcs1 hash=sha256
    
           See asymmetric-key(7) for more information.
    
       **Change notifications**
           **keyctl** watch [-f<filters>] <key>
           **keyctl** watch_session [-f <filters>] [-n <name>] \
                           <notifylog> <gclog> <fd> <prog> [<arg1> <arg2>
           ...]  **keyctl** watch_add <fd> <key>
           **keyctl** watch_rm <fd> <key>
    
           The **watch** command watches a single key, printing notifications to
           stdout until the key is destroyed.  Filters can be employed to cut
           down the events that will be delivered.  The _filter_ string is a
           series of letters, each one of which enables a particular event
           subtype:
    
                  **i** - The key has been instantiated
                  **p** - The key has been updated
                  **l** - A link has been added to a keyring
                  **n** - A link has been removed from a keyring
                  **c** - A keyring has been cleared
                  **r** - A key has been revoked
                  **v** - A key has been invalidated
                  **s** - A key has had its attributes changed
    
           The output of the command looks like:
    
                  <_keyid_ > <_event_ > [<_aux_ >]
    
           Where _keyid_ is the primary subject of the notification, _op_ is the
           event and _aux_ is the secondary key if there is one (such as link
           where the primary key is the keyring secondary key is the key
           being linked in to it).  For example:
    
                  255913279 link 340681059
                  255913279 clr
    
           An additional notication is generated when a key being watched is
           garbage collected, e.g.:
    
                  255913279 gc
    
           The **watch_session** command creates a new session keyring, with name
           _name_ if given, watches it for notifications and runs program _prog_
           with it.  The program is given the specified arguments.
    
           A second process is forked off to monitor the notifications.  The
           output from that is directed to the files _notifylog_ for most
           notifications and _gclog_ for key removal notifications (which are
           asynchronous and may be deferred).
    
           The **watch_queue**(7) device is exported to the program attached to
           fd number _fd_.  This can be passed by the other two commands.
    
           The **watch_add** command adds a watch on _key_ to the **watch_queue**
           attached to _fd_ as exported by watch_session and the **watch_rm**
           caommand removes it.  A watch_queue can handle multiple keys and
           even non-keys sources as well.
    


## ERRORS



           There are a number of common errors returned by this program:
    
           "Not a directory" - a key wasn't a keyring.
    
           "Requested key not found" - the looked for key isn't available.
    
           "Key has been revoked" - a revoked key was accessed.
    
           "Key has expired" - an expired key was accessed.
    
           "Permission denied" - permission was denied by a UID/GID/mask
           combination.
    


* * *