Documentation/security/keys/request-key.rst

Source file repositories/reference/linux-study-clean/Documentation/security/keys/request-key.rst

File Facts

System
Linux kernel
Corpus path
Documentation/security/keys/request-key.rst
Extension
.rst
Size
8068 bytes
Lines
208
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

===================
Key Request Service
===================

The key request service is part of the key retention service (refer to
Documentation/security/keys/core.rst).  This document explains more fully how
the requesting algorithm works.

The process starts by either the kernel requesting a service by calling
``request_key*()``::

	struct key *request_key(const struct key_type *type,
				const char *description,
				const char *callout_info);

or::

	struct key *request_key_tag(const struct key_type *type,
				    const char *description,
				    const struct key_tag *domain_tag,
				    const char *callout_info);

or::

	struct key *request_key_with_auxdata(const struct key_type *type,
					     const char *description,
					     const struct key_tag *domain_tag,
					     const char *callout_info,
					     size_t callout_len,
					     void *aux);

or::

	struct key *request_key_rcu(const struct key_type *type,
				    const char *description,
				    const struct key_tag *domain_tag);

Or by userspace invoking the request_key system call::

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

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_tag() call is like the in-kernel request_key(), except that it
also takes a domain tag that allows keys to be separated by namespace and
killed off as a group.

The request_key_with_auxdata() calls is like the request_key_tag() 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 request_key_rcu() call is like the request_key_tag() 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
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.

Annotation

Implementation Notes