keyctl_search.3

   1 .\"
   2 .\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved.
   3 .\" Written by David Howells (dhowells@redhat.com)
   4 .\"
   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 .\"
  10 .TH KEYCTL_SEARCH 3 "4 May 2006" Linux "Linux Key Management Calls"
  11 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
  12 .SH NAME
  13 keyctl_search \- Search a keyring for a key
  14 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
  15 .SH SYNOPSIS
  16 .nf
  17 .B #include <keyutils.h>
  18 .sp
  19 .BI "long keyctl_search(key_serial_t " keyring ", const char *" type ,
  20 .BI "const char *" description ", key_serial_t " destination ");"
  21 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
  22 .SH DESCRIPTION
  23 .BR keyctl_search ()
  24 recursively searches the
  25 .I keyring
  26 for a key of the specified
  27 .I type
  28 and
  29 .IR description .
  30 .P
  31 If found, the key will be attached to the
  32 .I destination
  33 keyring (if given), and its serial number will be returned.
  34 .P
  35 The source keyring must grant
  36 .B search
  37 permission to the caller, and for a key to be found, it must also grant
  38 .B search
  39 permission to the caller.  Child keyrings will be only be recursively searched
  40 if they grant
  41 .B search
  42 permission to the caller as well.
  43 .P
  44 If the destination keyring is
  45 .BR zero ,
  46 no attempt will be made to forge a link to the key, and just the serial number
  47 will be returned.
  48 .P
  49 If the destination keyring is given, then the link may only be formed if the
  50 found key grants the caller
  51 .B link
  52 permission and the destination keyring grants the caller
  53 .B write
  54 permission.
  55 .P
  56 If the search is successful, and if the destination keyring already contains a
  57 link to a key that matches the specified
  58 .IR type " and " description ,
  59 then that link will be replaced by a link to the found key.
  60 .P
  61 The source keyring and destination keyring serial numbers may be those of
  62 valid keyrings to which the caller has appropriate permission, or they may be
  63 special keyring IDs:
  64 .TP
  65 .B KEY_SPEC_THREAD_KEYRING
  66 This specifies the caller's thread-specific keyring.
  67 .TP
  68 .B KEY_SPEC_PROCESS_KEYRING
  69 This specifies the caller's process-specific keyring.
  70 .TP
  71 .B KEY_SPEC_SESSION_KEYRING
  72 This specifies the caller's session-specific keyring.
  73 .TP
  74 .B KEY_SPEC_USER_KEYRING
  75 This specifies the caller's UID-specific keyring.
  76 .TP
  77 .B KEY_SPEC_USER_SESSION_KEYRING
  78 This specifies the caller's UID-session keyring.
  79 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
  80 .SH RETURN VALUE
  81 On success
  82 .BR keyctl_search ()
  83 returns the serial number of the key it found.  On error, the value
  84 .B -1
  85 will be returned and errno will have been set to an appropriate error.
  86 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
  87 .SH ERRORS
  88 .TP
  89 .B ENOKEY
  90 One of the keyrings doesn't exist, no key was found by the search, or the only
  91 key found by the search was a negative key.
  92 .TP
  93 .B ENOTDIR
  94 One of the keyrings is a valid key that isn't a keyring.
  95 .TP
  96 .B EKEYEXPIRED
  97 One of the keyrings has expired, or the only key found was expired.
  98 .TP
  99 .B EKEYREVOKED
 100 One of the keyrings has been revoked, or the only key found was revoked.
 101 .TP
 102 .B ENOMEM
 103 Insufficient memory to expand the destination keyring.
 104 .TP
 105 .B EDQUOT
 106 The key quota for this user would be exceeded by creating a link to the found
 107 key in the destination keyring.
 108 .TP
 109 .B EACCES
 110 The source keyring didn't grant
 111 .B search
 112 permission, the destination keyring didn't grant
 113 .B write
 114 permission or the found key didn't grant
 115 .B link
 116 permission to the caller.
 117 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 118 .SH LINKING
 119 Although this is a Linux system call, it is not present in
 120 .I libc
 121 but can be found rather in
 122 .IR libkeyutils .
 123 When linking,
 124 .B -lkeyutils
 125 should be specified to the linker.
 126 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 127 .SH SEE ALSO
 128 .BR keyctl (1),
 129 .br
 130 .BR add_key (2),
 131 .br
 132 .BR keyctl (2),
 133 .br
 134 .BR request_key (2),
 135 .br
 136 .BR keyctl (3),
 137 .br
 138 .BR request-key (8)