Documentation/crypto/asymmetric-keys.rst

Source file repositories/reference/linux-study-clean/Documentation/crypto/asymmetric-keys.rst

File Facts

System
Linux kernel
Corpus path
Documentation/crypto/asymmetric-keys.rst
Extension
.rst
Size
16306 bytes
Lines
425
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 public_key_signature {
		u8 *digest;
		u8 digest_size;
		enum pkey_hash_algo pkey_hash_algo : 8;
		u8 nr_mpi;
		union {
			MPI mpi[2];
			...
		};
	};

The algorithm used must be noted in sig->pkey_hash_algo, and all the MPIs that
make up the actual signature must be stored in sig->mpi[] and the count of MPIs
placed in sig->nr_mpi.

In addition, the data must have been digested by the caller and the resulting
hash must be pointed to by sig->digest and the size of the hash be placed in
sig->digest_size.

The function will return 0 upon success or -EKEYREJECTED if the signature
doesn't match.

The function may also return -ENOTSUPP if an unsupported public-key algorithm
or public-key/hash algorithm combination is specified or the key doesn't
support the operation; -EBADMSG or -ERANGE if some of the parameters have weird
data; or -ENOMEM if an allocation can't be performed.  -EINVAL can be returned
if the key argument is the wrong type or is incompletely set up.


Asymmetric Key Subtypes
=======================

Asymmetric keys have a subtype that defines the set of operations that can be
performed on that key and that determines what data is attached as the key
payload.  The payload format is entirely at the whim of the subtype.

The subtype is selected by the key data parser and the parser must initialise
the data required for it.  The asymmetric key retains a reference on the
subtype module.

The subtype definition structure can be found in::

	#include <keys/asymmetric-subtype.h>

and looks like the following::

	struct asymmetric_key_subtype {
		struct module		*owner;
		const char		*name;

		void (*describe)(const struct key *key, struct seq_file *m);
		void (*destroy)(void *payload);
		int (*query)(const struct kernel_pkey_params *params,
			     struct kernel_pkey_query *info);
		int (*eds_op)(struct kernel_pkey_params *params,
			      const void *in, void *out);
		int (*verify_signature)(const struct key *key,
					const struct public_key_signature *sig);
	};

Asymmetric keys point to this with their payload[asym_subtype] member.

The owner and name fields should be set to the owning module and the name of
the subtype.  Currently, the name is only used for print statements.

There are a number of operations defined by the subtype:

  1) describe().

     Mandatory.  This allows the subtype to display something in /proc/keys

Annotation

Implementation Notes