diff options
Diffstat (limited to 'man')
36 files changed, 4469 insertions, 0 deletions
diff --git a/man/asymmetric-key.7 b/man/asymmetric-key.7 new file mode 100644 index 0000000..5fc78cb --- /dev/null +++ b/man/asymmetric-key.7 @@ -0,0 +1,232 @@ +.\" +.\" Copyright (C) 2018 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 Licence +.\" as published by the Free Software Foundation; either version +.\" 2 of the Licence, or (at your option) any later version. +.\" +.TH ASYMMETRIC-KEY 7 "8 Nov 2018" Linux "Asymmetric Kernel Key Type" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH NAME +asymmetric \- Kernel key type for holding asymmetric keys +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH OVERVIEW +.PP +A kernel key of +.B asymmetric +type acts as a handle to an asymmetric key as used for public-key +cryptography. The key material itself may be held inside the kernel or it may +be held in hardware with operations being offloaded. This prevents direct +user access to the cryptographic material. +.PP +Keys may be any asymmetric type (RSA, ECDSA, ...) and may have both private and +public components present or just the public component. +.PP +Asymmetric keys can be made use of by both the kernel and userspace. The +kernel can make use of them for module signature verification and kexec image +verification for example. Userspace is provided with a set of +.BR keyctl ( KEYCTL_PKEY_* ) +calls for querying and using the key. These are wrapped by +.B libkeyutils +as functions named +.BR keyctl_pkey_*() . +.PP +An asymmetric-type key can be loaded by the keyctl utility using a command +line like: +.PP +.in +4n +.EX +openssl x509 -in key.x509 -outform DER | +keyctl padd asymmetric foo @s +.EE +.in +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH DESCRIPTION +.PP +The asymmetric-type key can be viewed as a container that comprises of a +number of components: +.TP +Parsers +The asymmetric key parsers attempt to identify the content of the payload blob +and extract useful data from it with which to instantiate the key. The parser +is only used when adding, instantiating or updating a key and isn't thereafter +associated with the key. +.IP +Available parsers include ones that can deal with +.RB "DER-encoded " X.509 ", DER-encoded " PKCS#8 " and DER-encoded " TPM "-wrapped blobs." +.TP +Public and private keys +These are the cryptographic components of the key pair. The public half +should always be available, but the private half might not be. What +operations are available can be queried, as can the size of the key. The key +material may or may not actually reside in the kernel. +.TP +Identifiers +In addition to the normal key description (which can be generated by the +parser), a number of supplementary identifiers may be available that can be +searched for. These may be obtained, for example, by hashing the public key +material or from the subjectKeyIdentifier in an X.509 certificate. +.IP +Identifier-based searches are selected by passing as the description to +.BR keyctl_search () +a string constructed of hex characters prefixed with either "id:" or "ex:". +The "id:" prefix indicates that a partial tail match is permissible whereas +"ex:" requires an exact match on the full string. The hex characters indicate +the data to match. +.TP +Subtype +This is the driver inside the kernel that accesses the key material and +performs operations on it. It might be entirely software-based or it may +offload the operations to a hardware key store, such as a +.BR TPM . +.PP +Note that expiry times from the payload are ignored as these patches may be +used during boot before the system clock is set. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH PARSERS +.PP +The asymmetric key parsers can handle keys in a number of forms: +.TP +\fBX.509\fP +DER-encoded X.509 certificates can be accepted. Two identifiers are +constructed: one from from the certificate issuer and serial number and the +other from the subjectKeyIdentifier, if present. If left blank, the key +description will be filled in from the subject field plus either the +subjectKeyIdentifier or the serialNumber. Only the public key is filled in +and only the encrypt and verify operations are supported. +.IP +The signature on the X.509 certificate may be checked by the keyring it is +being added to and it may also be rejected if the key is blacklisted. +.TP +\fBPKCS#8\fP +Unencrypted DER-encoded PKCS#8 key data containers can be accepted. Currently +no identifiers are constructed. The private key and the public key are loaded +from the PKCS#8 blobs. Encrypted PKCS#8 is not currently supported. +.TP +\fBTPM-Wrapped keys\fP +DER-encoded TPM-wrapped TSS key blobs can be accepted. Currently no +identifiers are constructed. The public key is extracted from the blob but +the private key is expected to be resident in the TPM. Encryption and +signature verification is done in software, but decryption and signing are +offloaded to the TPM so as not to expose the private key. +.IP +This parser only supports TPM-1.2 wrappings and enc=pkcs1 encoding type. It +also uses a hard-coded null SRK password; password-protected SRKs are not yet +supported. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH USERSPACE API +.PP +In addition to the standard keyutils library functions, such as +.IR keyctl_update (), +there are five calls specific to the asymmetric key type (though they are open +to being used by other key types also): +.PP +.RS +\fIkeyctl_pkey_query\fP() +.br +\fIkeyctl_pkey_encrypt\fP() +.br +\fIkeyctl_pkey_decrypt\fP() +.br +\fIkeyctl_pkey_sign\fP() +.br +\fIkeyctl_pkey_verify\fP() +.RE +.PP +The query function can be used to retrieve information about an asymmetric key, +such as the key size, the amount of space required by buffers for the other +operations and which operations are actually supported. +.PP +The other operations form two pairs: encrypt/decrypt and create/verify +signature. Not all of these operations will necessarily be available; +typically, encrypt and verify only require the public key to be available +whereas decrypt and sign require the private key as well. +.PP +All of these operations take an information string parameter that supplies +additional information such as encoding type/form and the password(s) needed to +unlock/unwrap the key. This takes the form of a comma-separated list of +"key[=value]" pairs, the exact set of which depends on the subtype driver used +by a particular key. +.PP +Available parameters include: +.TP +enc=<type> +The encoding type for use in an encrypted blob or a signature. An example +might be "enc=pkcs1". +.TP +hash=<name> +The name of the hash algorithm that was used to digest the data to be signed. +Note that this is only used to construct any encoding that is used in a +signature. The data to be signed or verified must have been parsed by the +caller and the hash passed to \fIkeyctl_pkey_sign\fP() or +\fIkeyctl_pkey_verify\fP() beforehand. An example might be "hash=sha256". +.PP +Note that not all parameters are used by all subtypes. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH RESTRICTED KEYRINGS +.PP +An additional keyutils function, +.IR keyctl_restrict_keyring (), +can be used to gate a keyring so that a new key can only be added to the +affected keyring if (a) it's an asymmetric key, (b) it's validly signed by a +key in some appropriate keyring and (c) it's not blacklisted. +.PP +.in +4n +.EX + keyctl_restrict_keyring(keyring, "asymmetric", + "key_or_keyring:<signing-key>[:chain]"); +.EE +.in +.PP +Where \fI<signing-key>\fP is the ID of a key or a ring of keys that act as the +authority to permit a new key to be added to the keyring. The \fIchain\fP flag +indicates that keys that have been added to the keyring may also be used to +verify new keys. Authorising keys must themselves be asymmetric-type keys that +can be used to do a signature verification on the key being added. +.PP +Note that there are various system keyrings visible to the root user that may +permit additional keys to be added. These are typically gated by keys that +already exist, preventing unauthorised keys from being used for such things as +module verification. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH BLACKLISTING +.PP +When the attempt is made to add a key to the kernel, a hash of the public key +is checked against the +.BR blacklist. +This is a system keyring named +.B .blacklist +and contains keys of type +.BR blacklist . +If the blacklist contains a key whose description matches the hash of the new +key, that new key will be rejected with error +.BR EKEYREJECTED . +.PP +The blacklist keyring may be loaded from multiple sources, including a list +compiled into the kernel and the UEFI +.B dbx +variable. Further hashes may also be blacklisted by the administrator. Note +that blacklisting is not retroactive, so an asymmetric key that is already on +the system cannot be blacklisted by adding a matching blacklist entry later. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH VERSIONS +The +.B asymmetric +key type first appeared in v3.7 of the Linux kernel, the +.B restriction +function in v4.11 and the +.B public key operations +in v4.20. +.SH SEE ALSO +.ad l +.nh +.BR keyctl (1), +.BR add_key (2), +.BR keyctl (3), +.BR keyctl_pkey_encrypt (3), +.BR keyctl_pkey_query (3), +.BR keyctl_pkey_sign (3), +.BR keyrings (7), +.BR keyutils (7) diff --git a/man/find_key_by_type_and_name.3 b/man/find_key_by_type_and_name.3 new file mode 100644 index 0000000..2fbd21e --- /dev/null +++ b/man/find_key_by_type_and_name.3 @@ -0,0 +1,65 @@ +.\" +.\" Copyright (C) 2013 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 Licence +.\" as published by the Free Software Foundation; either version +.\" 2 of the Licence, or (at your option) any later version. +.\" +.TH FIND_KEY_BY_TYPE_AND_NAME 3 "10 Sep 2013" Linux "Linux Key Utility Calls" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH NAME +find_key_by_type_and_name \- find a key by type and name +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SYNOPSIS +.nf +.B #include <keyutils.h> +.sp +.BI "key_serial_t find_key_by_type_and_name(const char *" type , +.BI " const char *" description ", key_serial_t " destringid ");" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH DESCRIPTION +.BR find_key_by_type_and_name () +searches for a key with the given +.I type +and exact +.IR description , +firstly in the thread, process and session keyrings to which a process is +subscribed and secondly in +.IR /proc/keys . +.P +If a key is found, and +.I destringid +is not 0 and specifies a keyring, then the found key will be linked into it. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH RETURN VALUE +The function returns the ID of the key if a key was found or \-1 otherwise. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH ERRORS +.TP +.B ENOKEY +No key was found or the keyring specified is invalid. +.TP +.B EKEYEXPIRED +The key or keyring have expired. +.TP +.B EKEYREVOKED +The key or keyring have been revoked. +.TP +.B EACCES +The key is not accessible or keyring exists, but is not +.B writable +by the calling process. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH LINKING +When linking, +.B \-lkeyutils +should be specified to the linker. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SEE ALSO +.ad l +.nh +.BR request_key (2), +.BR keyctl (3), +.BR keyrings (7) diff --git a/man/key.dns_resolver.8 b/man/key.dns_resolver.8 new file mode 100644 index 0000000..e1882e0 --- /dev/null +++ b/man/key.dns_resolver.8 @@ -0,0 +1,34 @@ +.\" +.\" Copyright (C) 2011 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 KEY.DNS_RESOLVER 8 "04 Mar 2011" Linux "Linux Key Management Utilities" +.SH NAME +key.dns_resolver \- upcall for request\-key to handle dns_resolver keys +.SH SYNOPSIS +\fB/sbin/key.dns_resolver \fR<key> +.br +\fB/sbin/key.dns_resolver \fR\-D [\-v] [\-v] <keydesc> <calloutinfo> +.SH DESCRIPTION +This program is invoked by request\-key on behalf of the kernel when kernel +services (such as NFS, CIFS and AFS) want to perform a hostname lookup and the +kernel does not have the key cached. It is not ordinarily intended to be +called directly. +.P +It can be called in debugging mode to test its functionality by passing a +\fB\-D\fR flag on the command line. For this to work, the key description and +the callout information must be supplied. Verbosity can be increased by +supplying one or more \fB\-v\fR flags. +.SH ERRORS +All errors will be logged to the syslog. +.SH SEE ALSO +.ad l +.nh +.BR request\-key.conf (5), +.BR keyrings (7), +.BR request\-key (8) diff --git a/man/keyctl.1 b/man/keyctl.1 new file mode 100644 index 0000000..1c8f569 --- /dev/null +++ b/man/keyctl.1 @@ -0,0 +1,908 @@ +.\" +.\" 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>] +.br +\fBkeyctl\fR show [\-x] [<keyring>] +.br +\fBkeyctl\fR add <type> <desc> <data> <keyring> +.br +\fBkeyctl\fR padd <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 <key> <data> +.br +\fBkeyctl\fR pupdate <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 +.br +\fBkeyctl\fR session +.br +\fBkeyctl\fR session \- [<prog> <arg1> <arg2> ...] +.br +\fBkeyctl\fR session <name> [<prog> <arg1> <arg2> ...] +.br +\fBkeyctl\fR instantiate <key> <data> <keyring> +.br +\fBkeyctl\fR pinstantiate <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 <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]* +.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 +\fBkeyctl\fR supports [<cap>] + +This command can list the available capabilities: + +.RS +.nf +$ keyctl supports +have_capabilities=0 +have_persistent_keyrings=1 +have_dh_compute=1 +have_public_key=1 +... +.fi +.RE +.P +And it can query a capability: + +.RS +.nf +$ keyctl supports pkey +echo $? +0 +.fi +.RE + +which returns 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. + +.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 <type> <desc> <data> <keyring> +.br +\fBkeyctl padd\fR <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 +.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 <key> <data> +.br +\fBkeyctl pupdate\fR <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 +.fi +.RE +.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 <key> <data> <keyring> +.br +\fBkeyctl pinstantiate\fR <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 +.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\fR + +This command is used to give the invoking process (typically a shell) a new +session keyring, discarding its old session keyring. + +.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 +.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 <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. +.fi +.RE +.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. + +.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) diff --git a/man/keyctl.3 b/man/keyctl.3 new file mode 100644 index 0000000..b0f5fdc --- /dev/null +++ b/man/keyctl.3 @@ -0,0 +1,123 @@ +.\" +.\" Copyright (C) 2010 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 Licence +.\" as published by the Free Software Foundation; either version +.\" 2 of the Licence, or (at your option) any later version. +.\" +.TH KEYCTL 3 "21 Feb 2014" Linux "Linux Key Management Calls" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH NAME +keyctl_*() \- key management function wrappers +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH DESCRIPTION +The +.BR keyctl () +system call is a multiplexor for a number of key management functions. These +should be called via the wrappers in the libkeyutils library. +.P +The functions can be compiled in by including the \fBkeyutils\fR header file: +.sp +.RS +.nf +.B #include <keyutils.h> +.RE +.P +and then telling the linker it should link in the library: +.sp +.RS +.nf +.B \-lkeyutils +.RE +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH KEYCTL FUNCTIONS +.BR keyctl_assume_authority (3) +.br +.BR keyctl_chown (3) +.br +.BR keyctl_capabilities (3) +.br +.BR keyctl_clear (3) +.br +.BR keyctl_describe (3) +.br +.BR keyctl_describe_alloc (3) +.br +.BR keyctl_dh_compute (3) +.br +.BR keyctl_dh_compute_alloc (3) +.br +.BR keyctl_get_keyring_ID (3) +.br +.BR keyctl_get_persistent (3) +.br +.BR keyctl_get_security (3) +.br +.BR keyctl_get_security_alloc (3) +.br +.BR keyctl_instantiate (3) +.br +.BR keyctl_instantiate_iov (3) +.br +.BR keyctl_invalidate (3) +.br +.BR keyctl_join_session_keyring (3) +.br +.BR keyctl_link (3) +.br +.BR keyctl_move (3) +.br +.BR keyctl_negate (3) +.br +.BR keyctl_pkey_dec (3) +.br +.BR keyctl_pkey_enc (3) +.br +.BR keyctl_pkey_query (3) +.br +.BR keyctl_pkey_sign (3) +.br +.BR keyctl_pkey_verify (3) +.br +.BR keyctl_read (3) +.br +.BR keyctl_read_alloc (3) +.br +.BR keyctl_reject (3) +.br +.BR keyctl_restrict_keyring (3) +.br +.BR keyctl_revoke (3) +.br +.BR keyctl_search (3) +.br +.BR keyctl_session_to_parent (3) +.br +.BR keyctl_set_reqkey_keyring (3) +.br +.BR keyctl_set_timeout (3) +.br +.BR keyctl_setperm (3) +.br +.BR keyctl_unlink (3) +.br +.BR keyctl_update (3) +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH UTILITY FUNCTIONS +.BR find_key_by_type_and_name (3) +.br +.BR recursive_key_scan (3) +.br +.BR recursive_session_key_scan (3) +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SEE ALSO +.ad l +.nh +.BR keyctl (1), +.BR add_key (2), +.BR keyctl (2), +.BR request_key (2), +.BR keyrings (7), +.BR keyutils (7) diff --git a/man/keyctl_capabilities.3 b/man/keyctl_capabilities.3 new file mode 100644 index 0000000..cc4d86c --- /dev/null +++ b/man/keyctl_capabilities.3 @@ -0,0 +1,109 @@ +.\" +.\" Copyright (C) 2019 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_CAPABILITIES 3 "30 May 2019" Linux "Linux Key Management Calls" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH NAME +keyctl_capabilities \- Query subsystem capabilities +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SYNOPSIS +.nf +.B #include <keyutils.h> +.sp +.BI "long keyctl_capabilities(unsigned char *" buffer ", size_t " buflen ");" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH DESCRIPTION +.BR keyctl_capabilities () +queries the keyrings subsystem in the kernel to ask about its capabilities and +fills in the array in the buffer with bits that indicate the presence or +absence of specific features in the keyrings subsystem. +.P +The function returns the amount of data the kernel has available, irrespective +of the amount of buffer space available. If the buffer is shorter than the +data, a short copy will be made; if the buffer is larger than the data, the +excess space will be cleared. +.P +If this operation is not available in the kernel, the keyutils library will be +emulate it as best it can and the capability bit that indicates if the kernel +operation is available will be cleared. +.P +In +.IR buffer[0] , +the following capabilities exist: +.TP +.B KEYCTL_CAPS0_CAPABILITIES +This is set if the kernel supports this operation and cleared otherwise. If +it is cleared, the rest of the flags are emulated. +.TP +.B KEYCTL_CAPS0_PERSISTENT_KEYRINGS +This is set if the kernel supports persistent keyrings and cleared otherwise. +See +.BR keyctl_get_persistent ( 3 ). +.TP +.B KEYCTL_CAPS0_DIFFIE_HELLMAN +This is set if the kernel supports Diffie-Hellman calculation and cleared +otherwise. See +.BR keyctl_dh_compute ( 3 ). +.TP +.B KEYCTL_CAPS0_PUBLIC_KEY +This is set if the kernel supports public-key operations and cleared +otherwise. See +.BR keyctl_pkey_query ( 3 ). +.TP +.B KEYCTL_CAPS0_BIG_KEY +This is set if the kernel supports the big_key key type and cleared otherwise. +.TP +.B KEYCTL_CAPS0_INVALIDATE +This is set if the kernel supports key invalidation and cleared otherwise. +See +.BR keyctl_invalidate ( 3 ). +.TP +.B KEYCTL_CAPS0_RESTRICT_KEYRING +This is set if the kernel supports restrictions on keyrings and cleared +otherwise. See +.BR keyctl_restrict_keyring ( 3 ). +.TP +.B KEYCTL_CAPS0_MOVE +This is set if the kernel supports the move key operation and cleared +otherwise. See +.BR keyctl_move ( 3 ). +.P +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH RETURN VALUE +On success +.BR keyctl_capabilities () +returns the size of the data it has available, irrespective of the size of the +buffer. On error, the value +.B -1 +will be returned and +.I errno +will have been set to an appropriate error. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH ERRORS +.TP +.B EFAULT +The buffer cannot be written to. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH LINKING +This is a library function that can be found in +.IR libkeyutils . +When linking, +.B \-lkeyutils +should be specified to the linker. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SEE ALSO +.ad l +.nh +.BR keyctl (1), +.BR add_key (2), +.BR keyctl (2), +.BR request_key (2), +.BR keyctl (3), +.BR keyrings (7), +.BR keyutils (7) diff --git a/man/keyctl_chown.3 b/man/keyctl_chown.3 new file mode 100644 index 0000000..286bded --- /dev/null +++ b/man/keyctl_chown.3 @@ -0,0 +1,88 @@ +.\" +.\" Copyright (C) 2006 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_CHOWN 3 "4 May 2006" Linux "Linux Key Management Calls" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH NAME +keyctl_chown \- change the ownership of a key +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SYNOPSIS +.nf +.B #include <keyutils.h> +.sp +.BI "long keyctl_chown(key_serial_t " key ", uid_t " uid ", gid_t " gid ");" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH DESCRIPTION +.BR keyctl_chown () +changes the user and group ownership details of a key. +.P +A setting of +.B -1 +on either +.I uid +or +.I gid +will cause that setting to be ignored. +.P +A process that does not have the +.B SysAdmin +capability may not change a key's UID or set the key's GID to a value that +does not match the process's GID or one of its group list. +.P +The caller must have +.B setattr +permission on a key to be able change its ownership. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH RETURN VALUE +On success +.BR keyctl_chown () +returns +.B 0 . +On error, the value +.B -1 +will be returned and +.I errno +will have been set to an appropriate error. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH ERRORS +.TP +.B ENOKEY +The specified key does not exist. +.TP +.B EKEYEXPIRED +The specified key has expired. +.TP +.B EKEYREVOKED +The specified key has been revoked. +.TP +.B EDQUOT +Changing the UID to the one specified would run that UID out of quota. +.TP +.B EACCES +The key exists, but does not grant +.B setattr +permission to the calling process. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH LINKING +This is a library function that can be found in +.IR libkeyutils . +When linking, +.B \-lkeyutils +should be specified to the linker. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SEE ALSO +.ad l +.nh +.BR keyctl (1), +.BR add_key (2), +.BR keyctl (2), +.BR request_key (2), +.BR keyctl (3), +.BR keyrings (7), +.BR keyutils (7) diff --git a/man/keyctl_clear.3 b/man/keyctl_clear.3 new file mode 100644 index 0000000..21e0c26 --- /dev/null +++ b/man/keyctl_clear.3 @@ -0,0 +1,74 @@ +.\" +.\" Copyright (C) 2006 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_CLEAR 3 "4 May 2006" Linux "Linux Key Management Calls" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH NAME +keyctl_clear \- clear a keyring +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SYNOPSIS +.nf +.B #include <keyutils.h> +.sp +.BI "long keyctl_clear(key_serial_t " keyring ");" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH DESCRIPTION +.BR keyctl_clear () +clears the contents of a +.IR keyring . +.P +The caller must have +.B write +permission on a keyring to be able clear it. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH RETURN VALUE +On success +.BR keyctl_clear () +returns +.BR 0 . +On error, the value +.B -1 +will be returned and +.I errno +will have been set to an appropriate error. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH ERRORS +.TP +.B ENOKEY +The keyring specified is invalid. +.TP +.B EKEYEXPIRED +The keyring specified has expired. +.TP +.B EKEYREVOKED +The keyring specified had been revoked. +.TP +.B EACCES +The keyring exists, but is not +.B writable +by the calling process. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH LINKING +This is a library function that can be found in +.IR libkeyutils . +When linking, +.B \-lkeyutils +should be specified to the linker. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SEE ALSO +.ad l +.nh +.BR keyctl (1), +.BR add_key (2), +.BR keyctl (2), +.BR request_key (2), +.BR keyctl (3), +.BR keyrings (7), +.BR keyutils (7) + diff --git a/man/keyctl_describe.3 b/man/keyctl_describe.3 new file mode 100644 index 0000000..b4f100e --- /dev/null +++ b/man/keyctl_describe.3 @@ -0,0 +1,112 @@ +.\" +.\" Copyright (C) 2006 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_DESCRIBE 3 "4 May 2006" Linux "Linux Key Management Calls" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH NAME +keyctl_describe \- describe a key +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SYNOPSIS +.nf +.B #include <keyutils.h> +.sp +.BI "long keyctl_describe(key_serial_t " key ", char *" buffer , +.BI "size_t" buflen ");" +.sp +.BI "long keyctl_describe_alloc(key_serial_t " key ", char **" _buffer ");" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH DESCRIPTION +.BR keyctl_describe () +describes the attributes of a key as a NUL-terminated string. +.P +The caller must have +.B view +permission on a key to be able to get a description of it. +.P +.I buffer +and +.I buflen +specify the buffer into which the key description will be placed. If the +buffer is too small, the full size of the description will be returned, and no +copy will take place. +.P +.BR keyctl_describe_alloc () +is similar to +.BR keyctl_describe () +except that it allocates a buffer big enough to hold the description and +places the description in it. If successful, A pointer to the buffer is +placed in +.IR *_buffer . +The caller must free the buffer. +.P +The description will be a string of format: +.IP +.B "\*(lq%s;%d;%d;%08x;%s\*(rq" +.P +where the arguments are: key type name, key UID, key GID, key permissions mask +and key description. +.P +.B NOTE! +The key description will not contain any semicolons, so that should be +separated out by working backwards from the end of the string. This permits +extra information to be inserted before it by later versions of the kernel +simply by inserting more semicolon-terminated substrings. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH RETURN VALUE +On success +.BR keyctl_describe () +returns the amount of data placed into the buffer. If the buffer was too +small, then the size of buffer required will be returned, but no data will be +transferred. On error, the value +.B -1 +will be returned and +.I errno +will have been set to an appropriate error. +.P +On success +.BR keyctl_describe_alloc () +returns the amount of data in the buffer, less the NUL terminator. On error, the value +.B -1 +will be returned and +.I errno +will have been set to an appropriate error. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH ERRORS +.TP +.B ENOKEY +The key specified is invalid. +.TP +.B EKEYEXPIRED +The key specified has expired. +.TP +.B EKEYREVOKED +The key specified had been revoked. +.TP +.B EACCES +The key exists, but is not +.B viewable +by the calling process. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH LINKING +This is a library function that can be found in +.IR libkeyutils . +When linking, +.B \-lkeyutils +should be specified to the linker. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SEE ALSO +.ad l +.nh +.BR keyctl (1), +.BR add_key (2), +.BR keyctl (2), +.BR request_key (2), +.BR keyctl (3), +.BR keyrings (7), +.BR keyutils (7) diff --git a/man/keyctl_dh_compute.3 b/man/keyctl_dh_compute.3 new file mode 100644 index 0000000..5b79378 --- /dev/null +++ b/man/keyctl_dh_compute.3 @@ -0,0 +1,168 @@ +.\" +.\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved. +.\" Copyright (C) 2016 Intel Corporation. All rights reserved. +.\" +.\" 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_DH_COMPUTE 3 "07 Apr 2016" Linux "Linux Key Management Calls" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH NAME +keyctl_dh_compute \- Compute a Diffie-Hellman shared secret or public key +.br +keyctl_dh_compute_kdf \- Derive key from a Diffie-Hellman shared secret +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SYNOPSIS +.nf +.B #include <keyutils.h> +.sp +.BI "long keyctl_dh_compute(key_serial_t " private ", key_serial_t " prime , +.BI "key_serial_t " base ", char *" buffer ", size_t " buflen ");" +.sp +.BI "long keyctl_dh_compute_alloc(key_serial_t " private, +.BI "key_serial_t " prime ", key_serial_t " base ", void **" _buffer ");" +.sp +.BI "long keyctl_dh_compute_kdf(key_serial_t " private ", key_serial_t " prime , +.BI "key_serial_t " base ", char *" hashname ", char *" otherinfo ", +.BI "size_t " otherinfolen ", char *" buffer ", size_t " buflen ");" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH DESCRIPTION +.BR keyctl_dh_compute () +computes a Diffie-Hellman public key or shared secret. That computation is: +.IP +.I base +^ +.I private +( mod +.I prime +) +.P +When +.I base +is a key containing the shared generator value, the remote public key is +computed. When +.I base +is a key containing the remote public key, the shared secret is computed. +.P +.IR base ", " private ", and " prime +must all refer to +.BR user -type +keys containing the parameters for the computation. Each of these keys must +grant the caller +.B read +permission in order for them to be used. +.P +.I buffer +and +.I buflen +specify the buffer into which the computed result will be placed. +.I buflen +may be zero, in which case the buffer is not used and the minimum buffer length +is fetched. +.P +.BR keyctl_dh_compute_alloc () +is similar to +.BR keyctl_dh_compute () +except that it allocates a buffer big enough to hold the payload data and +places the data in it. If successful, a pointer to the buffer is placed in +.IR *_buffer . +The caller must free the buffer. +.P +.BR keyctl_dh_compute_kdf () +derives a key from a Diffie-Hellman shared secret according to the protocol +specified in SP800-56A. The Diffie-Hellman computation is based on the same +primitives as discussed +for +.BR keyctl_dh_compute (). +.P +To implement the protocol of SP800-56A +.I base +is a key containing the remote public key to compute the Diffie-Hellman +shared secret. That shared secret is post-processed with a key derivation +function. +.P +The +.I hashname +specifies the Linux kernel crypto API name for a hash that shall be used +for the key derivation function, such as sha256. +The +.I hashname +must be a NULL terminated string. See +.I /proc/crypto +for available hashes on the system. +.P +Following the specification of SP800-56A section 5.8.1.2 the +.I otherinfo +parameter may be provided. The format of the OtherInfo field is defined +by the caller. The caller may also specify NULL as a valid argument when +no OtherInfo data shall be processed. The length of the +.I otherinfo +parameter is specified with +.I otherinfolen +and is restricted to a maximum length by the kernel. +.P +The KDF returns the requested number of bytes specified with the +.I genlen +or the +.I buflen +parameter depending on the invoked function. +.P +.I buffer +and +.I buflen +specify the buffer into which the computed result will be placed. +.P +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH RETURN VALUE +On success +.BR keyctl_dh_compute () +returns the amount of data placed into the buffer when +.I buflen +is non-zero. When +.I buflen +is zero, the minimum buffer length to hold the data is returned. +.P +On success +.BR keyctl_dh_compute_alloc () +returns the amount of data in the buffer. +.P +On error, both functions set errno to an appropriate code and return the value +.BR -1 . +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH ERRORS +.TP +.B ENOKEY +One of the keys specified is invalid or not readable. +.TP +.B EINVAL +The buffer pointer is invalid or buflen is too small. +.TP +.B EOPNOTSUPP +One of the keys was not a valid user key. +.TP +.B EMSGSIZE +When using +.BR keyctl_dh_compute_kdf (), +the size of either +.I otherinfolen +or +.I buflen +is too big. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH LINKING +This is a library function that can be found in +.IR libkeyutils . +When linking, +.B \-lkeyutils +should be specified to the linker. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SEE ALSO +.BR keyctl (1), +.br +.BR keyctl (2), +.br +.BR keyctl (3), +.br +.BR keyutils (7) diff --git a/man/keyctl_get_keyring_ID.3 b/man/keyctl_get_keyring_ID.3 new file mode 100644 index 0000000..6525292 --- /dev/null +++ b/man/keyctl_get_keyring_ID.3 @@ -0,0 +1,96 @@ +.\" +.\" Copyright (C) 2006 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_GET_KEYRING_ID 3 "4 May 2006" Linux "Linux Key Management Calls" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH NAME +keyctl_get_keyring_ID \- get the ID of a special keyring +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SYNOPSIS +.nf +.B #include <keyutils.h> +.sp +.BI "key_serial_t keyctl_get_keyring_ID(key_serial_t " key "," +.BI " int " create ");" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH DESCRIPTION +.BR keyctl_get_keyring_ID () +maps a special +.I key +or keyring ID to the serial number of the key actually representing that +feature. The serial number will be returned if that key exists. +.P +If the key or keyring does not yet exist, then if +.I create +is non-zero, the key or keyring will be created if it is appropriate to do so. +.P +The following special key IDs may be specified as +.IR key : +.TP +.B KEY_SPEC_THREAD_KEYRING +This specifies the caller's thread-specific keyring. +.TP +.B KEY_SPEC_PROCESS_KEYRING +This specifies the caller's process-specific keyring. +.TP +.B KEY_SPEC_SESSION_KEYRING +This specifies the caller's session-specific keyring. +.TP +.B KEY_SPEC_USER_KEYRING +This specifies the caller's UID-specific keyring. +.TP +.B KEY_SPEC_USER_SESSION_KEYRING +This specifies the caller's UID-session keyring. +.TP +.B KEY_SPEC_REQKEY_AUTH_KEY +This specifies the authorisation key created by +.BR request_key () +and passed to the process it spawns to generate a key. +.P +If a valid keyring ID is passed in, then this will simply be returned if the +key exists; an error will be issued if it doesn't exist. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH RETURN VALUE +On success +.BR keyctl_get_keyring_ID () +returns the serial number of the key it found. On error, the value +.B -1 +will be returned and +.I errno +will have been set to an appropriate error. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH ERRORS +.TP +.B ENOKEY +No matching key was found. +.TP +.B ENOMEM +Insufficient memory to create a key. +.TP +.B EDQUOT +The key quota for this user would be exceeded by creating this key or linking +it to the keyring. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH LINKING +This is a library function that can be found in +.IR libkeyutils . +When linking, +.B \-lkeyutils +should be specified to the linker. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SEE ALSO +.ad l +.nh +.BR keyctl (1), +.BR add_key (2), +.BR keyctl (2), +.BR request_key (2), +.BR keyctl (3), +.BR keyrings (7), +.BR keyutils (7) diff --git a/man/keyctl_get_persistent.3 b/man/keyctl_get_persistent.3 new file mode 100644 index 0000000..8d79957 --- /dev/null +++ b/man/keyctl_get_persistent.3 @@ -0,0 +1,114 @@ +.\" +.\" Copyright (C) 2013 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_GET_PERSISTENT 3 "20 Feb 2014" Linux "Linux Key Management Calls" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH NAME +keyctl_get_persistent \- get the persistent keyring for a user +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SYNOPSIS +.nf +.B #include <keyutils.h> +.sp +.BI "long keyctl_get_persistent(uid_t " uid ", key_serial_t " keyring ");" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH DESCRIPTION +.BR keyctl_get_persistent () +gets the persistent keyring for the specified user ID. Unlike the session and +user keyrings, this keyring will persist once all login sessions have been +deleted and can thus be used to carry authentication tokens for processes that +run without user interaction, such as programs started by cron. +.P +The persistent keyring will be created by the kernel if it does not yet exist. +Each time this function is called, the persistent keyring will have its +expiration timeout reset 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. +.P +If +.I uid +is +.B -1 +then the calling process's real user ID will be used. If +.I uid +is not +.B -1 +then error +.B EPERM +will be given if the user ID requested does not match either the caller's real +or effective user IDs or if the calling process does not have +.B SetUid +capability. +.P +If successful, a link to the persistent keyring will be added into +.IR keyring . +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH RETURN VALUE +On success +.BR keyctl_get_persistent () +returns the serial number of the persistent keyring. On error, the value +.B -1 +will be returned and +.I errno +will have been set to an appropriate error. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH ERRORS +.TP +.B EPERM +Not permitted to access the persistent keyring for the requested +.IR uid . +.TP +.B ENOMEM +Insufficient memory to create the persistent keyring or to extend +.IR keyring . +.TP +.B ENOKEY +.I keyring +does not exist. +.TP +.B EKEYEXPIRED +.I keyring +has expired. +.TP +.B EKEYREVOKED +.I keyring +has been revoked. +.TP +.B EDQUOT +The user does not have sufficient quota to extend +.IR keyring . +.TP +.B EACCES +.I keyring +exists, but does not grant +.B write +permission to the calling process. + +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH LINKING +This is a library function that can be found in +.IR libkeyutils . +When linking, +.B \-lkeyutils +should be specified to the linker. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SEE ALSO +.ad l +.nh +.BR keyctl (1), +.BR add_key (2), +.BR keyctl (2), +.BR request_key (2), +.BR keyctl (3), +.BR keyrings (7), +.BR keyutils (7), +.BR persistent\-keyring (7), diff --git a/man/keyctl_get_security.3 b/man/keyctl_get_security.3 new file mode 100644 index 0000000..a2c5b41 --- /dev/null +++ b/man/keyctl_get_security.3 @@ -0,0 +1,102 @@ +.\" +.\" Copyright (C) 2010 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_GET_SECURITY 3 "26 Feb 2010" Linux "Linux Key Management Calls" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH NAME +keyctl_get_security \- retrieve a key's security context +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SYNOPSIS +.nf +.B #include <keyutils.h> +.sp +.BI "long keyctl_get_security(key_serial_t " key ", char *" buffer , +.BI "size_t " buflen ");" +.sp +.BI "long keyctl_get_security_alloc(key_serial_t " key ", char **" _buffer ");" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH DESCRIPTION +.BR keyctl_get_security () +retrieves the security context of a key as a NUL-terminated string. This will +be rendered in a form appropriate to the LSM in force - for instance, with +SELinux, it may look like +.IP +.B "unconfined_u:unconfined_r:unconfined_t:s0\-s0:c0.c1023" +.P +The caller must have +.B view +permission on a key to be able to get its security context. +.P +.I buffer +and +.I buflen +specify the buffer into which the string will be placed. If the buffer is too +small, the full size of the string will be returned, and no copy will take +place. +.P +.BR keyctl_get_security_alloc () +is similar to +.BR keyctl_get_security () +except that it allocates a buffer big enough to hold the string and copies the +string into it. If successful, A pointer to the buffer is placed in +.IR *_buffer . +The caller must free the buffer. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH RETURN VALUE +On success +.BR keyctl_get_security () +returns the amount of data placed into the buffer. If the buffer was too +small, then the size of buffer required will be returned, but no data will be +transferred. On error, the value +.B -1 +will be returned and +.I errno +will have been set to an appropriate error. +.P +On success +.BR keyctl_get_security_alloc () +returns the amount of data in the buffer, less the NUL terminator. On error, the value +.B -1 +will be returned and +.I errno +will have been set to an appropriate error. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH ERRORS +.TP +.B ENOKEY +The key specified is invalid. +.TP +.B EKEYEXPIRED +The key specified has expired. +.TP +.B EKEYREVOKED +The key specified had been revoked. +.TP +.B EACCES +The key exists, but is not +.B viewable +by the calling process. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH LINKING +This is a library function that can be found in +.IR libkeyutils . +When linking, +.B \-lkeyutils +should be specified to the linker. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SEE ALSO +.ad l +.nh +.BR keyctl (1), +.BR add_key (2), +.BR keyctl (2), +.BR request_key (2), +.BR keyctl (3), +.BR keyrings (7), +.BR keyutils (7) diff --git a/man/keyctl_instantiate.3 b/man/keyctl_instantiate.3 new file mode 100644 index 0000000..d436bf2 --- /dev/null +++ b/man/keyctl_instantiate.3 @@ -0,0 +1,191 @@ +.\" +.\" Copyright (C) 2006 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_INSTANTIATE 3 "4 May 2006" Linux "Linux Key Management Calls" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH NAME +keyctl_assume_authority, keyctl_instantiate, keyctl_instantiate_iov, keyctl_reject, keyctl_negate \- key instantiation functions +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SYNOPSIS +.nf +.B #include <keyutils.h> +.sp +.BI "long keyctl_assume_authority(key_serial_t " key ");" +.sp +.BI "long keyctl_instantiate(key_serial_t " key ", const void *" payload , +.BI "size_t " plen ", key_serial_t " keyring ");" +.sp +.BI "long keyctl_instantiate_iov(key_serial_t " key , +.BI "const struct iovec *" payload_iov ", unsigned " ioc , +.BI "key_serial_t " keyring ");" +.sp +.BI "long keyctl_negate(key_serial_t " key ", unsigned " timeout , +.BI "key_serial_t " keyring ");" +.sp +.BI "long keyctl_reject(key_serial_t " key ", unsigned " timeout , +.BI "unsigned " error ", key_serial_t " keyring ");" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH DESCRIPTION +.BR keyctl_assume_authority () +assumes the authority for the calling thread to deal with and instantiate the +specified uninstantiated +.IR key . +.P +The calling thread must have the appropriate authorisation key resident in one +of its keyrings for this to succeed, and that authority must not have been +revoked. +.P +The authorising key is allocated by +.BR request_key() +when it needs to invoke +userspace to generate a key for the requesting process. This is then attached +to one of the keyrings of the userspace process to which the task of +instantiating the key is given: +.IP +requester -> request_key() -> instantiator +.P +Calling this function modifies the way +.BR request_key () +works when called thereafter by the calling (instantiator) thread; once the +authority is assumed, the keyrings of the initial process are added to the +search path, using the initial process's UID, GID, groups and security +context. +.P +If a thread has multiple instantiations to deal with, it may call this +function to change the authorisation key currently in effect. Supplying a +.B zero +.I key +de-assumes the currently assumed authority. +.P +.B NOTE! +This is a per-thread setting and not a per-process setting so that a +multithreaded process can be used to instantiate several keys at once. +.P +.BR keyctl_instantiate () +instantiates the payload of an uninstantiated key from the data specified. +.I payload +and +.I plen +specify the data for the new payload. +.I payload +may be NULL and +.I plen +may be zero if the key type permits that. The key type may reject the data if +it's in the wrong format or in some other way invalid. +.P +.BR keyctl_instantiate_iov () +is similar, but the data is passed in an array of iovec structs instead of in +a flat buffer. +.I payload_iov +points to the base of the array and +.I ioc +indicates how many elements there are. +.I payload_iov +may be NULL or +.I ioc +may be zero to indicate that no data is being supplied. +.P +.BR keyctl_reject () +marks a key as negatively instantiated and sets the expiration timer on it. +.I timeout +specifies the lifetime of the key in seconds. +.I error +specifies the error to be returned when a search hits the key (this is +typically +.BR EKEYREJECTED ", " EKEYREVOKED " or " EKEYEXPIRED ")." +Note that +.BR keyctl_reject () +falls back to +.BR keyctl_negate () +if the kernel does not +support it. +.P +.BR keyctl_negate () +as +.BR keyctl_reject () +with an error code of +.IB ENOKEY . +.P +Only a key for which authority has been assumed may be instantiated or +negatively instantiated, and once instantiated, the authorisation key will be +revoked and the requesting process will be able to resume. +.P +The destination +.IR keyring , +if given, is assumed to belong to the initial requester, and not the +instantiating process. Therefore, the special keyring IDs refer to the +requesting process's keyrings, not the caller's, and the requester's UID, +etc. will be used to access them. +.P +The destination keyring can be +.B zero +if no extra link is desired. +.P +The requester, not the caller, must have +.B write +permission on the destination for a link to be made there. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH RETURN VALUE +On success +.BR keyctl_instantiate () +returns +.BR 0 . +On error, the value +.B -1 +will be returned and +.I errno +will have been set to an appropriate error. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH ERRORS +.TP +.B ENOKEY +The key or keyring specified is invalid. +.TP +.B EKEYEXPIRED +The keyring specified has expired. +.TP +.B EKEYREVOKED +The key or keyring specified had been revoked, or the authorisation has been +revoked. +.TP +.B EINVAL +The payload data was invalid. +.TP +.B ENOMEM +Insufficient memory to store the new payload or to expand the destination +keyring. +.TP +.B EDQUOT +The key quota for the key's user would be exceeded by increasing the size of +the key to accommodate the new payload or the key quota for the keyring's user +would be exceeded by expanding the destination keyring. +.TP +.B EACCES +The key exists, but is not +.B writable +by the requester. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH LINKING +This is a library function that can be found in +.IR libkeyutils . +When linking, +.B \-lkeyutils +should be specified to the linker. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SEE ALSO +.ad l +.nh +.BR keyctl (1), +.BR add_key (2), +.BR keyctl (2), +.BR request_key (2), +.BR keyctl (3), +.BR keyrings (7), +.BR keyutils (7), +.BR request\-key (8) diff --git a/man/keyctl_invalidate.3 b/man/keyctl_invalidate.3 new file mode 100644 index 0000000..120da45 --- /dev/null +++ b/man/keyctl_invalidate.3 @@ -0,0 +1,76 @@ +.\" +.\" Copyright (C) 2013 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_INVALIDATE 3 "29 Aug 2013" Linux "Linux Key Management Calls" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH NAME +keyctl_invalidate \- invalidate a key +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SYNOPSIS +.nf +.B #include <keyutils.h> +.sp +.BI "long keyctl_invalidate(key_serial_t " key ");" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH DESCRIPTION +.BR keyctl_invalidate () +invalidates a +.IR key . +The key is scheduled for immediate removal from all the keyrings that point to +it, after which it will be deleted. The key will be ignored by all searches +once this function is called even if it is not yet fully dealt with. +.P +The caller must have +.B search +permission on a key to be able to invalidate it. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH RETURN VALUE +On success +.BR keyctl_invalidate () +returns +.BR 0 . +On error, the value +.B -1 +will be returned and +.I errno +will have been set to an appropriate error. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH ERRORS +.TP +.B ENOKEY +The key specified is invalid. +.TP +.B EKEYEXPIRED +The key specified has expired. +.TP +.B EKEYREVOKED +The key specified had been revoked. +.TP +.B EACCES +The key exists, but is not +.B searchable +by the calling process. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH LINKING +This is a library function that can be found in +.IR libkeyutils . +When linking, +.B \-lkeyutils +should be specified to the linker. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SEE ALSO +.ad l +.nh +.BR keyctl (1), +.BR add_key (2), +.BR keyctl (2), +.BR request_key (2), +.BR keyctl (3), +.BR keyrings (7), +.BR keyutils (7) diff --git a/man/keyctl_join_session_keyring.3 b/man/keyctl_join_session_keyring.3 new file mode 100644 index 0000000..4e27717 --- /dev/null +++ b/man/keyctl_join_session_keyring.3 @@ -0,0 +1,84 @@ +.\" +.\" Copyright (C) 2006 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_JOIN_SESSION_KEYRING 3 "20 Feb 2014" Linux "Linux Key Management Calls" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH NAME +keyctl_join_session_keyring \- join a different session keyring +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SYNOPSIS +.nf +.B #include <keyutils.h> +.sp +.BI "key_serial_t keyctl_join_session_keyring(const char *" name ");" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH DESCRIPTION +.BR keyctl_join_session_keyring () +changes the session keyring to which a process is subscribed. +.P +If +.I name +is +.B NULL +then a new anonymous keyring will be created, and the process will be +subscribed to that. +.P +If +.I name +points to a string, then if a keyring of that name is available, the process +will attempt to subscribe to that keyring, giving an error if that is not +permitted; otherwise a new keyring of that name is created and attached as the +session keyring. +.P +To attach to an extant named keyring, the keyring must have +.B search +permission available to the calling process. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH RETURN VALUE +On success +.BR keyctl_join_session_keyring () +returns the serial number of the key it found or created. On error, the value +.B -1 +will be returned and +.I errno +will have been set to an appropriate error. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH ERRORS +.TP +.B ENOMEM +Insufficient memory to create a key. +.TP +.B EDQUOT +The key quota for this user would be exceeded by creating this key or linking +it to the keyring. +.TP +.B EACCES +The named keyring exists, but is not +.B searchable +by the calling process. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH LINKING +This is a library function that can be found in +.IR libkeyutils . +When linking, +.B \-lkeyutils +should be specified to the linker. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SEE ALSO +.ad l +.nh +.BR keyctl (1), +.BR add_key (2), +.BR keyctl (2), +.BR request_key (2), +.BR keyctl (3), +.BR keyrings (7), +.BR keyutils (7), +.BR session\-keyring (7), +.BR user\-session\-keyring (7) diff --git a/man/keyctl_link.3 b/man/keyctl_link.3 new file mode 100644 index 0000000..1185874 --- /dev/null +++ b/man/keyctl_link.3 @@ -0,0 +1,108 @@ +.\" +.\" Copyright (C) 2006 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_LINK 3 "4 May 2006" Linux "Linux Key Management Calls" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH NAME +keyctl_link, keyctl_unlink \- link/unlink a key to/from a keyring +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SYNOPSIS +.nf +.B #include <keyutils.h> +.sp +.BI "long keyctl_link(key_serial_t " key ", key_serial_t " keyring ");" +.sp +.BI "long keyctl_unlink(key_serial_t " key ", key_serial_t " keyring ");" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH DESCRIPTION +.BR keyctl_link () +creates a link from +.I keyring +to +.IR key , +displacing any link to another key of the same type and description in that +keyring if one exists. +.P +.BR keyctl_unlink () +removes the link from +.I keyring +to +.I key +if it exists. +.P +The caller must have +.B write +permission on a keyring to be able create or remove links in it. +.P +The caller must have +.B link +permission on a key to be able to create a link to it. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH RETURN VALUE +On success +.BR keyctl_link () +and +.BR keyctl_unlink () +return +.BR 0 . +On error, the value +.B -1 +will be returned and +.I errno +will have been set to an appropriate error. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH ERRORS +.TP +.B ENOKEY +The key or the keyring specified are invalid. +.TP +.B EKEYEXPIRED +The key or the keyring specified have expired. +.TP +.B EKEYREVOKED +The key or the keyring specified have been revoked. +.TP +.B EACCES +The keyring exists, but is not +.B writable +by the calling process. +.P +For +.BR keyctl_link () +only: +.TP +.B ENOMEM +Insufficient memory to expand the keyring +.TP +.B EDQUOT +Expanding the keyring would exceed the keyring owner's quota. +.TP +.B EACCES +The key exists, but is not +.B linkable +by the calling process. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH LINKING +This is a library function that can be found in +.IR libkeyutils . +When linking, +.B \-lkeyutils +should be specified to the linker. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SEE ALSO +.ad l +.nh +.BR keyctl (1), +.BR add_key (2), +.BR keyctl (2), +.BR request_key (2), +.BR keyctl (3), +.BR keyrings (7), +.BR keyutils (7) + diff --git a/man/keyctl_move.3 b/man/keyctl_move.3 new file mode 100644 index 0000000..b241f70 --- /dev/null +++ b/man/keyctl_move.3 @@ -0,0 +1,109 @@ +.\" +.\" Copyright (C) 2019 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_MOVE 3 "29 May 2019" Linux "Linux Key Management Calls" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH NAME +keyctl_move \- Move a key between keyrings +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SYNOPSIS +.nf +.B #include <keyutils.h> +.sp +.BI "long keyctl_move(key_serial_t " key ", key_serial_t " from_keyring "," +.br +.BI " key_serial_t " to_keyring ", unsigned int " flags ");" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH DESCRIPTION +.BR keyctl_move () +atomically unlinks +.I key +from +.I from_keyring +and links it into +.I to_keyring +in a single operation. Depending on the flags set, a link to any matching key +in to_keyring may get displaced. +.P +.I flags +is a bitwise-OR of zero or more of the following flags: +.P +.TP +.B KEYCTL_MOVE_EXCL +If there's a matching key in to_keyring, don't displace it but rather return +an error. +.P +The caller must have +.B write +permission on both keyring to be able create or remove links in them. +.P +The caller must have +.B link +permission on a key to be able to create a new link to it. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH RETURN VALUE +On success +.BR keyctl_move () +return +.BR 0 . +On error, the value +.B -1 +will be returned and +.I errno +will have been set to an appropriate error. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH ERRORS +.TP +.B ENOKEY +The key or one of the keyrings specified are invalid. +.TP +.B ENOKEY +A key with the same type and description is present in to_keyring and +KEYCTL_MOVE_EXCL is set. +.TP +.B EKEYEXPIRED +The key or one of the keyrings specified have expired. +.TP +.B EKEYREVOKED +The key or one of the keyrings specified have been revoked. +.TP +.B EACCES +The key exists, but is not +.B linkable +by the calling process. +.TP +.B EACCES +The keyrings exist, but are not +.B writable +by the calling process. +.TP +.B ENOMEM +Insufficient memory to effect the changes. +.TP +.B EDQUOT +Expanding to_keyring would exceed the keyring owner's quota. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH LINKING +This is a library function that can be found in +.IR libkeyutils . +When linking, +.B \-lkeyutils +should be specified to the linker. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SEE ALSO +.ad l +.nh +.BR keyctl (1), +.BR add_key (2), +.BR keyctl (2), +.BR request_key (2), +.BR keyctl (3), +.BR keyrings (7), +.BR keyutils (7) + diff --git a/man/keyctl_pkey_decrypt.3 b/man/keyctl_pkey_decrypt.3 new file mode 100644 index 0000000..47b1937 --- /dev/null +++ b/man/keyctl_pkey_decrypt.3 @@ -0,0 +1 @@ +.so keyctl_pkey_encrypt.3 diff --git a/man/keyctl_pkey_encrypt.3 b/man/keyctl_pkey_encrypt.3 new file mode 100644 index 0000000..44c640e --- /dev/null +++ b/man/keyctl_pkey_encrypt.3 @@ -0,0 +1,113 @@ +.\" +.\" Copyright (C) 2018 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 Licence +.\" as published by the Free Software Foundation; either version +.\" 2 of the Licence, or (at your option) any later version. +.\" +.TH KEYCTL_PKEY_ENCRYPT 3 "8 Nov 2018" Linux "Linux Public-Key Encryption" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH NAME +keyctl_pkey_encrypt, keyctl_pkey_decrypt \- Encrypt and decrypt data +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SYNOPSIS +.nf +.B #include <keyutils.h> +.sp +.BI "long keyctl_pkey_encrypt(key_serial_t " key ", const char *" info , +.BI " const void *" data ", size_t " data_len , +.BI " void *" enc ", size_t " enc_len ");" +.sp +.BI "long keyctl_pkey_decrypt(key_serial_t " key ", const char *" info , +.BI " const void *" enc ", size_t " enc_len , +.BI " void *" data ", size_t " data_len ");" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH DESCRIPTION +.BR keyctl_pkey_encrypt () +asks the kernel to use the crypto material attached to a key to encrypt a blob +of data and +.BR keyctl_pkey_decrypt () +asks the kernel to use the key to reverse the operation and recover the +original data. Note that these operations may involve the kernel calling out +to cryptographic hardware. The caller must have +.B search +permission on a key to be able to use them in this manner. +.PP +.PP +When invoking the function, +.I key +indicates the key that will provide the cryptographic material and +.I info +points to a comma-separated string of "key[=value]" parameters that indicate +things like encoding forms and passwords to unlock the key; see +asymmetric-key(7) for more information. +.PP +.IR data " and " datalen +indicate the address and size of the decrypted data buffer and +.IR enc " and " enclen +indicate the address and size of the encrypted data buffer. The encrypt +function draws data from the decrypted data buffer and places the output into +the encryption buffer. The decrypt function does the reverse, drawing from +the encryption buffer and writing into the data buffer. +.PP +.BR keyctl_pkey_query (2) +can be called to find out how large the buffers need to be. +.PP +Note that not all asymmetric-type keys will support these operations; further, +the operations available may depend on which components of the key material are +available: typically encryption only requires the public key, but decryption +requires the private key as well. Which operations are supported on a +particular key can also be determined using the query function. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH RETURN VALUE +On success +.BR keyctl_pkey_encrypt "() and " keyctl_pkey_decrypt () +return the amount of data written into the output buffer. On error, the value +.B -1 +will be returned and +.I errno +will have been set to an appropriate error. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH ERRORS +.TP +.B ENOKEY +The key specified is invalid. +.TP +.B EKEYEXPIRED +The key specified has expired. +.TP +.B EKEYREVOKED +The key specified has been revoked. +.TP +.B EACCES +The key exists, but is not +.B searchable +by the calling process. +.TP +.B ENOPKG +Some facility needed to complete the requested operation is not available. +This is most probably a requested or required digest or encryption algorithm. +.TP +.B EFAULT +Bad address. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH LINKING +This is a library function that can be found in +.IR libkeyutils . +When linking, +.B \-lkeyutils +should be specified to the linker. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SEE ALSO +.ad l +.nh +.BR keyctl (1), +.BR add_key (2), +.BR keyctl (2), +.BR keyctl (3), +.BR keyctl_pkey_query (3), +.BR keyctl_pkey_sign (3), +.BR keyrings (7), +.BR keyutils (7) diff --git a/man/keyctl_pkey_query.3 b/man/keyctl_pkey_query.3 new file mode 100644 index 0000000..dbeb0fd --- /dev/null +++ b/man/keyctl_pkey_query.3 @@ -0,0 +1,137 @@ +.\" +.\" Copyright (C) 2018 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 Licence +.\" as published by the Free Software Foundation; either version +.\" 2 of the Licence, or (at your option) any later version. +.\" +.TH KEYCTL_PKEY_QUERY 3 "8 Nov 2018" Linux "Linux Key Management Calls" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH NAME +keyctl_pkey_query \- Query public key parameters +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SYNOPSIS +.nf +.B #include <keyutils.h> +.sp +.BI "long keyctl_pkey_query(key_serial_t " key ", const char *" info , +.BI " struct keyctl_pkey_query *" result ");" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH DESCRIPTION +.BR keyctl_pkey_query () +queries the public key parameters associated with a kernel +key that supports these operations (typically +.BR asymmetric -type). +The caller must have +.B search +permission on the target key to be able to query its parameters. +.PP +When invoking the function, +.I key +indicates the key to be queried, +.I info +points to a comma-separated string of "key[=value]" parameters and +.I result +points to a buffer in which the result will be placed. +.PP +The parameters that can be used in the +.I info +parameter string are dependent on the type of key. Parameters can specify such +things as encoding types (such as "enc=pkcs1"); see asymmetric-key(7) for more +information. +.PP +If successful, the result is written into the following struct: +.PP +.in +4n +.EX +struct keyctl_pkey_query { + unsigned int supported_ops; + unsigned int key_size; + unsigned short max_data_size; + unsigned short max_sig_size; + unsigned short max_enc_size; + unsigned short max_dec_size; +}; +.EE +.in +.PP +The +.I supported_ops +field contains a bitmask of the following constants: +.PP +.in +4n +.TS +lB l. +KEYCTL_SUPPORTS_ENCRYPT +KEYCTL_SUPPORTS_DECRYPT +KEYCTL_SUPPORTS_SIGN +KEYCTL_SUPPORTS_VERIFY +.TE +.in +.PP +indicating what operations are supported and thus which of the other +.BR keyctl_pkey_* () +operations can be used with this key. +.PP +The +.I key_size +field indicates the number of bits in the key size and the +.IR max_data_size ", " max_sig_size ", " max_enc_size " and " max_dec_size +fields indicate the maximum sizes in bytes of a blob of data to be signed, a +signature blob, a blob to be encrypted and a blob to be decrypted respectively. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH RETURN VALUE +On success +.BR keyctl_pkey_query () +returns +.BR 0 . +On error, the value +.B -1 +will be returned and +.I errno +will have been set to an appropriate error. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH ERRORS +.TP +.B ENOKEY +The key specified is invalid. +.TP +.B EKEYEXPIRED +The key specified has expired. +.TP +.B EKEYREVOKED +The key specified has been revoked. +.TP +.B EACCES +The key exists, but is not +.B searchable +by the calling process. +.TP +.B ENOPKG +Some facility needed to complete the requested operation is not available. +This is most probably a requested or required digest or encryption algorithm. +.TP +.B EFAULT +Bad address. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH LINKING +This is a library function that can be found in +.IR libkeyutils . +When linking, +.B \-lkeyutils +should be specified to the linker. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SEE ALSO +.ad l +.nh +.BR keyctl (1), +.BR add_key (2), +.BR keyctl (2), +.BR keyctl (3), +.BR keyctl_pkey_encrypt (3), +.BR keyctl_pkey_sign (3), +.BR asymmetric-key (7), +.BR keyrings (7), +.BR keyutils (7) diff --git a/man/keyctl_pkey_sign.3 b/man/keyctl_pkey_sign.3 new file mode 100644 index 0000000..2f17e73 --- /dev/null +++ b/man/keyctl_pkey_sign.3 @@ -0,0 +1,133 @@ +.\" +.\" Copyright (C) 2018 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 Licence +.\" as published by the Free Software Foundation; either version +.\" 2 of the Licence, or (at your option) any later version. +.\" +.TH KEYCTL_PKEY_SIGN 3 "8 Nov 2018" Linux "Linux Public-Key Signatures" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH NAME +keyctl_pkey_sign, keyctl_pkey_verify \- Generate and verify signatures +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SYNOPSIS +.nf +.B #include <keyutils.h> +.sp +.BI "long keyctl_pkey_sign(key_serial_t " key ", const char *" info , +.BI " const void *" data ", size_t " data_len , +.BI " void *" sig ", size_t " sig_len ");" +.sp +.BI "long keyctl_pkey_verify(key_serial_t " key ", const char *" info , +.BI " const void *" data ", size_t " data_len , +.BI " const void *" sig ", size_t " sig_len ");" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH DESCRIPTION +.BR keyctl_pkey_sign () +asks the kernel to use the crypto data attached to a key to generate a +detached signature for a blob of data. Note that this may involve calling out +to cryptographic hardware. +.PP +.BR keyctl_pkey_verify () +asks the kernel to use the key to generate a verify the signature against the +same blob of data. This may also involve calling out to cryptographic +hardware. +.PP +The caller must have +.B search +permission on a key to be able to perform either operation. +.PP +.PP +When invoking the function, +.I key +indicates the key that will provide the cryptographic material and +.I info +points to a comma-separated string of "key[=value]" parameters that indicate +things like encoding forms and passwords to unlock the key; see +asymmetric-key(7) for more information. +.PP +.IR data " and " datalen +indicate the address and size of the buffer of data to be signed and +.IR sig " and " siglen +indicate the address and size of the signature buffer. The sign function +draws data from the data buffer, generates a signature from it and places the +output into the signature buffer. The verify function also draws data from +the data buffer, then decrypts the signature and compares the result. +.PP +Note that the data buffer is strictly limited in capacity, typically unable to +hold more bits than the size of the key. The caller is expected to have +pre-digested the actual data and will thus pass the digest output to this +function. The name of the digest used should be passed as part of the info +string as \fPhash=<name>\fR for use in constructing the signature metadata. +.PP +.BR keyctl_pkey_query (2) +can be called to find out how large the buffers need to be and what the +maximum size of the data can be for a specific signature encoding. +.PP +Note that not all asymmetric-type keys will support these operations; further, +the operations available may depend on which components of the key material are +available: typically encryption only requires the public key, but decryption +requires the private key as well. Which operations are supported on a +particular key can also be determined using the query function. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH RETURN VALUE +On success +.BR keyctl_pkey_sign () +returns the amount of data written into the signature buffer. +.BR keyctl_pkey_verify () +will return 0 in this case as it doesn't write to userspace. +.PP +On error the value +.B -1 +will be returned and +.I errno +will have been set to an appropriate error. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH ERRORS +.TP +.B ENOKEY +The key specified is invalid. +.TP +.B EKEYEXPIRED +The key specified has expired. +.TP +.B EKEYREVOKED +The key specified has been revoked. +.TP +.B EACCES +The key exists, but is not +.B searchable +by the calling process. +.TP +.BR EINVAL ", " EBADMSG ", " EOVERFLOW +Some part of the key material or signature data is bad. +.TP +.BR EKEYREJECTED +Signature verification failed. +.TP +.B ENOPKG +Some facility needed to complete the requested operation is not available. +This is most probably a requested or required digest or encryption algorithm. +.TP +.B EFAULT +Bad address. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH LINKING +This is a library function that can be found in +.IR libkeyutils . +When linking, +.B \-lkeyutils +should be specified to the linker. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SEE ALSO +.ad l +.nh +.BR keyctl (1), +.BR add_key (2), +.BR keyctl (2), +.BR keyctl (3), +.BR keyctl_pkey_query (3), +.BR keyrings (7), +.BR keyutils (7) diff --git a/man/keyctl_pkey_verify.3 b/man/keyctl_pkey_verify.3 new file mode 100644 index 0000000..0535113 --- /dev/null +++ b/man/keyctl_pkey_verify.3 @@ -0,0 +1 @@ +.so keyctl_pkey_sign.3 diff --git a/man/keyctl_read.3 b/man/keyctl_read.3 new file mode 100644 index 0000000..852bc05 --- /dev/null +++ b/man/keyctl_read.3 @@ -0,0 +1,112 @@ +.\" +.\" Copyright (C) 2006 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_READ 3 "21 Feb 2014" Linux "Linux Key Management Calls" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH NAME +keyctl_read \- read a key +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SYNOPSIS +.nf +.B #include <keyutils.h> +.sp +.BI "long keyctl_read(key_serial_t " key ", char *" buffer , +.BI "size_t" buflen ");" +.sp +.BI "long keyctl_read_alloc(key_serial_t " key ", void **" _buffer ");" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH DESCRIPTION +.BR keyctl_read () +reads the payload of a key if the key type supports it. +.P +The caller must have +.B read +permission on a key to be able to read it. +.P +.I buffer +and +.I buflen +specify the buffer into which the payload data will be placed. If the buffer +is too small, then the full size of the payload will be returned, and the +contents of the buffer may be overwritten in some undefined way. +.P +.BR keyctl_read_alloc () +is similar to +.BR keyctl_read () +except that it allocates a buffer big enough to hold the payload data and +places the data in it. If successful, a pointer to the buffer is placed in +.IR *_buffer . +The caller must free the buffer. +.P +.BR keyctl_read_alloc () +adds a NUL character after the data it retrieves, though this is not counted +in the size value it returns. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH READING KEYRINGS +This call can be used to list the contents of a keyring. The data is +presented to the user as an array of +.B key_serial_t +values, each of which corresponds to a key to which the keyring holds a link. +.P +The size of the keyring will be sizeof(key_serial_t) multiplied by the number +of keys. The size of key_serial_t is invariant across different word sizes, +though the byte-ordering is as appropriate for the kernel. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH RETURN VALUE +On success +.BR keyctl_read () +returns the amount of data placed into the buffer. If the buffer was too +small, then the size of buffer required will be returned, and the contents of +the buffer may have been overwritten in some undefined way. +.P +On success +.BR keyctl_read_alloc () +returns the amount of data in the buffer. +.P +On error, both functions set +.I errno +to an appropriate code and return the value +.BR -1 . +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH ERRORS +.TP +.B ENOKEY +The key specified is invalid. +.TP +.B EKEYEXPIRED +The key specified has expired. +.TP +.B EKEYREVOKED +The key specified had been revoked. +.TP +.B EACCES +The key exists, but is not +.B readable +by the calling process. +.TP +.B EOPNOTSUPP +The key type does not support reading of the payload data. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH LINKING +This is a library function that can be found in +.IR libkeyutils . +When linking, +.B \-lkeyutils +should be specified to the linker. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SEE ALSO +.ad l +.nh +.BR keyctl (1), +.BR add_key (2), +.BR keyctl (2), +.BR request_key (2), +.BR keyctl (3), +.BR keyrings (7), +.BR keyutils (7) diff --git a/man/keyctl_restrict_keyring.3 b/man/keyctl_restrict_keyring.3 new file mode 100644 index 0000000..468d5b4 --- /dev/null +++ b/man/keyctl_restrict_keyring.3 @@ -0,0 +1,82 @@ +.\" +.\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved. +.\" Copyright (C) 2017 Intel Corporation. All rights reserved. +.\" +.\" 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_RESTRICT_KEYRING 3 "28 Feb 2017" Linux "Linux Key Management Calls" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH NAME +keyctl_restrict_keyring \- restrict keys that may be linked to a keyring +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SYNOPSIS +.nf +.B #include <keyutils.h> +.sp +.BI "long keyctl_restrict_keyring(key_serial_t " keyring , +.BI "const char *" type ", const char *" restriction ");" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH DESCRIPTION +.BR keyctl_restrict_keyring () +limits the linkage of keys to the given +.I keyring +using a provided key +.I type +and +.I restriction +scheme. The available options vary depending on the key type, and +typically contain a restriction name possibly followed by key ids or +other data relevant to the restriction. If the type and restriction are +both +.B NULL, +the keyring will reject all links. +.P +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH RETURN VALUE +On success +.BR keyctl_restrict_keyring () +returns +.BR 0 . +On error, the value +.B -1 +will be returned and +.I errno +will have been set to an appropriate error. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH ERRORS +.TP +.B EDEADLK +A restriction cycle was avoided. Two keyrings cannot restrict each other. +.TP +.B EEXIST +The keyring is already restricted. +.TP +.B EINVAL +The restriction string is invalid or too large. +.TP +.B ENOKEY +The key type in the restriction is invalid or not available. +.TP +.B ENOTDIR +The provided key id references an item that is not a keyring. +.TP +.B ENOENT +The key type exists but does not support restrictions. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH LINKING +This is a library function that can be found in +.IR libkeyutils . +When linking, +.B \-lkeyutils +should be specified to the linker. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SEE ALSO +.ad l +.nh +.BR keyctl (1), +.BR keyctl (2), +.BR keyctl (3), +.BR keyutils (7) diff --git a/man/keyctl_revoke.3 b/man/keyctl_revoke.3 new file mode 100644 index 0000000..914a253 --- /dev/null +++ b/man/keyctl_revoke.3 @@ -0,0 +1,73 @@ +.\" +.\" Copyright (C) 2006 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_REVOKE 3 "4 May 2006" Linux "Linux Key Management Calls" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH NAME +keyctl_revoke \- revoke a key +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SYNOPSIS +.nf +.B #include <keyutils.h> +.sp +.BI "long keyctl_revoke(key_serial_t " key ");" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH DESCRIPTION +.BR keyctl_revoke () +marks a key as being revoked. +.P +After this operation has been performed on a key, attempts to access it will +meet with error +.BR EKEYREVOKED . +.P +The caller must have +.B write +permission on a key to be able revoke it. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH RETURN VALUE +On success +.BR keyctl_revoke () +returns +.BR 0 . +On error, the value +.B -1 +will be returned and +.I errno +will have been set to an appropriate error. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH ERRORS +.TP +.B ENOKEY +The specified key does not exist. +.TP +.B EKEYREVOKED +The key has already been revoked. +.TP +.B EACCES +The named key exists, but is not +.B writable +by the calling process. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH LINKING +This is a library function that can be found in +.IR libkeyutils . +When linking, +.B \-lkeyutils +should be specified to the linker. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SEE ALSO +.ad l +.nh +.BR keyctl (1), +.BR add_key (2), +.BR keyctl (2), +.BR request_key (2), +.BR keyctl (3), +.BR keyrings (7), +.BR keyutils (7) diff --git a/man/keyctl_search.3 b/man/keyctl_search.3 new file mode 100644 index 0000000..f3e7bc5 --- /dev/null +++ b/man/keyctl_search.3 @@ -0,0 +1,138 @@ +.\" +.\" Copyright (C) 2006 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_SEARCH 3 "4 May 2006" Linux "Linux Key Management Calls" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH NAME +keyctl_search \- search a keyring for a key +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SYNOPSIS +.nf +.B #include <keyutils.h> +.sp +.BI "long keyctl_search(key_serial_t " keyring ", const char *" type , +.BI "const char *" description ", key_serial_t " destination ");" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH DESCRIPTION +.BR keyctl_search () +recursively searches the +.I keyring +for a key of the specified +.I type +and +.IR description . +.P +If found, the key will be attached to the +.I destination +keyring (if given), and its serial number will be returned. +.P +The source keyring must grant +.B search +permission to the caller, and for a key to be found, it must also grant +.B search +permission to the caller. Child keyrings will be only be recursively searched +if they grant +.B search +permission to the caller as well. +.P +If the destination keyring is +.BR zero , +no attempt will be made to forge a link to the key, and just the serial number +will be returned. +.P +If the destination keyring is given, then the link may only be formed if the +found key grants the caller +.B link +permission and the destination keyring grants the caller +.B write +permission. +.P +If the search is successful, and if the destination keyring already contains a +link to a key that matches the specified +.IR type " and " description , +then that link will be replaced by a link to the found key. +.P +The source keyring and destination keyring serial numbers may be those of +valid keyrings to which the caller has appropriate permission, or they may be +special keyring IDs: +.TP +.B KEY_SPEC_THREAD_KEYRING +This specifies the caller's thread-specific keyring. +.TP +.B KEY_SPEC_PROCESS_KEYRING +This specifies the caller's process-specific keyring. +.TP +.B KEY_SPEC_SESSION_KEYRING +This specifies the caller's session-specific keyring. +.TP +.B KEY_SPEC_USER_KEYRING +This specifies the caller's UID-specific keyring. +.TP +.B KEY_SPEC_USER_SESSION_KEYRING +This specifies the caller's UID-session keyring. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH RETURN VALUE +On success +.BR keyctl_search () +returns the serial number of the key it found. On error, the value +.B -1 +will be returned and +.I errno +will have been set to an appropriate error. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH ERRORS +.TP +.B ENOKEY +One of the keyrings doesn't exist, no key was found by the search, or the only +key found by the search was a negative key. +.TP +.B ENOTDIR +One of the keyrings is a valid key that isn't a keyring. +.TP +.B EKEYEXPIRED +One of the keyrings has expired, or the only key found was expired. +.TP +.B EKEYREVOKED +One of the keyrings has been revoked, or the only key found was revoked. +.TP +.B ENOMEM +Insufficient memory to expand the destination keyring. +.TP +.B EDQUOT +The key quota for this user would be exceeded by creating a link to the found +key in the destination keyring. +.TP +.B EACCES +The source keyring didn't grant +.B search +permission, the destination keyring didn't grant +.B write +permission or the found key didn't grant +.B link +permission to the caller. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH LINKING +Although this is a Linux system call, it is not present in +.I libc +but can be found rather in +.IR libkeyutils . +When linking, +.B \-lkeyutils +should be specified to the linker. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SEE ALSO +.ad l +.nh +.BR keyctl (1), +.BR add_key (2), +.BR keyctl (2), +.BR request_key (2), +.BR keyctl (3), +.BR keyrings (7), +.BR keyutils (7) diff --git a/man/keyctl_session_to_parent.3 b/man/keyctl_session_to_parent.3 new file mode 100644 index 0000000..829b3be --- /dev/null +++ b/man/keyctl_session_to_parent.3 @@ -0,0 +1,77 @@ +.\" +.\" Copyright (C) 2010 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_SESSION_TO_PARENT 3 "20 Feb 2014" Linux "Linux Key Management Calls" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH NAME +keyctl_session_to_parent \- set the parent process's session keyring +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SYNOPSIS +.nf +.B #include <keyutils.h> +.sp +.BI "long keyctl_session_to_parent();" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH DESCRIPTION +.BR keyctl_session_to_parent () +changes the session keyring to which the calling process's parent subscribes +to be the that of the calling process. +.P +The keyring must have +.B link +permission available to the calling process, the parent process must have the +same UIDs/GIDs as the calling process, and the LSM must not reject the +replacement. Furthermore, this may not be used to affect init or a kernel +thread. +.P +Note that the replacement will not take immediate effect upon the parent +process, but will rather be deferred to the next time it returns to userspace +from kernel space. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH RETURN VALUE +On success +.BR keyctl_session_to_parent () +returns 0. On error, the value +.B -1 +will be returned and +.I errno +will have been set to an appropriate error. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH ERRORS +.TP +.B ENOMEM +Insufficient memory to create a key. +.TP +.B EPERM +The credentials of the parent don't match those of the caller. +.TP +.B EACCES +The named keyring exists, but is not +.B linkable +by the calling process. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH LINKING +This is a library function that can be found in +.IR libkeyutils . +When linking, +.B \-lkeyutils +should be specified to the linker. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SEE ALSO +.ad l +.nh +.BR keyctl (1), +.BR add_key (2), +.BR keyctl (2), +.BR request_key (2), +.BR keyctl (3), +.BR keyrings (7), +.BR keyutils (7), +.BR session\-keyring (7), +.BR user\-session-keyring (7) diff --git a/man/keyctl_set_reqkey_keyring.3 b/man/keyctl_set_reqkey_keyring.3 new file mode 100644 index 0000000..00da586 --- /dev/null +++ b/man/keyctl_set_reqkey_keyring.3 @@ -0,0 +1,101 @@ +.\" +.\" Copyright (C) 2006 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_SET_REQKEY_KEYRING 3 "4 May 2006" Linux "Linux Key Management Calls" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH NAME +keyctl_set_reqkey_keyring \- set the implicit destination keyring +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SYNOPSIS +.nf +.B #include <keyutils.h> +.sp +.BI "long keyctl_set_reqkey_keyring(int " reqkey_defl ");" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH DESCRIPTION +.BR keyctl_set_reqkey_keyring () +sets the default destination for implicit key requests for the current thread +and returns the old setting. +.P +After this operation has been issued, keys acquired by implicit key requests, +such as might be performed by +.BR open () +on an AFS or NFS filesystem, will be +linked by default to the specified keyring by this function. +.P +The valid values of +.I reqkey_defl +are: +.TP +.B KEY_REQKEY_DEFL_NO_CHANGE +This makes no change to the current setting. +.TP +.B KEY_REQKEY_DEFL_THREAD_KEYRING +This makes the thread-specific keyring the default destination. +.TP +.B KEY_REQKEY_DEFL_PROCESS_KEYRING +This makes the process-specific keyring the default destination. +.TP +.B KEY_REQKEY_DEFL_SESSION_KEYRING +This makes the session keyring the default destination. +.TP +.B KEY_REQKEY_DEFL_USER_KEYRING +This makes the UID-specific keyring the default destination. +.TP +.B KEY_REQKEY_DEFL_USER_SESSION_KEYRING +This makes the UID-specific session keyring the default destination. +.TP +.B KEY_REQKEY_DEFL_DEFAULT +This selects the default behaviour which is to use the thread-specific keyring +if there is one, otherwise the process-specific keyring if there is one, +otherwise the session keyring if there is one, otherwise the UID-specific +session keyring. +.P +This setting is inherited across +.BR fork () +and +.BR exec (). + +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH RETURN VALUE +On success +.BR keyctl_set_reqkey_keyring () +returns +.BR 0 . +On error, the value +.B -1 +will be returned and +.I errno +will have been set to an appropriate error. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH ERRORS +.TP +.B EINVAL +The value of +.I reqkey_defl +is invalid. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH LINKING +This is a library function that can be found in +.IR libkeyutils . +When linking, +.B \-lkeyutils +should be specified to the linker. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SEE ALSO +.ad l +.nh +.BR keyctl (1), +.BR add_key (2), +.BR keyctl (2), +.BR request_key (2), +.BR keyctl (3), +.BR keyutils (7), +.BR keyrings (7), +.BR request\-key (8) diff --git a/man/keyctl_set_timeout.3 b/man/keyctl_set_timeout.3 new file mode 100644 index 0000000..1b7ec94 --- /dev/null +++ b/man/keyctl_set_timeout.3 @@ -0,0 +1,81 @@ +.\" +.\" Copyright (C) 2006 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_SET_TIMEOUT 3 "4 May 2006" Linux "Linux Key Management Calls" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH NAME +keyctl_set_timeout \- set the expiration timer on a key +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SYNOPSIS +.nf +.B #include <keyutils.h> +.sp +.BI "long keyctl_set_timeout(key_serial_t " key ", unsigned " timeout ");" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH DESCRIPTION +.BR keyctl_set_timeout () +sets the expiration timer on a key to +.I timeout +seconds into the future. Setting +.I timeout +to +.B zero +cancels the expiration, assuming the key hasn't already expired. +.P +When the key expires, further attempts to access it will be met with error +.BR EKEYEXPIRED . +.P +The caller must have +.B setattr +permission on a key to be able change its permissions mask. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH RETURN VALUE +On success +.BR keyctl_set_timeout () +returns +.B 0 . +On error, the value +.B -1 +will be returned and +.I errno +will have been set to an appropriate error. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH ERRORS +.TP +.B ENOKEY +The specified key does not exist. +.TP +.B EKEYEXPIRED +The specified key has already expired. +.TP +.B EKEYREVOKED +The specified key has been revoked. +.TP +.B EACCES +The named key exists, but does not grant +.B setattr +permission to the calling process. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH LINKING +This is a library function that can be found in +.IR libkeyutils . +When linking, +.B \-lkeyutils +should be specified to the linker. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SEE ALSO +.ad l +.nh +.BR keyctl (1), +.BR add_key (2), +.BR keyctl (2), +.BR request_key (2), +.BR keyctl (3), +.BR keyrings (7), +.BR keyutils (7) diff --git a/man/keyctl_setperm.3 b/man/keyctl_setperm.3 new file mode 100644 index 0000000..0a4426d --- /dev/null +++ b/man/keyctl_setperm.3 @@ -0,0 +1,130 @@ +.\" +.\" Copyright (C) 2006 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_SETPERM 3 "4 May 2006" Linux "Linux Key Management Calls" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH NAME +keyctl_setperm \- change the permissions mask on a key +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SYNOPSIS +.nf +.B #include <keyutils.h> +.sp +.BI "long keyctl_setperm(key_serial_t " key ", key_perm_t " perm ");" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH DESCRIPTION +.BR keyctl_setperm () +changes the permissions mask on a key. +.P +A process that does not have the +.B SysAdmin +capability may not change the permissions mask on a key that doesn't have the +same UID as the caller. +.P +The caller must have +.B setattr +permission on a key to be able change its permissions mask. +.P +The permissions mask is a bitwise-OR of the following flags: +.TP +.B KEY_xxx_VIEW +Grant permission to view the attributes of a key. +.TP +.B KEY_xxx_READ +Grant permission to read the payload of a key or to list a keyring. +.TP +.B KEY_xxx_WRITE +Grant permission to modify the payload of a key or to add or remove links +to/from a keyring. +.TP +.B KEY_xxx_SEARCH +Grant permission to find a key or to search a keyring. +.TP +.B KEY_xxx_LINK +Grant permission to make links to a key. +.TP +.B KEY_xxx_SETATTR +Grant permission to change the ownership and permissions attributes of a key. +.TP +.B KEY_xxx_ALL +Grant all the above. +.P +The +.RB ' xxx ' +in the above should be replaced by one of: +.TP +.B POS +Grant the permission to a process that possesses the key (has it attached +searchably to one of the process's keyrings). +.TP +.B USR +Grant the permission to a process with the same UID as the key. +.TP +.B GRP +Grant the permission to a process with the same GID as the key, or with a +match for the key's GID amongst that process's Groups list. +.TP +.B OTH +Grant the permission to any other process. +.P +Examples include: +.BR KEY_POS_VIEW ", " KEY_USR_READ ", " KEY_GRP_SEARCH " and " KEY_OTH_ALL . +.P +User, group and other grants are exclusive: if a process qualifies in +the 'user' category, it will not qualify in the 'groups' category; and if a +process qualifies in either 'user' or 'groups' then it will not qualify in +the 'other' category. +.P +Possessor grants are cumulative with the grants from the 'user', 'groups' +and 'other' categories. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH RETURN VALUE +On success +.BR keyctl_setperm () +returns +.B 0 . +On error, the value +.B -1 +will be returned and +.I errno +will have been set to an appropriate error. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH ERRORS +.TP +.B ENOKEY +The specified key does not exist. +.TP +.B EKEYEXPIRED +The specified key has expired. +.TP +.B EKEYREVOKED +The specified key has been revoked. +.TP +.B EACCES +The named key exists, but does not grant +.B setattr +permission to the calling process. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH LINKING +This is a library function that can be found in +.IR libkeyutils . +When linking, +.B \-lkeyutils +should be specified to the linker. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SEE ALSO +.ad l +.nh +.BR keyctl (1), +.BR add_key (2), +.BR keyctl (2), +.BR request_key (2), +.BR keyctl (3), +.BR keyrings (7), +.BR keyutils (7) diff --git a/man/keyctl_update.3 b/man/keyctl_update.3 new file mode 100644 index 0000000..17fbdb4 --- /dev/null +++ b/man/keyctl_update.3 @@ -0,0 +1,96 @@ +.\" +.\" Copyright (C) 2006 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_UPDATE 3 "4 May 2006" Linux "Linux Key Management Calls" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH NAME +keyctl_update \- update a key +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SYNOPSIS +.nf +.B #include <keyutils.h> +.sp +.BI "long keyctl_update(key_serial_t " key ", const void *" payload , +.BI "size_t " plen ");" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH DESCRIPTION +.BR keyctl_update () +updates the payload of a key if the key type permits it. +.P +The caller must have +.B write +permission on a key to be able update it. +.P +.I payload +and +.I plen +specify the data for the new payload. +.I payload +may be NULL and +.I plen +may be zero if the key type permits that. The key type may reject the data if +it's in the wrong format or in some other way invalid. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH RETURN VALUE +On success +.BR keyctl_update () +returns +.BR 0 . +On error, the value +.B -1 +will be returned and +.I errno +will have been set to an appropriate error. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH ERRORS +.TP +.B ENOKEY +The key specified is invalid. +.TP +.B EKEYEXPIRED +The key specified has expired. +.TP +.B EKEYREVOKED +The key specified had been revoked. +.TP +.B EINVAL +The payload data was invalid. +.TP +.B ENOMEM +Insufficient memory to store the new payload. +.TP +.B EDQUOT +The key quota for this user would be exceeded by increasing the size of the +key to accommodate the new payload. +.TP +.B EACCES +The key exists, but is not +.B writable +by the calling process. +.TP +.B EOPNOTSUPP +The key type does not support the update operation on its keys. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH LINKING +This is a library function that can be found in +.IR libkeyutils . +When linking, +.B \-lkeyutils +should be specified to the linker. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SEE ALSO +.ad l +.nh +.BR keyctl (1), +.BR add_key (2), +.BR keyctl (2), +.BR request_key (2), +.BR keyctl (3), +.BR keyrings (7), +.BR keyutils (7) diff --git a/man/keyutils.7 b/man/keyutils.7 new file mode 100644 index 0000000..e17253b --- /dev/null +++ b/man/keyutils.7 @@ -0,0 +1,105 @@ +.\" +.\" Copyright (C) 2014 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 Licence +.\" as published by the Free Software Foundation; either version +.\" 2 of the Licence, or (at your option) any later version. +.\" +.TH KEYUTILS 7 "21 Feb 2014" Linux "Kernel key management" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH NAME +keyutils \- in-kernel key management utilities +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH DESCRIPTION +The +.B keyutils +package is a library and a set of utilities for accessing the kernel +\fBkeyrings\fP facility. +.P +A header file is supplied to provide the definitions and declarations required +to access the library: +.P +.RS +.B #include <keyutils.h> +.RE +.P +To link with the library, the following: +.P +.RS +.B \-lkeyutils +.RE +.P +should be specified to the linker. +.P +Three system calls are provided: +.TP +.BR add_key (2) +Supply a new key to the kernel. +.TP +.BR request_key (2) +Find an existing key for use, or, optionally, create one if one does not exist. +.TP +.BR keyctl (2) +Control a key in various ways. The library provides a variety of wrappers +around this system call and those should be used rather than calling it +directly. +.P +See the +.BR add_key (2), +.BR request_key (2), +and +.BR keyctl (2) +manual pages for more information. +.P +The \fBkeyctl\fP() wrappers are listed on the +.BR keyctl (3) +manual page. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH UTILITIES +.P +A program is provided to interact with the kernel facility by a number of +subcommands, e.g.: +.P +.RS +.B keyctl add user foo bar @s +.RE +.P +See the +.BR keyctl (1) +manual page for information on that. +.P +The kernel has the ability to upcall to userspace to fabricate new keys. This +can be triggered by \fBrequest_key\fP(), but userspace is better off using +\fBadd_key\fP() instead if it possibly can. +.P +The upcalling mechanism is usually routed via the +.BR request\-key (8) +program. What this does with any particular key is configurable in: +.P +.RS +.I /etc/request\-key.conf +.br +.I /etc/request\-key.d/ +.RE +.P +See the +.BR request\-key.conf (5) +and the +.BR request\-key (8) +manual pages for more information. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SEE ALSO +.ad l +.nh +.BR keyctl (1), +.BR keyctl (3), +.BR keyrings (7), +.BR persistent\-keyring (7), +.BR process\-keyring (7), +.BR session\-keyring (7), +.BR thread\-keyring (7), +.BR user\-keyring (7), +.BR user\-session\-keyring (7), +.BR pam_keyinit (8) diff --git a/man/recursive_key_scan.3 b/man/recursive_key_scan.3 new file mode 100644 index 0000000..8658002 --- /dev/null +++ b/man/recursive_key_scan.3 @@ -0,0 +1,90 @@ +.\" +.\" Copyright (C) 2011 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 Licence +.\" as published by the Free Software Foundation; either version +.\" 2 of the Licence, or (at your option) any later version. +.\" +.TH RECURSIVE_KEY_SCAN 3 "10 Mar 2011" Linux "Linux Key Utility Calls" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH NAME +recursive_key_scan, recursive_session_key_scan \- apply a function to all keys in a keyring tree +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SYNOPSIS +.nf +.B #include <keyutils.h> +.sp +.BI "typedef int (*" recursive_key_scanner_t ")(key_serial_t " parent , +.BI " key_serial_t " key ", char *" desc ", int " desc_len ", void *" data ");" +.sp +.BI "long recursive_key_scan(key_serial_t " keyring , +.BI " recursive_key_scanner_t " func ", void *" data ");" +.br +.BI "long recursive_session_key_scan(recursive_key_scanner_t " func , +.BI " void *" data ");" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH DESCRIPTION +.BR recursive_key_scan () +performs a depth-first recursive scan of the specified +.I keyring +tree and applies +.I func +to every link found in the accessible keyrings in that tree. +.I data +is passed to each invocation of func. +.P +The return values of +.I func +are summed and returned as the overall return value. Errors are ignored. +Inaccessible keyrings are not scanned, but links to them are still passed to +func. +.P +.BR recursive_session_key_scan () +works exactly like +.BR recursive_key_scan () +with the caller's session keyring specified as the starting keyring. +.P +The callback function is called for each link found in all the keyrings in the +nominated tree and so may be called multiple times for a particular key if that +key has multiple links to it. +.P +The callback function is passed the following parameters: +.TP +.B parent +The keyring containing the link or 0 for the initial key. +.TP +.BR key +The key to which the link points. +.TP +.BR desc " and " desc_len +A pointer to the raw description and its length as retrieved with +.BR keyctl_describe_alloc (). +These will be NULL and \-1 respectively if the description couldn't be +retrieved and +.I errno +will retain the error from +.BR keyctl_describe_alloc (). +.TP +.B data +The data passed to the scanner function. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH RETURN VALUE +These functions return the sum of the results of the callback functions they +invoke. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH ERRORS +Ignored. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH LINKING +When linking, +.B \-lkeyutils +should be specified to the linker. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SEE ALSO +.ad l +.nh +.BR keyctl (3), +.BR keyctl_describe_alloc (3), +.BR keyrings (7) diff --git a/man/request-key.8 b/man/request-key.8 new file mode 100644 index 0000000..50a7506 --- /dev/null +++ b/man/request-key.8 @@ -0,0 +1,61 @@ +.\" +.\" 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 REQUEST-KEY 8 "15 Nov 2011" Linux "Linux Key Management Utilities" +.SH NAME +request\-key \- handle key instantiation callback requests from the kernel +.SH SYNOPSIS +\fB/sbin/request\-key \fR<op> <key> <uid> <gid> <threadring> <processring> + <sessionring> [<info>] +.SH DESCRIPTION +This program is invoked by the kernel when the kernel is asked for a key that +it doesn't have immediately available. The kernel creates a partially set up +key and then calls out to this program to instantiate it. It is not intended +to be called directly. +.PP +However, for debugging purposes, it can be given some options on the command +line: +.IP \fB-d\fP +Turn on debugging mode. In this mode, no attempts are made to access any keys +and, if a handler program is selected, it won't be executed; instead, this +program will print a message and exit 0. +.IP \fB-D <description>\fP +In debugging mode, use the proposed key description specified with this rather +than the sample ("user;0;0;1f0000;debug:1234") built into the program. +.IP \fB-l\fP +Use configuration from the current directory. The program will use +.IR request-key.d/* " and " request-key.conf +from the current directory rather than from +.IR /etc . +.IP \fB-n\fP +Don't log to the system log. Ordinarily, error messages and debugging messages +will be copied to the system log - this will prevent that. +.IP \fB-v\fP +Turn on debugging output. This may be specified multiple times to produce +increasing levels of verbosity. +.IP \fB--version\fP +Print the program version and exit. +.SH ERRORS +All errors will be logged to the syslog. +.SH FILES +.ul +/etc/request\-key.d/*.conf +.ul 0 +Individual configuration files. +.P +.ul +/etc/request\-key.conf +.ul 0 +Fallback configuration file. +.SH SEE ALSO +.ad l +.nh +.BR keyctl (1), +.BR request\-key.conf (5), +.BR keyrings (7) diff --git a/man/request-key.conf.5 b/man/request-key.conf.5 new file mode 100644 index 0000000..276c771 --- /dev/null +++ b/man/request-key.conf.5 @@ -0,0 +1,145 @@ +.\" -*- nroff -*- +.\" Copyright (C) 2005 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 REQUEST-KEY.CONF 5 "15 November 2011" Linux "Linux Key Management Utilities" +.SH NAME +request\-key.conf \- Instantiation handler configuration file +.SH DESCRIPTION +.P +These files are used by the /sbin/request\-key program to determine which +program it should run to instantiate a key. +.P +request\-key looks for the best match, reading all the following files: +.IP + /etc/request\-key.d/*.conf +.br + /etc/request\-key.conf +.P +If it doesn't find a match, it will return an error +and the kernel will automatically negate the key. +.P +The best match is defined as the line with the shortest wildcard skips, ranking +the columns in order left to right. If two lines have the same length skips, +then the first read is the one taken. +.P +In the files, any blank line or line beginning with a hash mark '#' is +considered to be a comment and ignored. +.P +All other lines are assumed to be command lines with a number of white space +separated fields: +.P +<op> <type> <description> <callout\-info> <prog> <arg1> <arg2> ... +.P +The first four fields are used to match the parameters passed to request\-key by +the kernel. \fIop\fR is the operation type; currently the only supported +operation is "create". +.P +\fItype\fR, \fIdescription\fR and \fIcallout\-info\fR match the three +parameters passed to \fBkeyctl request2\fR or the \fBrequest_key()\fR system +call. Each of these may contain one asterisk '*' character as a wildcard +anywhere within the string. +.P +Should a match be made, the program specified by <prog> will be exec'd. This +must have a fully qualified path name. argv[0] will be set from the part of the +program name that follows the last slash '/' character. +.P +If the program name is prefixed with a pipe bar character '|', then the program +will be forked and exec'd attached to three pipes. The callout information will +be piped to it on it's stdin and the intended payload data will be retrieved +from its stdout. Anything sent to stderr will be posted in syslog. If the +program exits 0, then /sbin/request\-key will attempt to instantiate the key +with the data read from stdout. If it fails in any other way, then request\-key +will attempt to execute the appropriate 'negate' operation command. +.P +The program arguments can be substituted with various macros. Only complete +argument substitution is supported - macro substitutions can't be embedded. All +macros begin with a percent character '%'. An argument beginning with two +percent characters will have one of them discarded. +.P +The following macros are supported: +.P +.RS +%o Operation type +.br +%k Key ID +.br +%t Key type +.br +%d Key description +.br +%c Callout information +.br +%u Key UID +.br +%g Key GID +.br +%T Requestor's thread keyring +.br +%P Requestor's process keyring +.br +%S Requestor's session keyring +.RE +.P +There's another macro substitution too that permits the interpolation of the +contents of a key: +.P +.RS +%{<type>:<description>} +.RE +.P +This performs a lookup for a key of the given type and description on the +requestor's keyrings, and if found, substitutes the contents for the macro. If +not found an error will be logged and the key under construction will be +negated. +.SH EXAMPLE +.P +A basic file will be installed in the /etc. This will contain two debugging +lines that can be used to test the installation: +.P +.RS +create user debug:* negate /bin/keyctl negate %k 30 %S +.br +create user debug:loop:* * |/bin/cat +.br +create user debug:* * /usr/share/keyutils/request\-key\-debug.sh %k %d %c %S +.br +negate * * * /bin/keyctl negate %k 30 %S +.RE +.P +This is set up so that something like: +.P +.RS +keyctl request2 user debug:xxxx negate +.RE +.P +will create a negative user-defined key, something like: +.P +.RS +keyctl request2 user debug:yyyy spoon +.RE +.P +will create an instantiated user-defined key with "Debug spoon" as the payload, +and something like: +.P +.RS +keyctl request2 user debug:loop:zzzz abcdefghijkl +.RE +.P +will create an instantiated user-defined key with the callout information as +the payload. +.SH FILES +.ul +/etc/request\-key.conf +.ul 0 +.br +.ul +/etc/request\-key.d/*.conf +.ul 0 +.SH SEE ALSO +\fBkeyctl\fR(1), \fBrequest\-key.conf\fR(5) |