Doc: Update manpages for KEYCTL_DH_COMPUTE

Created a new manual page for section 3 for the keyctl_dh_compute and
keyctl_dh_compute_alloc functions and listed these functions in the
man3 page for keyctl. Updated the man1 page for the new 'keyctl
dh_compute' command.

Signed-off-by: Mat Martineau <mathew.j.martineau@linux.intel.com>
Signed-off-by: David Howells <dhowells@redhat.com>

4 files changed, 142 insertions, 0 deletions

diff --git a/Makefile b/Makefile
index 5eb939a..824bbbf 100644
--- a/Makefile
+++ b/Makefile
@@ -194,6 +194,7 @@ endif
 	$(LNS) keyctl_link.3 $(DESTDIR)$(MAN3)/keyctl_unlink.3
 	$(LNS) keyctl_read.3 $(DESTDIR)$(MAN3)/keyctl_read_alloc.3
 	$(LNS) recursive_key_scan.3 $(DESTDIR)$(MAN3)/recursive_session_key_scan.3
+	$(LNS) keyctl_dh_compute.3 $(DESTDIR)$(MAN3)/keyctl_dh_compute_alloc.3
 	$(INSTALL) -D -m 0644 keyutils.h $(DESTDIR)$(INCLUDEDIR)/keyutils.h
 
 ###############################################################################
diff --git a/man/keyctl.1 b/man/keyctl.1
index 56b29ce..a677342 100644
--- a/man/keyctl.1
+++ b/man/keyctl.1
@@ -90,6 +90,8 @@ keyctl - Key management facility control
 \fBkeyctl\fR purge \-s <type> <desc>
 .br
 \fBkeyctl\fR get_persistent <keyring> [<uid>]
+.br
+\fBkeyctl\fR dh_compute <private> <prime> <base>
 .SH DESCRIPTION
 This program is used to control the key management facility in various ways
 using a variety of subcommands.
@@ -745,6 +747,31 @@ will be removed and everything it pins can then be garbage collected.
 If a UID other than the process's real or effective UIDs is specified, then an
 error will be given if the process does not have the CAP_SETUID capability.
 .P
+(*) \fBCompute a Diffie-Hellman shared secret or public key\fR
+.P
+\fBkeyctl\fR dh_compute <private> <prime> <base>
+.P
+This command computes either a Diffie-Hellman shared secret or the
+public key corresponding to the provided private key using the
+payloads of three keys. The computation is:
+.IP
+base ^ private (mod prime)
+.P
+The three inputs must be user keys with read permission. If the
+provided base key contains the shared generator value, the public key
+will be computed.  If the provided base key contains the remote public
+key value, the shared secret will be computed.
+.P
+The result is printed to stdout as a hex dump.
+.P
+.RS
+testbox>keyctl dh_compute $1 $2 $3
+.br
+8 bytes of data in result:
+.br
+00010203 04050607
+.RE
+.P
 .SH ERRORS
 .P
 There are a number of common errors returned by this program:
@@ -758,6 +785,7 @@ There are a number of common errors returned by this program:
 "Key has expired" - an expired key was accessed.
 .P
 "Permission denied" - permission was denied by a UID/GID/mask combination.
+.P
 
 .SH SEE ALSO
 \fBkeyctl\fR(1), \fBrequest-key.conf\fR(5)
diff --git a/man/keyctl.3 b/man/keyctl.3
index 440c270..d978cc5 100644
--- a/man/keyctl.3
+++ b/man/keyctl.3
@@ -43,6 +43,10 @@ and then telling the linker it should link in the library:
 .br
 .BR keyctl_describe_alloc (3)
 .br
+.BR keyctl_dh_compute (3)
+.br
+.BR keyctl_dh_compute_alloc (3)
+.br
 .BR keyctl_get_keyring_ID (3)
 .br
 .BR keyctl_get_persistent (3)
diff --git a/man/keyctl_dh_compute.3 b/man/keyctl_dh_compute.3
new file mode 100644
index 0000000..b06d39e
--- /dev/null
+++ b/man/keyctl_dh_compute.3
@@ -0,0 +1,109 @@
+.\"
+.\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved.
+.\" Copyright (C) 2016 Intel Corporation. All rights reserved.
+.\"
+.\" This program is free software; you can redistribute it and/or
+.\" modify it under the terms of the GNU General Public License
+.\" as published by the Free Software Foundation; either version
+.\" 2 of the License, or (at your option) any later version.
+.\"
+.TH KEYCTL_DH_COMPUTE 3 "07 Apr 2016" Linux "Linux Key Management Calls"
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.SH NAME
+keyctl_dh_compute \- Compute a Diffie-Hellman shared secret or public key
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.SH SYNOPSIS
+.nf
+.B #include <keyutils.h>
+.sp
+.BI "long keyctl_dh_compute(key_serial_t " private ", key_serial_t " prime ,
+.BI "key_serial_t " base ", char *" buffer ", size_t " buflen ");"
+.sp
+.BI "long keyctl_dh_compute_alloc(key_serial_t " private,
+.BI "key_serial_t " prime ", key_serial_t " base ", void **" _buffer ");"
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.SH DESCRIPTION
+.BR keyctl_dh_compute ()
+computes a Diffie-Hellman public key or shared secret.  That computation is:
+.IP
+.I base
+^
+.I private
+( mod
+.I prime
+)
+.P
+When
+.I base
+is a key containing the shared generator value, the remote public key is
+computed.  When
+.I base
+is a key containing the remote private key, the shared secret is computed.
+.P
+.IR base ", " private ", and " prime
+must all refer to
+.BR user -type
+keys containing the parameters for the computation.  Each of these keys must
+grant the caller
+.B read
+permission in order for them to be used.
+.P
+.I buffer
+and
+.I buflen
+specify the buffer into which the computed result will be placed.
+.I buflen
+may be zero, in which case the buffer is not used and the minimum buffer length
+is fetched.
+.P
+.BR keyctl_dh_compute_alloc ()
+is similar to
+.BR keyctl_dh_compute ()
+except that it allocates a buffer big enough to hold the payload data and
+places the data in it.  If successful, a pointer to the buffer is placed in
+.IR *_buffer .
+The caller must free the buffer.
+.P
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.SH RETURN VALUE
+On success
+.BR keyctl_dh_compute ()
+returns the amount of data placed into the buffer when
+.I buflen
+is non-zero.  When
+.I buflen
+is zero, the minimum buffer length to hold the data is returned.
+.P
+On success
+.BR keyctl_dh_compute_alloc ()
+returns the amount of data in the buffer.
+.P
+On error, both functions set errno to an appropriate code and return the value
+.BR -1 .
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.SH ERRORS
+.TP
+.B ENOKEY
+One of the keys specified is invalid or not readable.
+.TP
+.B EINVAL
+The buffer pointer is invalid or buflen is too small.
+.TP
+.B EOPNOTSUPP
+One of the keys was not a valid user key.
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.SH LINKING
+This is a library function that can be found in
+.IR libkeyutils .
+When linking,
+.B -lkeyutils
+should be specified to the linker.
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.SH SEE ALSO
+.BR keyctl (1),
+.br
+.BR keyctl (2),
+.br
+.BR keyctl (3),
+.br
+.BR keyutils (7)