NAME

       keyctl_pkey_encrypt, keyctl_pkey_decrypt - Encrypt and decrypt data

SYNOPSIS

       #include <keyutils.h>

       long keyctl_pkey_encrypt(key_serial_t key, const char *info,
                                const void *data, size_t data_len,
                                void *enc, size_t enc_len);

       long keyctl_pkey_decrypt(key_serial_t key, const char *info,
                                const void *enc, size_t enc_len,
                                void *data, size_t data_len);

DESCRIPTION

       keyctl_pkey_encrypt()  asks  the  kernel  to  use the crypto material attached to a key to
       encrypt a blob of data and 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 search permission on a
       key to be able to use them in this manner.

       When  invoking  the  function,  key  indicates the key that will provide the cryptographic
       material and 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.

       data and datalen indicate the address and size of the decrypted data buffer  and  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.

       keyctl_pkey_query(2) can be called to find out how large the buffers need to be.

       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.

RETURN VALUE

       On success keyctl_pkey_encrypt() and  keyctl_pkey_decrypt()  return  the  amount  of  data
       written  into  the  output buffer.  On error, the value -1 will be returned and errno will
       have been set to an appropriate error.

ERRORS

       ENOKEY The key specified is invalid.

       EKEYEXPIRED
              The key specified has expired.

       EKEYREVOKED
              The key specified has been revoked.

       EACCES The key exists, but is not searchable by the calling process.

       ENOPKG Some facility needed to complete the requested operation is not available.  This is
              most probably a requested or required digest or encryption algorithm.

       EFAULT Bad address.

LINKING

       This  is  a  library  function that can be found in libkeyutils.  When linking, -lkeyutils
       should be specified to the linker.

SEE ALSO

       keyctl(1), add_key(2), keyctl(2), keyctl(3), keyctl_pkey_query(3), keyctl_pkey_sign(3),
       keyrings(7), keyutils(7)