1KEYCTL_PKEY_SIGN(3) Linux Public-Key Signatures KEYCTL_PKEY_SIGN(3)
2
6 keyctl_pkey_sign, keyctl_pkey_verify - Generate and verify signatures
7
9 #include <keyutils.h>
10 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 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
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 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 The caller must have search permission on a key to be able to perform
29 either operation.
30 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 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 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 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 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
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 On error the value -1 will be returned and errno will have been set to
68 an appropriate error.
69
71 ENOKEY The key specified is invalid.
72 EKEYEXPIRED
74 The key specified has expired.
75 EKEYREVOKED
77 The key specified has been revoked.
78 EACCES The key exists, but is not searchable by the calling process.
80 EINVAL, EBADMSG, EOVERFLOW
82 Some part of the key material or signature data is bad.
83 EKEYREJECTED
85 Signature verification failed.
86 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 EFAULT Bad address.
92
94 This is a library function that can be found in libkeyutils. When
95 linking, -lkeyutils should be specified to the linker.
96
98 keyctl(1), add_key(2), keyctl(2), keyctl(3), keyctl_pkey_query(3),
99 keyrings(7), keyutils(7)
100Linux 8 Nov 2018 KEYCTL_PKEY_SIGN(3)