112 lines
3.5 KiB
Plaintext
112 lines
3.5 KiB
Plaintext
.\"
|
|
.\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved.
|
|
.\" Written by David Howells (dhowells@redhat.com)
|
|
.\"
|
|
.\" This program is free software; you can redistribute it and/or
|
|
.\" modify it under the terms of the GNU General Public License
|
|
.\" as published by the Free Software Foundation; either version
|
|
.\" 2 of the License, or (at your option) any later version.
|
|
.\"
|
|
.TH KEYCTL_READ 3 "21 Feb 2014" Linux "Linux Key Management Calls"
|
|
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
|
.SH NAME
|
|
keyctl_read \- read a key
|
|
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #include <keyutils.h>
|
|
.sp
|
|
.BI "long keyctl_read(key_serial_t " key ", char *" buffer ", size_t " buflen ");"
|
|
.sp
|
|
.BI "long keyctl_read_alloc(key_serial_t " key ", void **" _buffer ");"
|
|
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
|
.SH DESCRIPTION
|
|
.BR keyctl_read ()
|
|
reads the payload of a key if the key type supports it.
|
|
.P
|
|
The caller must have
|
|
.B read
|
|
permission on a key to be able to read it.
|
|
.P
|
|
.I buffer
|
|
and
|
|
.I buflen
|
|
specify the buffer into which the payload data will be placed. If the buffer
|
|
is too small, then the full size of the payload will be returned, and the
|
|
contents of the buffer may be overwritten in some undefined way.
|
|
.P
|
|
.BR keyctl_read_alloc ()
|
|
is similar to
|
|
.BR keyctl_read ()
|
|
except that it allocates a buffer big enough to hold the payload data and
|
|
places the data in it. If successful, a pointer to the buffer is placed in
|
|
.IR *_buffer .
|
|
The caller must free the buffer.
|
|
.P
|
|
.BR keyctl_read_alloc ()
|
|
adds a NUL character after the data it retrieves, though this is not counted
|
|
in the size value it returns.
|
|
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
|
.SH READING KEYRINGS
|
|
This call can be used to list the contents of a keyring. The data is
|
|
presented to the user as an array of
|
|
.B key_serial_t
|
|
values, each of which corresponds to a key to which the keyring holds a link.
|
|
.P
|
|
The size of the keyring will be sizeof(key_serial_t) multiplied by the number
|
|
of keys. The size of key_serial_t is invariant across different word sizes,
|
|
though the byte-ordering is as appropriate for the kernel.
|
|
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
|
.SH RETURN VALUE
|
|
On success
|
|
.BR keyctl_read ()
|
|
returns the amount of data placed into the buffer. If the buffer was too
|
|
small, then the size of buffer required will be returned, and the contents of
|
|
the buffer may have been overwritten in some undefined way.
|
|
.P
|
|
On success
|
|
.BR keyctl_read_alloc ()
|
|
returns the amount of data in the buffer.
|
|
.P
|
|
On error, both functions set
|
|
.I errno
|
|
to an appropriate code and return the value
|
|
.BR -1 .
|
|
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
|
.SH ERRORS
|
|
.TP
|
|
.B ENOKEY
|
|
The key specified is invalid.
|
|
.TP
|
|
.B EKEYEXPIRED
|
|
The key specified has expired.
|
|
.TP
|
|
.B EKEYREVOKED
|
|
The key specified had been revoked.
|
|
.TP
|
|
.B EACCES
|
|
The key exists, but is not
|
|
.B readable
|
|
by the calling process.
|
|
.TP
|
|
.B EOPNOTSUPP
|
|
The key type does not support reading of the payload data.
|
|
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
|
.SH LINKING
|
|
This is a library function that can be found in
|
|
.IR libkeyutils .
|
|
When linking,
|
|
.B \-lkeyutils
|
|
should be specified to the linker.
|
|
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
|
.SH SEE ALSO
|
|
.ad l
|
|
.nh
|
|
.BR keyctl (1),
|
|
.BR add_key (2),
|
|
.BR keyctl (2),
|
|
.BR request_key (2),
|
|
.BR keyctl (3),
|
|
.BR keyrings (7),
|
|
.BR keyutils (7)
|