|
jpayne@68
|
1 .\"
|
|
jpayne@68
|
2 .\" Copyright (C) 2006 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_READ 3 "21 Feb 2014" Linux "Linux Key Management Calls"
|
|
jpayne@68
|
11 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
|
jpayne@68
|
12 .SH NAME
|
|
jpayne@68
|
13 keyctl_read \- read a key
|
|
jpayne@68
|
14 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
|
jpayne@68
|
15 .SH SYNOPSIS
|
|
jpayne@68
|
16 .nf
|
|
jpayne@68
|
17 .B #include <keyutils.h>
|
|
jpayne@68
|
18 .sp
|
|
jpayne@68
|
19 .BI "long keyctl_read(key_serial_t " key ", char *" buffer ,
|
|
jpayne@68
|
20 .BI "size_t" buflen ");"
|
|
jpayne@68
|
21 .sp
|
|
jpayne@68
|
22 .BI "long keyctl_read_alloc(key_serial_t " key ", void **" _buffer ");"
|
|
jpayne@68
|
23 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
|
jpayne@68
|
24 .SH DESCRIPTION
|
|
jpayne@68
|
25 .BR keyctl_read ()
|
|
jpayne@68
|
26 reads the payload of a key if the key type supports it.
|
|
jpayne@68
|
27 .P
|
|
jpayne@68
|
28 The caller must have
|
|
jpayne@68
|
29 .B read
|
|
jpayne@68
|
30 permission on a key to be able to read it.
|
|
jpayne@68
|
31 .P
|
|
jpayne@68
|
32 .I buffer
|
|
jpayne@68
|
33 and
|
|
jpayne@68
|
34 .I buflen
|
|
jpayne@68
|
35 specify the buffer into which the payload data will be placed. If the buffer
|
|
jpayne@68
|
36 is too small, then the full size of the payload will be returned, and the
|
|
jpayne@68
|
37 contents of the buffer may be overwritten in some undefined way.
|
|
jpayne@68
|
38 .P
|
|
jpayne@68
|
39 .BR keyctl_read_alloc ()
|
|
jpayne@68
|
40 is similar to
|
|
jpayne@68
|
41 .BR keyctl_read ()
|
|
jpayne@68
|
42 except that it allocates a buffer big enough to hold the payload data and
|
|
jpayne@68
|
43 places the data in it. If successful, a pointer to the buffer is placed in
|
|
jpayne@68
|
44 .IR *_buffer .
|
|
jpayne@68
|
45 The caller must free the buffer.
|
|
jpayne@68
|
46 .P
|
|
jpayne@68
|
47 .BR keyctl_read_alloc ()
|
|
jpayne@68
|
48 adds a NUL character after the data it retrieves, though this is not counted
|
|
jpayne@68
|
49 in the size value it returns.
|
|
jpayne@68
|
50 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
|
jpayne@68
|
51 .SH READING KEYRINGS
|
|
jpayne@68
|
52 This call can be used to list the contents of a keyring. The data is
|
|
jpayne@68
|
53 presented to the user as an array of
|
|
jpayne@68
|
54 .B key_serial_t
|
|
jpayne@68
|
55 values, each of which corresponds to a key to which the keyring holds a link.
|
|
jpayne@68
|
56 .P
|
|
jpayne@68
|
57 The size of the keyring will be sizeof(key_serial_t) multiplied by the number
|
|
jpayne@68
|
58 of keys. The size of key_serial_t is invariant across different word sizes,
|
|
jpayne@68
|
59 though the byte-ordering is as appropriate for the kernel.
|
|
jpayne@68
|
60 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
|
jpayne@68
|
61 .SH RETURN VALUE
|
|
jpayne@68
|
62 On success
|
|
jpayne@68
|
63 .BR keyctl_read ()
|
|
jpayne@68
|
64 returns the amount of data placed into the buffer. If the buffer was too
|
|
jpayne@68
|
65 small, then the size of buffer required will be returned, and the contents of
|
|
jpayne@68
|
66 the buffer may have been overwritten in some undefined way.
|
|
jpayne@68
|
67 .P
|
|
jpayne@68
|
68 On success
|
|
jpayne@68
|
69 .BR keyctl_read_alloc ()
|
|
jpayne@68
|
70 returns the amount of data in the buffer.
|
|
jpayne@68
|
71 .P
|
|
jpayne@68
|
72 On error, both functions set
|
|
jpayne@68
|
73 .I errno
|
|
jpayne@68
|
74 to an appropriate code and return the value
|
|
jpayne@68
|
75 .BR -1 .
|
|
jpayne@68
|
76 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
|
jpayne@68
|
77 .SH ERRORS
|
|
jpayne@68
|
78 .TP
|
|
jpayne@68
|
79 .B ENOKEY
|
|
jpayne@68
|
80 The key specified is invalid.
|
|
jpayne@68
|
81 .TP
|
|
jpayne@68
|
82 .B EKEYEXPIRED
|
|
jpayne@68
|
83 The key specified has expired.
|
|
jpayne@68
|
84 .TP
|
|
jpayne@68
|
85 .B EKEYREVOKED
|
|
jpayne@68
|
86 The key specified had been revoked.
|
|
jpayne@68
|
87 .TP
|
|
jpayne@68
|
88 .B EACCES
|
|
jpayne@68
|
89 The key exists, but is not
|
|
jpayne@68
|
90 .B readable
|
|
jpayne@68
|
91 by the calling process.
|
|
jpayne@68
|
92 .TP
|
|
jpayne@68
|
93 .B EOPNOTSUPP
|
|
jpayne@68
|
94 The key type does not support reading of the payload data.
|
|
jpayne@68
|
95 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
|
jpayne@68
|
96 .SH LINKING
|
|
jpayne@68
|
97 This is a library function that can be found in
|
|
jpayne@68
|
98 .IR libkeyutils .
|
|
jpayne@68
|
99 When linking,
|
|
jpayne@68
|
100 .B \-lkeyutils
|
|
jpayne@68
|
101 should be specified to the linker.
|
|
jpayne@68
|
102 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
|
jpayne@68
|
103 .SH SEE ALSO
|
|
jpayne@68
|
104 .ad l
|
|
jpayne@68
|
105 .nh
|
|
jpayne@68
|
106 .BR keyctl (1),
|
|
jpayne@68
|
107 .BR add_key (2),
|
|
jpayne@68
|
108 .BR keyctl (2),
|
|
jpayne@68
|
109 .BR request_key (2),
|
|
jpayne@68
|
110 .BR keyctl (3),
|
|
jpayne@68
|
111 .BR keyrings (7),
|
|
jpayne@68
|
112 .BR keyutils (7)
|
