Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/share/man/man1/keyctl.1 @ 68:5028fdace37b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 16:23:26 -0400
parents
children
rev   line source
jpayne@68 1 .\"
jpayne@68 2 .\" Copyright (C) 2004 Red Hat, Inc. All Rights Reserved.
jpayne@68 3 .\" Written by David Howells (dhowells@redhat.com)
jpayne@68 4 .\"
jpayne@68 5 .\" This program is free software; you can redistribute it and/or
jpayne@68 6 .\" modify it under the terms of the GNU General Public License
jpayne@68 7 .\" as published by the Free Software Foundation; either version
jpayne@68 8 .\" 2 of the License, or (at your option) any later version.
jpayne@68 9 .\"
jpayne@68 10 .TH KEYCTL 1 "20 Feb 2014" Linux "Linux Key Management Utilities"
jpayne@68 11 .SH NAME
jpayne@68 12 keyctl \- key management facility control
jpayne@68 13 .SH SYNOPSIS
jpayne@68 14 \fBkeyctl\fR \-\-version
jpayne@68 15 .br
jpayne@68 16 \fBkeyctl\fR supports [<cap>]
jpayne@68 17 .br
jpayne@68 18 \fBkeyctl\fR show [\-x] [<keyring>]
jpayne@68 19 .br
jpayne@68 20 \fBkeyctl\fR add <type> <desc> <data> <keyring>
jpayne@68 21 .br
jpayne@68 22 \fBkeyctl\fR padd <type> <desc> <keyring>
jpayne@68 23 .br
jpayne@68 24 \fBkeyctl\fR request <type> <desc> [<dest_keyring>]
jpayne@68 25 .br
jpayne@68 26 \fBkeyctl\fR request2 <type> <desc> <info> [<dest_keyring>]
jpayne@68 27 .br
jpayne@68 28 \fBkeyctl\fR prequest2 <type> <desc> [<dest_keyring>]
jpayne@68 29 .br
jpayne@68 30 \fBkeyctl\fR update <key> <data>
jpayne@68 31 .br
jpayne@68 32 \fBkeyctl\fR pupdate <key>
jpayne@68 33 .br
jpayne@68 34 \fBkeyctl\fR newring <name> <keyring>
jpayne@68 35 .br
jpayne@68 36 \fBkeyctl\fR revoke <key>
jpayne@68 37 .br
jpayne@68 38 \fBkeyctl\fR clear <keyring>
jpayne@68 39 .br
jpayne@68 40 \fBkeyctl\fR link <key> <keyring>
jpayne@68 41 .br
jpayne@68 42 \fBkeyctl\fR unlink <key> [<keyring>]
jpayne@68 43 .br
jpayne@68 44 \fBkeyctl\fR move [-f] <key> <from_keyring> <to_keyring>
jpayne@68 45 .br
jpayne@68 46 \fBkeyctl\fR search <keyring> <type> <desc> [<dest_keyring>]
jpayne@68 47 .br
jpayne@68 48 \fBkeyctl\fR restrict_keyring <keyring> [<type> [<restriction>]]
jpayne@68 49 .br
jpayne@68 50 \fBkeyctl\fR read <key>
jpayne@68 51 .br
jpayne@68 52 \fBkeyctl\fR pipe <key>
jpayne@68 53 .br
jpayne@68 54 \fBkeyctl\fR print <key>
jpayne@68 55 .br
jpayne@68 56 \fBkeyctl\fR list <keyring>
jpayne@68 57 .br
jpayne@68 58 \fBkeyctl\fR rlist <keyring>
jpayne@68 59 .br
jpayne@68 60 \fBkeyctl\fR describe <keyring>
jpayne@68 61 .br
jpayne@68 62 \fBkeyctl\fR rdescribe <keyring> [sep]
jpayne@68 63 .br
jpayne@68 64 \fBkeyctl\fR chown <key> <uid>
jpayne@68 65 .br
jpayne@68 66 \fBkeyctl\fR chgrp <key> <gid>
jpayne@68 67 .br
jpayne@68 68 \fBkeyctl\fR setperm <key> <mask>
jpayne@68 69 .br
jpayne@68 70 \fBkeyctl\fR new_session
jpayne@68 71 .br
jpayne@68 72 \fBkeyctl\fR session
jpayne@68 73 .br
jpayne@68 74 \fBkeyctl\fR session \- [<prog> <arg1> <arg2> ...]
jpayne@68 75 .br
jpayne@68 76 \fBkeyctl\fR session <name> [<prog> <arg1> <arg2> ...]
jpayne@68 77 .br
jpayne@68 78 \fBkeyctl\fR instantiate <key> <data> <keyring>
jpayne@68 79 .br
jpayne@68 80 \fBkeyctl\fR pinstantiate <key> <keyring>
jpayne@68 81 .br
jpayne@68 82 \fBkeyctl\fR negate <key> <timeout> <keyring>
jpayne@68 83 .br
jpayne@68 84 \fBkeyctl\fR reject <key> <timeout> <error> <keyring>
jpayne@68 85 .br
jpayne@68 86 \fBkeyctl\fR timeout <key> <timeout>
jpayne@68 87 .br
jpayne@68 88 \fBkeyctl\fR security <key>
jpayne@68 89 .br
jpayne@68 90 \fBkeyctl\fR reap [\-v]
jpayne@68 91 .br
jpayne@68 92 \fBkeyctl\fR purge <type>
jpayne@68 93 .br
jpayne@68 94 \fBkeyctl\fR purge [\-i] [\-p] <type> <desc>
jpayne@68 95 .br
jpayne@68 96 \fBkeyctl\fR purge \-s <type> <desc>
jpayne@68 97 .br
jpayne@68 98 \fBkeyctl\fR get_persistent <keyring> [<uid>]
jpayne@68 99 .br
jpayne@68 100 \fBkeyctl\fR dh_compute <private> <prime> <base>
jpayne@68 101 .br
jpayne@68 102 \fBkeyctl\fR dh_compute_kdf <private> <prime> <base> <output_length> <hash_type>
jpayne@68 103 .br
jpayne@68 104 \fBkeyctl\fR dh_compute_kdf_oi <private> <prime> <base> <output_length> <hash_type>
jpayne@68 105 .br
jpayne@68 106 \fBkeyctl\fR pkey_query <key> <pass> [k=v]*
jpayne@68 107 .br
jpayne@68 108 \fBkeyctl\fR pkey_encrypt <key> <pass> <datafile> [k=v]* ><encfile>
jpayne@68 109 .br
jpayne@68 110 \fBkeyctl\fR pkey_decrypt <key> <pass> <encfile> [k=v]* ><datafile>
jpayne@68 111 .br
jpayne@68 112 \fBkeyctl\fR pkey_sign <key> <pass> <datafile> [k=v]* ><sigfile>
jpayne@68 113 .br
jpayne@68 114 \fBkeyctl\fR pkey_decrypt <key> <pass> <datafile> <sigfile> [k=v]*
jpayne@68 115 .SH DESCRIPTION
jpayne@68 116 This program is used to control the key management facility in various ways
jpayne@68 117 using a variety of subcommands.
jpayne@68 118 .SH KEY IDENTIFIERS
jpayne@68 119 The key identifiers passed to or returned from keyctl are, in general, positive
jpayne@68 120 integers. There are, however, some special values with special meanings that
jpayne@68 121 can be passed as arguments:
jpayne@68 122 .TP
jpayne@68 123 No key: \fB0\fR
jpayne@68 124 .TP
jpayne@68 125 Thread keyring: \fB@t\fR or \fB\-1\fR
jpayne@68 126 Each thread may have its own keyring. This is searched first, before all
jpayne@68 127 others. The thread keyring is replaced by (v)fork, exec and clone.
jpayne@68 128 .TP
jpayne@68 129 Process keyring: \fB@p\fR or \fB\-2\fR
jpayne@68 130 Each process (thread group) may have its own keyring. This is shared between
jpayne@68 131 all members of a group and will be searched after the thread keyring. The
jpayne@68 132 process keyring is replaced by (v)fork and exec.
jpayne@68 133 .TP
jpayne@68 134 Session keyring: \fB@s\fR or \fB\-3\fR
jpayne@68 135 Each process subscribes to a session keyring that is inherited across (v)fork,
jpayne@68 136 exec and clone. This is searched after the process keyring. Session keyrings
jpayne@68 137 can be named and an extant keyring can be joined in place of a process's
jpayne@68 138 current session keyring.
jpayne@68 139 .TP
jpayne@68 140 User specific keyring: \fB@u\fR or \fB\-4\fR
jpayne@68 141 This keyring is shared between all the processes owned by a particular user. It
jpayne@68 142 isn't searched directly, but is normally linked to from the session keyring.
jpayne@68 143 .TP
jpayne@68 144 User default session keyring: \fB@us\fR or \fB\-5\fR
jpayne@68 145 This is the default session keyring for a particular user. Login processes that
jpayne@68 146 change to a particular user will bind to this session until another session is
jpayne@68 147 set.
jpayne@68 148 .TP
jpayne@68 149 Group specific keyring: \fB@g\fR or \fB\-6\fR
jpayne@68 150 This is a place holder for a group specific keyring, but is not actually
jpayne@68 151 implemented yet in the kernel.
jpayne@68 152 .TP
jpayne@68 153 Assumed request_key authorisation key: \fB@a\fR or \fB\-7\fR
jpayne@68 154 This selects the authorisation key provided to the
jpayne@68 155 .BR request_key ()
jpayne@68 156 helper to
jpayne@68 157 permit it to access the callers keyrings and instantiate the target key.
jpayne@68 158 .TP
jpayne@68 159 Keyring by name: \fB%:<name>\fR
jpayne@68 160 A named keyring. This will be searched for in the process's keyrings and in
jpayne@68 161 .IR /proc/keys .
jpayne@68 162 .TP
jpayne@68 163 Key by name: \fB%<type>:<name>\fR
jpayne@68 164 A named key of the given type. This will be searched for in the process's
jpayne@68 165 keyrings and in
jpayne@68 166 .IR /proc/keys .
jpayne@68 167 .SH COMMAND SYNTAX
jpayne@68 168 Any non-ambiguous shortening of a command name may be used in lieu of the full
jpayne@68 169 command name. This facility should not be used in scripting as new commands may
jpayne@68 170 be added in future that then cause ambiguity.
jpayne@68 171 .SS Display the package version number
jpayne@68 172 \fBkeyctl \-\-version\fR
jpayne@68 173
jpayne@68 174 This command prints the package version number and build date and exits:
jpayne@68 175
jpayne@68 176 .RS
jpayne@68 177 .nf
jpayne@68 178 $ keyctl \-\-version
jpayne@68 179 keyctl from keyutils\-1.5.3 (Built 2011\-08\-24)
jpayne@68 180 .fi
jpayne@68 181 .RE
jpayne@68 182 .SS Query subsystem capabilities
jpayne@68 183 \fBkeyctl\fR supports [<cap>]
jpayne@68 184
jpayne@68 185 This command can list the available capabilities:
jpayne@68 186
jpayne@68 187 .RS
jpayne@68 188 .nf
jpayne@68 189 $ keyctl supports
jpayne@68 190 have_capabilities=0
jpayne@68 191 have_persistent_keyrings=1
jpayne@68 192 have_dh_compute=1
jpayne@68 193 have_public_key=1
jpayne@68 194 ...
jpayne@68 195 .fi
jpayne@68 196 .RE
jpayne@68 197 .P
jpayne@68 198 And it can query a capability:
jpayne@68 199
jpayne@68 200 .RS
jpayne@68 201 .nf
jpayne@68 202 $ keyctl supports pkey
jpayne@68 203 echo $?
jpayne@68 204 0
jpayne@68 205 .fi
jpayne@68 206 .RE
jpayne@68 207
jpayne@68 208 which returns 0 if the capability is supported, 1 if it isn't and 3 if the
jpayne@68 209 name is not recognised. The capabilities supported are:
jpayne@68 210 .TP
jpayne@68 211 .B capabilities
jpayne@68 212 The kernel supports capability querying. If not, the other capabilities will
jpayne@68 213 be queried as best libkeyutils can manage.
jpayne@68 214 .TP
jpayne@68 215 .B persistent_keyrings
jpayne@68 216 The kernel supports persistent keyrings.
jpayne@68 217 .TP
jpayne@68 218 .B dh_compute
jpayne@68 219 The kernel supports Diffie-Hellman computation operations.
jpayne@68 220 .TP
jpayne@68 221 .B public_key
jpayne@68 222 The kernel supports public key operations.
jpayne@68 223 .TP
jpayne@68 224 .B big_key_type
jpayne@68 225 The kernel supports the big_key key type.
jpayne@68 226 .TP
jpayne@68 227 .B key_invalidate
jpayne@68 228 The kernel supports the invalidate key operaiton.
jpayne@68 229 .TP
jpayne@68 230 .B restrict_keyring
jpayne@68 231 The kernel supports the restrict_keyring operation.
jpayne@68 232 .TP
jpayne@68 233 .B move_key
jpayne@68 234 The kernel supports the move key operation.
jpayne@68 235
jpayne@68 236 .SS Show process keyrings
jpayne@68 237 \fBkeyctl show [\-x] [<keyring>]\fR
jpayne@68 238
jpayne@68 239 By default this command recursively shows what keyrings a process is subscribed
jpayne@68 240 to and what keys and keyrings they contain. If a keyring is specified then
jpayne@68 241 that keyring will be dumped instead. If \fB\-x\fR is specified then the keyring
jpayne@68 242 IDs will be dumped in hex instead of decimal.
jpayne@68 243 .SS Add a key to a keyring
jpayne@68 244 \fBkeyctl add\fR <type> <desc> <data> <keyring>
jpayne@68 245 .br
jpayne@68 246 \fBkeyctl padd\fR <type> <desc> <keyring>
jpayne@68 247
jpayne@68 248 This command creates a key of the specified type and description; instantiates
jpayne@68 249 it with the given data and attaches it to the specified keyring. It then prints
jpayne@68 250 the new key's ID on stdout:
jpayne@68 251
jpayne@68 252 .RS
jpayne@68 253 .nf
jpayne@68 254 $ keyctl add user mykey stuff @u
jpayne@68 255 26
jpayne@68 256 .fi
jpayne@68 257 .RE
jpayne@68 258
jpayne@68 259 The \fBpadd\fR variant of the command reads the data from stdin rather than
jpayne@68 260 taking it from the command line:
jpayne@68 261
jpayne@68 262 .RS
jpayne@68 263 .fi
jpayne@68 264 $ echo \-n stuff | keyctl padd user mykey @u
jpayne@68 265 26
jpayne@68 266 .fi
jpayne@68 267 .RE
jpayne@68 268 .SS Request a key
jpayne@68 269 \fBkeyctl request\fR <type> <desc> [<dest_keyring>]
jpayne@68 270 .br
jpayne@68 271 \fBkeyctl request2\fR <type> <desc> <info> [<dest_keyring>]
jpayne@68 272 .br
jpayne@68 273 \fBkeyctl prequest2\fR <type> <desc> [<dest_keyring>]
jpayne@68 274
jpayne@68 275 These three commands request the lookup of a key of the given type and
jpayne@68 276 description. The process's keyrings will be searched, and if a match is found
jpayne@68 277 the matching key's ID will be printed to stdout; and if a destination keyring
jpayne@68 278 is given, the key will be added to that keyring also.
jpayne@68 279
jpayne@68 280 If there is no key, the first command will simply return the error ENOKEY and
jpayne@68 281 fail. The second and third commands will create a partial key with the type and
jpayne@68 282 description, and call out to
jpayne@68 283 .IR /sbin/request\-key
jpayne@68 284 with that key and the
jpayne@68 285 extra information supplied. This will then attempt to instantiate the key in
jpayne@68 286 some manner, such that a valid key is obtained.
jpayne@68 287
jpayne@68 288 The third command is like the second, except that the callout information is
jpayne@68 289 read from stdin rather than being passed on the command line.
jpayne@68 290
jpayne@68 291 If a valid key is obtained, the ID will be printed and the key attached as if
jpayne@68 292 the original search had succeeded.
jpayne@68 293
jpayne@68 294 If there wasn't a valid key obtained, a temporary negative key will be attached
jpayne@68 295 to the destination keyring if given and the error "Requested key not available"
jpayne@68 296 will be given.
jpayne@68 297
jpayne@68 298 .RS
jpayne@68 299 .nf
jpayne@68 300 $ keyctl request2 user debug:hello wibble
jpayne@68 301 23
jpayne@68 302 $ echo \-n wibble | keyctl prequest2 user debug:hello
jpayne@68 303 23
jpayne@68 304 $ keyctl request user debug:hello
jpayne@68 305 23
jpayne@68 306 .fi
jpayne@68 307 .RE
jpayne@68 308 .SS Update a key
jpayne@68 309 \fBkeyctl update\fR <key> <data>
jpayne@68 310 .br
jpayne@68 311 \fBkeyctl pupdate\fR <key>
jpayne@68 312
jpayne@68 313 This command replaces the data attached to a key with a new set of data. If the
jpayne@68 314 type of the key doesn't support update then error "Operation not supported"
jpayne@68 315 will be returned.
jpayne@68 316
jpayne@68 317 .RS
jpayne@68 318 .nf
jpayne@68 319 $ keyctl update 23 zebra
jpayne@68 320 .fi
jpayne@68 321 .RE
jpayne@68 322
jpayne@68 323 The \fBpupdate\fR variant of the command reads the data from stdin rather than
jpayne@68 324 taking it from the command line:
jpayne@68 325
jpayne@68 326 .RS
jpayne@68 327 .nf
jpayne@68 328 $ echo \-n zebra | keyctl pupdate 23
jpayne@68 329 .fi
jpayne@68 330 .RE
jpayne@68 331 .SS Create a keyring
jpayne@68 332 \fBkeyctl newring\fR <name> <keyring>
jpayne@68 333
jpayne@68 334 This command creates a new keyring of the specified name and attaches it to the
jpayne@68 335 specified keyring. The ID of the new keyring will be printed to stdout if
jpayne@68 336 successful.
jpayne@68 337
jpayne@68 338 .RS
jpayne@68 339 .nf
jpayne@68 340 $ keyctl newring squelch @us
jpayne@68 341 27
jpayne@68 342 .fi
jpayne@68 343 .RE
jpayne@68 344 .SS Revoke a key
jpayne@68 345 \fBkeyctl revoke\fR <key>
jpayne@68 346
jpayne@68 347 This command marks a key as being revoked. Any further operations on that key
jpayne@68 348 (apart from unlinking it) will return error "Key has been revoked".
jpayne@68 349
jpayne@68 350 .RS
jpayne@68 351 .nf
jpayne@68 352 $ keyctl revoke 26
jpayne@68 353 $ keyctl describe 26
jpayne@68 354 keyctl_describe: Key has been revoked
jpayne@68 355 .fi
jpayne@68 356 .RE
jpayne@68 357 .SS Clear a keyring
jpayne@68 358 \fBkeyctl clear\fR <keyring>
jpayne@68 359
jpayne@68 360 This command unlinks all the keys attached to the specified keyring. Error
jpayne@68 361 "Not a directory" will be returned if the key specified is not a keyring.
jpayne@68 362
jpayne@68 363 .RS
jpayne@68 364 .nf
jpayne@68 365 $ keyctl clear 27
jpayne@68 366 .fi
jpayne@68 367 .RE
jpayne@68 368 .SS Link a key to a keyring
jpayne@68 369 \fBkeyctl link\fR <key> <keyring>
jpayne@68 370
jpayne@68 371 This command makes a link from the key to the keyring if there's enough
jpayne@68 372 capacity to do so. Error "Not a directory" will be returned if the destination
jpayne@68 373 is not a keyring. Error "Permission denied" will be returned if the key doesn't
jpayne@68 374 have link permission or the keyring doesn't have write permission. Error "File
jpayne@68 375 table overflow" will be returned if the keyring is full. Error "Resource
jpayne@68 376 deadlock avoided" will be returned if an attempt was made to introduce a
jpayne@68 377 recursive link.
jpayne@68 378
jpayne@68 379 .RS
jpayne@68 380 .nf
jpayne@68 381 $ keyctl link 23 27
jpayne@68 382 $ keyctl link 27 27
jpayne@68 383 keyctl_link: Resource deadlock avoided
jpayne@68 384 .fi
jpayne@68 385 .RE
jpayne@68 386 .SS Unlink a key from a keyring or the session keyring tree
jpayne@68 387 \fBkeyctl unlink\fR <key> [<keyring>]
jpayne@68 388
jpayne@68 389 If the keyring is specified, this command removes a link to the key from the
jpayne@68 390 keyring. Error "Not a directory" will be returned if the destination is not a
jpayne@68 391 keyring. Error "Permission denied" will be returned if the keyring doesn't have
jpayne@68 392 write permission. Error "No such file or directory" will be returned if the key
jpayne@68 393 is not linked to by the keyring.
jpayne@68 394
jpayne@68 395 If the keyring is not specified, this command performs a depth-first search of
jpayne@68 396 the session keyring tree and removes all the links to the nominated key that it
jpayne@68 397 finds (and that it is permitted to remove). It prints the number of successful
jpayne@68 398 unlinks before exiting.
jpayne@68 399
jpayne@68 400 .RS
jpayne@68 401 .nf
jpayne@68 402 $ keyctl unlink 23 27
jpayne@68 403 .fi
jpayne@68 404 .RE
jpayne@68 405 .SS Move a key between keyrings.
jpayne@68 406 \fBkeyctl move\fR [-f] <key> <from_keyring> <to_keyring>
jpayne@68 407
jpayne@68 408 This command moves a key from one keyring to another, atomically combining
jpayne@68 409 "keyctl unlink <key> <from_keyring>" and "keyctl link <key> <to_keyring>".
jpayne@68 410
jpayne@68 411 If the "-f" flag is present, any matching key will be displaced from
jpayne@68 412 "to_keyring"; if not present, the command will fail with the error message
jpayne@68 413 "File exists" if the key would otherwise displace another key from
jpayne@68 414 "to_keyring".
jpayne@68 415
jpayne@68 416 .RS
jpayne@68 417 .nf
jpayne@68 418 $ keyctl move 23 27 29
jpayne@68 419 $ keyctl move -f 71 @u @s
jpayne@68 420 .fi
jpayne@68 421 .RE
jpayne@68 422 .SS Search a keyring
jpayne@68 423 \fBkeyctl search\fR <keyring> <type> <desc> [<dest_keyring>]
jpayne@68 424
jpayne@68 425 This command non-recursively searches a keyring for a key of a particular type
jpayne@68 426 and description. If found, the ID of the key will be printed on stdout and the
jpayne@68 427 key will be attached to the destination keyring if present. Error "Requested
jpayne@68 428 key not available" will be returned if the key is not found.
jpayne@68 429
jpayne@68 430 .RS
jpayne@68 431 .nf
jpayne@68 432 $ keyctl search @us user debug:hello
jpayne@68 433 23
jpayne@68 434 $ keyctl search @us user debug:bye
jpayne@68 435 keyctl_search: Requested key not available
jpayne@68 436 .fi
jpayne@68 437 .RE
jpayne@68 438 .SS Restrict a keyring
jpayne@68 439 \fBkeyctl restrict_keyring\fR <keyring> [<type> [<restriction>]]
jpayne@68 440
jpayne@68 441 This command limits the linkage of keys to the given keyring using a provided
jpayne@68 442 restriction scheme. The scheme is associated with a given key type, with
jpayne@68 443 further details provided in the restriction option string. Options typically
jpayne@68 444 contain a restriction name possibly followed by key ids or other data relevant
jpayne@68 445 to the restriction. If no restriction scheme is provided, the keyring will
jpayne@68 446 reject all links.
jpayne@68 447
jpayne@68 448 .RS
jpayne@68 449 .nf
jpayne@68 450 $ keyctl restrict_keyring $1 asymmetric builtin_trusted
jpayne@68 451 .RE
jpayne@68 452 .SS Read a key
jpayne@68 453 \fBkeyctl read\fR <key>
jpayne@68 454 .br
jpayne@68 455 \fBkeyctl pipe\fR <key>
jpayne@68 456 .br
jpayne@68 457 \fBkeyctl print\fR <key>
jpayne@68 458
jpayne@68 459 These commands read the payload of a key. "read" prints it on stdout as a hex
jpayne@68 460 dump, "pipe" dumps the raw data to stdout and "print" dumps it to stdout
jpayne@68 461 directly if it's entirely printable or as a hexdump preceded by ":hex:" if not.
jpayne@68 462
jpayne@68 463 If the key type does not support reading of the payload, then error "Operation
jpayne@68 464 not supported" will be returned.
jpayne@68 465
jpayne@68 466 .RS
jpayne@68 467 .nf
jpayne@68 468 $ keyctl read 26
jpayne@68 469 1 bytes of data in key:
jpayne@68 470 62
jpayne@68 471 $ keyctl print 26
jpayne@68 472 b
jpayne@68 473 $ keyctl pipe 26
jpayne@68 474 $
jpayne@68 475 .fi
jpayne@68 476 .RE
jpayne@68 477 .SS List a keyring
jpayne@68 478 \fBkeyctl list\fR <keyring>
jpayne@68 479 .br
jpayne@68 480 \fBkeyctl rlist\fR <keyring>
jpayne@68 481
jpayne@68 482 These commands list the contents of a key as a keyring. "list" pretty prints
jpayne@68 483 the contents and "rlist" just produces a space-separated list of key IDs.
jpayne@68 484
jpayne@68 485 No attempt is made to check that the specified keyring is a keyring.
jpayne@68 486
jpayne@68 487 .RS
jpayne@68 488 .nf
jpayne@68 489 $ keyctl list @us
jpayne@68 490 2 keys in keyring:
jpayne@68 491 22: vrwsl\-\-\-\-\-\-\-\-\-\- 4043 \-1 keyring: _uid.4043
jpayne@68 492 23: vrwsl\-\-\-\-\-\-\-\-\-\- 4043 4043 user: debug:hello
jpayne@68 493 $ keyctl rlist @us
jpayne@68 494 22 23
jpayne@68 495 .fi
jpayne@68 496 .RE
jpayne@68 497 .SS Describe a key
jpayne@68 498 \fBkeyctl describe\fR <keyring>
jpayne@68 499 .br
jpayne@68 500 \fBkeyctl rdescribe\fR <keyring> [sep]
jpayne@68 501
jpayne@68 502 These commands fetch a description of a keyring. "describe" pretty prints the
jpayne@68 503 description in the same fashion as the "list" command; "rdescribe" prints the
jpayne@68 504 raw data returned from the kernel.
jpayne@68 505
jpayne@68 506 .RS
jpayne@68 507 .nf
jpayne@68 508 $ keyctl describe @us
jpayne@68 509 \-5: vrwsl\-\-\-\-\-\-\-\-\-\- 4043 \-1 keyring: _uid_ses.4043
jpayne@68 510 $ keyctl rdescribe @us
jpayne@68 511 keyring;4043;\-1;3f1f0000;_uid_ses.4043
jpayne@68 512 .fi
jpayne@68 513 .RE
jpayne@68 514
jpayne@68 515 The raw string is "<type>;<uid>;<gid>;<perms>;<description>", where \fIuid\fR
jpayne@68 516 and \fIgid\fR are the decimal user and group IDs, \fIperms\fR is the
jpayne@68 517 permissions mask in hex, \fItype\fR and \fIdescription\fR are the type name and
jpayne@68 518 description strings (neither of which will contain semicolons).
jpayne@68 519 .SS Change the access controls on a key
jpayne@68 520 \fBkeyctl chown\fR <key> <uid>
jpayne@68 521 .br
jpayne@68 522 \fBkeyctl chgrp\fR <key> <gid>
jpayne@68 523
jpayne@68 524 These two commands change the UID and GID associated with evaluating a key's
jpayne@68 525 permissions mask. The UID also governs which quota a key is taken out of.
jpayne@68 526
jpayne@68 527 The chown command is not currently supported; attempting it will earn the error
jpayne@68 528 "Operation not supported" at best.
jpayne@68 529
jpayne@68 530 For non-superuser users, the GID may only be set to the process's GID or a GID
jpayne@68 531 in the process's groups list. The superuser may set any GID it likes.
jpayne@68 532
jpayne@68 533 .RS
jpayne@68 534 .nf
jpayne@68 535 $ sudo keyctl chown 27 0
jpayne@68 536 keyctl_chown: Operation not supported
jpayne@68 537 $ sudo keyctl chgrp 27 0
jpayne@68 538 .fi
jpayne@68 539 .RE
jpayne@68 540 .SS Set the permissions mask on a key
jpayne@68 541 \fBkeyctl setperm\fR <key> <mask>
jpayne@68 542
jpayne@68 543 This command changes the permission control mask on a key. The mask may be
jpayne@68 544 specified as a hex number if it begins "0x", an octal number if it begins "0"
jpayne@68 545 or a decimal number otherwise.
jpayne@68 546
jpayne@68 547 The hex numbers are a combination of:
jpayne@68 548
jpayne@68 549 .RS
jpayne@68 550 .nf
jpayne@68 551 Possessor UID GID Other Permission Granted
jpayne@68 552 ======== ======== ======== ======== ==================
jpayne@68 553 01000000 00010000 00000100 00000001 View
jpayne@68 554 02000000 00020000 00000200 00000002 Read
jpayne@68 555 04000000 00040000 00000400 00000004 Write
jpayne@68 556 08000000 00080000 00000800 00000008 Search
jpayne@68 557 10000000 00100000 00001000 00000010 Link
jpayne@68 558 20000000 00200000 00002000 00000020 Set Attribute
jpayne@68 559 3f000000 003f0000 00003f00 0000003f All
jpayne@68 560 .fi
jpayne@68 561 .RE
jpayne@68 562
jpayne@68 563 \fIView\fR permits the type, description and other parameters of a key to be
jpayne@68 564 viewed.
jpayne@68 565
jpayne@68 566 \fIRead\fR permits the payload (or keyring list) to be read if supported by the
jpayne@68 567 type.
jpayne@68 568
jpayne@68 569 \fIWrite\fR permits the payload (or keyring list) to be modified or updated.
jpayne@68 570
jpayne@68 571 \fISearch\fR on a key permits it to be found when a keyring to which it is
jpayne@68 572 linked is searched.
jpayne@68 573
jpayne@68 574 \fILink\fR permits a key to be linked to a keyring.
jpayne@68 575
jpayne@68 576 \fISet Attribute\fR permits a key to have its owner, group membership,
jpayne@68 577 permissions mask and timeout changed.
jpayne@68 578
jpayne@68 579 .RS
jpayne@68 580 .nf
jpayne@68 581 $ keyctl setperm 27 0x1f1f1f00
jpayne@68 582 .fi
jpayne@68 583 .RE
jpayne@68 584 .SS Start a new session with fresh keyrings
jpayne@68 585 \fBkeyctl session\fR
jpayne@68 586 .br
jpayne@68 587 \fBkeyctl session\fR \- [<prog> <arg1> <arg2> ...]
jpayne@68 588 .br
jpayne@68 589 \fBkeyctl session\fR <name> [<prog> <arg1> <arg2> ...]
jpayne@68 590
jpayne@68 591 These commands join or create a new keyring and then run a shell or other
jpayne@68 592 program with that keyring as the session key.
jpayne@68 593
jpayne@68 594 The variation with no arguments just creates an anonymous session keyring and
jpayne@68 595 attaches that as the session keyring; it then exec's $SHELL.
jpayne@68 596
jpayne@68 597 The variation with a dash in place of a name creates an anonymous session
jpayne@68 598 keyring and attaches that as the session keyring; it then exec's the supplied
jpayne@68 599 command, or $SHELL if one isn't supplied.
jpayne@68 600
jpayne@68 601 The variation with a name supplied creates or joins the named keyring and
jpayne@68 602 attaches that as the session keyring; it then exec's the supplied command, or
jpayne@68 603 $SHELL if one isn't supplied.
jpayne@68 604
jpayne@68 605 .RS
jpayne@68 606 .nf
jpayne@68 607 $ keyctl rdescribe @s
jpayne@68 608 keyring;4043;\-1;3f1f0000;_uid_ses.4043
jpayne@68 609
jpayne@68 610 $ keyctl session
jpayne@68 611 Joined session keyring: 28
jpayne@68 612
jpayne@68 613 $ keyctl rdescribe @s
jpayne@68 614 keyring;4043;4043;3f1f0000;_ses.24082
jpayne@68 615
jpayne@68 616 $ keyctl session \-
jpayne@68 617 Joined session keyring: 29
jpayne@68 618 $ keyctl rdescribe @s
jpayne@68 619 keyring;4043;4043;3f1f0000;_ses.24139
jpayne@68 620
jpayne@68 621 $ keyctl session \- keyctl rdescribe @s
jpayne@68 622 Joined session keyring: 30
jpayne@68 623 keyring;4043;4043;3f1f0000;_ses.24185
jpayne@68 624
jpayne@68 625 $ keyctl session fish
jpayne@68 626 Joined session keyring: 34
jpayne@68 627 $ keyctl rdescribe @s
jpayne@68 628 keyring;4043;4043;3f1f0000;fish
jpayne@68 629
jpayne@68 630 $ keyctl session fish keyctl rdesc @s
jpayne@68 631 Joined session keyring: 35
jpayne@68 632 keyring;4043;4043;3f1f0000;fish
jpayne@68 633 .fi
jpayne@68 634 .RE
jpayne@68 635 .SS Instantiate a key
jpayne@68 636 \fBkeyctl instantiate\fR <key> <data> <keyring>
jpayne@68 637 .br
jpayne@68 638 \fBkeyctl pinstantiate\fR <key> <keyring>
jpayne@68 639 .br
jpayne@68 640 \fBkeyctl negate\fR <key> <timeout> <keyring>
jpayne@68 641 .br
jpayne@68 642 \fBkeyctl reject\fR <key> <timeout> <error> <keyring>
jpayne@68 643
jpayne@68 644 These commands are used to attach data to a partially set up key (as created by
jpayne@68 645 the kernel and passed to
jpayne@68 646 .IR /sbin/request\-key ).
jpayne@68 647 "instantiate" marks a key as
jpayne@68 648 being valid and attaches the data as the payload. "negate" and "reject" mark a
jpayne@68 649 key as invalid and sets a timeout on it so that it'll go away after a while.
jpayne@68 650 This prevents a lot of quickly sequential requests from slowing the system down
jpayne@68 651 overmuch when they all fail, as all subsequent requests will then fail with
jpayne@68 652 error "Requested key not found" (if negated) or the specified error (if
jpayne@68 653 rejected) until the negative key has expired.
jpayne@68 654
jpayne@68 655 Reject's error argument can either be a UNIX error number or one of
jpayne@68 656 .BR "" "'" rejected "', '" expired "' or '" revoked "'."
jpayne@68 657
jpayne@68 658 The newly instantiated key will be attached to the specified keyring.
jpayne@68 659
jpayne@68 660 These commands may only be run from the program run by request\-key - a special
jpayne@68 661 authorisation key is set up by the kernel and attached to the request\-key's
jpayne@68 662 session keyring. This special key is revoked once the key to which it refers
jpayne@68 663 has been instantiated one way or another.
jpayne@68 664
jpayne@68 665 .RS
jpayne@68 666 .nf
jpayne@68 667 $ keyctl instantiate $1 "Debug $3" $4
jpayne@68 668 $ keyctl negate $1 30 $4
jpayne@68 669 $ keyctl reject $1 30 64 $4
jpayne@68 670 .fi
jpayne@68 671 .RE
jpayne@68 672
jpayne@68 673 The \fBpinstantiate\fR variant of the command reads the data from stdin rather
jpayne@68 674 than taking it from the command line:
jpayne@68 675
jpayne@68 676 .RS
jpayne@68 677 .nf
jpayne@68 678 $ echo \-n "Debug $3" | keyctl pinstantiate $1 $4
jpayne@68 679 .fi
jpayne@68 680 .RE
jpayne@68 681 .SS Set the expiry time on a key
jpayne@68 682 \fBkeyctl timeout\fR <key> <timeout>
jpayne@68 683
jpayne@68 684 This command is used to set the timeout on a key, or clear an existing timeout
jpayne@68 685 if the value specified is zero. The timeout is given as a number of seconds
jpayne@68 686 into the future.
jpayne@68 687
jpayne@68 688 .RS
jpayne@68 689 .nf
jpayne@68 690 $ keyctl timeout $1 45
jpayne@68 691 .fi
jpayne@68 692 .RE
jpayne@68 693 .SS Retrieve a key's security context
jpayne@68 694 \fBkeyctl security\fR <key>
jpayne@68 695
jpayne@68 696 This command is used to retrieve a key's LSM security context. The label is
jpayne@68 697 printed on stdout.
jpayne@68 698
jpayne@68 699 .RS
jpayne@68 700 .nf
jpayne@68 701 $ keyctl security @s
jpayne@68 702 unconfined_u:unconfined_r:unconfined_t:s0\-s0:c0.c1023
jpayne@68 703 .fi
jpayne@68 704 .RE
jpayne@68 705 .SS Give the parent process a new session keyring
jpayne@68 706 \fBkeyctl new_session\fR
jpayne@68 707
jpayne@68 708 This command is used to give the invoking process (typically a shell) a new
jpayne@68 709 session keyring, discarding its old session keyring.
jpayne@68 710
jpayne@68 711 .RS
jpayne@68 712 .nf
jpayne@68 713 $ keyctl session foo
jpayne@68 714 Joined session keyring: 723488146
jpayne@68 715 $ keyctl show
jpayne@68 716 Session Keyring
jpayne@68 717 \-3 \-\-alswrv 0 0 keyring: foo
jpayne@68 718 $ keyctl new_session
jpayne@68 719 490511412
jpayne@68 720 $ keyctl show
jpayne@68 721 Session Keyring
jpayne@68 722 \-3 \-\-alswrv 0 0 keyring: _ses
jpayne@68 723 .fi
jpayne@68 724 .RE
jpayne@68 725
jpayne@68 726 Note that this affects the \fIparent\fP of the process that invokes the system
jpayne@68 727 call, and so may only affect processes with matching credentials.
jpayne@68 728 Furthermore, the change does not take effect till the parent process next
jpayne@68 729 transitions from kernel space to user space - typically when the \fBwait\fP()
jpayne@68 730 system call returns.
jpayne@68 731 .SS Remove dead keys from the session keyring tree
jpayne@68 732 \fBkeyctl reap\fR
jpayne@68 733
jpayne@68 734 This command performs a depth-first search of the caller's session keyring tree
jpayne@68 735 and attempts to unlink any key that it finds that is inaccessible due to
jpayne@68 736 expiry, revocation, rejection or negation. It does not attempt to remove live
jpayne@68 737 keys that are unavailable simply due to a lack of granted permission.
jpayne@68 738
jpayne@68 739 A key that is designated reapable will only be removed from a keyring if the
jpayne@68 740 caller has Write permission on that keyring, and only keyrings that grant
jpayne@68 741 Search permission to the caller will be searched.
jpayne@68 742
jpayne@68 743 The command prints the number of keys reaped before it exits. If the \fB\-v\fR
jpayne@68 744 flag is passed then the reaped keys are listed as they're being reaped,
jpayne@68 745 together with the success or failure of the unlink.
jpayne@68 746 .SS Remove matching keys from the session keyring tree
jpayne@68 747 \fBkeyctl\fR purge <type>
jpayne@68 748 .br
jpayne@68 749 \fBkeyctl\fR purge [\-i] [\-p] <type> <desc>
jpayne@68 750 .br
jpayne@68 751 \fBkeyctl\fR purge \-s <type> <desc>
jpayne@68 752
jpayne@68 753 These commands perform a depth-first search to find matching keys in the
jpayne@68 754 caller's session keyring tree and attempts to unlink them. The number of
jpayne@68 755 keys successfully unlinked is printed at the end.
jpayne@68 756
jpayne@68 757 The keyrings must grant Read and View permission to the caller to be searched,
jpayne@68 758 and the keys to be removed must also grant View permission. Keys can only be
jpayne@68 759 removed from keyrings that grant Write permission.
jpayne@68 760
jpayne@68 761 The first variant purges all keys of the specified type.
jpayne@68 762
jpayne@68 763 The second variant purges all keys of the specified type that also match the
jpayne@68 764 given description literally. The \-i flag allows a case-independent match and
jpayne@68 765 the \-p flag allows a prefix match.
jpayne@68 766
jpayne@68 767 The third variant purges all keys of the specified type and matching
jpayne@68 768 description using the key type's comparator in the kernel to match the
jpayne@68 769 description. This permits the key type to match a key with a variety of
jpayne@68 770 descriptions.
jpayne@68 771 .SS Get persistent keyring
jpayne@68 772 \fBkeyctl\fR get_persistent <keyring> [<uid>]
jpayne@68 773
jpayne@68 774 This command gets the persistent keyring for either the current UID or the
jpayne@68 775 specified UID and attaches it to the nominated keyring. The persistent
jpayne@68 776 keyring's ID will be printed on stdout.
jpayne@68 777
jpayne@68 778 The kernel will create the keyring if it doesn't exist and every time this
jpayne@68 779 command is called, will reset the expiration timeout on the keyring to the
jpayne@68 780 value in:
jpayne@68 781 .IP
jpayne@68 782 /proc/sys/kernel/keys/persistent_keyring_expiry
jpayne@68 783 .P
jpayne@68 784 (by default three days). Should the timeout be reached, the persistent keyring
jpayne@68 785 will be removed and everything it pins can then be garbage collected.
jpayne@68 786
jpayne@68 787 If a UID other than the process's real or effective UIDs is specified, then an
jpayne@68 788 error will be given if the process does not have the CAP_SETUID capability.
jpayne@68 789 .SS Compute a Diffie-Hellman shared secret or public key
jpayne@68 790 \fBkeyctl\fR dh_compute <private> <prime> <base>
jpayne@68 791
jpayne@68 792 This command computes either a Diffie-Hellman shared secret or the
jpayne@68 793 public key corresponding to the provided private key using the
jpayne@68 794 payloads of three keys. The computation is:
jpayne@68 795 .IP
jpayne@68 796 base ^ private (mod prime)
jpayne@68 797 .P
jpayne@68 798 The three inputs must be user keys with read permission. If the
jpayne@68 799 provided base key contains the shared generator value, the public key
jpayne@68 800 will be computed. If the provided base key contains the remote public
jpayne@68 801 key value, the shared secret will be computed.
jpayne@68 802
jpayne@68 803 The result is printed to stdout as a hex dump.
jpayne@68 804
jpayne@68 805 .RS
jpayne@68 806 .nf
jpayne@68 807 $ keyctl dh_compute $1 $2 $3
jpayne@68 808 8 bytes of data in result:
jpayne@68 809 00010203 04050607
jpayne@68 810 .SS Compute a Diffie-Hellman shared secret and derive key material
jpayne@68 811 \fBkeyctl\fR dh_compute_kdf <private> <prime> <base> <output_length> <hash_type>
jpayne@68 812
jpayne@68 813 This command computes a Diffie-Hellman shared secret and derives
jpayne@68 814 key material from the shared secret using a key derivation function (KDF).
jpayne@68 815 The shared secret is derived as outlined above and is input to the KDF
jpayne@68 816 using the specified hash type. The hash type must point to a hash name
jpayne@68 817 known to the kernel crypto API.
jpayne@68 818
jpayne@68 819 The operation derives key material of the length specified by the caller.
jpayne@68 820
jpayne@68 821 The operation is compliant to the specification of SP800-56A.
jpayne@68 822
jpayne@68 823 The result is printed to stdout as hex dump.
jpayne@68 824 .SS Compute a Diffie-Hellman shared secret and apply KDF with other input
jpayne@68 825 \fBkeyctl\fR dh_compute_kdf_oi <private> <prime> <base> <output_length> <hash_type>
jpayne@68 826
jpayne@68 827 This command is identical to the command
jpayne@68 828 .IR dh_compute_kdf
jpayne@68 829 to generate a Diffie-Hellman shared secret followed by a key derivation
jpayne@68 830 operation. This command allows the caller to provide the other input data
jpayne@68 831 (OI data) compliant to SP800-56A via stdin.
jpayne@68 832 .fi
jpayne@68 833 .RE
jpayne@68 834 .SS Perform public-key operations with an asymmetric key
jpayne@68 835 \fBkeyctl\fR pkey_query <key> <pass> [k=v]*
jpayne@68 836 .br
jpayne@68 837 \fBkeyctl\fR pkey_encrypt <key> <pass> <datafile> [k=v]* > <encfile>
jpayne@68 838 .br
jpayne@68 839 \fBkeyctl\fR pkey_decrypt <key> <pass> <encfile> [k=v]* > <datafile>
jpayne@68 840 .br
jpayne@68 841 \fBkeyctl\fR pkey_sign <key> <pass> <datafile> [k=v]* > <sigfile>
jpayne@68 842 .br
jpayne@68 843 \fBkeyctl\fR pkey_verify <key> <pass> <datafile> <sigfile> [k=v]*
jpayne@68 844 .PP
jpayne@68 845 These commands query an asymmetric key, encrypt data with it, decrypt the
jpayne@68 846 encrypted data, generate a signature over some data and verify that signature.
jpayne@68 847 For encrypt, decrypt and sign, the resulting data is written to stdout; verify
jpayne@68 848 reads the data and the signature files and compares them.
jpayne@68 849 .PP
jpayne@68 850 [\fB!\fP] NOTE that the data is of very limited capacity, with no more bits
jpayne@68 851 than the size of the key. For signatures, the caller is expected to digest
jpayne@68 852 the actual data and pass in the result of the digest as the datafile. The
jpayne@68 853 name of the digest should be specified on the end of the command line as
jpayne@68 854 "hash=<name>".
jpayne@68 855 .PP
jpayne@68 856 The
jpayne@68 857 .I key
jpayne@68 858 ID indicates the key to use;
jpayne@68 859 .I pass
jpayne@68 860 is a placeholder for future password provision and should be "0" for the
jpayne@68 861 moment;
jpayne@68 862 .I datafile
jpayne@68 863 is the unencrypted data to be encrypted, signed or to have its signature
jpayne@68 864 checked;
jpayne@68 865 .I encfile
jpayne@68 866 is a file containing encrypted data; and
jpayne@68 867 .I sigfile
jpayne@68 868 is a file containing a signature.
jpayne@68 869 .PP
jpayne@68 870 A list of parameters in "key[=val]" form can be included on the end of the
jpayne@68 871 command line. These specify things like the digest algorithm used
jpayne@68 872 ("hash=<name>") or the encoding form ("enc=<type>").
jpayne@68 873 .PP
jpayne@68 874 .RS
jpayne@68 875 .nf
jpayne@68 876 k=`keyctl padd asymmetric "" @s <key.pkcs8.der`
jpayne@68 877 keyctl pkey_query $k 0 enc=pkcs1 hash=sha256
jpayne@68 878 keyctl pkey_encrypt $k 0 foo.hash enc=pkcs1 >foo.enc
jpayne@68 879 keyctl pkey_decrypt $k 0 foo.enc enc=pkcs1 >foo.hash
jpayne@68 880 keyctl pkey_sign $k 0 foo.hash enc=pkcs1 hash=sha256 >foo.sig
jpayne@68 881 keyctl pkey_verify $k 0 foo.hash foo.sig enc=pkcs1 hash=sha256
jpayne@68 882 .fi
jpayne@68 883 .RE
jpayne@68 884 .PP
jpayne@68 885 See asymmetric-key(7) for more information.
jpayne@68 886
jpayne@68 887 .SH ERRORS
jpayne@68 888 There are a number of common errors returned by this program:
jpayne@68 889
jpayne@68 890 "Not a directory" - a key wasn't a keyring.
jpayne@68 891
jpayne@68 892 "Requested key not found" - the looked for key isn't available.
jpayne@68 893
jpayne@68 894 "Key has been revoked" - a revoked key was accessed.
jpayne@68 895
jpayne@68 896 "Key has expired" - an expired key was accessed.
jpayne@68 897
jpayne@68 898 "Permission denied" - permission was denied by a UID/GID/mask combination.
jpayne@68 899 .SH SEE ALSO
jpayne@68 900 .ad l
jpayne@68 901 .nh
jpayne@68 902 .BR keyctl (1),
jpayne@68 903 .BR keyctl (2),
jpayne@68 904 .BR request_key (2),
jpayne@68 905 .BR keyctl (3),
jpayne@68 906 .BR request\-key.conf (5),
jpayne@68 907 .BR keyrings (7),
jpayne@68 908 .BR request\-key (8)