1 files changed, 120 insertions, 0 deletions

diff --git a/src/lib/libcrypto/man/EVP_PKEY_derive.3 b/src/lib/libcrypto/man/EVP_PKEY_derive.3
new file mode 100644
index 0000000000..e67280cf20
--- /dev/null
+++ b/src/lib/libcrypto/man/EVP_PKEY_derive.3
@@ -0,0 +1,120 @@
+.Dd $Mdocdate: November 3 2016 $
+.Dt EVP_PKEY_DERIVE 3
+.Os
+.Sh NAME
+.Nm EVP_PKEY_derive_init ,
+.Nm EVP_PKEY_derive_set_peer ,
+.Nm EVP_PKEY_derive
+.Nd derive public key algorithm shared secret
+.Sh SYNOPSIS
+.In openssl/evp.h
+.Ft int
+.Fo EVP_PKEY_derive_init
+.Fa "EVP_PKEY_CTX *ctx"
+.Fc
+.Ft int
+.Fo EVP_PKEY_derive_set_peer
+.Fa "EVP_PKEY_CTX *ctx"
+.Fa "EVP_PKEY *peer"
+.Fc
+.Ft int
+.Fo EVP_PKEY_derive
+.Fa "EVP_PKEY_CTX *ctx"
+.Fa "unsigned char *key"
+.Fa "size_t *keylen"
+.Fc
+.Sh DESCRIPTION
+The
+.Fn EVP_PKEY_derive_init
+function initializes a public key algorithm context using key
+.Fa ctx->pkey
+for shared secret derivation.
+.Pp
+The
+.Fn EVP_PKEY_derive_set_peer
+function sets the peer key: this will normally be a public key.
+.Pp
+The
+.Fn EVP_PKEY_derive
+derives a shared secret using
+.Fa ctx .
+If
+.Fa key
+is
+.Dv NULL ,
+then the maximum size of the output buffer is written to the
+.Fa keylen
+parameter.
+If
+.Fa key
+is not
+.Dv NULL
+then before the call the
+.Fa keylen
+parameter should contain the length of the
+.Fa key
+buffer.
+If the call is successful, the shared secret is written to
+.Fa key
+and the amount of data written to
+.Fa keylen .
+.Pp
+After the call to
+.Fn EVP_PKEY_derive_init ,
+algorithm specific control operations can be performed to set any
+appropriate parameters for the operation.
+.Pp
+The function
+.Fn EVP_PKEY_derive
+can be called more than once on the same context if several operations
+are performed using the same parameters.
+.Sh RETURN VALUES
+.Fn EVP_PKEY_derive_init
+and
+.Fn EVP_PKEY_derive
+return 1 for success and 0 or a negative value for failure.
+In particular, a return value of -2 indicates the operation is not
+supported by the public key algorithm.
+.Sh EXAMPLES
+Derive shared secret (for example DH or EC keys):
+.Bd -literal
+#include <openssl/evp.h>
+#include <openssl/rsa.h>
+
+EVP_PKEY_CTX *ctx;
+unsigned char *skey;
+size_t skeylen;
+EVP_PKEY *pkey, *peerkey;
+/* NB: assumes pkey, peerkey have been already set up */
+
+ctx = EVP_PKEY_CTX_new(pkey);
+if (!ctx)
+        /* Error occurred */
+if (EVP_PKEY_derive_init(ctx) <= 0)
+        /* Error */
+if (EVP_PKEY_derive_set_peer(ctx, peerkey) <= 0)
+        /* Error */
+
+/* Determine buffer length */
+if (EVP_PKEY_derive(ctx, NULL, &skeylen) <= 0)
+        /* Error */
+
+skey = malloc(skeylen);
+
+if (!skey)
+        /* malloc failure */
+
+if (EVP_PKEY_derive(ctx, skey, &skeylen) <= 0)
+        /* Error */
+
+/* Shared secret is skey bytes written to buffer skey */
+.Ed
+.Sh SEE ALSO
+.Xr EVP_PKEY_CTX_new 3 ,
+.Xr EVP_PKEY_decrypt 3 ,
+.Xr EVP_PKEY_encrypt 3 ,
+.Xr EVP_PKEY_sign 3 ,
+.Xr EVP_PKEY_verify 3 ,
+.Xr EVP_PKEY_verify_recover 3
+.Sh HISTORY
+These functions were first added to OpenSSL 1.0.0.