Documentation/security/keys/core.rst

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

File Facts

System
Linux kernel
Corpus path
Documentation/security/keys/core.rst
Extension
.rst
Size
72604 bytes
Lines
1850
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

struct key_notification {
		struct watch_notification watch;
		__u32	key_id;
		__u32	aux;
	};

     In this, watch::type will be "WATCH_TYPE_KEY_NOTIFY" and subtype will be
     one of::

	NOTIFY_KEY_INSTANTIATED
	NOTIFY_KEY_UPDATED
	NOTIFY_KEY_LINKED
	NOTIFY_KEY_UNLINKED
	NOTIFY_KEY_CLEARED
	NOTIFY_KEY_REVOKED
	NOTIFY_KEY_INVALIDATED
	NOTIFY_KEY_SETATTR

     Where these indicate a key being instantiated/rejected, updated, a link
     being made in a keyring, a link being removed from a keyring, a keyring
     being cleared, a key being revoked, a key being invalidated or a key
     having one of its attributes changed (user, group, perm, timeout,
     restriction).

     If a watched key is deleted, a basic watch_notification will be issued
     with "type" set to WATCH_TYPE_META and "subtype" set to
     watch_meta_removal_notification.  The watchpoint ID will be set in the
     "info" field.

     This needs to be configured by enabling:

	"Provide key/keyring change notifications" (KEY_NOTIFICATIONS)


Kernel Services
===============

The kernel services for key management are fairly simple to deal with. They can
be broken down into two areas: keys and key types.

Dealing with keys is fairly straightforward. Firstly, the kernel service
registers its type, then it searches for a key of that type. It should retain
the key as long as it has need of it, and then it should release it. For a
filesystem or device file, a search would probably be performed during the open
call, and the key released upon close. How to deal with conflicting keys due to
two different users opening the same file is left to the filesystem author to
solve.

To access the key manager, the following header must be #included::

	<linux/key.h>

Specific key types should have a header file under include/keys/ that should be
used to access that type.  For keys of type "user", for example, that would be::

	<keys/user-type.h>

Note that there are two different types of pointers to keys that may be
encountered:

  *  struct key *

     This simply points to the key structure itself. Key structures will be at
     least four-byte aligned.

  *  key_ref_t

     This is equivalent to a ``struct key *``, but the least significant bit is set
     if the caller "possesses" the key. By "possession" it is meant that the
     calling processes has a searchable link to the key from one of its

Annotation

Implementation Notes