114 lines
4.1 KiB
Plaintext
114 lines
4.1 KiB
Plaintext
.\"
|
|
.\" Copyright (C) 2018 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 Licence
|
|
.\" as published by the Free Software Foundation; either version
|
|
.\" 2 of the Licence, or (at your option) any later version.
|
|
.\"
|
|
.TH KEYCTL_PKEY_ENCRYPT 3 "8 Nov 2018" Linux "Linux Public-Key Encryption"
|
|
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
|
.SH NAME
|
|
keyctl_pkey_encrypt, keyctl_pkey_decrypt \- Encrypt and decrypt data
|
|
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #include <keyutils.h>
|
|
.sp
|
|
.BI "long keyctl_pkey_encrypt(key_serial_t " key ", const char *" info ,
|
|
.BI " const void *" data ", size_t " data_len ,
|
|
.BI " void *" enc ", size_t " enc_len ");"
|
|
.sp
|
|
.BI "long keyctl_pkey_decrypt(key_serial_t " key ", const char *" info ,
|
|
.BI " const void *" enc ", size_t " enc_len ,
|
|
.BI " void *" data ", size_t " data_len ");"
|
|
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
|
.SH DESCRIPTION
|
|
.BR keyctl_pkey_encrypt ()
|
|
asks the kernel to use the crypto material attached to a key to encrypt a blob
|
|
of data and
|
|
.BR keyctl_pkey_decrypt ()
|
|
asks the kernel to use the key to reverse the operation and recover the
|
|
original data. Note that these operations may involve the kernel calling out
|
|
to cryptographic hardware. The caller must have
|
|
.B search
|
|
permission on a key to be able to use them in this manner.
|
|
.PP
|
|
.PP
|
|
When invoking the function,
|
|
.I key
|
|
indicates the key that will provide the cryptographic material and
|
|
.I info
|
|
points to a space- or tab-separated string of "key[=value]" parameters that
|
|
indicate things like encoding forms and passwords to unlock the key; see
|
|
asymmetric-key(7) for more information.
|
|
.PP
|
|
.IR data " and " datalen
|
|
indicate the address and size of the decrypted data buffer and
|
|
.IR enc " and " enclen
|
|
indicate the address and size of the encrypted data buffer. The encrypt
|
|
function draws data from the decrypted data buffer and places the output into
|
|
the encryption buffer. The decrypt function does the reverse, drawing from
|
|
the encryption buffer and writing into the data buffer.
|
|
.PP
|
|
.BR keyctl_pkey_query (2)
|
|
can be called to find out how large the buffers need to be.
|
|
.PP
|
|
Note that not all asymmetric-type keys will support these operations; further,
|
|
the operations available may depend on which components of the key material are
|
|
available: typically encryption only requires the public key, but decryption
|
|
requires the private key as well. Which operations are supported on a
|
|
particular key can also be determined using the query function.
|
|
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
|
.SH RETURN VALUE
|
|
On success
|
|
.BR keyctl_pkey_encrypt "() and " keyctl_pkey_decrypt ()
|
|
return the amount of data written into the output buffer. On error, the value
|
|
.B -1
|
|
will be returned and
|
|
.I errno
|
|
will have been set to an appropriate error.
|
|
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
|
.SH ERRORS
|
|
.TP
|
|
.B ENOKEY
|
|
The key specified is invalid.
|
|
.TP
|
|
.B EKEYEXPIRED
|
|
The key specified has expired.
|
|
.TP
|
|
.B EKEYREVOKED
|
|
The key specified has been revoked.
|
|
.TP
|
|
.B EACCES
|
|
The key exists, but is not
|
|
.B searchable
|
|
by the calling process.
|
|
.TP
|
|
.B ENOPKG
|
|
Some facility needed to complete the requested operation is not available.
|
|
This is most probably a requested or required digest or encryption algorithm.
|
|
.TP
|
|
.B EFAULT
|
|
Bad address.
|
|
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
|
.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 keyctl (3),
|
|
.BR keyctl_pkey_query (3),
|
|
.BR keyctl_pkey_sign (3),
|
|
.BR keyrings (7),
|
|
.BR keyutils (7)
|