add_key.2, keyrings.7: Migrate some info about key types from add_key(2) to keyrings(7)

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

man2/add_key.2

@@ -89,22 +89,19 @@ The key
 is a string that specifies the key's type.
 Internally, the kernel defines a number of key types that are
 available in the core key management code.
-The following types are available for user-space use,
+Among the types that are available for user-space use
 and can be specified as the
 .I type
 argument to
-.BR add_key ():
+.BR add_key ()
+are the following:
 .TP
 .IR """user"""
+This is a general purpose key type whose payload may be read and updated
+by user-space applications.
+The key is kept entirely within kernel memory.
 The payload for keys of this type is a blob of arbitrary data
 of up to 32,767 bytes.
-The
-.I description
-may be any valid string, though it is preferred that it
-start with a colon-delimited prefix representing the service
-to which the key is of interest
-(for instance
-.IR """afs:mykey""" ).
 .TP
 .I """keyring"""
 Keyrings are special key types that may contain links to sequences of other
@@ -119,15 +116,11 @@ should be zero.
 .\" commit 9f6ed2ca257fa8650b876377833e6f14e272848b
 This key type is essentially the same as
 .IR """user""" ,
-but does not provide reading (i.e., the
+but it does not provide reading.
-.BR keyctl (2)
+This is suitable for storing payloads
-.BR KEYCTL_READ
-operation),
-meaning that the key payload is never visible from user space.
-This is suitable for storing username and password pairs in the keyring
 that you do not want to be readable from user space.
 
-This key type also vets the
+This key type vets the
 .I description
 to ensure that it is qualified by a "service" prefix,
 by checking to ensure that the
@@ -139,12 +132,11 @@ contains a ':' that is preceded by other characters.
 This key type is similar to
 .IR """user""" ,
 but may hold a payload of up to 1 MiB.
-For this key type,
+If the key payload is large,
-the contents can be saved in a tmpfs filesystem and
+then it may be stored in swap space rather than kernel memory.
-thus swapped out to disk when memory pressure is high.
+.PP
-This key type is useful for tasks such as holding Kerberos ticket caches.
+For further details on these key types, see
-.\" David Howells: there are also other key types available for
+.BR keyrings (7).
-.\" user-space use.
 .SH RETURN VALUE
 On success,
 .BR add_key ()

man7/keyrings.7

@@ -96,32 +96,49 @@ the key is scheduled for garbage collection.
 .SS Key types
 The facility provides several basic types of key:
 .TP
+.I """user"""
+This is a general purpose key type.
+The key is kept entirely within kernel memory.
+The payload may be read and updated by user-space applications.
+
+The payload for keys of this type is a blob of arbitrary data
+of up to 32,767 bytes.
+
+The description may be any valid string, though it is preferred that it
+start with a colon-delimited prefix representing the service
+to which the key is of interest
+(for instance
+.IR """afs:mykey""" ).
+.TP
 .I """keyring"""
-Keys of this type are special.
+Keyrings are special keys whose payload consists of a set of links
-The payload consists of a set of links to other
+to other keys (including other keyrings),
-keys, analogous to a directory holding links to files.
+analogous to a directory holding links to files.
 The main purpose of a keyring is to prevent other keys from
 being garbage collected because nothing refers to them.
 .TP
-.I """user"""
+.IR """logon""" " (since Linux 3.3)"
-This is a general purpose key type.
+.\" commit 9f6ed2ca257fa8650b876377833e6f14e272848b
-It may be instantiated with an arbitrary blob of data of up to about 32KB.
+This key type is essentially the same as
-It is kept entirely within kernel memory.
+.IR """user""" ,
-It may be read and updated by user-space applications
+but it does not provide reading (i.e., the
+.BR keyctl (2)
+.BR KEYCTL_READ
+operation),
+meaning that the key payload is never visible from user space.
+This is suitable for storing username-password pairs
+that you do not want to be readable from user space.
 .TP
-.I """big_key"""
+.IR """big_key""" " (since Linux 3.13)"
-This is similar to the
+.\" commit ab3c3587f8cda9083209a61dbe3a4407d3cada10
+This key type is similar to the
 .I """user"""
 key type, but it may hold a payload of up to 1MiB in size.
 The data may be stored in the swap space rather than in kernel memory
-if the size exceeds the overhead of doing so
+if the data size exceeds the overhead of storing the data in swap space
 (a tmpfs file is used, which requires filesystem structures
 to be allocated in the kernel).
-.TP
+This key type is useful for tasks such as holding Kerberos ticket caches.
-.I """logon"""
-This is similar to the
-.I """user"""
-key type, but the contents may not be read by user-space applications.
 .PP
 There are more specialized key types available also, but they're not discussed
 here as they're not intended for normal user-space use.