summaryrefslogtreecommitdiffstats
path: root/man2/keyctl.2
diff options
context:
space:
mode:
Diffstat (limited to 'man2/keyctl.2')
-rw-r--r--man2/keyctl.2244
1 files changed, 125 insertions, 119 deletions
diff --git a/man2/keyctl.2 b/man2/keyctl.2
index 7d4324f85..559cee9fb 100644
--- a/man2/keyctl.2
+++ b/man2/keyctl.2
@@ -30,7 +30,7 @@ see VERSIONS.
glibc provides no wrapper for
.BR keyctl (),
necessitating the use of
-.BR syscall (2).
+.MR syscall 2 .
.SH DESCRIPTION
.BR keyctl ()
allows user-space programs to perform key manipulation.
@@ -67,49 +67,49 @@ The following values may be specified in
.B KEY_SPEC_THREAD_KEYRING
This specifies the calling thread's thread-specific keyring.
See
-.BR thread\-keyring (7).
+.MR thread\-keyring 7 .
.TP
.B KEY_SPEC_PROCESS_KEYRING
This specifies the caller's process-specific keyring.
See
-.BR process\-keyring (7).
+.MR process\-keyring 7 .
.TP
.B KEY_SPEC_SESSION_KEYRING
This specifies the caller's session-specific keyring.
See
-.BR session\-keyring (7).
+.MR session\-keyring 7 .
.TP
.B KEY_SPEC_USER_KEYRING
This specifies the caller's UID-specific keyring.
See
-.BR user\-keyring (7).
+.MR user\-keyring 7 .
.TP
.B KEY_SPEC_USER_SESSION_KEYRING
This specifies the caller's UID-session keyring.
See
-.BR user\-session\-keyring (7).
+.MR user\-session\-keyring 7 .
.TP
.BR KEY_SPEC_REQKEY_AUTH_KEY " (since Linux 2.6.16)"
.\" commit b5f545c880a2a47947ba2118b2509644ab7a2969
This specifies the authorization key created by
-.BR request_key (2)
+.MR request_key 2
and passed to the process it spawns to generate a key.
This key is available only in a
-.BR request\-key (8)-style
+.MR request\-key 8 -style
program that was passed an authorization key by the kernel and
ceases to be available once the requested key has been instantiated; see
-.BR request_key (2).
+.MR request_key 2 .
.TP
.BR KEY_SPEC_REQUESTOR_KEYRING " (since Linux 2.6.29)"
.\" commit 8bbf4976b59fc9fc2861e79cab7beb3f6d647640
This specifies the key ID for the
-.BR request_key (2)
+.MR request_key 2
destination keyring.
This keyring is available only in a
-.BR request\-key (8)-style
+.MR request\-key 8 -style
program that was passed an authorization key by the kernel and
ceases to be available once the requested key has been instantiated; see
-.BR request_key (2).
+.MR request_key 2 .
.RE
.IP
The behavior if the key specified in
@@ -151,7 +151,7 @@ are ignored.
This operation is exposed by
.I libkeyutils
via the function
-.BR keyctl_get_keyring_ID (3).
+.MR keyctl_get_keyring_ID 3 .
.TP
.BR KEYCTL_JOIN_SESSION_KEYRING " (since Linux 2.6.10)"
Replace the session keyring this process subscribes to with
@@ -198,7 +198,7 @@ are ignored.
This operation is exposed by
.I libkeyutils
via the function
-.BR keyctl_join_session_keyring (3).
+.MR keyctl_join_session_keyring 3 .
.TP
.BR KEYCTL_UPDATE " (since Linux 2.6.10)"
Update a key's data payload.
@@ -233,7 +233,7 @@ argument is ignored.
This operation is exposed by
.I libkeyutils
via the function
-.BR keyctl_update (3).
+.MR keyctl_update 3 .
.TP
.BR KEYCTL_REVOKE " (since Linux 2.6.10)"
Revoke the key with the ID provided in
@@ -265,7 +265,7 @@ are ignored.
This operation is exposed by
.I libkeyutils
via the function
-.BR keyctl_revoke (3).
+.MR keyctl_revoke 3 .
.TP
.BR KEYCTL_CHOWN " (since Linux 2.6.10)"
Change the ownership (user and group ID) of a key.
@@ -294,7 +294,7 @@ For the UID to be changed, or for the GID to be changed to a group
the caller is not a member of, the caller must have the
.B CAP_SYS_ADMIN
capability (see
-.BR capabilities (7)).
+.MR capabilities 7 ).
.IP
If the UID is to be changed, the new user must have sufficient
quota to accept the key.
@@ -308,7 +308,7 @@ argument is ignored.
This operation is exposed by
.I libkeyutils
via the function
-.BR keyctl_chown (3).
+.MR keyctl_chown 3 .
.TP
.BR KEYCTL_SETPERM " (since Linux 2.6.10)"
Change the permissions of the key with the ID provided in the
@@ -344,7 +344,7 @@ for each of the following user categories:
This is the permission granted to a process that possesses the key
(has it attached searchably to one of the process's keyrings);
see
-.BR keyrings (7).
+.MR keyrings 7 .
.TP
.I user
This is the permission granted to a process
@@ -515,7 +515,7 @@ arguments are ignored.
This operation is exposed by
.I libkeyutils
via the function
-.BR keyctl_setperm (3).
+.MR keyctl_setperm 3 .
.TP
.BR KEYCTL_DESCRIBE " (since Linux 2.6.10)"
Obtain a string describing the attributes of a specified key.
@@ -597,7 +597,7 @@ argument is ignored.
This operation is exposed by
.I libkeyutils
via the function
-.BR keyctl_describe (3).
+.MR keyctl_describe 3 .
.TP
.B KEYCTL_CLEAR
Clear the contents of (i.e., unlink all keys from) a keyring.
@@ -628,7 +628,7 @@ are ignored.
This operation is exposed by
.I libkeyutils
via the function
-.BR keyctl_clear (3).
+.MR keyctl_clear 3 .
.TP
.BR KEYCTL_LINK " (since Linux 2.6.10)"
Create a link from a keyring to a key.
@@ -669,7 +669,7 @@ are ignored.
This operation is exposed by
.I libkeyutils
via the function
-.BR keyctl_link (3).
+.MR keyctl_link 3 .
.TP
.BR KEYCTL_UNLINK " (since Linux 2.6.10)"
Unlink a key from a keyring.
@@ -701,7 +701,7 @@ are ignored.
This operation is exposed by
.I libkeyutils
via the function
-.BR keyctl_unlink (3).
+.MR keyctl_unlink 3 .
.TP
.BR KEYCTL_SEARCH " (since Linux 2.6.10)"
Search for a key in a keyring tree,
@@ -768,7 +768,7 @@ keyrings can be one of the special keyring IDs listed under
This operation is exposed by
.I libkeyutils
via the function
-.BR keyctl_search (3).
+.MR keyctl_search 3 .
.TP
.BR KEYCTL_READ " (since Linux 2.6.10)"
Read the payload data of a key.
@@ -828,7 +828,7 @@ argument is ignored.
This operation is exposed by
.I libkeyutils
via the function
-.BR keyctl_read (3).
+.MR keyctl_read 3 .
.TP
.BR KEYCTL_INSTANTIATE " (since Linux 2.6.10)"
(Positively) instantiate an uninstantiated key with a specified payload.
@@ -866,16 +866,16 @@ The caller must have the appropriate authorization key,
and once the uninstantiated key has been instantiated,
the authorization key is revoked.
In other words, this operation is available only from a
-.BR request\-key (8)-style
+.MR request\-key 8 -style
program.
See
-.BR request_key (2)
+.MR request_key 2
for an explanation of uninstantiated keys and key instantiation.
.IP
This operation is exposed by
.I libkeyutils
via the function
-.BR keyctl_instantiate (3).
+.MR keyctl_instantiate 3 .
.TP
.BR KEYCTL_NEGATE " (since Linux 2.6.10)"
Negatively instantiate an uninstantiated key.
@@ -895,7 +895,7 @@ argument is ignored.
This operation is exposed by
.I libkeyutils
via the function
-.BR keyctl_negate (3).
+.MR keyctl_negate 3 .
.TP
.BR KEYCTL_SET_REQKEY_KEYRING " (since Linux 2.6.13)"
Set the default keyring to which implicitly requested keys
@@ -908,7 +908,7 @@ such as can occur when, for example, opening files
on an AFS or NFS filesystem.
Setting the default keyring also has an effect when requesting
a key from user space; see
-.BR request_key (2)
+.MR request_key 2
for details.
.IP
The
@@ -934,27 +934,32 @@ otherwise the user-specific keyring.
.TP
.B KEY_REQKEY_DEFL_THREAD_KEYRING
Use the thread-specific keyring
-.RB ( thread\-keyring (7))
+\%(\c
+.MR thread\-keyring 7 )
as the new default keyring.
.TP
.B KEY_REQKEY_DEFL_PROCESS_KEYRING
Use the process-specific keyring
-.RB ( process\-keyring (7))
+\%(\c
+.MR process\-keyring 7 )
as the new default keyring.
.TP
.B KEY_REQKEY_DEFL_SESSION_KEYRING
Use the session-specific keyring
-.RB ( session\-keyring (7))
+\%(\c
+.MR session\-keyring 7 )
as the new default keyring.
.TP
.B KEY_REQKEY_DEFL_USER_KEYRING
Use the UID-specific keyring
-.RB ( user\-keyring (7))
+\%(\c
+.MR user\-keyring 7 )
as the new default keyring.
.TP
.B KEY_REQKEY_DEFL_USER_SESSION_KEYRING
Use the UID-specific session keyring
-.RB ( user\-session\-keyring (7))
+\%(\c
+.MR user\-session\-keyring 7 )
as the new default keyring.
.TP
.BR KEY_REQKEY_DEFL_REQUESTOR_KEYRING " (since Linux 2.6.29)"
@@ -980,14 +985,14 @@ and
are ignored.
.IP
The setting controlled by this operation is inherited by the child of
-.BR fork (2)
+.MR fork 2
and preserved across
.BR execve (2).
.IP
This operation is exposed by
.I libkeyutils
via the function
-.BR keyctl_set_reqkey_keyring (3).
+.MR keyctl_set_reqkey_keyring 3 .
.TP
.BR KEYCTL_SET_TIMEOUT " (since Linux 2.6.16)"
Set a timeout on a key.
@@ -1014,7 +1019,7 @@ The caller must either have the
.I setattr
permission on the key
or hold an instantiation authorization token for the key (see
-.BR request_key (2)).
+.MR request_key 2 ).
.IP
The key and any links to the key will be
automatically garbage collected after the timeout expires.
@@ -1033,7 +1038,7 @@ are ignored.
This operation is exposed by
.I libkeyutils
via the function
-.BR keyctl_set_timeout (3).
+.MR keyctl_set_timeout 3 .
.TP
.BR KEYCTL_ASSUME_AUTHORITY " (since Linux 2.6.16)"
Assume (or divest) the authority for the calling thread
@@ -1065,9 +1070,9 @@ associated with the specified key.
(In other words, the
.B KEYCTL_ASSUME_AUTHORITY
operation is available only from a
-.BR request\-key (8)-style
+.MR request\-key 8 -style
program; see
-.BR request_key (2)
+.MR request_key 2
for an explanation of how this operation is used.)
The caller must have
.I search
@@ -1078,7 +1083,7 @@ then the ID of that key is returned.
The authorization key can be read
.RB ( KEYCTL_READ )
to obtain the callout information passed to
-.BR request_key (2).
+.MR request_key 2 .
.IP
If the ID given in
.I arg2
@@ -1088,12 +1093,12 @@ and the value 0 is returned.
The
.B KEYCTL_ASSUME_AUTHORITY
mechanism allows a program such as
-.BR request\-key (8)
+.MR request\-key 8
to assume the necessary authority to instantiate a new uninstantiated key
that was created as a consequence of a call to
-.BR request_key (2).
+.MR request_key 2 .
For further information, see
-.BR request_key (2)
+.MR request_key 2
and the kernel source file
.IR Documentation/security/keys\-request\-key.txt .
.IP
@@ -1107,7 +1112,7 @@ are ignored.
This operation is exposed by
.I libkeyutils
via the function
-.BR keyctl_assume_authority (3).
+.MR keyctl_assume_authority 3 .
.TP
.BR KEYCTL_GET_SECURITY " (since Linux 2.6.26)"
.\" commit 70a5bb72b55e82fbfbf1e22cae6975fac58a1e2d
@@ -1160,9 +1165,9 @@ argument is ignored.
This operation is exposed by
.I libkeyutils
via the functions
-.BR keyctl_get_security (3)
+.MR keyctl_get_security 3
and
-.BR keyctl_get_security_alloc (3).
+.MR keyctl_get_security_alloc 3 .
.TP
.BR KEYCTL_SESSION_TO_PARENT " (since Linux 2.6.32)"
.\" commit ee18d64c1f632043a02e6f5ba5e045bb26a5465f
@@ -1191,7 +1196,7 @@ The fact that it is the parent process that is affected by this operation
allows a program such as the shell to start a child process that
uses this operation to change the shell's session keyring.
(This is what the
-.BR keyctl (1)
+.MR keyctl 1
.B new_session
command does.)
.IP
@@ -1206,7 +1211,7 @@ are ignored.
This operation is exposed by
.I libkeyutils
via the function
-.BR keyctl_session_to_parent (3).
+.MR keyctl_session_to_parent 3 .
.TP
.BR KEYCTL_REJECT " (since Linux 2.6.39)"
.\" commit fdd1b94581782a2ddf9124414e5b7a5f48ce2f9c
@@ -1248,25 +1253,25 @@ whose ID is specified in
.IP
The caller must have the appropriate authorization key.
In other words, this operation is available only from a
-.BR request\-key (8)-style
+.MR request\-key 8 -style
program.
See
-.BR request_key (2).
+.MR request_key 2 .
.IP
The caller must have the appropriate authorization key,
and once the uninstantiated key has been instantiated,
the authorization key is revoked.
In other words, this operation is available only from a
-.BR request\-key (8)-style
+.MR request\-key 8 -style
program.
See
-.BR request_key (2)
+.MR request_key 2
for an explanation of uninstantiated keys and key instantiation.
.IP
This operation is exposed by
.I libkeyutils
via the function
-.BR keyctl_reject (3).
+.MR keyctl_reject 3 .
.TP
.BR KEYCTL_INSTANTIATE_IOV " (since Linux 2.6.39)"
.\" commit ee009e4a0d4555ed522a631bae9896399674f063
@@ -1278,7 +1283,7 @@ This operation is the same as
but the payload data is specified as an array of
.I iovec
structures (see
-.BR iovec (3type)).
+.MR iovec 3type ).
.IP
The pointer to the payload vector is specified in
.I arg3
@@ -1301,7 +1306,7 @@ are interpreted as for
This operation is exposed by
.I libkeyutils
via the function
-.BR keyctl_instantiate_iov (3).
+.MR keyctl_instantiate_iov 3 .
.TP
.BR KEYCTL_INVALIDATE " (since Linux 3.5)"
.\" commit fd75815f727f157a05f4c96b5294a4617c0557da
@@ -1342,12 +1347,13 @@ are ignored.
This operation is exposed by
.I libkeyutils
via the function
-.BR keyctl_invalidate (3).
+.MR keyctl_invalidate 3 .
.TP
.BR KEYCTL_GET_PERSISTENT " (since Linux 3.13)"
.\" commit f36f8c75ae2e7d4da34f4c908cebdb4aa42c977e
Get the persistent keyring
-.RB ( persistent\-keyring (7))
+\%(\c
+.MR persistent\-keyring 7 )
for a specified user and link it to a specified keyring.
.IP
The user ID is specified in
@@ -1404,7 +1410,7 @@ are ignored.
This operation is exposed by
.I libkeyutils
via the function
-.BR keyctl_get_persistent (3).
+.MR keyctl_get_persistent 3 .
.TP
.BR KEYCTL_DH_COMPUTE " (since Linux 4.7)"
.\" commit ddbb41148724367394d0880c516bfaeed127b52e
@@ -1545,9 +1551,9 @@ This operation is exposed by
(from
.I libkeyutils
1.5.10 onwards) via the functions
-.BR keyctl_dh_compute (3)
+.MR keyctl_dh_compute 3
and
-.BR keyctl_dh_compute_alloc (3).
+.MR keyctl_dh_compute_alloc 3 .
.TP
.BR KEYCTL_RESTRICT_KEYRING " (since Linux 4.12)"
.\" commit 6563c91fd645556c7801748f15bc727c77fcd311
@@ -1938,7 +1944,7 @@ the UID of the caller's session keyring did not match
the effective UID of the caller;
the parent process is not single-thread;
or the parent process is
-.BR init (1)
+.MR init 1
or a kernel thread.
.TP
.B ETIMEDOUT
@@ -1962,7 +1968,7 @@ Linux.
Linux 2.6.10.
.SH EXAMPLES
The program below provide subset of the functionality of the
-.BR request\-key (8)
+.MR request\-key 8
program provided by the
.I keyutils
package.
@@ -1970,9 +1976,9 @@ For informational purposes,
the program records various information in a log file.
.P
As described in
-.BR request_key (2),
+.MR request_key 2 ,
the
-.BR request\-key (8)
+.MR request\-key 8
program is invoked with command-line arguments that
describe a key that is to be instantiated.
The example program fetches and logs these arguments.
@@ -1982,14 +1988,14 @@ and then instantiates that key.
The following shell session demonstrates the use of this program.
In the session,
we compile the program and then use it to temporarily replace the standard
-.BR request\-key (8)
+.MR request\-key 8
program.
(Note that temporarily disabling the standard
-.BR request\-key (8)
+.MR request\-key 8
program may not be safe on some systems.)
While our example program is installed,
we use the example program shown in
-.BR request_key (2)
+.MR request_key 2
to request a key.
.P
.in +4n
@@ -2038,10 +2044,10 @@ which included the name of the key
the payload of the authorization key, which consisted of the data
.RI ( somepayloaddata )
passed to
-.BR request_key (2);
+.MR request_key 2 ;
.IP \[bu]
the destination keyring that was specified in the call to
-.BR request_key (2);
+.MR request_key 2 ;
and
.IP \[bu]
the description of the authorization key,
@@ -2050,7 +2056,7 @@ the ID of the key that is to be instantiated
.RI ( 20d035bf ).
.P
The example program in
-.BR request_key (2)
+.MR request_key 2
specified the destination keyring as
.BR KEY_SPEC_SESSION_KEYRING .
By examining the contents of
@@ -2242,54 +2248,54 @@ main(int argc, char *argv[])
.SH SEE ALSO
.ad l
.nh
-.BR keyctl (1),
-.BR add_key (2),
-.BR request_key (2),
+.MR keyctl 1 ,
+.MR add_key 2 ,
+.MR request_key 2 ,
.\" .BR find_key_by_type_and_name (3)
.\" There is a man page, but this function seems not to exist
-.BR keyctl (3),
-.BR keyctl_assume_authority (3),
-.BR keyctl_chown (3),
-.BR keyctl_clear (3),
-.BR keyctl_describe (3),
-.BR keyctl_describe_alloc (3),
-.BR keyctl_dh_compute (3),
-.BR keyctl_dh_compute_alloc (3),
-.BR keyctl_get_keyring_ID (3),
-.BR keyctl_get_persistent (3),
-.BR keyctl_get_security (3),
-.BR keyctl_get_security_alloc (3),
-.BR keyctl_instantiate (3),
-.BR keyctl_instantiate_iov (3),
-.BR keyctl_invalidate (3),
-.BR keyctl_join_session_keyring (3),
-.BR keyctl_link (3),
-.BR keyctl_negate (3),
-.BR keyctl_read (3),
-.BR keyctl_read_alloc (3),
-.BR keyctl_reject (3),
-.BR keyctl_revoke (3),
-.BR keyctl_search (3),
-.BR keyctl_session_to_parent (3),
-.BR keyctl_set_reqkey_keyring (3),
-.BR keyctl_set_timeout (3),
-.BR keyctl_setperm (3),
-.BR keyctl_unlink (3),
-.BR keyctl_update (3),
-.BR recursive_key_scan (3),
-.BR recursive_session_key_scan (3),
-.BR capabilities (7),
-.BR credentials (7),
-.BR keyrings (7),
-.BR keyutils (7),
-.BR persistent\-keyring (7),
-.BR process\-keyring (7),
-.BR session\-keyring (7),
-.BR thread\-keyring (7),
-.BR user\-keyring (7),
-.BR user_namespaces (7),
-.BR user\-session\-keyring (7),
-.BR request\-key (8)
+.MR keyctl 3 ,
+.MR keyctl_assume_authority 3 ,
+.MR keyctl_chown 3 ,
+.MR keyctl_clear 3 ,
+.MR keyctl_describe 3 ,
+.MR keyctl_describe_alloc 3 ,
+.MR keyctl_dh_compute 3 ,
+.MR keyctl_dh_compute_alloc 3 ,
+.MR keyctl_get_keyring_ID 3 ,
+.MR keyctl_get_persistent 3 ,
+.MR keyctl_get_security 3 ,
+.MR keyctl_get_security_alloc 3 ,
+.MR keyctl_instantiate 3 ,
+.MR keyctl_instantiate_iov 3 ,
+.MR keyctl_invalidate 3 ,
+.MR keyctl_join_session_keyring 3 ,
+.MR keyctl_link 3 ,
+.MR keyctl_negate 3 ,
+.MR keyctl_read 3 ,
+.MR keyctl_read_alloc 3 ,
+.MR keyctl_reject 3 ,
+.MR keyctl_revoke 3 ,
+.MR keyctl_search 3 ,
+.MR keyctl_session_to_parent 3 ,
+.MR keyctl_set_reqkey_keyring 3 ,
+.MR keyctl_set_timeout 3 ,
+.MR keyctl_setperm 3 ,
+.MR keyctl_unlink 3 ,
+.MR keyctl_update 3 ,
+.MR recursive_key_scan 3 ,
+.MR recursive_session_key_scan 3 ,
+.MR capabilities 7 ,
+.MR credentials 7 ,
+.MR keyrings 7 ,
+.MR keyutils 7 ,
+.MR persistent\-keyring 7 ,
+.MR process\-keyring 7 ,
+.MR session\-keyring 7 ,
+.MR thread\-keyring 7 ,
+.MR user\-keyring 7 ,
+.MR user_namespaces 7 ,
+.MR user\-session\-keyring 7 ,
+.MR request\-key 8
.P
The kernel source files under
.I Documentation/security/keys/
generated by cgit v1.2.3 (git 2.39.1) at 2024-06-01 13:16:27 +0000