1078 lines
31 KiB
Groff
1078 lines
31 KiB
Groff
.\"
|
|
.\" Copyright (C) 2004 Red Hat, Inc. All Rights Reserved.
|
|
.\" Written by David Howells (dhowells@redhat.com)
|
|
.\"
|
|
.\" This program is free software; you can redistribute it and/or
|
|
.\" modify it under the terms of the GNU General Public License
|
|
.\" as published by the Free Software Foundation; either version
|
|
.\" 2 of the License, or (at your option) any later version.
|
|
.\"
|
|
.TH KEYCTL 1 "20 Feb 2014" Linux "Linux Key Management Utilities"
|
|
.SH NAME
|
|
keyctl \- key management facility control
|
|
.SH SYNOPSIS
|
|
\fBkeyctl\fR \-\-version
|
|
.br
|
|
\fBkeyctl\fR supports [<cap> | --raw]
|
|
.br
|
|
\fBkeyctl\fR id [<keyring>]
|
|
.br
|
|
\fBkeyctl\fR show [\-x] [<keyring>]
|
|
.br
|
|
\fBkeyctl\fR add [\-x] <type> <desc> <data> <keyring>
|
|
.br
|
|
\fBkeyctl\fR padd [\-x] <type> <desc> <keyring>
|
|
.br
|
|
\fBkeyctl\fR request <type> <desc> [<dest_keyring>]
|
|
.br
|
|
\fBkeyctl\fR request2 <type> <desc> <info> [<dest_keyring>]
|
|
.br
|
|
\fBkeyctl\fR prequest2 <type> <desc> [<dest_keyring>]
|
|
.br
|
|
\fBkeyctl\fR update [\-x] <key> <data>
|
|
.br
|
|
\fBkeyctl\fR pupdate [\-x] <key>
|
|
.br
|
|
\fBkeyctl\fR newring <name> <keyring>
|
|
.br
|
|
\fBkeyctl\fR revoke <key>
|
|
.br
|
|
\fBkeyctl\fR clear <keyring>
|
|
.br
|
|
\fBkeyctl\fR link <key> <keyring>
|
|
.br
|
|
\fBkeyctl\fR unlink <key> [<keyring>]
|
|
.br
|
|
\fBkeyctl\fR move [-f] <key> <from_keyring> <to_keyring>
|
|
.br
|
|
\fBkeyctl\fR search <keyring> <type> <desc> [<dest_keyring>]
|
|
.br
|
|
\fBkeyctl\fR restrict_keyring <keyring> [<type> [<restriction>]]
|
|
.br
|
|
\fBkeyctl\fR read <key>
|
|
.br
|
|
\fBkeyctl\fR pipe <key>
|
|
.br
|
|
\fBkeyctl\fR print <key>
|
|
.br
|
|
\fBkeyctl\fR list <keyring>
|
|
.br
|
|
\fBkeyctl\fR rlist <keyring>
|
|
.br
|
|
\fBkeyctl\fR describe <keyring>
|
|
.br
|
|
\fBkeyctl\fR rdescribe <keyring> [sep]
|
|
.br
|
|
\fBkeyctl\fR chown <key> <uid>
|
|
.br
|
|
\fBkeyctl\fR chgrp <key> <gid>
|
|
.br
|
|
\fBkeyctl\fR setperm <key> <mask>
|
|
.br
|
|
\fBkeyctl\fR new_session [<name>]
|
|
.br
|
|
\fBkeyctl\fR session
|
|
.br
|
|
\fBkeyctl\fR session \- [<prog> <arg1> <arg2> ...]
|
|
.br
|
|
\fBkeyctl\fR session <name> [<prog> <arg1> <arg2> ...]
|
|
.br
|
|
\fBkeyctl\fR instantiate [\-x] <key> <data> <keyring>
|
|
.br
|
|
\fBkeyctl\fR pinstantiate [\-x] <key> <keyring>
|
|
.br
|
|
\fBkeyctl\fR negate <key> <timeout> <keyring>
|
|
.br
|
|
\fBkeyctl\fR reject <key> <timeout> <error> <keyring>
|
|
.br
|
|
\fBkeyctl\fR timeout <key> <timeout>
|
|
.br
|
|
\fBkeyctl\fR security <key>
|
|
.br
|
|
\fBkeyctl\fR reap [\-v]
|
|
.br
|
|
\fBkeyctl\fR purge <type>
|
|
.br
|
|
\fBkeyctl\fR purge [\-i] [\-p] <type> <desc>
|
|
.br
|
|
\fBkeyctl\fR purge \-s <type> <desc>
|
|
.br
|
|
\fBkeyctl\fR get_persistent <keyring> [<uid>]
|
|
.br
|
|
\fBkeyctl\fR dh_compute <private> <prime> <base>
|
|
.br
|
|
\fBkeyctl\fR dh_compute_kdf <private> <prime> <base> <output_length> <hash_type>
|
|
.br
|
|
\fBkeyctl\fR dh_compute_kdf_oi [\-x] <private> <prime> <base> <output_length> <hash_type>
|
|
.br
|
|
\fBkeyctl\fR pkey_query <key> <pass> [k=v]*
|
|
.br
|
|
\fBkeyctl\fR pkey_encrypt <key> <pass> <datafile> [k=v]* ><encfile>
|
|
.br
|
|
\fBkeyctl\fR pkey_decrypt <key> <pass> <encfile> [k=v]* ><datafile>
|
|
.br
|
|
\fBkeyctl\fR pkey_sign <key> <pass> <datafile> [k=v]* ><sigfile>
|
|
.br
|
|
\fBkeyctl\fR pkey_decrypt <key> <pass> <datafile> <sigfile> [k=v]*
|
|
.br
|
|
\fBkeyctl\fR watch [\-f<filters>] <key>
|
|
.br
|
|
\fBkeyctl\fR watch_add <fd> <key>
|
|
.br
|
|
\fBkeyctl\fR watch_rm <fd> <key>
|
|
.br
|
|
\fBkeyctl\fR watch_session [\-f <filters>] [-n <name>] \\
|
|
<notifylog> <gclog> <fd> <prog> [<arg1> <arg2> ...]
|
|
.SH DESCRIPTION
|
|
This program is used to control the key management facility in various ways
|
|
using a variety of subcommands.
|
|
.SH 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:
|
|
.TP
|
|
No key: \fB0\fR
|
|
.TP
|
|
Thread keyring: \fB@t\fR or \fB\-1\fR
|
|
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.
|
|
.TP
|
|
Process keyring: \fB@p\fR or \fB\-2\fR
|
|
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.
|
|
.TP
|
|
Session keyring: \fB@s\fR or \fB\-3\fR
|
|
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.
|
|
.TP
|
|
User specific keyring: \fB@u\fR or \fB\-4\fR
|
|
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.
|
|
.TP
|
|
User default session keyring: \fB@us\fR or \fB\-5\fR
|
|
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.
|
|
.TP
|
|
Group specific keyring: \fB@g\fR or \fB\-6\fR
|
|
This is a place holder for a group specific keyring, but is not actually
|
|
implemented yet in the kernel.
|
|
.TP
|
|
Assumed request_key authorisation key: \fB@a\fR or \fB\-7\fR
|
|
This selects the authorisation key provided to the
|
|
.BR request_key ()
|
|
helper to
|
|
permit it to access the callers keyrings and instantiate the target key.
|
|
.TP
|
|
Keyring by name: \fB%:<name>\fR
|
|
A named keyring. This will be searched for in the process's keyrings and in
|
|
.IR /proc/keys .
|
|
.TP
|
|
Key by name: \fB%<type>:<name>\fR
|
|
A named key of the given type. This will be searched for in the process's
|
|
keyrings and in
|
|
.IR /proc/keys .
|
|
.SH 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.
|
|
.SS Display the package version number
|
|
\fBkeyctl \-\-version\fR
|
|
|
|
This command prints the package version number and build date and exits:
|
|
|
|
.RS
|
|
.nf
|
|
$ keyctl \-\-version
|
|
keyctl from keyutils\-1.5.3 (Built 2011\-08\-24)
|
|
.fi
|
|
.RE
|
|
.SS Query subsystem capabilities
|
|
.nf
|
|
\fBkeyctl\fR supports
|
|
\fBkeyctl\fR supports --raw
|
|
\fBkeyctl\fR supports <cap>
|
|
.fi
|
|
.P
|
|
This command can list the available capabilities:
|
|
.P
|
|
.RS
|
|
.nf
|
|
$ keyctl supports
|
|
have_capabilities=0
|
|
have_persistent_keyrings=1
|
|
have_dh_compute=1
|
|
have_public_key=1
|
|
...
|
|
.fi
|
|
.RE
|
|
.P
|
|
produce a raw hex dump of the capabilities list:
|
|
.P
|
|
.RS
|
|
.nf
|
|
$ keyctl supports --raw
|
|
ff0f
|
|
.fi
|
|
.RE
|
|
.P
|
|
or query a specific capability:
|
|
|
|
.RS
|
|
.nf
|
|
$ keyctl supports pkey
|
|
echo $?
|
|
0
|
|
.fi
|
|
.RE
|
|
|
|
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:
|
|
.TP
|
|
.B capabilities
|
|
The kernel supports capability querying. If not, the other capabilities will
|
|
be queried as best libkeyutils can manage.
|
|
.TP
|
|
.B persistent_keyrings
|
|
The kernel supports persistent keyrings.
|
|
.TP
|
|
.B dh_compute
|
|
The kernel supports Diffie-Hellman computation operations.
|
|
.TP
|
|
.B public_key
|
|
The kernel supports public key operations.
|
|
.TP
|
|
.B big_key_type
|
|
The kernel supports the big_key key type.
|
|
.TP
|
|
.B key_invalidate
|
|
The kernel supports the invalidate key operaiton.
|
|
.TP
|
|
.B restrict_keyring
|
|
The kernel supports the restrict_keyring operation.
|
|
.TP
|
|
.B move_key
|
|
The kernel supports the move key operation.
|
|
.TP
|
|
.B ns_keyring_name
|
|
Keyring names are segregated according to the user-namespace in which the
|
|
keyrings are created.
|
|
.TP
|
|
.B 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.
|
|
|
|
.SS Show actual key or keyring ID
|
|
\fBkeyctl id [<key>]\fR
|
|
|
|
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.
|
|
|
|
.SS Show process keyrings
|
|
\fBkeyctl show [\-x] [<keyring>]\fR
|
|
|
|
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 \fB\-x\fR is specified then the keyring
|
|
IDs will be dumped in hex instead of decimal.
|
|
.SS Add a key to a keyring
|
|
\fBkeyctl add\fR [\-x] <type> <desc> <data> <keyring>
|
|
.br
|
|
\fBkeyctl padd\fR [\-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:
|
|
|
|
.RS
|
|
.nf
|
|
$ keyctl add user mykey stuff @u
|
|
26
|
|
.fi
|
|
.RE
|
|
|
|
The \fBpadd\fR variant of the command reads the data from stdin rather than
|
|
taking it from the command line:
|
|
|
|
.RS
|
|
.fi
|
|
$ echo \-n stuff | keyctl padd user mykey @u
|
|
26
|
|
.fi
|
|
.RE
|
|
|
|
If \fB\-x\fR is given, then the data is hex-decoded with whitespace being
|
|
discarded.
|
|
|
|
.SS Request a key
|
|
\fBkeyctl request\fR <type> <desc> [<dest_keyring>]
|
|
.br
|
|
\fBkeyctl request2\fR <type> <desc> <info> [<dest_keyring>]
|
|
.br
|
|
\fBkeyctl prequest2\fR <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
|
|
.IR /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.
|
|
|
|
.RS
|
|
.nf
|
|
$ keyctl request2 user debug:hello wibble
|
|
23
|
|
$ echo \-n wibble | keyctl prequest2 user debug:hello
|
|
23
|
|
$ keyctl request user debug:hello
|
|
23
|
|
.fi
|
|
.RE
|
|
.SS Update a key
|
|
\fBkeyctl update\fR [\-x] <key> <data>
|
|
.br
|
|
\fBkeyctl pupdate\fR [\-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.
|
|
|
|
.RS
|
|
.nf
|
|
$ keyctl update 23 zebra
|
|
.fi
|
|
.RE
|
|
|
|
The \fBpupdate\fR variant of the command reads the data from stdin rather than
|
|
taking it from the command line:
|
|
|
|
.RS
|
|
.nf
|
|
$ echo \-n zebra | keyctl pupdate 23
|
|
$ echo 616263313233 | keyctl pupdate -x 23
|
|
.fi
|
|
.RE
|
|
|
|
If \fB\-x\fR is given, then the data is hex-decoded with whitespace being
|
|
discarded.
|
|
|
|
.SS Create a keyring
|
|
\fBkeyctl newring\fR <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.
|
|
|
|
.RS
|
|
.nf
|
|
$ keyctl newring squelch @us
|
|
27
|
|
.fi
|
|
.RE
|
|
.SS Revoke a key
|
|
\fBkeyctl revoke\fR <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".
|
|
|
|
.RS
|
|
.nf
|
|
$ keyctl revoke 26
|
|
$ keyctl describe 26
|
|
keyctl_describe: Key has been revoked
|
|
.fi
|
|
.RE
|
|
.SS Clear a keyring
|
|
\fBkeyctl clear\fR <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.
|
|
|
|
.RS
|
|
.nf
|
|
$ keyctl clear 27
|
|
.fi
|
|
.RE
|
|
.SS Link a key to a keyring
|
|
\fBkeyctl link\fR <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.
|
|
|
|
.RS
|
|
.nf
|
|
$ keyctl link 23 27
|
|
$ keyctl link 27 27
|
|
keyctl_link: Resource deadlock avoided
|
|
.fi
|
|
.RE
|
|
.SS Unlink a key from a keyring or the session keyring tree
|
|
\fBkeyctl unlink\fR <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.
|
|
|
|
.RS
|
|
.nf
|
|
$ keyctl unlink 23 27
|
|
.fi
|
|
.RE
|
|
.SS Move a key between keyrings.
|
|
\fBkeyctl move\fR [-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".
|
|
|
|
.RS
|
|
.nf
|
|
$ keyctl move 23 27 29
|
|
$ keyctl move -f 71 @u @s
|
|
.fi
|
|
.RE
|
|
.SS Search a keyring
|
|
\fBkeyctl search\fR <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.
|
|
|
|
.RS
|
|
.nf
|
|
$ keyctl search @us user debug:hello
|
|
23
|
|
$ keyctl search @us user debug:bye
|
|
keyctl_search: Requested key not available
|
|
.fi
|
|
.RE
|
|
.SS Restrict a keyring
|
|
\fBkeyctl restrict_keyring\fR <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.
|
|
|
|
.RS
|
|
.nf
|
|
$ keyctl restrict_keyring $1 asymmetric builtin_trusted
|
|
.RE
|
|
.SS Read a key
|
|
\fBkeyctl read\fR <key>
|
|
.br
|
|
\fBkeyctl pipe\fR <key>
|
|
.br
|
|
\fBkeyctl print\fR <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.
|
|
|
|
.RS
|
|
.nf
|
|
$ keyctl read 26
|
|
1 bytes of data in key:
|
|
62
|
|
$ keyctl print 26
|
|
b
|
|
$ keyctl pipe 26
|
|
$
|
|
.fi
|
|
.RE
|
|
.SS List a keyring
|
|
\fBkeyctl list\fR <keyring>
|
|
.br
|
|
\fBkeyctl rlist\fR <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.
|
|
|
|
.RS
|
|
.nf
|
|
$ 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
|
|
.fi
|
|
.RE
|
|
.SS Describe a key
|
|
\fBkeyctl describe\fR <keyring>
|
|
.br
|
|
\fBkeyctl rdescribe\fR <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.
|
|
|
|
.RS
|
|
.nf
|
|
$ keyctl describe @us
|
|
\-5: vrwsl\-\-\-\-\-\-\-\-\-\- 4043 \-1 keyring: _uid_ses.4043
|
|
$ keyctl rdescribe @us
|
|
keyring;4043;\-1;3f1f0000;_uid_ses.4043
|
|
.fi
|
|
.RE
|
|
|
|
The raw string is "<type>;<uid>;<gid>;<perms>;<description>", where \fIuid\fR
|
|
and \fIgid\fR are the decimal user and group IDs, \fIperms\fR is the
|
|
permissions mask in hex, \fItype\fR and \fIdescription\fR are the type name and
|
|
description strings (neither of which will contain semicolons).
|
|
.SS Change the access controls on a key
|
|
\fBkeyctl chown\fR <key> <uid>
|
|
.br
|
|
\fBkeyctl chgrp\fR <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.
|
|
|
|
.RS
|
|
.nf
|
|
$ sudo keyctl chown 27 0
|
|
keyctl_chown: Operation not supported
|
|
$ sudo keyctl chgrp 27 0
|
|
.fi
|
|
.RE
|
|
.SS Set the permissions mask on a key
|
|
\fBkeyctl setperm\fR <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:
|
|
|
|
.RS
|
|
.nf
|
|
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
|
|
.fi
|
|
.RE
|
|
|
|
\fIView\fR permits the type, description and other parameters of a key to be
|
|
viewed.
|
|
|
|
\fIRead\fR permits the payload (or keyring list) to be read if supported by the
|
|
type.
|
|
|
|
\fIWrite\fR permits the payload (or keyring list) to be modified or updated.
|
|
|
|
\fISearch\fR on a key permits it to be found when a keyring to which it is
|
|
linked is searched.
|
|
|
|
\fILink\fR permits a key to be linked to a keyring.
|
|
|
|
\fISet Attribute\fR permits a key to have its owner, group membership,
|
|
permissions mask and timeout changed.
|
|
|
|
.RS
|
|
.nf
|
|
$ keyctl setperm 27 0x1f1f1f00
|
|
.fi
|
|
.RE
|
|
.SS Start a new session with fresh keyrings
|
|
\fBkeyctl session\fR
|
|
.br
|
|
\fBkeyctl session\fR \- [<prog> <arg1> <arg2> ...]
|
|
.br
|
|
\fBkeyctl session\fR <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.
|
|
|
|
.RS
|
|
.nf
|
|
$ 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
|
|
.fi
|
|
.RE
|
|
.SS Instantiate a key
|
|
\fBkeyctl instantiate\fR [\-x] <key> <data> <keyring>
|
|
.br
|
|
\fBkeyctl pinstantiate\fR [\-x] <key> <keyring>
|
|
.br
|
|
\fBkeyctl negate\fR <key> <timeout> <keyring>
|
|
.br
|
|
\fBkeyctl reject\fR <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
|
|
.IR /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
|
|
.BR "" "'" 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.
|
|
|
|
.RS
|
|
.nf
|
|
$ keyctl instantiate $1 "Debug $3" $4
|
|
$ keyctl negate $1 30 $4
|
|
$ keyctl reject $1 30 64 $4
|
|
.fi
|
|
.RE
|
|
|
|
The \fBpinstantiate\fR variant of the command reads the data from stdin rather
|
|
than taking it from the command line:
|
|
|
|
.RS
|
|
.nf
|
|
$ echo \-n "Debug $3" | keyctl pinstantiate $1 $4
|
|
.fi
|
|
.RE
|
|
|
|
If \fB\-x\fR is given, then the data is hex-decoded with whitespace being
|
|
discarded:
|
|
|
|
.RS
|
|
.nf
|
|
$ echo 01 02 03 04 | keyctl pinstantiate -x $1 $4
|
|
.fi
|
|
.RE
|
|
|
|
.SS Set the expiry time on a key
|
|
\fBkeyctl timeout\fR <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.
|
|
|
|
.RS
|
|
.nf
|
|
$ keyctl timeout $1 45
|
|
.fi
|
|
.RE
|
|
.SS Retrieve a key's security context
|
|
\fBkeyctl security\fR <key>
|
|
|
|
This command is used to retrieve a key's LSM security context. The label is
|
|
printed on stdout.
|
|
|
|
.RS
|
|
.nf
|
|
$ keyctl security @s
|
|
unconfined_u:unconfined_r:unconfined_t:s0\-s0:c0.c1023
|
|
.fi
|
|
.RE
|
|
.SS Give the parent process a new session keyring
|
|
\fBkeyctl new_session [<name>]\fR
|
|
|
|
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.
|
|
|
|
.RS
|
|
.nf
|
|
$ 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
|
|
.fi
|
|
.RE
|
|
|
|
Note that this affects the \fIparent\fP 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 \fBwait\fP()
|
|
system call returns.
|
|
|
|
.SS Remove dead keys from the session keyring tree
|
|
\fBkeyctl reap\fR
|
|
|
|
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 \fB\-v\fR
|
|
flag is passed then the reaped keys are listed as they're being reaped,
|
|
together with the success or failure of the unlink.
|
|
.SS Remove matching keys from the session keyring tree
|
|
\fBkeyctl\fR purge <type>
|
|
.br
|
|
\fBkeyctl\fR purge [\-i] [\-p] <type> <desc>
|
|
.br
|
|
\fBkeyctl\fR 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.
|
|
.SS Get persistent keyring
|
|
\fBkeyctl\fR 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:
|
|
.IP
|
|
/proc/sys/kernel/keys/persistent_keyring_expiry
|
|
.P
|
|
(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.
|
|
.SS Compute a Diffie-Hellman shared secret or public key
|
|
\fBkeyctl\fR 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:
|
|
.IP
|
|
base ^ private (mod prime)
|
|
.P
|
|
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.
|
|
|
|
.RS
|
|
.nf
|
|
$ keyctl dh_compute $1 $2 $3
|
|
8 bytes of data in result:
|
|
00010203 04050607
|
|
.fi
|
|
.RE
|
|
|
|
.SS Compute a Diffie-Hellman shared secret and derive key material
|
|
\fBkeyctl\fR 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.
|
|
.SS Compute a Diffie-Hellman shared secret and apply KDF with other input
|
|
\fBkeyctl\fR dh_compute_kdf_oi [\-x] <private> <prime> <base> <output_length> <hash_type>
|
|
|
|
This command is identical to the command
|
|
.IR 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 \fB\-x\fR is given, then the data passed to stdin is hex-decoded with
|
|
whitespace being discarded.
|
|
|
|
.SS Perform public-key operations with an asymmetric key
|
|
\fBkeyctl\fR pkey_query <key> <pass> [k=v]*
|
|
.br
|
|
\fBkeyctl\fR pkey_encrypt <key> <pass> <datafile> [k=v]* > <encfile>
|
|
.br
|
|
\fBkeyctl\fR pkey_decrypt <key> <pass> <encfile> [k=v]* > <datafile>
|
|
.br
|
|
\fBkeyctl\fR pkey_sign <key> <pass> <datafile> [k=v]* > <sigfile>
|
|
.br
|
|
\fBkeyctl\fR pkey_verify <key> <pass> <datafile> <sigfile> [k=v]*
|
|
.PP
|
|
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.
|
|
.PP
|
|
[\fB!\fP] 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>".
|
|
.PP
|
|
The
|
|
.I key
|
|
ID indicates the key to use;
|
|
.I pass
|
|
is a placeholder for future password provision and should be "0" for the
|
|
moment;
|
|
.I datafile
|
|
is the unencrypted data to be encrypted, signed or to have its signature
|
|
checked;
|
|
.I encfile
|
|
is a file containing encrypted data; and
|
|
.I sigfile
|
|
is a file containing a signature.
|
|
.PP
|
|
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>").
|
|
.PP
|
|
.RS
|
|
.nf
|
|
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
|
|
.fi
|
|
.RE
|
|
.PP
|
|
See asymmetric-key(7) for more information.
|
|
|
|
.SS Change notifications
|
|
\fBkeyctl\fR watch [\-f<filters>] <key>
|
|
.br
|
|
\fBkeyctl\fR watch_session [\-f <filters>] [-n <name>] \\
|
|
<notifylog> <gclog> <fd> <prog> [<arg1> <arg2> ...]
|
|
\fBkeyctl\fR watch_add <fd> <key>
|
|
.br
|
|
\fBkeyctl\fR watch_rm <fd> <key>
|
|
.br
|
|
.PP
|
|
The
|
|
.B 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
|
|
.I filter
|
|
string is a series of letters, each one of which enables a particular event
|
|
subtype:
|
|
.PP
|
|
.RS
|
|
.nf
|
|
.BR i " - The key has been instantiated"
|
|
.BR p " - The key has been updated"
|
|
.BR l " - A link has been added to a keyring"
|
|
.BR n " - A link has been removed from a keyring"
|
|
.BR c " - A keyring has been cleared"
|
|
.BR r " - A key has been revoked"
|
|
.BR v " - A key has been invalidated"
|
|
.BR s " - A key has had its attributes changed"
|
|
.fi
|
|
.RE
|
|
.PP
|
|
The output of the command looks like:
|
|
.PP
|
|
.RS
|
|
.nf
|
|
.RI < keyid "> <" event "> [<" aux ">]"
|
|
.fi
|
|
.RE
|
|
.PP
|
|
Where
|
|
.I keyid
|
|
is the primary subject of the notification,
|
|
.I op
|
|
is the event and
|
|
.I 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:
|
|
.PP
|
|
.RS
|
|
.nf
|
|
255913279 link 340681059
|
|
255913279 clr
|
|
.fi
|
|
.RE
|
|
.PP
|
|
An additional notication is generated when a key being watched is garbage
|
|
collected, e.g.:
|
|
.PP
|
|
.RS
|
|
.nf
|
|
255913279 gc
|
|
.fi
|
|
.RE
|
|
.PP
|
|
The
|
|
.B watch_session
|
|
command creates a new session keyring, with name
|
|
.I name
|
|
if given, watches it for notifications and runs program
|
|
.I prog
|
|
with it. The program is given the specified arguments.
|
|
.PP
|
|
A second process is forked off to monitor the notifications. The output from
|
|
that is directed to the files
|
|
.I notifylog
|
|
for most notifications and
|
|
.I gclog
|
|
for key removal notifications (which are asynchronous and may be deferred).
|
|
.PP
|
|
The
|
|
.BR watch_queue (7)
|
|
device is exported to the program attached to fd number
|
|
.IR fd .
|
|
This can be passed by the other two commands.
|
|
.PP
|
|
The
|
|
.B watch_add
|
|
command adds a watch on
|
|
.I key
|
|
to the
|
|
.B watch_queue
|
|
attached to
|
|
.I fd
|
|
as exported by watch_session and the
|
|
.B watch_rm
|
|
caommand removes it. A watch_queue can handle multiple keys and even non-keys
|
|
sources as well.
|
|
|
|
|
|
.SH 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.
|
|
.SH SEE ALSO
|
|
.ad l
|
|
.nh
|
|
.BR keyctl (1),
|
|
.BR keyctl (2),
|
|
.BR request_key (2),
|
|
.BR keyctl (3),
|
|
.BR request\-key.conf (5),
|
|
.BR keyrings (7),
|
|
.BR request\-key (8)
|