keyctl_get_security.3

   1 .\"
   2 .\" Copyright (C) 2010 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_GET_SECURITY 3 "26 Feb 2010" Linux "Linux Key Management Calls"
  11 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
  12 .SH NAME
  13 keyctl_get_security \- Retrieve a key's security context
  14 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
  15 .SH SYNOPSIS
  16 .nf
  17 .B #include <keyutils.h>
  18 .sp
  19 .BI "long keyctl_get_security(key_serial_t " key ", char *" buffer ,
  20 .BI "size_t " buflen ");"
  21 .sp
  22 .BI "long keyctl_get_security_alloc(key_serial_t " key ", char **" _buffer ");"
  23 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
  24 .SH DESCRIPTION
  25 .BR keyctl_get_security ()
  26 retrieves the security context of a key as a NUL-terminated string.  This will
  27 be rendered in a form appropriate to the LSM in force - for instance, with
  28 SELinux, it may look like
  29 .IP
  30 .B "unconfined_u:unconfined_r:unconfined_t:s0-s0:c0.c1023"
  31 .P
  32 The caller must have
  33 .B view
  34 permission on a key to be able to get its security context.
  35 .P
  36 .I buffer
  37 and
  38 .I buflen
  39 specify the buffer into which the string will be placed.  If the buffer is too
  40 small, the full size of the string will be returned, and no copy will take
  41 place.
  42 .P
  43 .BR keyctl_get_security_alloc ()
  44 is similar to
  45 .BR keyctl_get_security ()
  46 except that it allocates a buffer big enough to hold the string and copies the
  47 string into it.  If successful, A pointer to the buffer is placed in
  48 .IR *_buffer .
  49 The caller must free the buffer.
  50 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
  51 .SH RETURN VALUE
  52 On success
  53 .BR keyctl_get_security ()
  54 returns the amount of data placed into the buffer.  If the buffer was too
  55 small, then the size of buffer required will be returned, but no data will be
  56 transferred.  On error, the value
  57 .B -1
  58 will be returned and errno will have been set to an appropriate error.
  59 .P
  60 On success
  61 .BR keyctl_get_security_alloc ()
  62 returns the amount of data in the buffer, less the NUL terminator.  On error, the value
  63 .B -1
  64 will be returned and errno will have been set to an appropriate error.
  65 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
  66 .SH ERRORS
  67 .TP
  68 .B ENOKEY
  69 The key specified is invalid.
  70 .TP
  71 .B EKEYEXPIRED
  72 The key specified has expired.
  73 .TP
  74 .B EKEYREVOKED
  75 The key specified had been revoked.
  76 .TP
  77 .B EACCES
  78 The key exists, but is not
  79 .B viewable
  80 by the calling process.
  81 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
  82 .SH LINKING
  83 This is a library function that can be found in
  84 .IR libkeyutils .
  85 When linking,
  86 .B -lkeyutils
  87 should be specified to the linker.
  88 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
  89 .SH SEE ALSO
  90 .BR keyctl (1),
  91 .br
  92 .BR add_key (2),
  93 .br
  94 .BR keyctl (2),
  95 .br
  96 .BR request_key (2),
  97 .br
  98 .BR keyctl (3),
  99 .br
 100 .BR request-key (8)