[PATCH] Keys: Allow in-kernel key requestor to pass auxiliary data to upcaller

			      ===================

The key request service is part of the key retention service (refer to

Documentation/keys.txt). This document explains more fully how that the

requesting algorithm works.

Documentation/keys.txt).  This document explains more fully how the requesting

algorithm works.

The process starts by either the kernel requesting a service by calling

request_key():

request_key*():

	struct key *request_key(const struct key_type *type,

				const char *description,

				const char *callout_string);

or:

	struct key *request_key_with_auxdata(const struct key_type *type,

					     const char *description,

					     const char *callout_string,

					     void *aux);

Or by userspace invoking the request_key system call:

	key_serial_t request_key(const char *type,

				 const char *callout_info,

				 key_serial_t dest_keyring);

The main difference between the two access points is that the in-kernel

interface does not need to link the key to a keyring to prevent it from being

immediately destroyed. The kernel interface returns a pointer directly to the

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

The main difference between the access points is that the in-kernel interface

does not need to link the key to a keyring to prevent it from being immediately

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() call is like the in-kernel request_key() call,

except that it permits 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 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

the caller.

The following example assumes that the key types involved don't define their

own upcall mechanisms.  If they do, then those should be substituted for the

forking and execution of /sbin/request-key.

===========

THE PROCESS

===========

     interface].

 (2) request_key() searches the process's subscribed keyrings to see if there's

     a suitable key there. If there is, it returns the key. If there isn't, and

     callout_info is not set, an error is returned. Otherwise the process

     a suitable key there.  If there is, it returns the key.  If there isn't,

     and callout_info is not set, an error is returned.  Otherwise the process

     proceeds to the next step.

 (3) request_key() sees that A doesn't have the desired key yet, so it creates

(10) The program then exits 0 and request_key() deletes key V and returns key

     U to the caller.

This also extends further. If key W (step 7 above) didn't exist, key W would be

created uninstantiated, another auth key (X) would be created (as per step 3)

and another copy of /sbin/request-key spawned (as per step 4); but the context

specified by auth key X will still be process A, as it was in auth key V.

This also extends further.  If key W (step 7 above) didn't exist, key W would

be created uninstantiated, another auth key (X) would be created (as per step

3) and another copy of /sbin/request-key spawned (as per step 4); but the

context specified by auth key X will still be process A, as it was in auth key

V.

This is because process A's keyrings can't simply be attached to

/sbin/request-key at the appropriate places because (a) execve will discard two

    See also Documentation/keys-request-key.txt.

(*) To search for a key, passing auxiliary data to the upcaller, call:

	struct key *request_key_with_auxdata(const struct key_type *type,

					     const char *description,

					     const char *callout_string,

					     void *aux);

    This is identical to request_key(), except that the auxiliary data is

    passed to the key_type->request_key() op if it exists.

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

	void key_put(struct key *key);

     as might happen when the userspace buffer is accessed.

 (*) int (*request_key)(struct key *key, struct key *authkey, const char *op,

			void *aux);

     This method is optional.  If provided, request_key() and

     request_key_with_auxdata() will invoke this function rather than

     upcalling to /sbin/request-key to operate upon a key of this type.

     The aux parameter is as passed to request_key_with_auxdata() or is NULL

     otherwise.  Also passed are the key to be operated upon, the

     authorisation key for this operation and the operation type (currently

     only "create").

     This function should return only when the upcall is complete.  Upon return

     the authorisation key will be revoked, and the target key will be

     negatively instantiated if it is still uninstantiated.  The error will be

     returned to the caller of request_key*().

============================

REQUEST-KEY CALLBACK SERVICE

============================

/*

 * kernel managed key type definition

 */

typedef int (*request_key_actor_t)(struct key *key, struct key *authkey, const char *op);

typedef int (*request_key_actor_t)(struct key *key, struct key *authkey,

				   const char *op, void *aux);

struct key_type {

	/* name of the type */

			       const char *description,

			       const char *callout_info);

extern struct key *request_key_with_auxdata(struct key_type *type,

					    const char *description,

					    const char *callout_info,

					    void *aux);

extern int key_validate(struct key *key);

extern key_ref_t key_create_or_update(key_ref_t keyring,

extern struct key *request_key_and_link(struct key_type *type,

					const char *description,

					const char *callout_info,

					void *aux,

					struct key *dest_keyring,

					unsigned long flags);

	}

	/* do the search */

	key = request_key_and_link(ktype, description, callout_info,

	key = request_key_and_link(ktype, description, callout_info, NULL,

				   key_ref_to_ptr(dest_ref),

				   KEY_ALLOC_IN_QUOTA);

	if (IS_ERR(key)) {