--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/share/man/man7/asymmetric-key.7	Tue Mar 18 16:23:26 2025 -0400
@@ -0,0 +1,232 @@
+.\"
+.\" Copyright (C) 2018 Red Hat, Inc. All Rights Reserved.
+.\" Written by David Howells (dhowells@redhat.com)
+.\"
+.\" This program is free software; you can redistribute it and/or
+.\" modify it under the terms of the GNU General Public Licence
+.\" as published by the Free Software Foundation; either version
+.\" 2 of the Licence, or (at your option) any later version.
+.\"
+.TH ASYMMETRIC-KEY 7 "8 Nov 2018" Linux "Asymmetric Kernel Key Type"
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.SH NAME
+asymmetric \- Kernel key type for holding asymmetric keys
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.SH OVERVIEW
+.PP
+A kernel key of
+.B asymmetric
+type acts as a handle to an asymmetric key as used for public-key
+cryptography.  The key material itself may be held inside the kernel or it may
+be held in hardware with operations being offloaded.  This prevents direct
+user access to the cryptographic material.
+.PP
+Keys may be any asymmetric type (RSA, ECDSA, ...) and may have both private and
+public components present or just the public component.
+.PP
+Asymmetric keys can be made use of by both the kernel and userspace.  The
+kernel can make use of them for module signature verification and kexec image
+verification for example.  Userspace is provided with a set of
+.BR keyctl ( KEYCTL_PKEY_* )
+calls for querying and using the key.  These are wrapped by
+.B libkeyutils
+as functions named
+.BR keyctl_pkey_*() .
+.PP
+An asymmetric-type key can be loaded by the keyctl utility using a command
+line like:
+.PP
+.in +4n
+.EX
+openssl x509 -in key.x509 -outform DER |
+keyctl padd asymmetric foo @s
+.EE
+.in
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.SH DESCRIPTION
+.PP
+The asymmetric-type key can be viewed as a container that comprises of a
+number of components:
+.TP
+Parsers
+The asymmetric key parsers attempt to identify the content of the payload blob
+and extract useful data from it with which to instantiate the key.  The parser
+is only used when adding, instantiating or updating a key and isn't thereafter
+associated with the key.
+.IP
+Available parsers include ones that can deal with
+.RB "DER-encoded " X.509 ", DER-encoded " PKCS#8 " and DER-encoded " TPM "-wrapped blobs."
+.TP
+Public and private keys
+These are the cryptographic components of the key pair.  The public half
+should always be available, but the private half might not be.  What
+operations are available can be queried, as can the size of the key.  The key
+material may or may not actually reside in the kernel.
+.TP
+Identifiers
+In addition to the normal key description (which can be generated by the
+parser), a number of supplementary identifiers may be available that can be
+searched for.  These may be obtained, for example, by hashing the public key
+material or from the subjectKeyIdentifier in an X.509 certificate.
+.IP
+Identifier-based searches are selected by passing as the description to
+.BR keyctl_search ()
+a string constructed of hex characters prefixed with either "id:" or "ex:".
+The "id:" prefix indicates that a partial tail match is permissible whereas
+"ex:" requires an exact match on the full string.  The hex characters indicate
+the data to match.
+.TP
+Subtype
+This is the driver inside the kernel that accesses the key material and
+performs operations on it.  It might be entirely software-based or it may
+offload the operations to a hardware key store, such as a
+.BR TPM .
+.PP
+Note that expiry times from the payload are ignored as these patches may be
+used during boot before the system clock is set.
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.SH PARSERS
+.PP
+The asymmetric key parsers can handle keys in a number of forms:
+.TP
+\fBX.509\fP
+DER-encoded X.509 certificates can be accepted.  Two identifiers are
+constructed: one from from the certificate issuer and serial number and the
+other from the subjectKeyIdentifier, if present.  If left blank, the key
+description will be filled in from the subject field plus either the
+subjectKeyIdentifier or the serialNumber.  Only the public key is filled in
+and only the encrypt and verify operations are supported.
+.IP
+The signature on the X.509 certificate may be checked by the keyring it is
+being added to and it may also be rejected if the key is blacklisted.
+.TP
+\fBPKCS#8\fP
+Unencrypted DER-encoded PKCS#8 key data containers can be accepted.  Currently
+no identifiers are constructed.  The private key and the public key are loaded
+from the PKCS#8 blobs.  Encrypted PKCS#8 is not currently supported.
+.TP
+\fBTPM-Wrapped keys\fP
+DER-encoded TPM-wrapped TSS key blobs can be accepted.  Currently no
+identifiers are constructed.  The public key is extracted from the blob but
+the private key is expected to be resident in the TPM.  Encryption and
+signature verification is done in software, but decryption and signing are
+offloaded to the TPM so as not to expose the private key.
+.IP
+This parser only supports TPM-1.2 wrappings and enc=pkcs1 encoding type.  It
+also uses a hard-coded null SRK password; password-protected SRKs are not yet
+supported.
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.SH USERSPACE API
+.PP
+In addition to the standard keyutils library functions, such as
+.IR keyctl_update (),
+there are five calls specific to the asymmetric key type (though they are open
+to being used by other key types also):
+.PP
+.RS
+\fIkeyctl_pkey_query\fP()
+.br
+\fIkeyctl_pkey_encrypt\fP()
+.br
+\fIkeyctl_pkey_decrypt\fP()
+.br
+\fIkeyctl_pkey_sign\fP()
+.br
+\fIkeyctl_pkey_verify\fP()
+.RE
+.PP
+The query function can be used to retrieve information about an asymmetric key,
+such as the key size, the amount of space required by buffers for the other
+operations and which operations are actually supported.
+.PP
+The other operations form two pairs: encrypt/decrypt and create/verify
+signature.  Not all of these operations will necessarily be available;
+typically, encrypt and verify only require the public key to be available
+whereas decrypt and sign require the private key as well.
+.PP
+All of these operations take an information string parameter that supplies
+additional information such as encoding type/form and the password(s) needed to
+unlock/unwrap the key.  This takes the form of a comma-separated list of
+"key[=value]" pairs, the exact set of which depends on the subtype driver used
+by a particular key.
+.PP
+Available parameters include:
+.TP
+enc=<type>
+The encoding type for use in an encrypted blob or a signature.  An example
+might be "enc=pkcs1".
+.TP
+hash=<name>
+The name of the hash algorithm that was used to digest the data to be signed.
+Note that this is only used to construct any encoding that is used in a
+signature.  The data to be signed or verified must have been parsed by the
+caller and the hash passed to \fIkeyctl_pkey_sign\fP() or
+\fIkeyctl_pkey_verify\fP() beforehand.  An example might be "hash=sha256".
+.PP
+Note that not all parameters are used by all subtypes.
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.SH RESTRICTED KEYRINGS
+.PP
+An additional keyutils function,
+.IR keyctl_restrict_keyring (),
+can be used to gate a keyring so that a new key can only be added to the
+affected keyring if (a) it's an asymmetric key, (b) it's validly signed by a
+key in some appropriate keyring and (c) it's not blacklisted.
+.PP
+.in +4n
+.EX
+ keyctl_restrict_keyring(keyring, "asymmetric",
+                         "key_or_keyring:<signing-key>[:chain]");
+.EE
+.in
+.PP
+Where \fI<signing-key>\fP is the ID of a key or a ring of keys that act as the
+authority to permit a new key to be added to the keyring.  The \fIchain\fP flag
+indicates that keys that have been added to the keyring may also be used to
+verify new keys.  Authorising keys must themselves be asymmetric-type keys that
+can be used to do a signature verification on the key being added.
+.PP
+Note that there are various system keyrings visible to the root user that may
+permit additional keys to be added.  These are typically gated by keys that
+already exist, preventing unauthorised keys from being used for such things as
+module verification.
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.SH BLACKLISTING
+.PP
+When the attempt is made to add a key to the kernel, a hash of the public key
+is checked against the
+.BR blacklist.
+This is a system keyring named
+.B .blacklist
+and contains keys of type
+.BR blacklist .
+If the blacklist contains a key whose description matches the hash of the new
+key, that new key will be rejected with error
+.BR EKEYREJECTED .
+.PP
+The blacklist keyring may be loaded from multiple sources, including a list
+compiled into the kernel and the UEFI
+.B dbx
+variable.  Further hashes may also be blacklisted by the administrator.  Note
+that blacklisting is not retroactive, so an asymmetric key that is already on
+the system cannot be blacklisted by adding a matching blacklist entry later.
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.SH VERSIONS
+The
+.B asymmetric
+key type first appeared in v3.7 of the Linux kernel, the
+.B restriction
+function in v4.11 and the
+.B public key operations
+in v4.20.
+.SH SEE ALSO
+.ad l
+.nh
+.BR keyctl (1),
+.BR add_key (2),
+.BR keyctl (3),
+.BR keyctl_pkey_encrypt (3),
+.BR keyctl_pkey_query (3),
+.BR keyctl_pkey_sign (3),
+.BR keyrings (7),
+.BR keyutils (7)