1KEYCTL_PKEY_SIGN(3)       Linux Public-Key Signatures      KEYCTL_PKEY_SIGN(3)
2
3
4

NAME

6       keyctl_pkey_sign, keyctl_pkey_verify - Generate and verify signatures
7

SYNOPSIS

9       #include <keyutils.h>
10
11       long keyctl_pkey_sign(key_serial_t key, const char *info,
12                             const void *data, size_t data_len,
13                             void *sig, size_t sig_len);
14
15       long keyctl_pkey_verify(key_serial_t key, const char *info,
16                               const void *data, size_t data_len,
17                               const void *sig, size_t sig_len);
18

DESCRIPTION

20       keyctl_pkey_sign() asks the kernel to use the crypto data attached to a
21       key to generate a detached signature for a blob  of  data.   Note  that
22       this may involve calling out to cryptographic hardware.
23
24       keyctl_pkey_verify()  asks the kernel to use the key to generate a ver‐
25       ify the signature against the same blob of data.  This may also involve
26       calling out to cryptographic hardware.
27
28       The  caller  must have search permission on a key to be able to perform
29       either operation.
30
31       When invoking the function, key indicates the key that will provide the
32       cryptographic  material  and info points to a comma-separated string of
33       "key[=value]" parameters that indicate things like encoding  forms  and
34       passwords  to  unlock  the key; see asymmetric-key(7) for more informa‐
35       tion.
36
37       data and datalen indicate the address and size of the buffer of data to
38       be  signed and sig and siglen indicate the address and size of the sig‐
39       nature buffer.  The sign function draws data from the data buffer, gen‐
40       erates  a  signature  from  it and places the output into the signature
41       buffer.  The verify function also draws data from the data buffer, then
42       decrypts the signature and compares the result.
43
44       Note  that  the  data buffer is strictly limited in capacity, typically
45       unable to hold more bits than the size  of  the  key.   The  caller  is
46       expected  to  have  pre-digested the actual data and will thus pass the
47       digest output to this function.  The name of the digest used should  be
48       passed  as part of the info string as hash=<name> for use in construct‐
49       ing the signature metadata.
50
51       keyctl_pkey_query(2) can be called to find out how  large  the  buffers
52       need  to be and what the maximum size of the data can be for a specific
53       signature encoding.
54
55       Note that not all asymmetric-type keys will support  these  operations;
56       further, the operations available may depend on which components of the
57       key material are available: typically encryption only requires the pub‐
58       lic key, but decryption requires the private key as well.  Which opera‐
59       tions are supported on a particular key can also  be  determined  using
60       the query function.
61

RETURN VALUE

63       On  success  keyctl_pkey_sign() returns the amount of data written into
64       the signature buffer.  keyctl_pkey_verify() will return 0 in this  case
65       as it doesn't write to userspace.
66
67       On  error the value -1 will be returned and errno will have been set to
68       an appropriate error.
69

ERRORS

71       ENOKEY The key specified is invalid.
72
73       EKEYEXPIRED
74              The key specified has expired.
75
76       EKEYREVOKED
77              The key specified has been revoked.
78
79       EACCES The key exists, but is not searchable by the calling process.
80
81       EINVAL, EBADMSG, EOVERFLOW
82              Some part of the key material or signature data is bad.
83
84       EKEYREJECTED
85              Signature verification failed.
86
87       ENOPKG Some facility needed to complete the requested operation is  not
88              available.  This is most probably a requested or required digest
89              or encryption algorithm.
90
91       EFAULT Bad address.
92

LINKING

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

SEE ALSO

98       keyctl(1), add_key(2), keyctl(2), keyctl(3), keyctl_pkey_query(3),
99       keyrings(7), keyutils(7)
100
101
102
103Linux                             8 Nov 2018               KEYCTL_PKEY_SIGN(3)
Impressum