original/man2/keyctl.2

   1 .\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved.
   2 .\" Written by David Howells (dhowells@redhat.com)
   3 .\"
   4 .\" %%%LICENSE_START(GPLv2+_SW_ONEPARA)
   5 .\" This program is free software; you can redistribute it and/or
   6 .\" modify it under the terms of the GNU General Public License
   7 .\" as published by the Free Software Foundation; either version
   8 .\" 2 of the License, or (at your option) any later version.
   9 .\" %%%LICENSE_END
  10 .\"
  11 .\" FIXME Document KEYCTL_REJECT (new in 2.6.39)
  12 .\"             commit fdd1b94581782a2ddf9124414e5b7a5f48ce2f9c
  13 .\"             Documentation/security/keys.txt
  14 .\" FIXME Document KEYCTL_INSTANTIATE_IOV (new in 2.6.39)
  15 .\"             commit ee009e4a0d4555ed522a631bae9896399674f064
  16 .\"             Documentation/security/keys.txt
  17 .\" FIXME Document KEYCTL_INVALIDATE (new in 3.5)
  18 .\"             commit fd75815f727f157a05f4c96b5294a4617c0557da
  19 .\"             Documentation/security/keys.txt
  20 .\"
  21 .TH KEYCTL 2 2010-02-25 Linux "Linux Key Management Calls"
  22 .SH NAME
  23 keyctl \- manipulate the kernel's key management facility
  24 .SH SYNOPSIS
  25 .nf
  26 .B #include <keyutils.h>
  27 .sp
  28 .BI "long keyctl(int " cmd ", ...);"
  29 .fi
  30 .SH DESCRIPTION
  31 .BR keyctl ()
  32 has a number of functions available:
  33 .TP
  34 .B KEYCTL_GET_KEYRING_ID
  35 Ask for a keyring's ID.
  36 .TP
  37 .B KEYCTL_JOIN_SESSION_KEYRING
  38 Join or start named session keyring.
  39 .TP
  40 .B KEYCTL_UPDATE
  41 Update a key.
  42 .TP
  43 .B KEYCTL_REVOKE
  44 Revoke a key.
  45 .TP
  46 .B KEYCTL_CHOWN
  47 Set ownership of a key.
  48 .TP
  49 .B KEYCTL_SETPERM
  50 Set perms on a key.
  51 .TP
  52 .B KEYCTL_DESCRIBE
  53 Describe a key.
  54 .TP
  55 .B KEYCTL_CLEAR
  56 Clear contents of a keyring.
  57 .TP
  58 .B KEYCTL_LINK
  59 Link a key into a keyring.
  60 .TP
  61 .B KEYCTL_UNLINK
  62 Unlink a key from a keyring.
  63 .TP
  64 .B KEYCTL_SEARCH
  65 Search for a key in a keyring.
  66 .TP
  67 .B KEYCTL_READ
  68 Read a key or keyring's contents.
  69 .TP
  70 .B KEYCTL_INSTANTIATE
  71 Instantiate a partially constructed key.
  72 .TP
  73 .B KEYCTL_NEGATE
  74 Negate a partially constructed key.
  75 .TP
  76 .B KEYCTL_SET_REQKEY_KEYRING
  77 Set default request-key keyring.
  78 .TP
  79 .B KEYCTL_SET_TIMEOUT
  80 Set timeout on a key.
  81 .TP
  82 .B KEYCTL_ASSUME_AUTHORITY
  83 Assume authority to instantiate key.
  84 .P
  85 These are wrapped by
  86 .B libkeyutils
  87 into individual functions to permit compiler the compiler to check types.
  88 See the
  89 .B See Also
  90 section at the bottom.
  91 .SH RETURN VALUE
  92 On success
  93 .BR keyctl ()
  94 returns the serial number of the key it found.
  95 On error, the value \-1
  96 will be returned and errno will have been set to an appropriate error.
  97 .SH ERRORS
  98 .TP
  99 .B EACCES
 100 A key operation wasn't permitted.
 101 .TP
 102 .B EDQUOT
 103 The key quota for the caller's user would be exceeded by creating a key or
 104 linking it to the keyring.
 105 .TP
 106 .B EKEYEXPIRED
 107 An expired key was found or specified.
 108 .TP
 109 .B EKEYREJECTED
 110 A rejected key was found or specified.
 111 .TP
 112 .B EKEYREVOKED
 113 A revoked key was found or specified.
 114 .TP
 115 .B ENOKEY
 116 No matching key was found or an invalid key was specified.
 117 .SH LINKING
 118 Although this is a Linux system call, it is not present in
 119 .I libc
 120 but can be found rather in
 121 .IR libkeyutils .
 122 When linking,
 123 .B -lkeyutils
 124 should be specified to the linker.
 125 .SH SEE ALSO
 126 .ad l
 127 .nh
 128 .BR keyctl (1),
 129 .BR add_key (2),
 130 .BR request_key (2),
 131 .BR keyctl_set_timeout (3),
 132 .BR keyctl_chown (3),
 133 .BR keyctl_clear (3),
 134 .BR keyctl_describe (3),
 135 .BR keyctl_describe_alloc (3),
 136 .BR keyctl_get_keyring_ID (3),
 137 .BR keyctl_instantiate (3),
 138 .BR keyctl_join_session_keyring (3),
 139 .BR keyctl_link (3),
 140 .BR keyctl_negate (3),
 141 .BR keyctl_revoke (3),
 142 .BR keyctl_search (3),
 143 .BR keyctl_setperm (3),
 144 .BR keyctl_set_reqkey_keyring (3),
 145 .BR keyctl_set_timeout (3),
 146 .BR keyctl_read (3),
 147 .BR keyctl_read_alloc (3),
 148 .BR keyctl_unlink (3),
 149 .BR keyctl_update (3),
 150 .BR request-key (8)