Revised request_key(2) man page for review

PATCH Applied Michael Kerrisk (man-pages) 5 participants 26 messages Nov 4, 2016 – Dec 20, 2016 5 messages not in the archive Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore

Share & tools

lore

Michael Kerrisk (man-pages)

author

2016-11-04 15:45 UTC #0 lore raw

Hi David (and anyone else with an interest to review)

Triggered by Eugene Syromyatnikov's recent input for the keyctl(2) man page, I've been doing a fair bit of work on improving the key management syscall man pages, and wonder if I could ask you for some review assistance?

First off, below, I've pasted the current draft of the request_key(2) page, which has seen quite a a lot of changes (increasing from around 100 rendered lines to nearly 300). Could you take a look (and also take a look at the outstanding FIXME)? (The page source file is attached, in case you want to see all the formatting.)

Thanks,

Michael

====

NAME
request_key - request a key from the kernel's key management facility

SYNOPSIS
#include <sys/types.h>
#include <keyutils.h>

key_serial_t request_key(const char *type, const char *description,
const char *callout_info, key_serial_t dest_keyring);

No glibc wrapper is provided for this system call; see NOTES.

DESCRIPTION
request_key() attempts to find a key of the given type with a description (name) that matches the specified description. If such a key could not be found, then the key is optionally cre‐
ated. If the key is found or created, request_key() attaches
it to the keyring whose ID is specified in dest_keyring and returns the key's serial number.

┌─────────────────────────────────────────────────────┐
│FIXME │
├─────────────────────────────────────────────────────┤ │Is 'keyring' allowed to be 0? Reading the source, it │ │appears so. In this case, by default, the key is │
│assigned to the session keyring. But, the │
│KEYCTL_SET_REQKEY_KEYRING also seems to have an │
│influence here. What are the details here? │
│ │
└─────────────────────────────────────────────────────┘

request_key() first recursively searches for a matching key in
all of the keyrings attached to the calling process. The
keyrings are searched in the order: thread-specific keyring, process-specific keyring, and then session keyring.

If request_key() is called from a program invoked by
request_key() on behalf of some other process to generate a key, then the keyrings of that other process will be searched next, using that other process's user ID, group ID, supplemen‐ tary group IDs, and security context to determine access.

The search of the keyring tree is breadth-first: the keys in each keyring searched are checked for a match before any child keyrings are recursed into. Only keys for which the caller has search permission be found, and only keyrings for which the caller has search permission may be searched.

If the key is not found and callout is NULL, then the call fails with the error ENOKEY.

If the key is not found and callout is not NULL, then the ker‐ nel attempts to invoke a user-space program to instantiate the key. The details are given below.

The dest_keyring serial number may be that of a valid keyring for which the caller has write permission, or it may be one of the following special keyring IDs:

KEY_SPEC_THREAD_KEYRING
This specifies the caller's thread-specific keyring (thread-keyring(7)).

KEY_SPEC_PROCESS_KEYRING
This specifies the caller's process-specific keyring (process-keyring(7)).

KEY_SPEC_SESSION_KEYRING
This specifies the caller's session-specific keyring (session-keyring(7)).

KEY_SPEC_USER_KEYRING
This specifies the caller's UID-specific keyring (user- keyring(7)).

KEY_SPEC_USER_SESSION_KEYRING
This specifies the caller's UID-session keyring (user- session-keyring(7)).

Requesting user-space instantiation of a key
If the kernel cannot find a key matching type and description, and callout is not NULL, then the kernel attempts to invoke a user-space program to instantiate a key with the given type and description. In this case, the following steps are performed:

a) The kernel creates an uninstantiated key, U, with the requested type and description.

b) The kernel creates an authorization key, V, that refers to the key U and records the facts that the caller of request_key(2) is:

(1) the context in which the key U should be instantiated and secured, and

(2) the context from which associated key requests may be satisfied.

The authorization key is constructed as follows:

* The key type is ".request_key_auth".

* The key's UID and GID are the same as the corresponding filesystem IDs of the requesting process.

* The key grants view, read, and search permissions to the key possessor as well as view permission for the key user.

* The description (name) of the key is the hexadecimal string representing the ID of the key that is to be instantiated in the requesting program.

* The payload of the key is taken from the data specified in callout_info.

* Internally, the kernel also records a record of the PID of the process that called request_key(2).

c) The kernel creates a process that executes a user-space service such as request-key(8) with a new session keyring that contains a link to the authorization key, V.

This program is supplied with the following command-line arguments:

[0] The string "/sbin/request-key".

[1] The string "create" (indicating that a key is to be created).

[2] The ID of the key that is to be instantiated.

[3] The filesystem UID of the caller of request_key().

[4] The filesystem GID of the caller of request_key().

[5] The ID of the thread keyring of the caller of
request_key(). This may be zero if that keyring hasn't been created.

[6] The ID of the process keyring of the caller of request_key(). This may be zero if that keyring hasn't been created.

[7] The ID of the session keyring of the caller of request_key().

Note: each of the command-line arguments that is a key ID is encoded in decimal (unlike the key IDs shown in /proc/keys, which are shown as hexadecimal values).

d) The program spawned in the previous step:

* Assumes the authority to instantiate the key U using the keyctl(2) KEYCTL_ASSUME_AUTHORITY operation (typically via the keyctl_assume_authority(3) function).

* Obtains the callout data from the payload of the autho‐ rization key V (using the keyctl(2) KEYCTL_READ opera‐ tion (or, more commonly, the keyctl_read(3) function) with a key ID value of KEY_SPEC_REQKEY_AUTH_KEY).

* Instantiates the key (or execs another program that per‐ forms that task), specifying the payload and destination
keyring. (The destination keyring that the requestor
specified when calling request_key() can be accessed using the special key ID KEY_SPEC_REQUESTOR_KEYRING.)
Instantiation is performed using the keyctl(2)
KEYCTL_INSTANTIATE operation (or, more commonly, the
keyctl_instantiate(3) function). At this point, the
request_key(2) call completes, and the requesting pro‐ gram can continue execution.

If these steps are unsuccessful, then an ENOKEY error will be returned to the caller of request_key() and a temporary nega‐ tive key will be installed in the keyring specified by
dest_keyring. This will expire after a few seconds, but will
cause subsequent calls to request_key() to fail until it does. The purpose of this negatively instantiated key is to prevent (possibly different) processes making repeated requests (that require expensive request-key(8) upcalls) for a key that can't (at the moment) be positively instantiated.

Once the key has been instantiated, the authorization key (KEY_SPEC_REQKEY_AUTH_KEY) is revoked, and the destination keyring (KEY_SPEC_REQUESTOR_KEYRING) is no longer accessible from the request-key(8) program.

If a key is created, then—regardless of whether it is a valid key or a negative key—it will displace any other key with the same type and description from the keyring specified in dest_keyring.

RETURN VALUE
On success, request_key() returns the serial number of the key it found or caused to be created. On error, -1 is returned and errno is set to indicate the cause of the error.

ERRORS
EACCES The keyring wasn't available for modification by the
user.

EDQUOT The key quota for this user would be exceeded by creat‐
ing this key or linking it to the keyring.

EINTR The request was interrupted by a signal; see signal(7).

EINVAL The size of the string (including the terminating null
byte) specified in type or description exceeded the limit (32 bytes and 4096 bytes respectively).

EINVAL The size of the string (including the terminating null
byte) specified in callout_info exceeded the system page size.

EKEYEXPIRED
An expired key was found, but no replacement could be obtained.

EKEYREJECTED
The attempt to generate a new key was rejected.

EKEYREVOKED
A revoked key was found, but no replacement could be obtained.

ENOKEY No matching key was found.

ENOMEM Insufficient memory to create a key.

VERSIONS
This system call first appeared in Linux 2.6.10.

CONFORMING TO
This system call is a nonstandard Linux extension.

NOTES
No wrapper for this system call is provided in glibc. A wrap‐ per is provided in the libkeyutils package. When employing the wrapper in that library, link with -lkeyutils.

EXAMPLE
The program below demonstrates the use of request_key(). The
type, description, and callout_info arguments for the system call are taken from the values supplied in the command line
arguments. The call specifies the session keyring as the tar‐
get keyring.

In order to demonstrate this program, we first create a suit‐ able entry in the file /etc/request-key.conf.

$ sudo sh
# echo 'create user mtk:* * /bin/keyctl instantiate %k %c %S' \
> /etc/request-keys.conf
# exit

This entry specifies that when a new "user" key with the prefix "mtk:" must be instantiated, that task should be performed via the keyctl(1) command's instantiate operation. (The program could The arguments supplied to the instantiate operation are:
the ID of the uninstantiated key (%k); the callout data sup‐ plied to the request_key() call (%c); and the session keyring (%S) of the requestor (i.e., the caller of request)key()). i(See request-key.conf(5) for details of these % specifiers.)

Then we run the program and check the contents of /proc/keys to verify that the requested kay has been instantiated:

$ ./a.out user mtk:key1 "Payload data"
$ grep '2dddaf50' /proc/keys
2dddaf50 I--Q--- 1 perm 3f010000 1000 1000 user mtk:key1: 12

   Program source
       The program below
       #include <sys/types.h>
       #include <keyutils.h>
       #include <stdio.h>
       #include <stdlib.h>
       #include <string.h>

       #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \
                               } while (0)

       int
       main(int argc, char *argv[])
       {
           key_serial_t key;

           if (argc != 4) {
               fprintf(stderr, "Usage: %s type description callout-data\n",
                       argv[0]);
               exit(EXIT_FAILURE);
           }

           key = request_key(argv[1], argv[2], argv[3],
                             KEY_SPEC_SESSION_KEYRING);
           if (key == -1)
               errExit("request_key");

           printf("Key ID is %lx\n", (long) key);

           exit(EXIT_SUCCESS);
       }

Eugene Syromyatnikov

2016-11-21 20:59 UTC #2 lore raw

Hello.

Possible amendments are in the following patches. The one thing i couldn't comprehend properly is the following paragraph:

[[
This entry specifies that when a new "user" key with the prefix "mtk:" must be instantiated, that task should be performed via the .BR keyctl (1)
command's
.B instantiate
operation.
(The program could
The arguments supplied to the
.B instantiate
operation are:
the ID of the uninstantiated key
.RI ( %k );
the callout data supplied to the
.BR request_key ()
call
.RI ( %c );
and the session keyring
.RI ( %S )
of the requestor (i.e., the caller of
.BR request)key ()).
i(See
.BR request-key.conf (5)
for details of these
.I %
specifiers.)
]]

I suppose there's some sort of copy-paste mistake.

Eugene Syromyatnikov (5):
request_key.2: add information regarding default keyring requesT_key.2: add information regarding minimal kernel version for
key instantiation on request
request_key.2: whitespace fix
request_key.2: wfix
request_key.2: additional error information

 man2/request_key.2 | 64 +++++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 56 insertions(+), 8 deletions(-)

Signature · 6 lines

2.10.2

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Michael Kerrisk (man-pages)

2016-11-21 22:33 UTC #3 lore raw

Hello Eugene,

Quoted 5 lines · Eugene Syromyatnikov

Hello.
Possible amendments are in the following patches. The one thing i couldn't comprehend properly is the following paragraph:

Quoted 8 lines

[[
This entry specifies that when a new "user" key with the prefix "mtk:" must be instantiated, that task should be performed via the .BR keyctl (1)
command's
.B instantiate
operation.
(The program could

The above line should not have been present.

Quoted 20 lines

The arguments supplied to the
.B instantiate
operation are:
the ID of the uninstantiated key
.RI ( %k );
the callout data supplied to the
.BR request_key ()
call
.RI ( %c );
and the session keyring
.RI ( %S )
of the requestor (i.e., the caller of
.BR request)key ()).
i(See
.BR request-key.conf (5)
for details of these
.I %
specifiers.)
]]

Quoted 1 line

I suppose there's some sort of copy-paste mistake.

Yes. Fixed now.

Cheers,

Michael

Quoted 11 lines

Eugene Syromyatnikov (5):
request_key.2: add information regarding default keyring requesT_key.2: add information regarding minimal kernel version for
key instantiation on request
request_key.2: whitespace fix
request_key.2: wfix
request_key.2: additional error information
 man2/request_key.2 | 64 +++++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 56 insertions(+), 8 deletions(-)

Signature · 7 lines

Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Eugene Syromyatnikov

2016-11-21 20:59 UTC #4 lore raw

PATCH 1/5 request_key.2: add information regarding default keyring

In reply to a message not in the archive

---
 man2/request_key.2 | 47 ++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 42 insertions(+), 5 deletions(-)

man2/request_key.2 +42 -5

index a9d0561..e29ca06 100644
@@ -35,11 +35,6 @@ If the key is found or created,
 attaches it to the keyring whose ID is specified in
 .I dest_keyring
 and returns the key's serial number.
-.\" FIXME Is 'keyring' allowed to be 0? Reading the source, it appears so.
-.\" In this case, by default, the key is assigned to the session keyring.
-.\" But, the KEYCTL_SET_REQKEY_KEYRING also seems to have an influence here.
-.\" What are the details here?
-.\"
 
 .BR request_key ()
 first recursively searches for a matching key in all of the keyrings

@@ -104,6 +99,48 @@ This specifies the caller's UID-specific keyring
 .B KEY_SPEC_USER_SESSION_KEYRING
 This specifies the caller's UID-session keyring
 .RB ( user-session-keyring (7)).
+.PP
+When the
+.I dest_keyring
+is specified to
+.BR 0 ,
+and no key construction have been performed, then no additional linking is done.
+Otherwise, if new key is constructed, it would be linked to the "default"
+keyring (which can be specified via the
+.BR keyctl (2)
+command
+.BR KEYCTL_SET_REQKEY_KEYRING ).
+More specifically, when kernel tries to determine to which keyring the
+newly constructed key should be linked, it tries the following options, starting
+from the value set via
+.BR KEYCTL_SET_REQKEY_KEYRING " " keyctl (2)
+command until it finds the first available one:
+.IP \(bu 3
+.\" 8bbf4976b59fc9fc2861e79cab7beb3f6d647640
+Requestor keyring (specified via
+.BR KEY_REQKEY_DEFL_REQUESTOR_KEYRING ,
+since Linux 2.6.29)
+.IP \(bu
+Thread-specific keyring (specified via
+.BR KEY_REQKEY_DEFL_THREAD_KEYRING )
+.IP \(bu
+Process-specific keyring (specified via
+.BR KEY_REQKEY_DEFL_PROCESS_KEYRING )
+.IP \(bu
+Session-specific keyring (specified via
+.BR KEY_REQKEY_DEFL_SESSION_KEYRING )
+.IP \(bu
+Session keyring for the process's user ID  (specified via
+.BR KEY_REQKEY_DEFL_USER_SESSION_KEYRING ).
+This keyring is expected to always exist.
+.IP \(bu
+UID-specific keyring (specified via
+.BR KEY_REQKEY_DEFL_USER_KEYRING ).
+This keyring is also expected to always exist.
+.PP
+Specifying
+.B KEY_REQKEY_DEFL_DEFAULT
+leads to starting from the beginning of the list.
 .\"
 .SS Requesting user-space instantiation of a key
 If the kernel cannot find a key matching

Signature · 6 lines

2.10.2

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Michael Kerrisk (man-pages)

2016-11-21 22:08 UTC #5 lore raw

Re: [PATCH 1/5] request_key.2: add information regarding default keyring

Hi Eugene,

Thanks for taking a shot at this. I'd really be keen to hear from David on this before I apply.

David, could you comment please?

Cheers,

Michael

Quoted 70 lines · Eugene Syromyatnikov

---
 man2/request_key.2 | 47 ++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 42 insertions(+), 5 deletions(-)

man2/request_key.2 +42 -5

index a9d0561..e29ca06 100644
@@ -35,11 +35,6 @@ If the key is found or created,
 attaches it to the keyring whose ID is specified in
 .I dest_keyring
 and returns the key's serial number.
-.\" FIXME Is 'keyring' allowed to be 0? Reading the source, it appears so.
-.\" In this case, by default, the key is assigned to the session keyring.
-.\" But, the KEYCTL_SET_REQKEY_KEYRING also seems to have an influence here.
-.\" What are the details here?
-.\"
 
 .BR request_key ()
 first recursively searches for a matching key in all of the keyrings

@@ -104,6 +99,48 @@ This specifies the caller's UID-specific keyring
 .B KEY_SPEC_USER_SESSION_KEYRING
 This specifies the caller's UID-session keyring
 .RB ( user-session-keyring (7)).
+.PP
+When the
+.I dest_keyring
+is specified to
+.BR 0 ,
+and no key construction have been performed, then no additional linking is done.
+Otherwise, if new key is constructed, it would be linked to the "default"
+keyring (which can be specified via the
+.BR keyctl (2)
+command
+.BR KEYCTL_SET_REQKEY_KEYRING ).
+More specifically, when kernel tries to determine to which keyring the
+newly constructed key should be linked, it tries the following options, starting
+from the value set via
+.BR KEYCTL_SET_REQKEY_KEYRING " " keyctl (2)
+command until it finds the first available one:
+.IP \(bu 3
+.\" 8bbf4976b59fc9fc2861e79cab7beb3f6d647640
+Requestor keyring (specified via
+.BR KEY_REQKEY_DEFL_REQUESTOR_KEYRING ,
+since Linux 2.6.29)
+.IP \(bu
+Thread-specific keyring (specified via
+.BR KEY_REQKEY_DEFL_THREAD_KEYRING )
+.IP \(bu
+Process-specific keyring (specified via
+.BR KEY_REQKEY_DEFL_PROCESS_KEYRING )
+.IP \(bu
+Session-specific keyring (specified via
+.BR KEY_REQKEY_DEFL_SESSION_KEYRING )
+.IP \(bu
+Session keyring for the process's user ID  (specified via
+.BR KEY_REQKEY_DEFL_USER_SESSION_KEYRING ).
+This keyring is expected to always exist.
+.IP \(bu
+UID-specific keyring (specified via
+.BR KEY_REQKEY_DEFL_USER_KEYRING ).
+This keyring is also expected to always exist.
+.PP
+Specifying
+.B KEY_REQKEY_DEFL_DEFAULT
+leads to starting from the beginning of the list.
 .\"
 .SS Requesting user-space instantiation of a key
 If the kernel cannot find a key matching

Signature · 7 lines

Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Michael Kerrisk (man-pages)

2016-11-25 10:01 UTC #6 lore raw

Re: [PATCH 1/5] request_key.2: add information regarding default keyring

In reply to Eugene Syromyatnikov

Hi Eugene,

Quoted 25 lines · Eugene Syromyatnikov

---
 man2/request_key.2 | 47 ++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 42 insertions(+), 5 deletions(-)

man2/request_key.2 +1 -5

index a9d0561..e29ca06 100644
@@ -35,11 +35,6 @@ If the key is found or created,
 attaches it to the keyring whose ID is specified in
 .I dest_keyring
 and returns the key's serial number.
-.\" FIXME Is 'keyring' allowed to be 0? Reading the source, it appears so.
-.\" In this case, by default, the key is assigned to the session keyring.
-.\" But, the KEYCTL_SET_REQKEY_KEYRING also seems to have an influence here.
-.\" What are the details here?
-.\"
 
 .BR request_key ()
 first recursively searches for a matching key in all of the keyrings

@@ -104,6 +99,48 @@ This specifies the caller's UID-specific keyring
 .B KEY_SPEC_USER_SESSION_KEYRING
 This specifies the caller's UID-session keyring
 .RB ( user-session-keyring (7)).
+.PP

man2/request_key.2 This specifies the caller's UID-specific keyring · line 112

Quoted 10 lines

man2/request_key.2 +10 -0

+When the
+.I dest_keyring
+is specified to
+.BR 0 ,
+and no key construction have been performed, then no additional linking is done.
+Otherwise, if new key is constructed, it would be linked to the "default"
+keyring (which can be specified via the
+.BR keyctl (2)
+command
+.BR KEYCTL_SET_REQKEY_KEYRING ).

For the purpose of me reviewing this, could you outline how you verified the following details:

Quoted 25 lines

man2/request_key.2 +24 -0

+More specifically, when kernel tries to determine to which keyring the
+newly constructed key should be linked, it tries the following options, starting
+from the value set via
+.BR KEYCTL_SET_REQKEY_KEYRING " " keyctl (2)
+command until it finds the first available one:
+.IP \(bu 3
+.\" 8bbf4976b59fc9fc2861e79cab7beb3f6d647640
+Requestor keyring (specified via
+.BR KEY_REQKEY_DEFL_REQUESTOR_KEYRING ,
+since Linux 2.6.29)
+.IP \(bu
+Thread-specific keyring (specified via
+.BR KEY_REQKEY_DEFL_THREAD_KEYRING )
+.IP \(bu
+Process-specific keyring (specified via
+.BR KEY_REQKEY_DEFL_PROCESS_KEYRING )
+.IP \(bu
+Session-specific keyring (specified via
+.BR KEY_REQKEY_DEFL_SESSION_KEYRING )
+.IP \(bu
+Session keyring for the process's user ID  (specified via
+.BR KEY_REQKEY_DEFL_USER_SESSION_KEYRING ).
+This keyring is expected to always exist.
+.IP \(bu

man2/request_key.2 This specifies the caller's UID-specific keyring · line 146

Quoted 10 lines

man2/request_key.2 +7 -0

+UID-specific keyring (specified via
+.BR KEY_REQKEY_DEFL_USER_KEYRING ).
+This keyring is also expected to always exist.
+.PP
+Specifying
+.B KEY_REQKEY_DEFL_DEFAULT
+leads to starting from the beginning of the list.
 .\"
 .SS Requesting user-space instantiation of a key
 If the kernel cannot find a key matching

Cheers,

Michael

Signature · 7 lines

Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

A message that is not in the archive (sent off-list or not yet received): 54aa766c-25de-74ba-fba5-59cd95b2ae91-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org

Eugene Syromyatnikov

2016-11-25 20:11 UTC #8 lore raw

Re: [PATCH 1/5] request_key.2: add information regarding default keyring

Quoted 69 lines · Michael Kerrisk (man-pages)

Hi Eugene,

Quoted 25 lines · Eugene Syromyatnikov

---
 man2/request_key.2 | 47 ++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 42 insertions(+), 5 deletions(-)

man2/request_key.2 +1 -5

index a9d0561..e29ca06 100644
@@ -35,11 +35,6 @@ If the key is found or created,
 attaches it to the keyring whose ID is specified in
 .I dest_keyring
 and returns the key's serial number.
-.\" FIXME Is 'keyring' allowed to be 0? Reading the source, it appears so.
-.\" In this case, by default, the key is assigned to the session keyring.
-.\" But, the KEYCTL_SET_REQKEY_KEYRING also seems to have an influence here.
-.\" What are the details here?
-.\"
 
 .BR request_key ()
 first recursively searches for a matching key in all of the keyrings

@@ -104,6 +99,48 @@ This specifies the caller's UID-specific keyring
 .B KEY_SPEC_USER_SESSION_KEYRING
 This specifies the caller's UID-session keyring
 .RB ( user-session-keyring (7)).
+.PP

man2/request_key.2 This specifies the caller's UID-specific keyring · line 112

Quoted 10 lines

man2/request_key.2 +10 -0

+When the
+.I dest_keyring
+is specified to
+.BR 0 ,
+and no key construction have been performed, then no additional linking is done.
+Otherwise, if new key is constructed, it would be linked to the "default"
+keyring (which can be specified via the
+.BR keyctl (2)
+command
+.BR KEYCTL_SET_REQKEY_KEYRING ).

For the purpose of me reviewing this, could you outline how you verified the following details:

Quoted 27 lines

man2/request_key.2 +27 -0

+More specifically, when kernel tries to determine to which keyring the
+newly constructed key should be linked, it tries the following options, starting
+from the value set via
+.BR KEYCTL_SET_REQKEY_KEYRING " " keyctl (2)
+command until it finds the first available one:
+.IP \(bu 3
+.\" 8bbf4976b59fc9fc2861e79cab7beb3f6d647640
+Requestor keyring (specified via
+.BR KEY_REQKEY_DEFL_REQUESTOR_KEYRING ,
+since Linux 2.6.29)
+.IP \(bu
+Thread-specific keyring (specified via
+.BR KEY_REQKEY_DEFL_THREAD_KEYRING )
+.IP \(bu
+Process-specific keyring (specified via
+.BR KEY_REQKEY_DEFL_PROCESS_KEYRING )
+.IP \(bu
+Session-specific keyring (specified via
+.BR KEY_REQKEY_DEFL_SESSION_KEYRING )
+.IP \(bu
+Session keyring for the process's user ID  (specified via
+.BR KEY_REQKEY_DEFL_USER_SESSION_KEYRING ).
+This keyring is expected to always exist.
+.IP \(bu
+UID-specific keyring (specified via
+.BR KEY_REQKEY_DEFL_USER_KEYRING ).
+This keyring is also expected to always exist.

Quoted 9 lines

man2/request_key.2 This specifies the caller's UID-specific keyring · line 146
Quoted 8 lines
man2/request_key.2 +4 -0
+.PP
+Specifying
+.B KEY_REQKEY_DEFL_DEFAULT
+leads to starting from the beginning of the list.
 .\"
 .SS Requesting user-space instantiation of a key
 If the kernel cannot find a key matching

Based on linux v4.9-rc6 (9c763584):

* security/keys/keyctl.c, SYSCALL_DEFINE4(request_key, ...), line 158:
* Assume that call is performed with with destringid == 0:
* We skip check on line 196, so dest_ref remains NULL
* On line 213, request_key_and_link is called with key_ref_to_ptr(dest_ref)
* key_ref_to_ptr() itself just zeroes lower bit which is used for indication that key reference in the possession of the current context.
* security/keys/request_key.c, request_key_and_link, line 508:
* On line 543, we try to search process keyrings for the key (we fill ctx at hte beginning of the function and then pass it to search_process_keyrings)
* If key is found (key_ref is not erroneous), we convert key_ref to ptr on line 546 and skip the following block on line 547 since dest_keyring is 0.
* If key is not found and error is not EAGAIN, then

    construct_key_and_link is called on line 566 with dest_keyring ==
    NULL.
 * security/keys/request_key.c, construct_key_and_link, line 430:
  * On line 450, construct_get_dest_keyring is called with dest_keyring
    == NULL.
 * security/keys/request_key.c, construct_get_dest_keyring, line 253:
  * The argument here (which is pointer to pointer to struct key) is
    named _dest_keyring, but on line 257 it is dereferenced to local
    variable dest_keyring (so it stores NULL now).
  * We re going to the "else" branch (starting from line 266) of check
    on line 262

* Now we are switching against cred->jit_keyring with the behavour described in the patch.
* git grep jit_keyring security/keys reveals that it is assigned inside keyctl_set_reqkey_keyring, security/keys/keyctl.c, line 1257.
* keyctl_set_reqkey_keyring is called from SYSCALL_DEFINE5(keyctl, ...), when option passed to keyctl is KEYCTL_SET_REQKEY_KEYRING (line 1652).
* Default value for jit_keyring is sort of difficult to find out, since it is inherited, but overall it is explicitly set to KEY_REQKEY_DEFL_THREAD_KEYRING or copied from zeroed-out structures (so it is equal to KEY_REQKEY_DEFL_DEFAULT) which leads to the same behaviour in case the process has not been upcalled by request_key construction.

Quoted 8 lines

Cheers,

Michael

Signature · 3 lines

Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

Michael Kerrisk (man-pages)

2016-12-13 13:20 UTC #9 lore raw

Re: [PATCH 1/5] request_key.2: add information regarding default keyring

Hi Eugene,

This is just a reminder to us that one way or another I should not fiorget this patch of yours...

Cheers,

Michael

Quoted 130 lines · Eugene Syromyatnikov

Quoted 69 lines · Michael Kerrisk (man-pages)
Hi Eugene,
Quoted 25 lines · Eugene Syromyatnikov
---
 man2/request_key.2 | 47 ++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 42 insertions(+), 5 deletions(-)
man2/request_key.2 +1 -5
index a9d0561..e29ca06 100644
@@ -35,11 +35,6 @@ If the key is found or created,
 attaches it to the keyring whose ID is specified in
 .I dest_keyring
 and returns the key's serial number.
-.\" FIXME Is 'keyring' allowed to be 0? Reading the source, it appears so.
-.\" In this case, by default, the key is assigned to the session keyring.
-.\" But, the KEYCTL_SET_REQKEY_KEYRING also seems to have an influence here.
-.\" What are the details here?
-.\"
 
 .BR request_key ()
 first recursively searches for a matching key in all of the keyrings
@@ -104,6 +99,48 @@ This specifies the caller's UID-specific keyring
 .B KEY_SPEC_USER_SESSION_KEYRING
 This specifies the caller's UID-session keyring
 .RB ( user-session-keyring (7)).
+.PP
man2/request_key.2 This specifies the caller's UID-specific keyring · line 112
Quoted 10 lines
man2/request_key.2 +10 -0
+When the
+.I dest_keyring
+is specified to
+.BR 0 ,
+and no key construction have been performed, then no additional linking is done.
+Otherwise, if new key is constructed, it would be linked to the "default"
+keyring (which can be specified via the
+.BR keyctl (2)
+command
+.BR KEYCTL_SET_REQKEY_KEYRING ).
For the purpose of me reviewing this, could you outline how you verified the following details:
Quoted 27 lines
man2/request_key.2 +27 -0
+More specifically, when kernel tries to determine to which keyring the
+newly constructed key should be linked, it tries the following options, starting
+from the value set via
+.BR KEYCTL_SET_REQKEY_KEYRING " " keyctl (2)
+command until it finds the first available one:
+.IP \(bu 3
+.\" 8bbf4976b59fc9fc2861e79cab7beb3f6d647640
+Requestor keyring (specified via
+.BR KEY_REQKEY_DEFL_REQUESTOR_KEYRING ,
+since Linux 2.6.29)
+.IP \(bu
+Thread-specific keyring (specified via
+.BR KEY_REQKEY_DEFL_THREAD_KEYRING )
+.IP \(bu
+Process-specific keyring (specified via
+.BR KEY_REQKEY_DEFL_PROCESS_KEYRING )
+.IP \(bu
+Session-specific keyring (specified via
+.BR KEY_REQKEY_DEFL_SESSION_KEYRING )
+.IP \(bu
+Session keyring for the process's user ID  (specified via
+.BR KEY_REQKEY_DEFL_USER_SESSION_KEYRING ).
+This keyring is expected to always exist.
+.IP \(bu
+UID-specific keyring (specified via
+.BR KEY_REQKEY_DEFL_USER_KEYRING ).
+This keyring is also expected to always exist.
Quoted 9 lines
man2/request_key.2 This specifies the caller's UID-specific keyring · line 146
Quoted 8 lines
man2/request_key.2 +4 -0
+.PP
+Specifying
+.B KEY_REQKEY_DEFL_DEFAULT
+leads to starting from the beginning of the list.
 .\"
 .SS Requesting user-space instantiation of a key
 If the kernel cannot find a key matching
Based on linux v4.9-rc6 (9c763584):
* security/keys/keyctl.c, SYSCALL_DEFINE4(request_key, ...), line 158:
* Assume that call is performed with with destringid == 0:
* We skip check on line 196, so dest_ref remains NULL
* On line 213, request_key_and_link is called with key_ref_to_ptr(dest_ref)
* key_ref_to_ptr() itself just zeroes lower bit which is used for indication that key reference in the possession of the current context.
* security/keys/request_key.c, request_key_and_link, line 508:
* On line 543, we try to search process keyrings for the key (we fill ctx at hte beginning of the function and then pass it to search_process_keyrings)
* If key is found (key_ref is not erroneous), we convert key_ref to ptr on line 546 and skip the following block on line 547 since dest_keyring is 0.
* If key is not found and error is not EAGAIN, then
    construct_key_and_link is called on line 566 with dest_keyring ==
    NULL.
 * security/keys/request_key.c, construct_key_and_link, line 430:
  * On line 450, construct_get_dest_keyring is called with dest_keyring
    == NULL.
 * security/keys/request_key.c, construct_get_dest_keyring, line 253:
  * The argument here (which is pointer to pointer to struct key) is
    named _dest_keyring, but on line 257 it is dereferenced to local
    variable dest_keyring (so it stores NULL now).
  * We re going to the "else" branch (starting from line 266) of check
    on line 262
* Now we are switching against cred->jit_keyring with the behavour described in the patch.
* git grep jit_keyring security/keys reveals that it is assigned inside keyctl_set_reqkey_keyring, security/keys/keyctl.c, line 1257.
* keyctl_set_reqkey_keyring is called from SYSCALL_DEFINE5(keyctl, ...), when option passed to keyctl is KEYCTL_SET_REQKEY_KEYRING (line 1652).
* Default value for jit_keyring is sort of difficult to find out, since it is inherited, but overall it is explicitly set to KEY_REQKEY_DEFL_THREAD_KEYRING or copied from zeroed-out structures (so it is equal to KEY_REQKEY_DEFL_DEFAULT) which leads to the same behaviour in case the process has not been upcalled by request_key construction.
Quoted 8 lines
Cheers,
Michael
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Signature · 7 lines

Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Michael Kerrisk (man-pages)

2016-12-17 12:21 UTC #10 lore raw

Re: [PATCH 1/5] request_key.2: add information regarding default keyring

In reply to Eugene Syromyatnikov

Hello Eugene, (and David)

[David, could you take a look at the FIXMEs below?]

Quoted 59 lines · Eugene Syromyatnikov

---
 man2/request_key.2 | 47 ++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 42 insertions(+), 5 deletions(-)

man2/request_key.2 +35 -5

index a9d0561..e29ca06 100644
@@ -35,11 +35,6 @@ If the key is found or created,
 attaches it to the keyring whose ID is specified in
 .I dest_keyring
 and returns the key's serial number.
-.\" FIXME Is 'keyring' allowed to be 0? Reading the source, it appears so.
-.\" In this case, by default, the key is assigned to the session keyring.
-.\" But, the KEYCTL_SET_REQKEY_KEYRING also seems to have an influence here.
-.\" What are the details here?
-.\"
 
 .BR request_key ()
 first recursively searches for a matching key in all of the keyrings

@@ -104,6 +99,48 @@ This specifies the caller's UID-specific keyring
 .B KEY_SPEC_USER_SESSION_KEYRING
 This specifies the caller's UID-session keyring
 .RB ( user-session-keyring (7)).
+.PP
+When the
+.I dest_keyring
+is specified to
+.BR 0 ,
+and no key construction have been performed, then no additional linking is done.
+Otherwise, if new key is constructed, it would be linked to the "default"
+keyring (which can be specified via the
+.BR keyctl (2)
+command
+.BR KEYCTL_SET_REQKEY_KEYRING ).
+More specifically, when kernel tries to determine to which keyring the
+newly constructed key should be linked, it tries the following options, starting
+from the value set via
+.BR KEYCTL_SET_REQKEY_KEYRING " " keyctl (2)
+command until it finds the first available one:
+.IP \(bu 3
+.\" 8bbf4976b59fc9fc2861e79cab7beb3f6d647640
+Requestor keyring (specified via
+.BR KEY_REQKEY_DEFL_REQUESTOR_KEYRING ,
+since Linux 2.6.29)
+.IP \(bu
+Thread-specific keyring (specified via
+.BR KEY_REQKEY_DEFL_THREAD_KEYRING )
+.IP \(bu
+Process-specific keyring (specified via
+.BR KEY_REQKEY_DEFL_PROCESS_KEYRING )
+.IP \(bu
+Session-specific keyring (specified via
+.BR KEY_REQKEY_DEFL_SESSION_KEYRING )
+.IP \(bu
+Session keyring for the process's user ID  (specified via
+.BR KEY_REQKEY_DEFL_USER_SESSION_KEYRING ).
+This keyring is expected to always exist.
+.IP \(bu

man2/request_key.2 This specifies the caller's UID-specific keyring · line 146

Quoted 10 lines

man2/request_key.2 +7 -0

+UID-specific keyring (specified via
+.BR KEY_REQKEY_DEFL_USER_KEYRING ).
+This keyring is also expected to always exist.
+.PP
+Specifying
+.B KEY_REQKEY_DEFL_DEFAULT
+leads to starting from the beginning of the list.
 .\"
 .SS Requesting user-space instantiation of a key
 If the kernel cannot find a key matching

Thanks. Everything that I tested concurs with your patch, but I've done some rewording that makes things a bit clearer, and I've added one or two details.

How does the following look:

The dest_keyring serial number may be that of a valid keyring for which the caller has write permission, or it may be one of the following special keyring IDs:

KEY_SPEC_THREAD_KEYRING
This specifies the caller's thread-specific keyring
(thread-keyring(7)).

KEY_SPEC_PROCESS_KEYRING
This specifies the caller's process-specific keyring
(process-keyring(7)).

KEY_SPEC_SESSION_KEYRING
This specifies the caller's session-specific keyring (ses‐ sion-keyring(7)).

KEY_SPEC_USER_KEYRING
This specifies the caller's UID-specific keyring (user- keyring(7)).

KEY_SPEC_USER_SESSION_KEYRING
This specifies the caller's UID-session keyring (user-ses‐ sion-keyring(7)).

When the dest_keyring is specified to 0, and no key construction have been performed, then no additional linking is done.

Otherwise, if dest_keyring is 0 and a new key is constructed, the new key will be linked to the "default" keyring. More precisely, when the kernel tries to determine to which keyring the newly constructed key should be linked, it tries the following keyrings, beginning with the keyring set via the keyctl(2) KEYCTL_SET_REQKEY_KEYRING command and continuing in the order shown below until it finds the first keyring that exists:

· The requestor keyring (KEY_REQKEY_DEFL_REQUESTOR_KEYRING, since
Linux 2.6.29).

┌─────────────────────────────────────────────────────┐
│FIXME │
├─────────────────────────────────────────────────────┤
│Actually, is the preceding point correct? If I │
│understand correctly, we'll only get here if won't │
│refer to a keyring. Have I misunderstood? │
└─────────────────────────────────────────────────────┘

· The thread-specific keyring (KEY_REQKEY_DEFL_THREAD_KEYRING).

· The process-specific keyring (KEY_REQKEY_DEFL_PROCESS_KEYRING).

· The session-specific keyring (KEY_REQKEY_DEFL_SESSION_KEYRING).

· The session keyring for the process's user ID
(KEY_REQKEY_DEFL_USER_SESSION_KEYRING). This keyring is expected to always exist.

┌─────────────────────────────────────────────────────┐
│FIXME │
├─────────────────────────────────────────────────────┤ │Are there circumstances where the session keyring │
│does not exist? What are they? │
└─────────────────────────────────────────────────────┘

· The UID-specific keyring (KEY_REQKEY_DEFL_USER_KEYRING). This
keyring is also expected to always exist.

┌─────────────────────────────────────────────────────┐
│FIXME │
├─────────────────────────────────────────────────────┤
│Are there circumstances where the UID-specific │
│keyring does not exist? What are they? │
└─────────────────────────────────────────────────────┘

If the keyctl(2) KEYCTL_SET_REQKEY_KEYRING command specifies
KEY_REQKEY_DEFL_DEFAULT (or no KEYCTL_SET_REQKEY_KEYRING command is performed), then the kernel looks for a keyring starting from the beginning of the list.

These changes have been pushed to the public branch:
http://git.kernel.org/cgit/docs/man-pages/man-pages.git/log/?h=draft_2_keys

Cheers,

Michael

Signature · 7 lines

Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

A message that is not in the archive (sent off-list or not yet received): 6df2c812-c2d6-321c-902f-93b4d3aaa953-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org

Eugene Syromyatnikov

2016-12-18 06:40 UTC #12 lore raw

Re: [PATCH 1/5] request_key.2: add information regarding default keyring

Quoted 119 lines · Michael Kerrisk (man-pages)

Hello Eugene, (and David)
[David, could you take a look at the FIXMEs below?]
Quoted 59 lines · Eugene Syromyatnikov
---
 man2/request_key.2 | 47 ++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 42 insertions(+), 5 deletions(-)
man2/request_key.2 +35 -5
index a9d0561..e29ca06 100644
@@ -35,11 +35,6 @@ If the key is found or created,
 attaches it to the keyring whose ID is specified in
 .I dest_keyring
 and returns the key's serial number.
-.\" FIXME Is 'keyring' allowed to be 0? Reading the source, it appears so.
-.\" In this case, by default, the key is assigned to the session keyring.
-.\" But, the KEYCTL_SET_REQKEY_KEYRING also seems to have an influence here.
-.\" What are the details here?
-.\"
 
 .BR request_key ()
 first recursively searches for a matching key in all of the keyrings
@@ -104,6 +99,48 @@ This specifies the caller's UID-specific keyring
 .B KEY_SPEC_USER_SESSION_KEYRING
 This specifies the caller's UID-session keyring
 .RB ( user-session-keyring (7)).
+.PP
+When the
+.I dest_keyring
+is specified to
+.BR 0 ,
+and no key construction have been performed, then no additional linking is done.
+Otherwise, if new key is constructed, it would be linked to the "default"
+keyring (which can be specified via the
+.BR keyctl (2)
+command
+.BR KEYCTL_SET_REQKEY_KEYRING ).
+More specifically, when kernel tries to determine to which keyring the
+newly constructed key should be linked, it tries the following options, starting
+from the value set via
+.BR KEYCTL_SET_REQKEY_KEYRING " " keyctl (2)
+command until it finds the first available one:
+.IP \(bu 3
+.\" 8bbf4976b59fc9fc2861e79cab7beb3f6d647640
+Requestor keyring (specified via
+.BR KEY_REQKEY_DEFL_REQUESTOR_KEYRING ,
+since Linux 2.6.29)
+.IP \(bu
+Thread-specific keyring (specified via
+.BR KEY_REQKEY_DEFL_THREAD_KEYRING )
+.IP \(bu
+Process-specific keyring (specified via
+.BR KEY_REQKEY_DEFL_PROCESS_KEYRING )
+.IP \(bu
+Session-specific keyring (specified via
+.BR KEY_REQKEY_DEFL_SESSION_KEYRING )
+.IP \(bu
+Session keyring for the process's user ID  (specified via
+.BR KEY_REQKEY_DEFL_USER_SESSION_KEYRING ).
+This keyring is expected to always exist.
+.IP \(bu
man2/request_key.2 This specifies the caller's UID-specific keyring · line 146
Quoted 10 lines
man2/request_key.2 +7 -0
+UID-specific keyring (specified via
+.BR KEY_REQKEY_DEFL_USER_KEYRING ).
+This keyring is also expected to always exist.
+.PP
+Specifying
+.B KEY_REQKEY_DEFL_DEFAULT
+leads to starting from the beginning of the list.
 .\"
 .SS Requesting user-space instantiation of a key
 If the kernel cannot find a key matching
Thanks. Everything that I tested concurs with your patch, but I've done some rewording that makes things a bit clearer, and I've added one or two details.
How does the following look:
The dest_keyring serial number may be that of a valid keyring for which the caller has write permission, or it may be one of the following special keyring IDs:
KEY_SPEC_THREAD_KEYRING
This specifies the caller's thread-specific keyring
(thread-keyring(7)).
KEY_SPEC_PROCESS_KEYRING
This specifies the caller's process-specific keyring
(process-keyring(7)).
KEY_SPEC_SESSION_KEYRING
This specifies the caller's session-specific keyring (ses‐ sion-keyring(7)).
KEY_SPEC_USER_KEYRING
This specifies the caller's UID-specific keyring (user- keyring(7)).
KEY_SPEC_USER_SESSION_KEYRING
This specifies the caller's UID-session keyring (user-ses‐ sion-keyring(7)).
When the dest_keyring is specified to 0, and no key construction have been performed, then no additional linking is done.
Otherwise, if dest_keyring is 0 and a new key is constructed, the new key will be linked to the "default" keyring. More precisely, when the kernel tries to determine to which keyring the newly constructed key should be linked, it tries the following keyrings, beginning with the keyring set via the keyctl(2) KEYCTL_SET_REQKEY_KEYRING command and continuing in the order shown below until it finds the first keyring that exists:
· The requestor keyring (KEY_REQKEY_DEFL_REQUESTOR_KEYRING, since
Linux 2.6.29).

Quoted 7 lines

┌─────────────────────────────────────────────────────┐
│FIXME │
├─────────────────────────────────────────────────────┤
│Actually, is the preceding point correct? If I │
│understand correctly, we'll only get here if won't │
│refer to a keyring. Have I misunderstood? │
└─────────────────────────────────────────────────────┘

(The "if (cred->request_key_auth)" condition at request_key.c:271 is entered only in case cred->request_key_auth is set, and it is set to non-zero value (apart from cred copying) only in keyctl_change_reqkey_auth() at keyctl.c:1017. This function, in turn, is called with non-zero argument only in keyctl_assume_authority(), keyctl.c:1408. And this uses result of key_get_instantiation_authkey() (defined in request_key_auth.c:242), which searches of a key of type key_type_request_key_auth. Keys of this type are constructed by request_key_auth_new() at request_key_auth.c:147 (if i understood correctly), and the only call site for this function is construct_key() at request_key.c:203. It is then calls call_sbin_request_key (or other actor of type request_key_actor_t which can be set in key type—maybe this should be pointed out somewhere in terms how it is set/configured, but the only place where it is non-NULL—found by quick git grep—is fs/nfs/nfs4idmap.c:
.request_key = nfs_idmap_legacy_upcall, but it's difficult to say
whether it has other uses despite message of commit b5f545c which initially introduced request_key field and functionality also points at NFS) with the struct key_construction provided in the furst argument, where authley field is set to the newly constructed authkey. In call_sbin_request_key() authkey is linked (at request_key.c:127) to the newly created (at request_key.c:117) keyring and latter then passed to call_usermodehelper_keys() at request_key.c:175 as a session_keyring. In call_usermodehelper_keys() it is passed as subprocess data, which is then used by provided in the call_usermodehelper_setup() call at request_key.c:80 umh_keys_init callback for installing it as a session keyring with a install_session_keyring_to_cred() call (defined in process_keys.c:223).

So, this is possible (only?—i haven't seen a possibility to set requestor keyring from the user space) in case the kernel upcalls helper process for instantiating a key—this makes request authorization key being linked to a session keyring. And by calling keyctl(KEYCTL_ASSUME_AUTHORITY), this process might set request_key_auth (since it knows appropriate ID as it has target key ID passed as a second parameter—request_key.c:166). This helper process could then perform request_key with destringid set to 0 (and with the default keyring being set to KEY_REQKEY_DEFL_REQUESTOR_KEYRING or KEY_REQKEY_DEFL_DEFAULT), effectively meeting all conditions for executing this code.

Quoted 45 lines

· The thread-specific keyring (KEY_REQKEY_DEFL_THREAD_KEYRING).
· The process-specific keyring (KEY_REQKEY_DEFL_PROCESS_KEYRING).
· The session-specific keyring (KEY_REQKEY_DEFL_SESSION_KEYRING).
· The session keyring for the process's user ID
(KEY_REQKEY_DEFL_USER_SESSION_KEYRING). This keyring is expected to always exist.
┌─────────────────────────────────────────────────────┐
│FIXME │
├─────────────────────────────────────────────────────┤ │Are there circumstances where the session keyring │
│does not exist? What are they? │
└─────────────────────────────────────────────────────┘
· The UID-specific keyring (KEY_REQKEY_DEFL_USER_KEYRING). This
keyring is also expected to always exist.
┌─────────────────────────────────────────────────────┐
│FIXME │
├─────────────────────────────────────────────────────┤
│Are there circumstances where the UID-specific │
│keyring does not exist? What are they? │
└─────────────────────────────────────────────────────┘
If the keyctl(2) KEYCTL_SET_REQKEY_KEYRING command specifies
KEY_REQKEY_DEFL_DEFAULT (or no KEYCTL_SET_REQKEY_KEYRING command is performed), then the kernel looks for a keyring starting from the beginning of the list.
These changes have been pushed to the public branch:
http://git.kernel.org/cgit/docs/man-pages/man-pages.git/log/?h=draft_2_keys
Cheers,
Michael
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Signature · 7 lines

Eugene Syromyatnikov
mailto:[email protected]
xmpp:esyr@jabber.{ru|org}
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

David Howells

2016-12-19 08:19 UTC #13 lore raw

Re: [PATCH 1/5] request_key.2: add information regarding default keyring

In reply to a message not in the archive

TWljaGFlbCBLZXJyaXNrIChtYW4tcGFnZXMpIDxtdGsubWFucGFnZXNAZ21haWwuY29tPiB3cm90 ZToNCg0KPiAgICAgICAgT3RoZXJ3aXNlLCAgaWYgIGRlc3Rfa2V5cmluZyBpcyAwIGFuZCBhIG5l dyBrZXkgaXMgY29uc3RydWN0ZWQsIHRoZSBuZXcNCj4gICAgICAgIGtleSB3aWxsIGJlIGxpbmtl ZCB0byB0aGUgImRlZmF1bHQiIGtleXJpbmcuICBNb3JlIHByZWNpc2VseSwgd2hlbiAgdGhlDQo+ ICAgICAgICBrZXJuZWwgIHRyaWVzICB0byAgZGV0ZXJtaW5lIHRvIHdoaWNoIGtleXJpbmcgdGhl IG5ld2x5IGNvbnN0cnVjdGVkIGtleQ0KPiAgICAgICAgc2hvdWxkIGJlIGxpbmtlZCwgaXQgdHJp ZXMgdGhlIGZvbGxvd2luZyBrZXlyaW5ncywgYmVnaW5uaW5nICB3aXRoICB0aGUNCj4gICAgICAg IGtleXJpbmcgIHNldCAgdmlhICB0aGUgIGtleWN0bCgyKSBLRVlDVExfU0VUX1JFUUtFWV9LRVlS SU5HIGNvbW1hbmQgYW5kDQo+ICAgICAgICBjb250aW51aW5nIGluIHRoZSBvcmRlciBzaG93biBi ZWxvdyB1bnRpbCBpdCBmaW5kcyAgdGhlICBmaXJzdCAga2V5cmluZw0KPiAgICAgICAgdGhhdCBl eGlzdHM6DQo+IA0KPiAgICAgICAgwrcgIFRoZSAgIHJlcXVlc3RvciAga2V5cmluZyAgKEtFWV9S RVFLRVlfREVGTF9SRVFVRVNUT1JfS0VZUklORywgIHNpbmNlDQo+ICAgICAgICAgICBMaW51eCAy LjYuMjkpLg0KDQpUaGlzIGlzIG9ubHkgYXZhaWxhYmxlIGluIHRoZSAvc2Jpbi9yZXF1ZXN0LWtl eSB1cGNhbGwsIHdoZXJlIGl0IHJlZmVycyBiYWNrDQp0byB0aGUgZGVzdGluYXRpb24ga2V5cmlu ZyBvZiB3aG9ldmVyIGNhbGxlZCByZXF1ZXN0X2tleSgpLg0KDQo+ICAgICAgICDCtyAgVGhlICAg IHNlc3Npb24gICAga2V5cmluZyAgICBmb3IgICAgdGhlICAgIHByb2Nlc3MncyAgICAgdXNlciAg ICAgSUQNCj4gICAgICAgICAgIChLRVlfUkVRS0VZX0RFRkxfVVNFUl9TRVNTSU9OX0tFWVJJTkcp LiAgVGhpcyBrZXlyaW5nIGlzIGV4cGVjdGVkIHRvDQo+ICAgICAgICAgICBhbHdheXMgZXhpc3Qu DQo+IA0KPiAgICAgICAgICAg4pSM4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA 4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA 4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA 4pSA4pSA4pSA4pSQDQo+ICAgICAgICAgICDilIJGSVhNRSAgICAgICAgICAgICAgICAgICAgICAg ICAgICAgICAgICAgICAgICAgICAgICAgIOKUgg0KPiAgICAgICAgICAg4pSc4pSA4pSA4pSA4pSA 4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA 4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA 4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSkDQo+ICAgICAgICAgICDilIJBcmUg dGhlcmUgY2lyY3Vtc3RhbmNlcyB3aGVyZSAgdGhlICBzZXNzaW9uICBrZXlyaW5nIOKUgg0KPiAg ICAgICAgICAg4pSCZG9lcyBub3QgZXhpc3Q/ICBXaGF0IGFyZSB0aGV5PyAgICAgICAgICAgICAg ICAgICAgICDilIINCj4gICAgICAgICAgIOKUlOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKU gOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKU gOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKU gOKUgOKUgOKUgOKUgOKUgOKUmA0KDQpUaGUgc2Vzc2lvbiBrZXlyaW5nIGRvZXMgbm90IGV4aXN0 IGluIC9zYmluL2luaXQncyBwcm9jZXNzLCBmb3IgZXhhbXBsZSwNCnVubGVzcyB0aGF0IHByb2Nl c3MgY3JlYXRlZCBvbmUuICBJdCdzIGV4aXN0ZW5jZSBvciBub24tZXhpc3RlbmNlIGlzIHRoZW4N CmluaGVyaXRlZCBieSBhbGwgdGhlIHByb2Nlc3NlcyB0aGF0IGFyZSBzdGFydGVkIGZyb20gdGhh dC4gIFVwb24gYSBsb2ctaW4sIFBBTQ0KaXMgZXhwZWN0ZWQgdG8gY3JlYXRlIGEgc2Vzc2lvbiBr ZXlyaW5nLg0KDQo+ICAgICAgICDCtyAgVGhlICAgVUlELXNwZWNpZmljICAga2V5cmluZyAgKEtF WV9SRVFLRVlfREVGTF9VU0VSX0tFWVJJTkcpLiAgIFRoaXMNCj4gICAgICAgICAgIGtleXJpbmcg aXMgYWxzbyBleHBlY3RlZCB0byBhbHdheXMgZXhpc3QuDQo+IA0KPiAgICAgICAgICAg4pSM4pSA 4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA 4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA 4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSQDQo+ICAgICAgICAg ICDilIJGSVhNRSAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAg IOKUgg0KPiAgICAgICAgICAg4pSc4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA 4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA 4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA 4pSA4pSA4pSA4pSkDQo+ICAgICAgICAgICDilIJBcmUgIHRoZXJlICBjaXJjdW1zdGFuY2VzICB3 aGVyZSAgdGhlICAgVUlELXNwZWNpZmljIOKUgg0KPiAgICAgICAgICAg4pSCa2V5cmluZyBkb2Vz IG5vdCBleGlzdD8gIFdoYXQgYXJlIHRoZXk/ICAgICAgICAgICAgICDilIINCj4gICAgICAgICAg IOKUlOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKU gOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKU gOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUmA0KDQpU aGUgdWlkIGtleXJpbmdzIGRvbid0IGV4aXN0IHVudGlsIHNvbWVvbmUgdHJpZXMgdG8gYWNjZXNz IHRoZW0gLSBhdCB3aGljaA0KcG9pbnQgdGhleSdyZSBib3RoIGNyZWF0ZWQuICBXaGVuIHlvdSBs b2cgaW4sIHBhbV9rZXlpbml0IGNyZWF0ZXMgYSBsaW5rIHRvDQp5b3VyIHVzZXIga2V5cmluZyBp biB0aGUgc2Vzc2lvbiBrZXlyaW5nIGl0IGp1c3QgY3JlYXRlZCwgdGhlcmVieSBjcmVhdGluZyB0 aGUNCnVzZXIgYW5kIHVzZXItc2Vzc2lvbiBrZXlyaW5ncy4NCg0KRGF2aWQNCg== --
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

A message that is not in the archive (sent off-list or not yet received): 15546.1482135577-S6HVgzuS8uM4Awkfq6JHfwNdhmdF6hFW@public.gmane.org

Michael Kerrisk (man-pages)

2016-12-19 08:47 UTC #15 lore raw

Re: [PATCH 1/5] request_key.2: add information regarding default keyring

Quoted 10 lines · David Howells

Quoted 8 lines · Michael Kerrisk (man-pages)
Otherwise, if dest_keyring is 0 and a new key is constructed, the new key will be linked to the "default" keyring. More precisely, when the kernel tries to determine to which keyring the newly constructed key should be linked, it tries the following keyrings, beginning with the keyring set via the keyctl(2) KEYCTL_SET_REQKEY_KEYRING command and continuing in the order shown below until it finds the first keyring that exists:

Quoted 5 lines

Quoted 2 lines
· The requestor keyring (KEY_REQKEY_DEFL_REQUESTOR_KEYRING, since
Linux 2.6.29).
This is only available in the /sbin/request-key upcall, where it refers back to the destination keyring of whoever called request_key().

Eugene has sent a longer analysis, which I didn't yet scan thoroughly. But, I feel like I must be missing something obvious. (And unfortunately, my FIXME text was a bit garbled). Here, we're talking about the situation where request_key(2) is called with a destination keyring argument (final argument to the call) that is 0. Does not KEY_REQKEY_DEFL_REQUESTOR_KEYRING then yield "0" as its value, and thus this case is a no-op in the list of keyrings searched?. (Is there something here that I'm missing to do with chained upcalls?)

Quoted 26 lines

Quoted 10 lines
· The session keyring for the process's user ID
(KEY_REQKEY_DEFL_USER_SESSION_KEYRING). This keyring is expected to always exist.
┌─────────────────────────────────────────────────────┐
│FIXME │
├─────────────────────────────────────────────────────┤ │Are there circumstances where the session keyring │
│does not exist? What are they? │
└─────────────────────────────────────────────────────┘
The session keyring does not exist in /sbin/init's process, for example, unless that process created one. It's existence or non-existence is then inherited by all the processes that are started from that. Upon a log-in, PAM is expected to create a session keyring.
Quoted 9 lines
· The UID-specific keyring (KEY_REQKEY_DEFL_USER_KEYRING). This
keyring is also expected to always exist.
┌─────────────────────────────────────────────────────┐
│FIXME │
├─────────────────────────────────────────────────────┤
│Are there circumstances where the UID-specific │
│keyring does not exist? What are they? │
└─────────────────────────────────────────────────────┘

Quoted 2 lines

The uid keyrings don't exist until someone tries to access them - at which point they're both created.

Does "access" here mean attempt to "read ow update" the keyring, or are the UID keyring created only on the first attempt to "update: them?

Cheers,

Michael

Quoted 6 lines

When you log in, pam_keyinit creates a link to
your user keyring in the session keyring it just created, thereby creating the user and user-session keyrings.
David

Signature · 7 lines

Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

A message that is not in the archive (sent off-list or not yet received): f06829ea-1d7c-3f9a-1f4b-e6880aacbdc2-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org

Eugene Syromyatnikov

2016-12-19 09:31 UTC #17 lore raw

Re: [PATCH 1/5] request_key.2: add information regarding default keyring

T24gTW9uLCBEZWMgMTksIDIwMTYgYXQgODo0NyBBTSwgTWljaGFlbCBLZXJyaXNrIChtYW4tcGFn ZXMpDQo8bXRrLm1hbnBhZ2VzQGdtYWlsLmNvbT4gd3JvdGU6DQo+IE9uIDEyLzE5LzIwMTYgMDk6 MTkgQU0sIERhdmlkIEhvd2VsbHMgd3JvdGU6DQo+PiBNaWNoYWVsIEtlcnJpc2sgKG1hbi1wYWdl cykgPG10ay5tYW5wYWdlc0BnbWFpbC5jb20+IHdyb3RlOg0KPj4NCj4+PiAgICAgICAgT3RoZXJ3 aXNlLCAgaWYgIGRlc3Rfa2V5cmluZyBpcyAwIGFuZCBhIG5ldyBrZXkgaXMgY29uc3RydWN0ZWQs IHRoZSBuZXcNCj4+PiAgICAgICAga2V5IHdpbGwgYmUgbGlua2VkIHRvIHRoZSAiZGVmYXVsdCIg a2V5cmluZy4gIE1vcmUgcHJlY2lzZWx5LCB3aGVuICB0aGUNCj4+PiAgICAgICAga2VybmVsICB0 cmllcyAgdG8gIGRldGVybWluZSB0byB3aGljaCBrZXlyaW5nIHRoZSBuZXdseSBjb25zdHJ1Y3Rl ZCBrZXkNCj4+PiAgICAgICAgc2hvdWxkIGJlIGxpbmtlZCwgaXQgdHJpZXMgdGhlIGZvbGxvd2lu ZyBrZXlyaW5ncywgYmVnaW5uaW5nICB3aXRoICB0aGUNCj4+PiAgICAgICAga2V5cmluZyAgc2V0 ICB2aWEgIHRoZSAga2V5Y3RsKDIpIEtFWUNUTF9TRVRfUkVRS0VZX0tFWVJJTkcgY29tbWFuZCBh bmQNCj4+PiAgICAgICAgY29udGludWluZyBpbiB0aGUgb3JkZXIgc2hvd24gYmVsb3cgdW50aWwg aXQgZmluZHMgIHRoZSAgZmlyc3QgIGtleXJpbmcNCj4+PiAgICAgICAgdGhhdCBleGlzdHM6DQo+ Pj4NCj4+PiAgICAgICAgwrcgIFRoZSAgIHJlcXVlc3RvciAga2V5cmluZyAgKEtFWV9SRVFLRVlf REVGTF9SRVFVRVNUT1JfS0VZUklORywgIHNpbmNlDQo+Pj4gICAgICAgICAgIExpbnV4IDIuNi4y OSkuDQo+Pg0KPj4gVGhpcyBpcyBvbmx5IGF2YWlsYWJsZSBpbiB0aGUgL3NiaW4vcmVxdWVzdC1r ZXkgdXBjYWxsLCB3aGVyZSBpdCByZWZlcnMgYmFjaw0KPj4gdG8gdGhlIGRlc3RpbmF0aW9uIGtl eXJpbmcgb2Ygd2hvZXZlciBjYWxsZWQgcmVxdWVzdF9rZXkoKS4NCj4NCj4gRXVnZW5lIGhhcyBz ZW50IGEgbG9uZ2VyIGFuYWx5c2lzLCB3aGljaCBJIGRpZG4ndCB5ZXQgc2NhbiB0aG9yb3VnaGx5 Lg0KPiBCdXQsIEkgZmVlbCBsaWtlIEkgbXVzdCBiZSBtaXNzaW5nIHNvbWV0aGluZyBvYnZpb3Vz LiAoQW5kIHVuZm9ydHVuYXRlbHksIG15DQo+IEZJWE1FIHRleHQgd2FzIGEgYml0IGdhcmJsZWQp LiBIZXJlLCB3ZSdyZSB0YWxraW5nIGFib3V0IHRoZSBzaXR1YXRpb24gd2hlcmUNCj4gcmVxdWVz dF9rZXkoMikgaXMgY2FsbGVkIHdpdGggYSBkZXN0aW5hdGlvbiBrZXlyaW5nIGFyZ3VtZW50IChm aW5hbCBhcmd1bWVudA0KPiB0byB0aGUgY2FsbCkgdGhhdCBpcyAwLiBEb2VzIG5vdCBLRVlfUkVR S0VZX0RFRkxfUkVRVUVTVE9SX0tFWVJJTkcgdGhlbiB5aWVsZA0KPiAiMCIgYXMgaXRzIHZhbHVl LCBhbmQgdGh1cyB0aGlzIGNhc2UgaXMgYSBuby1vcCBpbiB0aGUgbGlzdCBvZiBrZXlyaW5ncyBz ZWFyY2hlZD8uDQo+IChJcyB0aGVyZSBzb21ldGhpbmcgaGVyZSB0aGF0IEknbSBtaXNzaW5nIHRv IGRvIHdpdGggY2hhaW5lZCB1cGNhbGxzPykNCkFmdGVyIHRoZSBzdWNjZXNzZnVsIGtleWN0bChL RVlDVExfQVNTVU1FX0FVVEhPUklUWSwgZGVzdF9rZXlfaWQpIGNhbGwNCih3aGVyZSBkZXN0X2tl eV9pZCBpcyB0aGUga2V5X2lkIHBhc3NlZCB0byB0aGUgdXBjYWxsZWQgcHJvZ3JhbSBpbiB0aGUN CnNlY29uZCBwYXJhbWV0ZXIpLCB0aGUgcmVxdWVzdF9rZXlfYXV0aCBmaWVsZCBvZiB0aGUgY3Jl ZCBzdHJ1Y3R1cmUNCndvdWxkIGJlIHNldCB3aXRoIHRoZSBhcHByb3ByaWF0ZSBhdXRoa2V5LCB3 aGljaCBlbmFibGVzIGVudGVyaW5nIGludG8NCnRoZSBjb25kaXRpb24gYXQgcmVxdWVzdF9rZXku YzoyNzEuIE90aGVyd2lzZSB0aGlzIGNvbmRpdGlvbiB3b3VsZCBiZQ0KcGFzc2VkLg0KDQo+Pj4g ICAgICAgIMK3ICBUaGUgICAgc2Vzc2lvbiAgICBrZXlyaW5nICAgIGZvciAgICB0aGUgICAgcHJv Y2VzcydzICAgICB1c2VyICAgICBJRA0KPj4+ICAgICAgICAgICAoS0VZX1JFUUtFWV9ERUZMX1VT RVJfU0VTU0lPTl9LRVlSSU5HKS4gIFRoaXMga2V5cmluZyBpcyBleHBlY3RlZCB0bw0KPj4+ICAg ICAgICAgICBhbHdheXMgZXhpc3QuDQo+Pj4NCj4+PiAgICAgICAgICAg4pSM4pSA4pSA4pSA4pSA 4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA 4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA 4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSQDQo+Pj4gICAgICAgICAgIOKUgkZJ WE1FICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAg4pSCDQo+ Pj4gICAgICAgICAgIOKUnOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKU gOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKU gOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKU gOKUgOKUpA0KPj4+ICAgICAgICAgICDilIJBcmUgdGhlcmUgY2lyY3Vtc3RhbmNlcyB3aGVyZSAg dGhlICBzZXNzaW9uICBrZXlyaW5nIOKUgg0KPj4+ICAgICAgICAgICDilIJkb2VzIG5vdCBleGlz dD8gIFdoYXQgYXJlIHRoZXk/ICAgICAgICAgICAgICAgICAgICAgIOKUgg0KPj4+ICAgICAgICAg ICDilJTilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDi lIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDi lIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilJgNCj4+ DQo+PiBUaGUgc2Vzc2lvbiBrZXlyaW5nIGRvZXMgbm90IGV4aXN0IGluIC9zYmluL2luaXQncyBw cm9jZXNzLCBmb3IgZXhhbXBsZSwNCj4+IHVubGVzcyB0aGF0IHByb2Nlc3MgY3JlYXRlZCBvbmUu ICBJdCdzIGV4aXN0ZW5jZSBvciBub24tZXhpc3RlbmNlIGlzIHRoZW4NCj4+IGluaGVyaXRlZCBi eSBhbGwgdGhlIHByb2Nlc3NlcyB0aGF0IGFyZSBzdGFydGVkIGZyb20gdGhhdC4gIFVwb24gYSBs b2ctaW4sIFBBTQ0KPj4gaXMgZXhwZWN0ZWQgdG8gY3JlYXRlIGEgc2Vzc2lvbiBrZXlyaW5nLg0K Pj4NCj4+PiAgICAgICAgwrcgIFRoZSAgIFVJRC1zcGVjaWZpYyAgIGtleXJpbmcgIChLRVlfUkVR S0VZX0RFRkxfVVNFUl9LRVlSSU5HKS4gICBUaGlzDQo+Pj4gICAgICAgICAgIGtleXJpbmcgaXMg YWxzbyBleHBlY3RlZCB0byBhbHdheXMgZXhpc3QuDQo+Pj4NCj4+PiAgICAgICAgICAg4pSM4pSA 4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA 4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA 4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSQDQo+Pj4gICAgICAg ICAgIOKUgkZJWE1FICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAg ICAg4pSCDQo+Pj4gICAgICAgICAgIOKUnOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKU gOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKU gOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKU gOKUgOKUgOKUgOKUgOKUpA0KPj4+ICAgICAgICAgICDilIJBcmUgIHRoZXJlICBjaXJjdW1zdGFu Y2VzICB3aGVyZSAgdGhlICAgVUlELXNwZWNpZmljIOKUgg0KPj4+ICAgICAgICAgICDilIJrZXly aW5nIGRvZXMgbm90IGV4aXN0PyAgV2hhdCBhcmUgdGhleT8gICAgICAgICAgICAgIOKUgg0KPj4+ ICAgICAgICAgICDilJTilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDi lIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDi lIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDi lIDilJgNCj4+DQo+PiBUaGUgdWlkIGtleXJpbmdzIGRvbid0IGV4aXN0IHVudGlsIHNvbWVvbmUg dHJpZXMgdG8gYWNjZXNzIHRoZW0gLSBhdCB3aGljaA0KPj4gcG9pbnQgdGhleSdyZSBib3RoIGNy ZWF0ZWQuDQo+DQo+IERvZXMgImFjY2VzcyIgaGVyZSBtZWFuIGF0dGVtcHQgdG8gInJlYWQgb3cg dXBkYXRlIiB0aGUga2V5cmluZywgb3IgYXJlIHRoZQ0KPiBVSUQga2V5cmluZyBjcmVhdGVkIG9u bHkgb24gdGhlIGZpcnN0IGF0dGVtcHQgdG8gInVwZGF0ZTogdGhlbT8NCj4NCj4gQ2hlZXJzLA0K Pg0KPiBNaWNoYWVsDQo+DQo+PiBXaGVuIHlvdSBsb2cgaW4sIHBhbV9rZXlpbml0IGNyZWF0ZXMg YSBsaW5rIHRvDQo+PiB5b3VyIHVzZXIga2V5cmluZyBpbiB0aGUgc2Vzc2lvbiBrZXlyaW5nIGl0 IGp1c3QgY3JlYXRlZCwgdGhlcmVieSBjcmVhdGluZyB0aGUNCj4+IHVzZXIgYW5kIHVzZXItc2Vz c2lvbiBrZXlyaW5ncy4NCj4+DQo+PiBEYXZpZA0KPj4NCj4NCj4NCj4gLS0NCj4gTWljaGFlbCBL ZXJyaXNrDQo+IExpbnV4IG1hbi1wYWdlcyBtYWludGFpbmVyOyBodHRwOi8vd3d3Lmtlcm5lbC5v cmcvZG9jL21hbi1wYWdlcy8NCj4gTGludXgvVU5JWCBTeXN0ZW0gUHJvZ3JhbW1pbmcgVHJhaW5p bmc6IGh0dHA6Ly9tYW43Lm9yZy90cmFpbmluZy8NCg0KDQoNCi0tIA0KRXVnZW5lIFN5cm9teWF0 bmlrb3YNCm1haWx0bzpldmdzeXJAZ21haWwuY29tDQp4bXBwOmVzeXJAamFiYmVyLntydXxvcmd9 DQo=
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

David Howells

2016-12-20 09:14 UTC #18 lore raw

Re: [PATCH 1/5] request_key.2: add information regarding default keyring

In reply to a message not in the archive

Quoted 2 lines · Michael Kerrisk (man-pages)

Here, we're talking about the situation where request_key(2) is called with a destination keyring argument (final argument to the call) that is 0.

Yep.

Quoted 2 lines

Does not KEY_REQKEY_DEFL_REQUESTOR_KEYRING then yield "0" as its value, and thus this case is a no-op in the list of keyrings searched?.

No. construct_key_and_link() calls construct_get_dest_keyring() to get the destination keyring (which includes handling the defaults) and then calls construct_key() which passes this default to request_key_auth_new().

However, if there is no authorisation key around, KEY_REQKEY_DEFL_REQUESTOR_KEYRING defaults to the same as KEY_REQKEY_DEFL_THREAD_KEYRING.

Quoted 1 line

(Is there something here that I'm missing to do with chained upcalls?)

For chained upcalls, consider the following sequence:

(1) A process does request_key(). This selects a destination keyring which it will paste into the auth key.

(2) request_key() upcalls and passes the auth key to /sbin/request-key which assumes its authority and exec's an appropriate handler. The default keyring setting is KEY_REQKEY_DEFL_DEFAULT, inherited from init_creds.

(3) The handler process calls request_key() without specifying a destination keyring and without changing the default. This upcalls and selects the destination keyring from (1) and pastes it into the auth key.

(4) request_key() upcalls ...

Quoted 5 lines

Quoted 2 lines
The uid keyrings don't exist until someone tries to access them - at which point they're both created.
Does "access" here mean attempt to "read ow update" the keyring, or are the UID keyring created only on the first attempt to "update: them?

It means lookup_user_key() was passed KEY_LOOKUP_CREATE. So:

add_key() - destination keyring request_key() - destination keyring KEYCTL_GET_KEYRING_ID - if create arg is true KEYCTL_CLEAR
KEYCTL_LINK - both args
KEYCTL_SEARCH - destination keyring KEYCTL_CHOWN
KEYCTL_SETPERM
KEYCTL_SET_TIMEOUT
KEYCTL_INSTANTIATE - destination keyring KEYCTL_INSTANTIATE_IOV - destination keyring KEYCTL_NEGATE - destination keyring KEYCTL_REJECT - destination keyring KEYCTL_GET_PERSISTENT - destination keyring

will all create a keyring under some circumstances. Whereas the rest, such as KEYCTL_GET_SECURITY, KEYCTL_READ and KEYCTL_REVOKE, won't.

David
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

Eugene Syromyatnikov

2016-11-21 20:59 UTC #19 lore raw

PATCH 2/5 requesT_key.2: add information regarding minimal kernel version for key instantiation on request

In reply to a message not in the archive

---
 man2/request_key.2 | 2 ++
 1 file changed, 2 insertions(+)

man2/request_key.2 +2 -0

index e29ca06..e46dd61 100644
@@ -364,6 +364,8 @@ No matching key was found.
 Insufficient memory to create a key.
 .SH VERSIONS
 This system call first appeared in Linux 2.6.10.
+.\" 3e30148c3d524a9c1c63ca28261bc24c457eb07a
+The ability to instantiate keys upon request has been added in Linux 2.6.13.
 .SH CONFORMING TO
 This system call is a nonstandard Linux extension.
 .SH NOTES

Signature · 6 lines

2.10.2

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Michael Kerrisk (man-pages)

Applied

2016-11-21 22:00 UTC #20 lore raw

Re: [PATCH 2/5] requesT_key.2: add information regarding minimal kernel version for key instantiation on request

Hello Eugene,

Quoted 3 lines · Eugene Syromyatnikov

---
 man2/request_key.2 | 2 ++
 1 file changed, 2 insertions(+)

Applied. Thank you!

Cheers,

Michael

Quoted 14 lines

man2/request_key.2 +2 -0

index e29ca06..e46dd61 100644
@@ -364,6 +364,8 @@ No matching key was found.
 Insufficient memory to create a key.
 .SH VERSIONS
 This system call first appeared in Linux 2.6.10.
+.\" 3e30148c3d524a9c1c63ca28261bc24c457eb07a
+The ability to instantiate keys upon request has been added in Linux 2.6.13.
 .SH CONFORMING TO
 This system call is a nonstandard Linux extension.
 .SH NOTES

Signature · 7 lines

Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Eugene Syromyatnikov

2016-11-21 20:59 UTC #21 lore raw

PATCH 3/5 request_key.2: whitespace fix

In reply to a message not in the archive

---
 man2/request_key.2 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

man2/request_key.2 +1 -1

index e46dd61..63e8206 100644
@@ -169,7 +169,7 @@ is:
 .RS
 .IP (1) 4
 the context in which the key U should be instantiated and secured, and
-.IP (2) 
+.IP (2)
 the context from which associated key requests may be satisfied.
 .RE
 .IP

Signature · 6 lines

2.10.2

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Michael Kerrisk (man-pages)

Applied

2016-11-21 21:59 UTC #22 lore raw

Re: [PATCH 3/5] request_key.2: whitespace fix

Hi Eugene,

Quoted 3 lines · Eugene Syromyatnikov

---
 man2/request_key.2 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

Applied. Thanks!

Cheers,

Michael

Quoted 15 lines

man2/request_key.2 +1 -1

index e46dd61..63e8206 100644
@@ -169,7 +169,7 @@ is:
 .RS
 .IP (1) 4
 the context in which the key U should be instantiated and secured, and
-.IP (2) 
+.IP (2)
 the context from which associated key requests may be satisfied.
 .RE
 .IP

Signature · 7 lines

Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Eugene Syromyatnikov

2016-11-21 21:00 UTC #23 lore raw

PATCH 4/5 request_key.2: wfix

In reply to a message not in the archive

---
 man2/request_key.2 | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

man2/request_key.2 +1 -2

index 63e8206..1a3af3f 100644
@@ -198,8 +198,7 @@ in the requesting program.
 The payload of the key is taken from the data specified in
 .IR callout_info .
 .IP *
-Internally, the kernel also records a record of the PID of the process
-that called
+Internally, the kernel also records the PID of the process that called
 .BR request_key (2).
 .RE
 .IP c)

Signature · 6 lines

2.10.2

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Michael Kerrisk (man-pages)

Applied

2016-11-21 21:59 UTC #24 lore raw

Re: [PATCH 4/5] request_key.2: wfix

Hi Eugene

On 11/21/2016 10:00 PM, Eugene Syromyatnikov wrote:> ---

Quoted 2 lines

 man2/request_key.2 | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

Applied. Thanks!

Cheers,

Michael

Quoted 15 lines

man2/request_key.2 +1 -2

index 63e8206..1a3af3f 100644
@@ -198,8 +198,7 @@ in the requesting program.
 The payload of the key is taken from the data specified in
 .IR callout_info .
 .IP *
-Internally, the kernel also records a record of the PID of the process
-that called
+Internally, the kernel also records the PID of the process that called
 .BR request_key (2).
 .RE
 .IP c)

Signature · 7 lines

Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Eugene Syromyatnikov

2016-11-21 21:00 UTC #25 lore raw

PATCH 5/5 request_key.2: additional error information

In reply to a message not in the archive

---
 man2/request_key.2 | 10 ++++++++++
 1 file changed, 10 insertions(+)

man2/request_key.2 +10 -0

index 1a3af3f..936989a 100644
@@ -331,6 +331,11 @@ The keyring wasn't available for modification by the user.
 The key quota for this user would be exceeded by creating this key or linking
 it to the keyring.
 .TP
+.B EFAULT
+(Part of)
+.IR type ", " description " or " callout_info
+points outside process' accessible address space.
+.TP
 .B EINTR
 The request was interrupted by a signal; see
 .BR signal (7).

@@ -361,6 +366,11 @@ No matching key was found.
 .TP
 .B ENOMEM
 Insufficient memory to create a key.
+.TP
+.B EPERM
+The
+.I type
+started from dot.
 .SH VERSIONS
 This system call first appeared in Linux 2.6.10.
 .\" 3e30148c3d524a9c1c63ca28261bc24c457eb07a

Signature · 6 lines

2.10.2

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Michael Kerrisk (man-pages)

Applied

2016-11-21 22:00 UTC #26 lore raw

Re: [PATCH 5/5] request_key.2: additional error information

Quoted 3 lines · Eugene Syromyatnikov

---
 man2/request_key.2 | 10 ++++++++++
 1 file changed, 10 insertions(+)

Hello Eugene,

Applied. Thank you!

Cheers,

Michael

Quoted 29 lines

man2/request_key.2 +10 -0

index 1a3af3f..936989a 100644
@@ -331,6 +331,11 @@ The keyring wasn't available for modification by the user.
 The key quota for this user would be exceeded by creating this key or linking
 it to the keyring.
 .TP
+.B EFAULT
+(Part of)
+.IR type ", " description " or " callout_info
+points outside process' accessible address space.
+.TP
 .B EINTR
 The request was interrupted by a signal; see
 .BR signal (7).

@@ -361,6 +366,11 @@ No matching key was found.
 .TP
 .B ENOMEM
 Insufficient memory to create a key.
+.TP
+.B EPERM
+The
+.I type
+started from dot.
 .SH VERSIONS
 This system call first appeared in Linux 2.6.10.
 .\" 3e30148c3d524a9c1c63ca28261bc24c457eb07a

Signature · 7 lines

Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Michael Kerrisk (man-pages)

author

2016-12-14 14:23 UTC #27 lore raw

In reply to Michael Kerrisk (man-pages)

Hi David,

Might you also have a chance to take a look at this page?

Cheers,

Michael

Quoted 344 lines · Michael Kerrisk (man-pages)

Hi David (and anyone else with an interest to review)
Triggered by Eugene Syromyatnikov's recent input for the keyctl(2) man page, I've been doing a fair bit of work on improving the key management syscall man pages, and wonder if I could ask you for some review assistance?
First off, below, I've pasted the current draft of the request_key(2) page, which has seen quite a a lot of changes (increasing from around 100 rendered lines to nearly 300). Could you take a look (and also take a look at the outstanding FIXME)? (The page source file is attached, in case you want to see all the formatting.)
Thanks,
Michael
====
NAME
request_key - request a key from the kernel's key management facility
SYNOPSIS
#include <sys/types.h>
#include <keyutils.h>
key_serial_t request_key(const char *type, const char *description,
const char *callout_info, key_serial_t dest_keyring);
No glibc wrapper is provided for this system call; see NOTES.
DESCRIPTION
request_key() attempts to find a key of the given type with a description (name) that matches the specified description. If such a key could not be found, then the key is optionally cre‐
ated. If the key is found or created, request_key() attaches
it to the keyring whose ID is specified in dest_keyring and returns the key's serial number.
┌─────────────────────────────────────────────────────┐
│FIXME │
├─────────────────────────────────────────────────────┤ │Is 'keyring' allowed to be 0? Reading the source, it │ │appears so. In this case, by default, the key is │
│assigned to the session keyring. But, the │
│KEYCTL_SET_REQKEY_KEYRING also seems to have an │
│influence here. What are the details here? │
│ │
└─────────────────────────────────────────────────────┘
request_key() first recursively searches for a matching key in
all of the keyrings attached to the calling process. The
keyrings are searched in the order: thread-specific keyring, process-specific keyring, and then session keyring.
If request_key() is called from a program invoked by
request_key() on behalf of some other process to generate a key, then the keyrings of that other process will be searched next, using that other process's user ID, group ID, supplemen‐ tary group IDs, and security context to determine access.
The search of the keyring tree is breadth-first: the keys in each keyring searched are checked for a match before any child keyrings are recursed into. Only keys for which the caller has search permission be found, and only keyrings for which the caller has search permission may be searched.
If the key is not found and callout is NULL, then the call fails with the error ENOKEY.
If the key is not found and callout is not NULL, then the ker‐ nel attempts to invoke a user-space program to instantiate the key. The details are given below.
The dest_keyring serial number may be that of a valid keyring for which the caller has write permission, or it may be one of the following special keyring IDs:
KEY_SPEC_THREAD_KEYRING
This specifies the caller's thread-specific keyring (thread-keyring(7)).
KEY_SPEC_PROCESS_KEYRING
This specifies the caller's process-specific keyring (process-keyring(7)).
KEY_SPEC_SESSION_KEYRING
This specifies the caller's session-specific keyring (session-keyring(7)).
KEY_SPEC_USER_KEYRING
This specifies the caller's UID-specific keyring (user- keyring(7)).
KEY_SPEC_USER_SESSION_KEYRING
This specifies the caller's UID-session keyring (user- session-keyring(7)).
Requesting user-space instantiation of a key
If the kernel cannot find a key matching type and description, and callout is not NULL, then the kernel attempts to invoke a user-space program to instantiate a key with the given type and description. In this case, the following steps are performed:
a) The kernel creates an uninstantiated key, U, with the requested type and description.
b) The kernel creates an authorization key, V, that refers to the key U and records the facts that the caller of request_key(2) is:
(1) the context in which the key U should be instantiated and secured, and
(2) the context from which associated key requests may be satisfied.
The authorization key is constructed as follows:
* The key type is ".request_key_auth".
* The key's UID and GID are the same as the corresponding filesystem IDs of the requesting process.
* The key grants view, read, and search permissions to the key possessor as well as view permission for the key user.
* The description (name) of the key is the hexadecimal string representing the ID of the key that is to be instantiated in the requesting program.
* The payload of the key is taken from the data specified in callout_info.
* Internally, the kernel also records a record of the PID of the process that called request_key(2).
c) The kernel creates a process that executes a user-space service such as request-key(8) with a new session keyring that contains a link to the authorization key, V.
This program is supplied with the following command-line arguments:
[0] The string "/sbin/request-key".
[1] The string "create" (indicating that a key is to be created).
[2] The ID of the key that is to be instantiated.
[3] The filesystem UID of the caller of request_key().
[4] The filesystem GID of the caller of request_key().
[5] The ID of the thread keyring of the caller of
request_key(). This may be zero if that keyring hasn't been created.
[6] The ID of the process keyring of the caller of request_key(). This may be zero if that keyring hasn't been created.
[7] The ID of the session keyring of the caller of request_key().
Note: each of the command-line arguments that is a key ID is encoded in decimal (unlike the key IDs shown in /proc/keys, which are shown as hexadecimal values).
d) The program spawned in the previous step:
* Assumes the authority to instantiate the key U using the keyctl(2) KEYCTL_ASSUME_AUTHORITY operation (typically via the keyctl_assume_authority(3) function).
* Obtains the callout data from the payload of the autho‐ rization key V (using the keyctl(2) KEYCTL_READ opera‐ tion (or, more commonly, the keyctl_read(3) function) with a key ID value of KEY_SPEC_REQKEY_AUTH_KEY).
* Instantiates the key (or execs another program that per‐ forms that task), specifying the payload and destination
keyring. (The destination keyring that the requestor
specified when calling request_key() can be accessed using the special key ID KEY_SPEC_REQUESTOR_KEYRING.)
Instantiation is performed using the keyctl(2)
KEYCTL_INSTANTIATE operation (or, more commonly, the
keyctl_instantiate(3) function). At this point, the
request_key(2) call completes, and the requesting pro‐ gram can continue execution.
If these steps are unsuccessful, then an ENOKEY error will be returned to the caller of request_key() and a temporary nega‐ tive key will be installed in the keyring specified by
dest_keyring. This will expire after a few seconds, but will
cause subsequent calls to request_key() to fail until it does. The purpose of this negatively instantiated key is to prevent (possibly different) processes making repeated requests (that require expensive request-key(8) upcalls) for a key that can't (at the moment) be positively instantiated.
Once the key has been instantiated, the authorization key (KEY_SPEC_REQKEY_AUTH_KEY) is revoked, and the destination keyring (KEY_SPEC_REQUESTOR_KEYRING) is no longer accessible from the request-key(8) program.
If a key is created, then—regardless of whether it is a valid key or a negative key—it will displace any other key with the same type and description from the keyring specified in dest_keyring.
RETURN VALUE
On success, request_key() returns the serial number of the key it found or caused to be created. On error, -1 is returned and errno is set to indicate the cause of the error.
ERRORS
EACCES The keyring wasn't available for modification by the
user.
EDQUOT The key quota for this user would be exceeded by creat‐
ing this key or linking it to the keyring.
EINTR The request was interrupted by a signal; see signal(7).
EINVAL The size of the string (including the terminating null
byte) specified in type or description exceeded the limit (32 bytes and 4096 bytes respectively).
EINVAL The size of the string (including the terminating null
byte) specified in callout_info exceeded the system page size.
EKEYEXPIRED
An expired key was found, but no replacement could be obtained.
EKEYREJECTED
The attempt to generate a new key was rejected.
EKEYREVOKED
A revoked key was found, but no replacement could be obtained.
ENOKEY No matching key was found.
ENOMEM Insufficient memory to create a key.
VERSIONS
This system call first appeared in Linux 2.6.10.
CONFORMING TO
This system call is a nonstandard Linux extension.
NOTES
No wrapper for this system call is provided in glibc. A wrap‐ per is provided in the libkeyutils package. When employing the wrapper in that library, link with -lkeyutils.
EXAMPLE
The program below demonstrates the use of request_key(). The
type, description, and callout_info arguments for the system call are taken from the values supplied in the command line
arguments. The call specifies the session keyring as the tar‐
get keyring.
In order to demonstrate this program, we first create a suit‐ able entry in the file /etc/request-key.conf.
$ sudo sh
# echo 'create user mtk:* * /bin/keyctl instantiate %k %c %S' \
> /etc/request-keys.conf
# exit
This entry specifies that when a new "user" key with the prefix "mtk:" must be instantiated, that task should be performed via the keyctl(1) command's instantiate operation. (The program could The arguments supplied to the instantiate operation are:
the ID of the uninstantiated key (%k); the callout data sup‐ plied to the request_key() call (%c); and the session keyring (%S) of the requestor (i.e., the caller of request)key()). i(See request-key.conf(5) for details of these % specifiers.)
Then we run the program and check the contents of /proc/keys to verify that the requested kay has been instantiated:
$ ./a.out user mtk:key1 "Payload data"
$ grep '2dddaf50' /proc/keys
2dddaf50 I--Q--- 1 perm 3f010000 1000 1000 user mtk:key1: 12
   Program source
       The program below
       #include <sys/types.h>
       #include <keyutils.h>
       #include <stdio.h>
       #include <stdlib.h>
       #include <string.h>
       #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \
                               } while (0)

       int
       main(int argc, char *argv[])
       {
           key_serial_t key;

           if (argc != 4) {
               fprintf(stderr, "Usage: %s type description callout-data\n",
                       argv[0]);
               exit(EXIT_FAILURE);
           }

           key = request_key(argv[1], argv[2], argv[3],
                             KEY_SPEC_SESSION_KEYRING);
           if (key == -1)
               errExit("request_key");

           printf("Key ID is %lx\n", (long) key);

           exit(EXIT_SUCCESS);
       }
SEE ALSO
       keyctl(1), add_key(2), keyctl(2), keyctl(3), keyrings(7),
       keyutils(7), capabilities(7), persistent-keyring(7),
       process-keyring(7), session-keyring(7), thread-keyring(7),
       user-keyring(7), user-session-keyring(7), request-key(8)

       The kernel source files Documentation/security/keys.txt and
       Documentation/security/keys-request-key.txt.
Linux 2016-10-08 REQUEST_KEY(2)
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Signature · 3 lines

Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

David Howells

2016-12-15 10:10 UTC #28 lore raw

Quoted 5 lines · Michael Kerrisk (man-pages)

Quoted 5 lines

       │Is 'keyring' allowed to be 0? Reading the source, it │
       │appears so.  In this case, by default,  the  key  is │
       │assigned   to   the   session   keyring.   But,  the │
       │KEYCTL_SET_REQKEY_KEYRING  also  seems  to  have  an │
       │influence here.  What are the details here?          │

Yes, the destination keyring can be 0. If you don't specify a destination keyring, then:

(1) If the key is found to already exist, the serial number is returned, but no extra link is made.

(2) If an error occurs other than "this key doesn't exist", then you'll just get the error.

(3) If we have to construct a new key, this will be attached to the default keyring (as there's no destination keyring to attach to).

Quoted 2 lines

           # echo 'create user mtk:* *   /bin/keyctl instantiate %k %c %S' \
                     > /etc/request-keys.conf

There's a /etc/request-keys.d/ directory now.

David
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

Michael Kerrisk (man-pages)

author

2016-12-17 10:34 UTC #29 lore raw

Hello David,

Quoted 11 lines · David Howells

Quoted 5 lines · Michael Kerrisk (man-pages)

Quoted 5 lines

       │Is 'keyring' allowed to be 0? Reading the source, it │
       │appears so.  In this case, by default,  the  key  is │
       │assigned   to   the   session   keyring.   But,  the │
       │KEYCTL_SET_REQKEY_KEYRING  also  seems  to  have  an │
       │influence here.  What are the details here?          │

Yes, the destination keyring can be 0. If you don't specify a destination keyring, then:

Quoted 8 lines

(1) If the key is found to already exist, the serial number is returned, but no extra link is made.
(2) If an error occurs other than "this key doesn't exist", then you'll just get the error.
(3) If we have to construct a new key, this will be attached to the default keyring (as there's no destination keyring to attach to).

Okay. Please take a look at the revised text that I'll send out after applying Eugene's patch. (Mail in a few minutes.)

Quoted 4 lines

Quoted 2 lines
Quoted 2 lines
           # echo 'create user mtk:* *   /bin/keyctl instantiate %k %c %S' \
                     > /etc/request-keys.conf
There's a /etc/request-keys.d/ directory now.

Yes, I'm aware. Did you mean I should fix something on this page?

Cheers,

Michael

Signature · 7 lines

Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

David Howells

2016-12-19 08:13 UTC #30 lore raw

Quoted 6 lines · Michael Kerrisk (man-pages)

Quoted 4 lines
Quoted 2 lines
Quoted 2 lines
           # echo 'create user mtk:* *   /bin/keyctl instantiate %k %c %S' \
                     > /etc/request-keys.conf
There's a /etc/request-keys.d/ directory now.
Yes, I'm aware. Did you mean I should fix something on this page?

I mean you probably shouldn't modify /etc/request-keys.conf, but rather put something in the .d dir.

David
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html