jpayne@68: .\" jpayne@68: .\" Copyright (C) 2004 Red Hat, Inc. All Rights Reserved. jpayne@68: .\" Written by David Howells (dhowells@redhat.com) jpayne@68: .\" jpayne@68: .\" This program is free software; you can redistribute it and/or jpayne@68: .\" modify it under the terms of the GNU General Public License jpayne@68: .\" as published by the Free Software Foundation; either version jpayne@68: .\" 2 of the License, or (at your option) any later version. jpayne@68: .\" jpayne@68: .TH KEYCTL 1 "20 Feb 2014" Linux "Linux Key Management Utilities" jpayne@68: .SH NAME jpayne@68: keyctl \- key management facility control jpayne@68: .SH SYNOPSIS jpayne@68: \fBkeyctl\fR \-\-version jpayne@68: .br jpayne@68: \fBkeyctl\fR supports [] jpayne@68: .br jpayne@68: \fBkeyctl\fR show [\-x] [] jpayne@68: .br jpayne@68: \fBkeyctl\fR add jpayne@68: .br jpayne@68: \fBkeyctl\fR padd jpayne@68: .br jpayne@68: \fBkeyctl\fR request [] jpayne@68: .br jpayne@68: \fBkeyctl\fR request2 [] jpayne@68: .br jpayne@68: \fBkeyctl\fR prequest2 [] jpayne@68: .br jpayne@68: \fBkeyctl\fR update jpayne@68: .br jpayne@68: \fBkeyctl\fR pupdate jpayne@68: .br jpayne@68: \fBkeyctl\fR newring jpayne@68: .br jpayne@68: \fBkeyctl\fR revoke jpayne@68: .br jpayne@68: \fBkeyctl\fR clear jpayne@68: .br jpayne@68: \fBkeyctl\fR link jpayne@68: .br jpayne@68: \fBkeyctl\fR unlink [] jpayne@68: .br jpayne@68: \fBkeyctl\fR move [-f] jpayne@68: .br jpayne@68: \fBkeyctl\fR search [] jpayne@68: .br jpayne@68: \fBkeyctl\fR restrict_keyring [ []] jpayne@68: .br jpayne@68: \fBkeyctl\fR read jpayne@68: .br jpayne@68: \fBkeyctl\fR pipe jpayne@68: .br jpayne@68: \fBkeyctl\fR print jpayne@68: .br jpayne@68: \fBkeyctl\fR list jpayne@68: .br jpayne@68: \fBkeyctl\fR rlist jpayne@68: .br jpayne@68: \fBkeyctl\fR describe jpayne@68: .br jpayne@68: \fBkeyctl\fR rdescribe [sep] jpayne@68: .br jpayne@68: \fBkeyctl\fR chown jpayne@68: .br jpayne@68: \fBkeyctl\fR chgrp jpayne@68: .br jpayne@68: \fBkeyctl\fR setperm jpayne@68: .br jpayne@68: \fBkeyctl\fR new_session jpayne@68: .br jpayne@68: \fBkeyctl\fR session jpayne@68: .br jpayne@68: \fBkeyctl\fR session \- [ ...] jpayne@68: .br jpayne@68: \fBkeyctl\fR session [ ...] jpayne@68: .br jpayne@68: \fBkeyctl\fR instantiate jpayne@68: .br jpayne@68: \fBkeyctl\fR pinstantiate jpayne@68: .br jpayne@68: \fBkeyctl\fR negate jpayne@68: .br jpayne@68: \fBkeyctl\fR reject jpayne@68: .br jpayne@68: \fBkeyctl\fR timeout jpayne@68: .br jpayne@68: \fBkeyctl\fR security jpayne@68: .br jpayne@68: \fBkeyctl\fR reap [\-v] jpayne@68: .br jpayne@68: \fBkeyctl\fR purge jpayne@68: .br jpayne@68: \fBkeyctl\fR purge [\-i] [\-p] jpayne@68: .br jpayne@68: \fBkeyctl\fR purge \-s jpayne@68: .br jpayne@68: \fBkeyctl\fR get_persistent [] jpayne@68: .br jpayne@68: \fBkeyctl\fR dh_compute jpayne@68: .br jpayne@68: \fBkeyctl\fR dh_compute_kdf jpayne@68: .br jpayne@68: \fBkeyctl\fR dh_compute_kdf_oi jpayne@68: .br jpayne@68: \fBkeyctl\fR pkey_query [k=v]* jpayne@68: .br jpayne@68: \fBkeyctl\fR pkey_encrypt [k=v]* > jpayne@68: .br jpayne@68: \fBkeyctl\fR pkey_decrypt [k=v]* > jpayne@68: .br jpayne@68: \fBkeyctl\fR pkey_sign [k=v]* > jpayne@68: .br jpayne@68: \fBkeyctl\fR pkey_decrypt [k=v]* jpayne@68: .SH DESCRIPTION jpayne@68: This program is used to control the key management facility in various ways jpayne@68: using a variety of subcommands. jpayne@68: .SH KEY IDENTIFIERS jpayne@68: The key identifiers passed to or returned from keyctl are, in general, positive jpayne@68: integers. There are, however, some special values with special meanings that jpayne@68: can be passed as arguments: jpayne@68: .TP jpayne@68: No key: \fB0\fR jpayne@68: .TP jpayne@68: Thread keyring: \fB@t\fR or \fB\-1\fR jpayne@68: Each thread may have its own keyring. This is searched first, before all jpayne@68: others. The thread keyring is replaced by (v)fork, exec and clone. jpayne@68: .TP jpayne@68: Process keyring: \fB@p\fR or \fB\-2\fR jpayne@68: Each process (thread group) may have its own keyring. This is shared between jpayne@68: all members of a group and will be searched after the thread keyring. The jpayne@68: process keyring is replaced by (v)fork and exec. jpayne@68: .TP jpayne@68: Session keyring: \fB@s\fR or \fB\-3\fR jpayne@68: Each process subscribes to a session keyring that is inherited across (v)fork, jpayne@68: exec and clone. This is searched after the process keyring. Session keyrings jpayne@68: can be named and an extant keyring can be joined in place of a process's jpayne@68: current session keyring. jpayne@68: .TP jpayne@68: User specific keyring: \fB@u\fR or \fB\-4\fR jpayne@68: This keyring is shared between all the processes owned by a particular user. It jpayne@68: isn't searched directly, but is normally linked to from the session keyring. jpayne@68: .TP jpayne@68: User default session keyring: \fB@us\fR or \fB\-5\fR jpayne@68: This is the default session keyring for a particular user. Login processes that jpayne@68: change to a particular user will bind to this session until another session is jpayne@68: set. jpayne@68: .TP jpayne@68: Group specific keyring: \fB@g\fR or \fB\-6\fR jpayne@68: This is a place holder for a group specific keyring, but is not actually jpayne@68: implemented yet in the kernel. jpayne@68: .TP jpayne@68: Assumed request_key authorisation key: \fB@a\fR or \fB\-7\fR jpayne@68: This selects the authorisation key provided to the jpayne@68: .BR request_key () jpayne@68: helper to jpayne@68: permit it to access the callers keyrings and instantiate the target key. jpayne@68: .TP jpayne@68: Keyring by name: \fB%:\fR jpayne@68: A named keyring. This will be searched for in the process's keyrings and in jpayne@68: .IR /proc/keys . jpayne@68: .TP jpayne@68: Key by name: \fB%:\fR jpayne@68: A named key of the given type. This will be searched for in the process's jpayne@68: keyrings and in jpayne@68: .IR /proc/keys . jpayne@68: .SH COMMAND SYNTAX jpayne@68: Any non-ambiguous shortening of a command name may be used in lieu of the full jpayne@68: command name. This facility should not be used in scripting as new commands may jpayne@68: be added in future that then cause ambiguity. jpayne@68: .SS Display the package version number jpayne@68: \fBkeyctl \-\-version\fR jpayne@68: jpayne@68: This command prints the package version number and build date and exits: jpayne@68: jpayne@68: .RS jpayne@68: .nf jpayne@68: $ keyctl \-\-version jpayne@68: keyctl from keyutils\-1.5.3 (Built 2011\-08\-24) jpayne@68: .fi jpayne@68: .RE jpayne@68: .SS Query subsystem capabilities jpayne@68: \fBkeyctl\fR supports [] jpayne@68: jpayne@68: This command can list the available capabilities: jpayne@68: jpayne@68: .RS jpayne@68: .nf jpayne@68: $ keyctl supports jpayne@68: have_capabilities=0 jpayne@68: have_persistent_keyrings=1 jpayne@68: have_dh_compute=1 jpayne@68: have_public_key=1 jpayne@68: ... jpayne@68: .fi jpayne@68: .RE jpayne@68: .P jpayne@68: And it can query a capability: jpayne@68: jpayne@68: .RS jpayne@68: .nf jpayne@68: $ keyctl supports pkey jpayne@68: echo $? jpayne@68: 0 jpayne@68: .fi jpayne@68: .RE jpayne@68: jpayne@68: which returns 0 if the capability is supported, 1 if it isn't and 3 if the jpayne@68: name is not recognised. The capabilities supported are: jpayne@68: .TP jpayne@68: .B capabilities jpayne@68: The kernel supports capability querying. If not, the other capabilities will jpayne@68: be queried as best libkeyutils can manage. jpayne@68: .TP jpayne@68: .B persistent_keyrings jpayne@68: The kernel supports persistent keyrings. jpayne@68: .TP jpayne@68: .B dh_compute jpayne@68: The kernel supports Diffie-Hellman computation operations. jpayne@68: .TP jpayne@68: .B public_key jpayne@68: The kernel supports public key operations. jpayne@68: .TP jpayne@68: .B big_key_type jpayne@68: The kernel supports the big_key key type. jpayne@68: .TP jpayne@68: .B key_invalidate jpayne@68: The kernel supports the invalidate key operaiton. jpayne@68: .TP jpayne@68: .B restrict_keyring jpayne@68: The kernel supports the restrict_keyring operation. jpayne@68: .TP jpayne@68: .B move_key jpayne@68: The kernel supports the move key operation. jpayne@68: jpayne@68: .SS Show process keyrings jpayne@68: \fBkeyctl show [\-x] []\fR jpayne@68: jpayne@68: By default this command recursively shows what keyrings a process is subscribed jpayne@68: to and what keys and keyrings they contain. If a keyring is specified then jpayne@68: that keyring will be dumped instead. If \fB\-x\fR is specified then the keyring jpayne@68: IDs will be dumped in hex instead of decimal. jpayne@68: .SS Add a key to a keyring jpayne@68: \fBkeyctl add\fR jpayne@68: .br jpayne@68: \fBkeyctl padd\fR jpayne@68: jpayne@68: This command creates a key of the specified type and description; instantiates jpayne@68: it with the given data and attaches it to the specified keyring. It then prints jpayne@68: the new key's ID on stdout: jpayne@68: jpayne@68: .RS jpayne@68: .nf jpayne@68: $ keyctl add user mykey stuff @u jpayne@68: 26 jpayne@68: .fi jpayne@68: .RE jpayne@68: jpayne@68: The \fBpadd\fR variant of the command reads the data from stdin rather than jpayne@68: taking it from the command line: jpayne@68: jpayne@68: .RS jpayne@68: .fi jpayne@68: $ echo \-n stuff | keyctl padd user mykey @u jpayne@68: 26 jpayne@68: .fi jpayne@68: .RE jpayne@68: .SS Request a key jpayne@68: \fBkeyctl request\fR [] jpayne@68: .br jpayne@68: \fBkeyctl request2\fR [] jpayne@68: .br jpayne@68: \fBkeyctl prequest2\fR [] jpayne@68: jpayne@68: These three commands request the lookup of a key of the given type and jpayne@68: description. The process's keyrings will be searched, and if a match is found jpayne@68: the matching key's ID will be printed to stdout; and if a destination keyring jpayne@68: is given, the key will be added to that keyring also. jpayne@68: jpayne@68: If there is no key, the first command will simply return the error ENOKEY and jpayne@68: fail. The second and third commands will create a partial key with the type and jpayne@68: description, and call out to jpayne@68: .IR /sbin/request\-key jpayne@68: with that key and the jpayne@68: extra information supplied. This will then attempt to instantiate the key in jpayne@68: some manner, such that a valid key is obtained. jpayne@68: jpayne@68: The third command is like the second, except that the callout information is jpayne@68: read from stdin rather than being passed on the command line. jpayne@68: jpayne@68: If a valid key is obtained, the ID will be printed and the key attached as if jpayne@68: the original search had succeeded. jpayne@68: jpayne@68: If there wasn't a valid key obtained, a temporary negative key will be attached jpayne@68: to the destination keyring if given and the error "Requested key not available" jpayne@68: will be given. jpayne@68: jpayne@68: .RS jpayne@68: .nf jpayne@68: $ keyctl request2 user debug:hello wibble jpayne@68: 23 jpayne@68: $ echo \-n wibble | keyctl prequest2 user debug:hello jpayne@68: 23 jpayne@68: $ keyctl request user debug:hello jpayne@68: 23 jpayne@68: .fi jpayne@68: .RE jpayne@68: .SS Update a key jpayne@68: \fBkeyctl update\fR jpayne@68: .br jpayne@68: \fBkeyctl pupdate\fR jpayne@68: jpayne@68: This command replaces the data attached to a key with a new set of data. If the jpayne@68: type of the key doesn't support update then error "Operation not supported" jpayne@68: will be returned. jpayne@68: jpayne@68: .RS jpayne@68: .nf jpayne@68: $ keyctl update 23 zebra jpayne@68: .fi jpayne@68: .RE jpayne@68: jpayne@68: The \fBpupdate\fR variant of the command reads the data from stdin rather than jpayne@68: taking it from the command line: jpayne@68: jpayne@68: .RS jpayne@68: .nf jpayne@68: $ echo \-n zebra | keyctl pupdate 23 jpayne@68: .fi jpayne@68: .RE jpayne@68: .SS Create a keyring jpayne@68: \fBkeyctl newring\fR jpayne@68: jpayne@68: This command creates a new keyring of the specified name and attaches it to the jpayne@68: specified keyring. The ID of the new keyring will be printed to stdout if jpayne@68: successful. jpayne@68: jpayne@68: .RS jpayne@68: .nf jpayne@68: $ keyctl newring squelch @us jpayne@68: 27 jpayne@68: .fi jpayne@68: .RE jpayne@68: .SS Revoke a key jpayne@68: \fBkeyctl revoke\fR jpayne@68: jpayne@68: This command marks a key as being revoked. Any further operations on that key jpayne@68: (apart from unlinking it) will return error "Key has been revoked". jpayne@68: jpayne@68: .RS jpayne@68: .nf jpayne@68: $ keyctl revoke 26 jpayne@68: $ keyctl describe 26 jpayne@68: keyctl_describe: Key has been revoked jpayne@68: .fi jpayne@68: .RE jpayne@68: .SS Clear a keyring jpayne@68: \fBkeyctl clear\fR jpayne@68: jpayne@68: This command unlinks all the keys attached to the specified keyring. Error jpayne@68: "Not a directory" will be returned if the key specified is not a keyring. jpayne@68: jpayne@68: .RS jpayne@68: .nf jpayne@68: $ keyctl clear 27 jpayne@68: .fi jpayne@68: .RE jpayne@68: .SS Link a key to a keyring jpayne@68: \fBkeyctl link\fR jpayne@68: jpayne@68: This command makes a link from the key to the keyring if there's enough jpayne@68: capacity to do so. Error "Not a directory" will be returned if the destination jpayne@68: is not a keyring. Error "Permission denied" will be returned if the key doesn't jpayne@68: have link permission or the keyring doesn't have write permission. Error "File jpayne@68: table overflow" will be returned if the keyring is full. Error "Resource jpayne@68: deadlock avoided" will be returned if an attempt was made to introduce a jpayne@68: recursive link. jpayne@68: jpayne@68: .RS jpayne@68: .nf jpayne@68: $ keyctl link 23 27 jpayne@68: $ keyctl link 27 27 jpayne@68: keyctl_link: Resource deadlock avoided jpayne@68: .fi jpayne@68: .RE jpayne@68: .SS Unlink a key from a keyring or the session keyring tree jpayne@68: \fBkeyctl unlink\fR [] jpayne@68: jpayne@68: If the keyring is specified, this command removes a link to the key from the jpayne@68: keyring. Error "Not a directory" will be returned if the destination is not a jpayne@68: keyring. Error "Permission denied" will be returned if the keyring doesn't have jpayne@68: write permission. Error "No such file or directory" will be returned if the key jpayne@68: is not linked to by the keyring. jpayne@68: jpayne@68: If the keyring is not specified, this command performs a depth-first search of jpayne@68: the session keyring tree and removes all the links to the nominated key that it jpayne@68: finds (and that it is permitted to remove). It prints the number of successful jpayne@68: unlinks before exiting. jpayne@68: jpayne@68: .RS jpayne@68: .nf jpayne@68: $ keyctl unlink 23 27 jpayne@68: .fi jpayne@68: .RE jpayne@68: .SS Move a key between keyrings. jpayne@68: \fBkeyctl move\fR [-f] jpayne@68: jpayne@68: This command moves a key from one keyring to another, atomically combining jpayne@68: "keyctl unlink " and "keyctl link ". jpayne@68: jpayne@68: If the "-f" flag is present, any matching key will be displaced from jpayne@68: "to_keyring"; if not present, the command will fail with the error message jpayne@68: "File exists" if the key would otherwise displace another key from jpayne@68: "to_keyring". jpayne@68: jpayne@68: .RS jpayne@68: .nf jpayne@68: $ keyctl move 23 27 29 jpayne@68: $ keyctl move -f 71 @u @s jpayne@68: .fi jpayne@68: .RE jpayne@68: .SS Search a keyring jpayne@68: \fBkeyctl search\fR [] jpayne@68: jpayne@68: This command non-recursively searches a keyring for a key of a particular type jpayne@68: and description. If found, the ID of the key will be printed on stdout and the jpayne@68: key will be attached to the destination keyring if present. Error "Requested jpayne@68: key not available" will be returned if the key is not found. jpayne@68: jpayne@68: .RS jpayne@68: .nf jpayne@68: $ keyctl search @us user debug:hello jpayne@68: 23 jpayne@68: $ keyctl search @us user debug:bye jpayne@68: keyctl_search: Requested key not available jpayne@68: .fi jpayne@68: .RE jpayne@68: .SS Restrict a keyring jpayne@68: \fBkeyctl restrict_keyring\fR [ []] jpayne@68: jpayne@68: This command limits the linkage of keys to the given keyring using a provided jpayne@68: restriction scheme. The scheme is associated with a given key type, with jpayne@68: further details provided in the restriction option string. Options typically jpayne@68: contain a restriction name possibly followed by key ids or other data relevant jpayne@68: to the restriction. If no restriction scheme is provided, the keyring will jpayne@68: reject all links. jpayne@68: jpayne@68: .RS jpayne@68: .nf jpayne@68: $ keyctl restrict_keyring $1 asymmetric builtin_trusted jpayne@68: .RE jpayne@68: .SS Read a key jpayne@68: \fBkeyctl read\fR jpayne@68: .br jpayne@68: \fBkeyctl pipe\fR jpayne@68: .br jpayne@68: \fBkeyctl print\fR jpayne@68: jpayne@68: These commands read the payload of a key. "read" prints it on stdout as a hex jpayne@68: dump, "pipe" dumps the raw data to stdout and "print" dumps it to stdout jpayne@68: directly if it's entirely printable or as a hexdump preceded by ":hex:" if not. jpayne@68: jpayne@68: If the key type does not support reading of the payload, then error "Operation jpayne@68: not supported" will be returned. jpayne@68: jpayne@68: .RS jpayne@68: .nf jpayne@68: $ keyctl read 26 jpayne@68: 1 bytes of data in key: jpayne@68: 62 jpayne@68: $ keyctl print 26 jpayne@68: b jpayne@68: $ keyctl pipe 26 jpayne@68: $ jpayne@68: .fi jpayne@68: .RE jpayne@68: .SS List a keyring jpayne@68: \fBkeyctl list\fR jpayne@68: .br jpayne@68: \fBkeyctl rlist\fR jpayne@68: jpayne@68: These commands list the contents of a key as a keyring. "list" pretty prints jpayne@68: the contents and "rlist" just produces a space-separated list of key IDs. jpayne@68: jpayne@68: No attempt is made to check that the specified keyring is a keyring. jpayne@68: jpayne@68: .RS jpayne@68: .nf jpayne@68: $ keyctl list @us jpayne@68: 2 keys in keyring: jpayne@68: 22: vrwsl\-\-\-\-\-\-\-\-\-\- 4043 \-1 keyring: _uid.4043 jpayne@68: 23: vrwsl\-\-\-\-\-\-\-\-\-\- 4043 4043 user: debug:hello jpayne@68: $ keyctl rlist @us jpayne@68: 22 23 jpayne@68: .fi jpayne@68: .RE jpayne@68: .SS Describe a key jpayne@68: \fBkeyctl describe\fR jpayne@68: .br jpayne@68: \fBkeyctl rdescribe\fR [sep] jpayne@68: jpayne@68: These commands fetch a description of a keyring. "describe" pretty prints the jpayne@68: description in the same fashion as the "list" command; "rdescribe" prints the jpayne@68: raw data returned from the kernel. jpayne@68: jpayne@68: .RS jpayne@68: .nf jpayne@68: $ keyctl describe @us jpayne@68: \-5: vrwsl\-\-\-\-\-\-\-\-\-\- 4043 \-1 keyring: _uid_ses.4043 jpayne@68: $ keyctl rdescribe @us jpayne@68: keyring;4043;\-1;3f1f0000;_uid_ses.4043 jpayne@68: .fi jpayne@68: .RE jpayne@68: jpayne@68: The raw string is ";;;;", where \fIuid\fR jpayne@68: and \fIgid\fR are the decimal user and group IDs, \fIperms\fR is the jpayne@68: permissions mask in hex, \fItype\fR and \fIdescription\fR are the type name and jpayne@68: description strings (neither of which will contain semicolons). jpayne@68: .SS Change the access controls on a key jpayne@68: \fBkeyctl chown\fR jpayne@68: .br jpayne@68: \fBkeyctl chgrp\fR jpayne@68: jpayne@68: These two commands change the UID and GID associated with evaluating a key's jpayne@68: permissions mask. The UID also governs which quota a key is taken out of. jpayne@68: jpayne@68: The chown command is not currently supported; attempting it will earn the error jpayne@68: "Operation not supported" at best. jpayne@68: jpayne@68: For non-superuser users, the GID may only be set to the process's GID or a GID jpayne@68: in the process's groups list. The superuser may set any GID it likes. jpayne@68: jpayne@68: .RS jpayne@68: .nf jpayne@68: $ sudo keyctl chown 27 0 jpayne@68: keyctl_chown: Operation not supported jpayne@68: $ sudo keyctl chgrp 27 0 jpayne@68: .fi jpayne@68: .RE jpayne@68: .SS Set the permissions mask on a key jpayne@68: \fBkeyctl setperm\fR jpayne@68: jpayne@68: This command changes the permission control mask on a key. The mask may be jpayne@68: specified as a hex number if it begins "0x", an octal number if it begins "0" jpayne@68: or a decimal number otherwise. jpayne@68: jpayne@68: The hex numbers are a combination of: jpayne@68: jpayne@68: .RS jpayne@68: .nf jpayne@68: Possessor UID GID Other Permission Granted jpayne@68: ======== ======== ======== ======== ================== jpayne@68: 01000000 00010000 00000100 00000001 View jpayne@68: 02000000 00020000 00000200 00000002 Read jpayne@68: 04000000 00040000 00000400 00000004 Write jpayne@68: 08000000 00080000 00000800 00000008 Search jpayne@68: 10000000 00100000 00001000 00000010 Link jpayne@68: 20000000 00200000 00002000 00000020 Set Attribute jpayne@68: 3f000000 003f0000 00003f00 0000003f All jpayne@68: .fi jpayne@68: .RE jpayne@68: jpayne@68: \fIView\fR permits the type, description and other parameters of a key to be jpayne@68: viewed. jpayne@68: jpayne@68: \fIRead\fR permits the payload (or keyring list) to be read if supported by the jpayne@68: type. jpayne@68: jpayne@68: \fIWrite\fR permits the payload (or keyring list) to be modified or updated. jpayne@68: jpayne@68: \fISearch\fR on a key permits it to be found when a keyring to which it is jpayne@68: linked is searched. jpayne@68: jpayne@68: \fILink\fR permits a key to be linked to a keyring. jpayne@68: jpayne@68: \fISet Attribute\fR permits a key to have its owner, group membership, jpayne@68: permissions mask and timeout changed. jpayne@68: jpayne@68: .RS jpayne@68: .nf jpayne@68: $ keyctl setperm 27 0x1f1f1f00 jpayne@68: .fi jpayne@68: .RE jpayne@68: .SS Start a new session with fresh keyrings jpayne@68: \fBkeyctl session\fR jpayne@68: .br jpayne@68: \fBkeyctl session\fR \- [ ...] jpayne@68: .br jpayne@68: \fBkeyctl session\fR [ ...] jpayne@68: jpayne@68: These commands join or create a new keyring and then run a shell or other jpayne@68: program with that keyring as the session key. jpayne@68: jpayne@68: The variation with no arguments just creates an anonymous session keyring and jpayne@68: attaches that as the session keyring; it then exec's $SHELL. jpayne@68: jpayne@68: The variation with a dash in place of a name creates an anonymous session jpayne@68: keyring and attaches that as the session keyring; it then exec's the supplied jpayne@68: command, or $SHELL if one isn't supplied. jpayne@68: jpayne@68: The variation with a name supplied creates or joins the named keyring and jpayne@68: attaches that as the session keyring; it then exec's the supplied command, or jpayne@68: $SHELL if one isn't supplied. jpayne@68: jpayne@68: .RS jpayne@68: .nf jpayne@68: $ keyctl rdescribe @s jpayne@68: keyring;4043;\-1;3f1f0000;_uid_ses.4043 jpayne@68: jpayne@68: $ keyctl session jpayne@68: Joined session keyring: 28 jpayne@68: jpayne@68: $ keyctl rdescribe @s jpayne@68: keyring;4043;4043;3f1f0000;_ses.24082 jpayne@68: jpayne@68: $ keyctl session \- jpayne@68: Joined session keyring: 29 jpayne@68: $ keyctl rdescribe @s jpayne@68: keyring;4043;4043;3f1f0000;_ses.24139 jpayne@68: jpayne@68: $ keyctl session \- keyctl rdescribe @s jpayne@68: Joined session keyring: 30 jpayne@68: keyring;4043;4043;3f1f0000;_ses.24185 jpayne@68: jpayne@68: $ keyctl session fish jpayne@68: Joined session keyring: 34 jpayne@68: $ keyctl rdescribe @s jpayne@68: keyring;4043;4043;3f1f0000;fish jpayne@68: jpayne@68: $ keyctl session fish keyctl rdesc @s jpayne@68: Joined session keyring: 35 jpayne@68: keyring;4043;4043;3f1f0000;fish jpayne@68: .fi jpayne@68: .RE jpayne@68: .SS Instantiate a key jpayne@68: \fBkeyctl instantiate\fR jpayne@68: .br jpayne@68: \fBkeyctl pinstantiate\fR jpayne@68: .br jpayne@68: \fBkeyctl negate\fR jpayne@68: .br jpayne@68: \fBkeyctl reject\fR jpayne@68: jpayne@68: These commands are used to attach data to a partially set up key (as created by jpayne@68: the kernel and passed to jpayne@68: .IR /sbin/request\-key ). jpayne@68: "instantiate" marks a key as jpayne@68: being valid and attaches the data as the payload. "negate" and "reject" mark a jpayne@68: key as invalid and sets a timeout on it so that it'll go away after a while. jpayne@68: This prevents a lot of quickly sequential requests from slowing the system down jpayne@68: overmuch when they all fail, as all subsequent requests will then fail with jpayne@68: error "Requested key not found" (if negated) or the specified error (if jpayne@68: rejected) until the negative key has expired. jpayne@68: jpayne@68: Reject's error argument can either be a UNIX error number or one of jpayne@68: .BR "" "'" rejected "', '" expired "' or '" revoked "'." jpayne@68: jpayne@68: The newly instantiated key will be attached to the specified keyring. jpayne@68: jpayne@68: These commands may only be run from the program run by request\-key - a special jpayne@68: authorisation key is set up by the kernel and attached to the request\-key's jpayne@68: session keyring. This special key is revoked once the key to which it refers jpayne@68: has been instantiated one way or another. jpayne@68: jpayne@68: .RS jpayne@68: .nf jpayne@68: $ keyctl instantiate $1 "Debug $3" $4 jpayne@68: $ keyctl negate $1 30 $4 jpayne@68: $ keyctl reject $1 30 64 $4 jpayne@68: .fi jpayne@68: .RE jpayne@68: jpayne@68: The \fBpinstantiate\fR variant of the command reads the data from stdin rather jpayne@68: than taking it from the command line: jpayne@68: jpayne@68: .RS jpayne@68: .nf jpayne@68: $ echo \-n "Debug $3" | keyctl pinstantiate $1 $4 jpayne@68: .fi jpayne@68: .RE jpayne@68: .SS Set the expiry time on a key jpayne@68: \fBkeyctl timeout\fR jpayne@68: jpayne@68: This command is used to set the timeout on a key, or clear an existing timeout jpayne@68: if the value specified is zero. The timeout is given as a number of seconds jpayne@68: into the future. jpayne@68: jpayne@68: .RS jpayne@68: .nf jpayne@68: $ keyctl timeout $1 45 jpayne@68: .fi jpayne@68: .RE jpayne@68: .SS Retrieve a key's security context jpayne@68: \fBkeyctl security\fR jpayne@68: jpayne@68: This command is used to retrieve a key's LSM security context. The label is jpayne@68: printed on stdout. jpayne@68: jpayne@68: .RS jpayne@68: .nf jpayne@68: $ keyctl security @s jpayne@68: unconfined_u:unconfined_r:unconfined_t:s0\-s0:c0.c1023 jpayne@68: .fi jpayne@68: .RE jpayne@68: .SS Give the parent process a new session keyring jpayne@68: \fBkeyctl new_session\fR jpayne@68: jpayne@68: This command is used to give the invoking process (typically a shell) a new jpayne@68: session keyring, discarding its old session keyring. jpayne@68: jpayne@68: .RS jpayne@68: .nf jpayne@68: $ keyctl session foo jpayne@68: Joined session keyring: 723488146 jpayne@68: $ keyctl show jpayne@68: Session Keyring jpayne@68: \-3 \-\-alswrv 0 0 keyring: foo jpayne@68: $ keyctl new_session jpayne@68: 490511412 jpayne@68: $ keyctl show jpayne@68: Session Keyring jpayne@68: \-3 \-\-alswrv 0 0 keyring: _ses jpayne@68: .fi jpayne@68: .RE jpayne@68: jpayne@68: Note that this affects the \fIparent\fP of the process that invokes the system jpayne@68: call, and so may only affect processes with matching credentials. jpayne@68: Furthermore, the change does not take effect till the parent process next jpayne@68: transitions from kernel space to user space - typically when the \fBwait\fP() jpayne@68: system call returns. jpayne@68: .SS Remove dead keys from the session keyring tree jpayne@68: \fBkeyctl reap\fR jpayne@68: jpayne@68: This command performs a depth-first search of the caller's session keyring tree jpayne@68: and attempts to unlink any key that it finds that is inaccessible due to jpayne@68: expiry, revocation, rejection or negation. It does not attempt to remove live jpayne@68: keys that are unavailable simply due to a lack of granted permission. jpayne@68: jpayne@68: A key that is designated reapable will only be removed from a keyring if the jpayne@68: caller has Write permission on that keyring, and only keyrings that grant jpayne@68: Search permission to the caller will be searched. jpayne@68: jpayne@68: The command prints the number of keys reaped before it exits. If the \fB\-v\fR jpayne@68: flag is passed then the reaped keys are listed as they're being reaped, jpayne@68: together with the success or failure of the unlink. jpayne@68: .SS Remove matching keys from the session keyring tree jpayne@68: \fBkeyctl\fR purge jpayne@68: .br jpayne@68: \fBkeyctl\fR purge [\-i] [\-p] jpayne@68: .br jpayne@68: \fBkeyctl\fR purge \-s jpayne@68: jpayne@68: These commands perform a depth-first search to find matching keys in the jpayne@68: caller's session keyring tree and attempts to unlink them. The number of jpayne@68: keys successfully unlinked is printed at the end. jpayne@68: jpayne@68: The keyrings must grant Read and View permission to the caller to be searched, jpayne@68: and the keys to be removed must also grant View permission. Keys can only be jpayne@68: removed from keyrings that grant Write permission. jpayne@68: jpayne@68: The first variant purges all keys of the specified type. jpayne@68: jpayne@68: The second variant purges all keys of the specified type that also match the jpayne@68: given description literally. The \-i flag allows a case-independent match and jpayne@68: the \-p flag allows a prefix match. jpayne@68: jpayne@68: The third variant purges all keys of the specified type and matching jpayne@68: description using the key type's comparator in the kernel to match the jpayne@68: description. This permits the key type to match a key with a variety of jpayne@68: descriptions. jpayne@68: .SS Get persistent keyring jpayne@68: \fBkeyctl\fR get_persistent [] jpayne@68: jpayne@68: This command gets the persistent keyring for either the current UID or the jpayne@68: specified UID and attaches it to the nominated keyring. The persistent jpayne@68: keyring's ID will be printed on stdout. jpayne@68: jpayne@68: The kernel will create the keyring if it doesn't exist and every time this jpayne@68: command is called, will reset the expiration timeout on the keyring to the jpayne@68: value in: jpayne@68: .IP jpayne@68: /proc/sys/kernel/keys/persistent_keyring_expiry jpayne@68: .P jpayne@68: (by default three days). Should the timeout be reached, the persistent keyring jpayne@68: will be removed and everything it pins can then be garbage collected. jpayne@68: jpayne@68: If a UID other than the process's real or effective UIDs is specified, then an jpayne@68: error will be given if the process does not have the CAP_SETUID capability. jpayne@68: .SS Compute a Diffie-Hellman shared secret or public key jpayne@68: \fBkeyctl\fR dh_compute jpayne@68: jpayne@68: This command computes either a Diffie-Hellman shared secret or the jpayne@68: public key corresponding to the provided private key using the jpayne@68: payloads of three keys. The computation is: jpayne@68: .IP jpayne@68: base ^ private (mod prime) jpayne@68: .P jpayne@68: The three inputs must be user keys with read permission. If the jpayne@68: provided base key contains the shared generator value, the public key jpayne@68: will be computed. If the provided base key contains the remote public jpayne@68: key value, the shared secret will be computed. jpayne@68: jpayne@68: The result is printed to stdout as a hex dump. jpayne@68: jpayne@68: .RS jpayne@68: .nf jpayne@68: $ keyctl dh_compute $1 $2 $3 jpayne@68: 8 bytes of data in result: jpayne@68: 00010203 04050607 jpayne@68: .SS Compute a Diffie-Hellman shared secret and derive key material jpayne@68: \fBkeyctl\fR dh_compute_kdf jpayne@68: jpayne@68: This command computes a Diffie-Hellman shared secret and derives jpayne@68: key material from the shared secret using a key derivation function (KDF). jpayne@68: The shared secret is derived as outlined above and is input to the KDF jpayne@68: using the specified hash type. The hash type must point to a hash name jpayne@68: known to the kernel crypto API. jpayne@68: jpayne@68: The operation derives key material of the length specified by the caller. jpayne@68: jpayne@68: The operation is compliant to the specification of SP800-56A. jpayne@68: jpayne@68: The result is printed to stdout as hex dump. jpayne@68: .SS Compute a Diffie-Hellman shared secret and apply KDF with other input jpayne@68: \fBkeyctl\fR dh_compute_kdf_oi jpayne@68: jpayne@68: This command is identical to the command jpayne@68: .IR dh_compute_kdf jpayne@68: to generate a Diffie-Hellman shared secret followed by a key derivation jpayne@68: operation. This command allows the caller to provide the other input data jpayne@68: (OI data) compliant to SP800-56A via stdin. jpayne@68: .fi jpayne@68: .RE jpayne@68: .SS Perform public-key operations with an asymmetric key jpayne@68: \fBkeyctl\fR pkey_query [k=v]* jpayne@68: .br jpayne@68: \fBkeyctl\fR pkey_encrypt [k=v]* > jpayne@68: .br jpayne@68: \fBkeyctl\fR pkey_decrypt [k=v]* > jpayne@68: .br jpayne@68: \fBkeyctl\fR pkey_sign [k=v]* > jpayne@68: .br jpayne@68: \fBkeyctl\fR pkey_verify [k=v]* jpayne@68: .PP jpayne@68: These commands query an asymmetric key, encrypt data with it, decrypt the jpayne@68: encrypted data, generate a signature over some data and verify that signature. jpayne@68: For encrypt, decrypt and sign, the resulting data is written to stdout; verify jpayne@68: reads the data and the signature files and compares them. jpayne@68: .PP jpayne@68: [\fB!\fP] NOTE that the data is of very limited capacity, with no more bits jpayne@68: than the size of the key. For signatures, the caller is expected to digest jpayne@68: the actual data and pass in the result of the digest as the datafile. The jpayne@68: name of the digest should be specified on the end of the command line as jpayne@68: "hash=". jpayne@68: .PP jpayne@68: The jpayne@68: .I key jpayne@68: ID indicates the key to use; jpayne@68: .I pass jpayne@68: is a placeholder for future password provision and should be "0" for the jpayne@68: moment; jpayne@68: .I datafile jpayne@68: is the unencrypted data to be encrypted, signed or to have its signature jpayne@68: checked; jpayne@68: .I encfile jpayne@68: is a file containing encrypted data; and jpayne@68: .I sigfile jpayne@68: is a file containing a signature. jpayne@68: .PP jpayne@68: A list of parameters in "key[=val]" form can be included on the end of the jpayne@68: command line. These specify things like the digest algorithm used jpayne@68: ("hash=") or the encoding form ("enc="). jpayne@68: .PP jpayne@68: .RS jpayne@68: .nf jpayne@68: k=`keyctl padd asymmetric "" @s foo.enc jpayne@68: keyctl pkey_decrypt $k 0 foo.enc enc=pkcs1 >foo.hash jpayne@68: keyctl pkey_sign $k 0 foo.hash enc=pkcs1 hash=sha256 >foo.sig jpayne@68: keyctl pkey_verify $k 0 foo.hash foo.sig enc=pkcs1 hash=sha256 jpayne@68: .fi jpayne@68: .RE jpayne@68: .PP jpayne@68: See asymmetric-key(7) for more information. jpayne@68: jpayne@68: .SH ERRORS jpayne@68: There are a number of common errors returned by this program: jpayne@68: jpayne@68: "Not a directory" - a key wasn't a keyring. jpayne@68: jpayne@68: "Requested key not found" - the looked for key isn't available. jpayne@68: jpayne@68: "Key has been revoked" - a revoked key was accessed. jpayne@68: jpayne@68: "Key has expired" - an expired key was accessed. jpayne@68: jpayne@68: "Permission denied" - permission was denied by a UID/GID/mask combination. jpayne@68: .SH SEE ALSO jpayne@68: .ad l jpayne@68: .nh jpayne@68: .BR keyctl (1), jpayne@68: .BR keyctl (2), jpayne@68: .BR request_key (2), jpayne@68: .BR keyctl (3), jpayne@68: .BR request\-key.conf (5), jpayne@68: .BR keyrings (7), jpayne@68: .BR request\-key (8)