HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. |  |
NAME |LIBRARY |SYNOPSIS |DESCRIPTION |RETURN VALUE |ERRORS |STANDARDS |HISTORY |SEE ALSO |COLOPHON | |
KEYCTL_DH_COMPUTE(2const)KEYCTL_DH_COMPUTE(2const)KEYCTL_DH_COMPUTE - compute a Diffie-Hellman shared secret or public key
Standard C library (libc,-lc)
#include <linux/keyctl.h>/* Definition ofKEY*constants */#include <sys/syscall.h>/* Definition ofSYS_*constants */#include <unistd.h>long syscall(size_t n;SYS_keyctl, KEYCTL_DH_COMPUTE,struct keyctl_dh_params *dh_params,charbuf[n], size_tn,struct keyctl_kdf_params *_Nullablekdf_params);
Compute a Diffie-Hellman shared secret or public key, optionally applying key derivation function (KDF) to the result. Thedh_params argument is a pointer to a set of parameters containing serial numbers for three"user" keys used in the Diffie-Hellman calculation, packaged in a structure of the following form: struct keyctl_dh_params { int32_t private; /* The local private key */ int32_t prime; /* The prime, known to both parties */ int32_t base; /* The base integer: either a shared generator or the remote public key */ }; Each of the three keys specified in this structure must grant the callerread permission. The payloads of these keys are used to calculate the Diffie-Hellman result as: base ^ private mod prime If the base is the shared generator, the result is the local public key. If the base is the remote public key, the result is the shared secret. Thebuf argument points to a buffer where the result of the calculation is placed. The size of that buffer is specified inn. The buffer must be large enough to accommodate the output data, otherwise an error is returned. Ifn is specified zero, in which case the buffer is not used and the operation returns the minimum required buffer size (i.e., the length of the prime). Diffie-Hellman computations can be performed in user space, but require a multiple-precision integer (MPI) library. Moving the implementation into the kernel gives access to the kernel MPI implementation, and allows access to secure or acceleration hardware. Adding support for DH computation to thekeyctl() system call was considered a good fit due to the DH algorithm's use for deriving shared keys; it also allows the type of the key to determine which DH implementation (software or hardware) is appropriate. If thekdf_params argument isNULL, then the DH result itself is returned. Otherwise (since Linux 4.12), it is a pointer to a structure which specifies parameters of the KDF operation to be applied: struct keyctl_kdf_params { char *hashname; /* Hash algorithm name */ char *otherinfo; /* SP800-56A OtherInfo */ __u32 otherinfolen; /* Length of otherinfo data */ __u32 __spare[8]; /* Reserved */ }; Thehashname field is a null-terminated string which specifies a hash name (available in the kernel's crypto API; the list of the hashes available is rather tricky to observe; please refer to the "Kernel Crypto API Architecture" ⟨https://www.kernel.org/doc/html/latest/crypto/architecture.html⟩ documentation for the information regarding how hash names are constructed and your kernel's source and configuration regarding what ciphers and templates with typeCRYPTO_ALG_TYPE_SHASHare available) to be applied to DH result in KDF operation. Theotherinfo field is anOtherInfo data as described in SP800-56A section 5.8.1.2 and is algorithm-specific. This data is concatenated with the result of DH operation and is provided as an input to the KDF operation. Its size is provided in theotherinfolen field and is limited byKEYCTL_KDF_MAX_OI_LEN constant that defined insecurity/keys/internal.h to a value of 64. The__sparefield is currently unused. It was ignored until Linux 4.13 (but still should be user-addressable since it is copied to the kernel), and should contain zeros since Linux 4.13. The KDF implementation complies with SP800-56A as well as with SP800-108 (the counter KDF). This operation is exposed bylibkeyutils (fromlibkeyutils 1.5.10 onwards) via the functionskeyctl_dh_compute(3) andkeyctl_dh_compute_alloc(3).On success, the number of bytes copied to the buffer, or, ifn is 0, the required buffer size. On error, -1 is returned, anderrno is set to indicate the error.
EAGAINThere was an error during crypto module initialization.EFAULTOne of the following has failed: • copying of thestruct keyctl_dh_params, provided in thedh_params argument, from user space; • copying of thestruct keyctl_kdf_params, provided in the non-NULLkdf_params argument, from user space (in case kernel supports performing KDF operation on DH operation result); • copying of data pointed by thehashname field of thestruct keyctl_kdf_params from user space; • copying of data pointed by theotherinfo field of thestruct keyctl_kdf_params from user space if theotherinfolen field was nonzero; • copying of the result to user space.EINVAL(before Linux 4.12) Argumentkdf_params was non-NULL.EINVALThe digest size of the hashing algorithm supplied is zero.EINVALThe buffer size provided is not enough to hold the result. Provide 0 as a buffer size in order to obtain the minimum buffer size.EINVALThe hash name provided in thehashname field of thestructkeyctl_kdf_params pointed bykdf_params argument is too big (the limit is implementation-specific and varies between kernel versions, but it is deemed big enough for all valid algorithm names).EINVALThe__spare field of thestruct keyctl_kdf_params provided in thekdf_params argument contains nonzero values.EMSGSIZE The buffer length exceedsKEYCTL_KDF_MAX_OUTPUT_LEN(which is 1024 currently) or theotherinfolen field of thestructkeyctl_kdf_parms passed inkdf_params exceedsKEYCTL_KDF_MAX_OI_LEN(which is 64 currently).ENOENTThe hashing algorithm specified in thehashname field of thestruct keyctl_kdf_params pointed bykdf_params argument hasn't been found.ETIMEDOUT The initialization of crypto modules has timed out.
Linux.
Linux 4.7.
keyctl(2),keyctl_dh_compute(3),keyctl_dh_compute_alloc(3),keyctl_dh_compute_kdf(3)
This page is part of theman-pages (Linux kernel and C library user-space interface documentation) project. Information about the project can be found at ⟨https://www.kernel.org/doc/man-pages/⟩. If you have a bug report for this manual page, see ⟨https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/CONTRIBUTING⟩. This page was obtained from the tarball man-pages-6.15.tar.gz fetched from ⟨https://mirrors.edge.kernel.org/pub/linux/docs/man-pages/⟩ on 2025-08-11. If you discover any rendering problems in this HTML version of the page, or you believe there is a better or more up- to-date source for the page, or you have corrections or improvements to the information in this COLOPHON (which isnot part of the original manual page), send a mail to man-pages@man7.orgLinux man-pages 6.15 2025-06-28KEYCTL_DH_COMPUTE(2const)Pages that refer to this page:keyctl(2)
HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. | |