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 .\"             Author: David Howells <dhowells@redhat.com>
  14 .\"             Documentation/security/keys.txt
  15 .\" FIXME Document KEYCTL_INSTANTIATE_IOV (new in 2.6.39)
  16 .\"             commit ee009e4a0d4555ed522a631bae9896399674f064
  17 .\"             Author: David Howells <dhowells@redhat.com>
  18 .\"             Documentation/security/keys.txt
  19 .\" FIXME Document KEYCTL_INVALIDATE (new in 3.5)
  20 .\"             commit fd75815f727f157a05f4c96b5294a4617c0557da
  21 .\"             Author: David Howells <dhowells@redhat.com>
  22 .\"             Documentation/security/keys.txt
  23 .\" FIXME Document KEYCTL_GET_PERSISTENT (new in 3.13)
  24 .\"             commit f36f8c75ae2e7d4da34f4c908cebdb4aa42c977e
  25 .\"             Author: David Howells <dhowells@redhat.com>
  26 .\"
  27 .TH KEYCTL 2 2014-01-22 Linux "Linux Key Management Calls"
  28 .SH NAME
  29 keyctl \- manipulate the kernel's key management facility
  30 .SH SYNOPSIS
  31 .nf
  32 .B #include <keyutils.h>
  33 .sp
  34 .BI "long keyctl(int " cmd ", ...);"
  35 .fi
  36 .SH DESCRIPTION
  37 .BR keyctl ()
  38 has a number of functions available:
  39 .TP
  40 .B KEYCTL_GET_KEYRING_ID
  41 Ask for a keyring's ID.
  42 .TP
  43 .B KEYCTL_JOIN_SESSION_KEYRING
  44 Join or start named session keyring.
  45 .TP
  46 .B KEYCTL_UPDATE
  47 Update a key.
  48 .TP
  49 .B KEYCTL_REVOKE
  50 Revoke a key.
  51 .TP
  52 .B KEYCTL_CHOWN
  53 Set ownership of a key.
  54 .TP
  55 .B KEYCTL_SETPERM
  56 Set perms on a key.
  57 .TP
  58 .B KEYCTL_DESCRIBE
  59 Describe a key.
  60 .TP
  61 .B KEYCTL_CLEAR
  62 Clear contents of a keyring.
  63 .TP
  64 .B KEYCTL_LINK
  65 Link a key into a keyring.
  66 .TP
  67 .B KEYCTL_UNLINK
  68 Unlink a key from a keyring.
  69 .TP
  70 .B KEYCTL_SEARCH
  71 Search for a key in a keyring.
  72 .TP
  73 .B KEYCTL_READ
  74 Read a key or keyring's contents.
  75 .TP
  76 .B KEYCTL_INSTANTIATE
  77 Instantiate a partially constructed key.
  78 .TP
  79 .B KEYCTL_NEGATE
  80 Negate a partially constructed key.
  81 .TP
  82 .B KEYCTL_SET_REQKEY_KEYRING
  83 Set default request-key keyring.
  84 .TP
  85 .B KEYCTL_SET_TIMEOUT
  86 Set timeout on a key.
  87 .TP
  88 .B KEYCTL_ASSUME_AUTHORITY
  89 Assume authority to instantiate key.
  90 .P
  91 These are wrapped by
  92 .B libkeyutils
  93 into individual functions to permit compiler the compiler to check types.
  94 See the
  95 .B See Also
  96 section at the bottom.
  97 .SH RETURN VALUE
  98 On success
  99 .BR keyctl ()
 100 returns the serial number of the key it found.
 101 On error, the value \-1
 102 will be returned and errno will have been set to an appropriate error.
 103 .SH ERRORS
 104 .TP
 105 .B EACCES
 106 A key operation wasn't permitted.
 107 .TP
 108 .B EDQUOT
 109 The key quota for the caller's user would be exceeded by creating a key or
 110 linking it to the keyring.
 111 .TP
 112 .B EKEYEXPIRED
 113 An expired key was found or specified.
 114 .TP
 115 .B EKEYREJECTED
 116 A rejected key was found or specified.
 117 .TP
 118 .B EKEYREVOKED
 119 A revoked key was found or specified.
 120 .TP
 121 .B ENOKEY
 122 No matching key was found or an invalid key was specified.
 123 .SH LINKING
 124 Although this is a Linux system call, it is not present in
 125 .I libc
 126 but can be found rather in
 127 .IR libkeyutils .
 128 When linking,
 129 .B -lkeyutils
 130 should be specified to the linker.
 131 .SH SEE ALSO
 132 .ad l
 133 .nh
 134 .BR keyctl (1),
 135 .BR add_key (2),
 136 .BR request_key (2),
 137 .BR keyctl_set_timeout (3),
 138 .BR keyctl_chown (3),
 139 .BR keyctl_clear (3),
 140 .BR keyctl_describe (3),
 141 .BR keyctl_describe_alloc (3),
 142 .BR keyctl_get_keyring_ID (3),
 143 .BR keyctl_instantiate (3),
 144 .BR keyctl_join_session_keyring (3),
 145 .BR keyctl_link (3),
 146 .BR keyctl_negate (3),
 147 .BR keyctl_revoke (3),
 148 .BR keyctl_search (3),
 149 .BR keyctl_setperm (3),
 150 .BR keyctl_set_reqkey_keyring (3),
 151 .BR keyctl_set_timeout (3),
 152 .BR keyctl_read (3),
 153 .BR keyctl_read_alloc (3),
 154 .BR keyctl_unlink (3),
 155 .BR keyctl_update (3),
 156 .BR request-key (8)
 157
 158 The kernel source file
 159 .IR Documentation/security/keys.txt .
 160 .SH COLOPHON
 161 This page is part of release 3.68 of the Linux
 162 .I man-pages
 163 project.
 164 A description of the project,
 165 information about reporting bugs,
 166 and the latest version of this page,
 167 can be found at
 168 \%http://www.kernel.org/doc/man\-pages/.