path: root/Documentation/security/keys.txt
diff options
authorMat Martineau <mathew.j.martineau@linux.intel.com>2016-04-12 19:54:58 +0100
committerDavid Howells <dhowells@redhat.com>2016-04-12 19:54:58 +0100
commitddbb41148724367394d0880c516bfaeed127b52e (patch)
tree3e5cc20804b646256525cd9c2de7a9681d7e4996 /Documentation/security/keys.txt
parentSecurity: Keys: Big keys stored encrypted (diff)
This adds userspace access to Diffie-Hellman computations through a new keyctl() syscall command to calculate shared secrets or public keys using input parameters stored in the keyring. Input key ids are provided in a struct due to the current 5-arg limit for the keyctl syscall. Only user keys are supported in order to avoid exposing the content of logon or encrypted keys. The output is written to the provided buffer, based on the assumption that the values are only needed in userspace. Future support for other types of key derivation would involve a new command, like KEYCTL_ECDH_COMPUTE. Once Diffie-Hellman support is included in the crypto API, this code can be converted to use the crypto API to take advantage of possible hardware acceleration and reduce redundant code. Signed-off-by: Mat Martineau <mathew.j.martineau@linux.intel.com> Signed-off-by: David Howells <dhowells@redhat.com>
Diffstat (limited to 'Documentation/security/keys.txt')
1 files changed, 30 insertions, 0 deletions
diff --git a/Documentation/security/keys.txt b/Documentation/security/keys.txt
index 8c183873b2b7..a2f70cf6763a 100644
--- a/Documentation/security/keys.txt
+++ b/Documentation/security/keys.txt
@@ -823,6 +823,36 @@ The keyctl syscall functions are:
A process must have search permission on the key for this function to be
+ (*) Compute a Diffie-Hellman shared secret or public key
+ long keyctl(KEYCTL_DH_COMPUTE, struct keyctl_dh_params *params,
+ char *buffer, size_t buflen);
+ The params struct contains serial numbers for three keys:
+ - The prime, p, known to both parties
+ - The local private key
+ - The base integer, which is either a shared generator or the
+ remote public key
+ The value computed is:
+ result = 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.
+ The buffer length must be at least the length of the prime, or zero.
+ If the buffer length is nonzero, the length of the result is
+ returned when it is successfully calculated and copied in to the
+ buffer. When the buffer length is zero, the minimum required
+ buffer length is returned.
+ This function will return error EOPNOTSUPP if the key type is not
+ supported, error ENOKEY if the key could not be found, or error
+ EACCES if the key is not readable by the caller.