Merge tag 'keys-request-20190626' of...

     /sbin/request-key will be invoked in an attempt to obtain a key. The

     callout_info string will be passed as an argument to the program.

     To link a key into the destination keyring the key must grant link

     permission on the key to the caller and the keyring must grant write

     permission.

     See also Documentation/security/keys/request-key.rst.

    is a blob of length callout_len, if given (the length may be 0).

 *  A key can be requested asynchronously by calling one of::

	struct key *request_key_async(const struct key_type *type,

				      const char *description,

				      const void *callout_info,

				      size_t callout_len);

    or::

	struct key *request_key_async_with_auxdata(const struct key_type *type,

						   const char *description,

						   const char *callout_info,

					     	   size_t callout_len,

					     	   void *aux);

    which are asynchronous equivalents of request_key() and

    request_key_with_auxdata() respectively.

    These two functions return with the key potentially still under

    construction.  To wait for construction completion, the following should be

    called::

	int wait_for_key_construction(struct key *key, bool intr);

 *  To search for a key under RCU conditions, call::

    The function will wait for the key to finish being constructed and then

    invokes key_validate() to return an appropriate value to indicate the state

    of the key (0 indicates the key is usable).

	struct key *request_key_rcu(const struct key_type *type,

				    const char *description);

    If intr is true, then the wait can be interrupted by a signal, in which

    case error ERESTARTSYS will be returned.

    which is similar to request_key() except that it does not check for keys

    that are under construction and it will not call out to userspace to

    construct a key if it can't find a match.

 *  When it is no longer required, the key should be released using::

or::

	struct key *request_key_async(const struct key_type *type,

				      const char *description,

				      const char *callout_info,

				      size_t callout_len);

or::

	struct key *request_key_async_with_auxdata(const struct key_type *type,

						   const char *description,

						   const char *callout_info,

					     	   size_t callout_len,

						   void *aux);

	struct key *request_key_rcu(const struct key_type *type,

				    const char *description);

Or by userspace invoking the request_key system call::

destroyed.  The kernel interface returns a pointer directly to the key, and

it's up to the caller to destroy the key.

The request_key*_with_auxdata() calls are like the in-kernel request_key*()

calls, except that they permit auxiliary data to be passed to the upcaller (the

The request_key_with_auxdata() calls is like the in-kernel request_key() call,

except that they permit auxiliary data to be passed to the upcaller (the

default is NULL).  This is only useful for those key types that define their

own upcall mechanism rather than using /sbin/request-key.

The two async in-kernel calls may return keys that are still in the process of

being constructed.  The two non-async ones will wait for construction to

complete first.

The request_key_rcu() call is like the in-kernel request_key() call, except

that it doesn't check for keys that are under construction and doesn't attempt

to construct missing keys.

The userspace interface links the key to a keyring associated with the process

to prevent the key from going away, and returns the serial number of the key to

A search of any particular keyring proceeds in the following fashion:

  1) When the key management code searches for a key (keyring_search_aux) it

  1) When the key management code searches for a key (keyring_search_rcu) it

     firstly calls key_permission(SEARCH) on the keyring it's starting with,

     if this denies permission, it doesn't search further.

use it.  Any error from a previous match attempt is discarded and the key is

returned.

When request_key() is invoked, if CONFIG_KEYS_REQUEST_CACHE=y, a per-task

one-key cache is first checked for a match.

When search_process_keyrings() is invoked, it performs the following searches

until one succeeds:

      c) The calling process's session keyring is searched.

The moment one succeeds, all pending errors are discarded and the found key is

returned.

returned.  If CONFIG_KEYS_REQUEST_CACHE=y, then that key is placed in the

per-task cache, displacing the previous key.  The cache is cleared on exit or

just prior to resumption of userspace.

Only if all these fail does the whole thing fail with the highest priority

error.  Note that several errors may have come from LSM.

 * Authorisation record for request_key().

 */

struct request_key_auth {

	struct rcu_head		rcu;

	struct key		*target_key;

	struct key		*dest_keyring;

	const struct cred	*cred;

			       const char *description,

			       const char *callout_info);

extern struct key *request_key_with_auxdata(struct key_type *type,

					    const char *description,

					    const void *callout_info,

					    size_t callout_len,

					    void *aux);

extern struct key *request_key_async(struct key_type *type,

				     const char *description,

				     const void *callout_info,

				     size_t callout_len);

extern struct key *request_key_rcu(struct key_type *type,

				   const char *description);

extern struct key *request_key_async_with_auxdata(struct key_type *type,

extern struct key *request_key_with_auxdata(struct key_type *type,

					    const char *description,

					    const void *callout_info,

					    size_t callout_len,

	/* Effective (overridable) subjective task credentials (COW): */

	const struct cred __rcu		*cred;

#ifdef CONFIG_KEYS

	/* Cached requested key. */

	struct key			*cached_requested_key;

#endif

	/*

	 * executable name, excluding path.

	 *