aboutsummaryrefslogtreecommitdiff
path: root/secure/lib/libcrypto/man/man3/EVP_PKEY_derive.3
diff options
context:
space:
mode:
Diffstat (limited to 'secure/lib/libcrypto/man/man3/EVP_PKEY_derive.3')
-rw-r--r--secure/lib/libcrypto/man/man3/EVP_PKEY_derive.369
1 files changed, 44 insertions, 25 deletions
diff --git a/secure/lib/libcrypto/man/man3/EVP_PKEY_derive.3 b/secure/lib/libcrypto/man/man3/EVP_PKEY_derive.3
index b4a3c1b88645..3942c345c62c 100644
--- a/secure/lib/libcrypto/man/man3/EVP_PKEY_derive.3
+++ b/secure/lib/libcrypto/man/man3/EVP_PKEY_derive.3
@@ -1,4 +1,4 @@
-.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
+.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
@@ -68,8 +68,6 @@
. \}
.\}
.rr rF
-.\"
-.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
@@ -132,50 +130,66 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
-.IX Title "EVP_PKEY_DERIVE 3"
-.TH EVP_PKEY_DERIVE 3 "2022-07-05" "1.1.1q" "OpenSSL"
+.IX Title "EVP_PKEY_DERIVE 3ossl"
+.TH EVP_PKEY_DERIVE 3ossl "2023-09-19" "3.0.11" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
-EVP_PKEY_derive_init, EVP_PKEY_derive_set_peer, EVP_PKEY_derive \- derive public key algorithm shared secret
+EVP_PKEY_derive_init, EVP_PKEY_derive_init_ex,
+EVP_PKEY_derive_set_peer_ex, EVP_PKEY_derive_set_peer, EVP_PKEY_derive
+\&\- derive public key algorithm shared secret
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/evp.h>
\&
\& int EVP_PKEY_derive_init(EVP_PKEY_CTX *ctx);
+\& int EVP_PKEY_derive_init_ex(EVP_PKEY_CTX *ctx, const OSSL_PARAM params[]);
+\& int EVP_PKEY_derive_set_peer_ex(EVP_PKEY_CTX *ctx, EVP_PKEY *peer,
+\& int validate_peer);
\& int EVP_PKEY_derive_set_peer(EVP_PKEY_CTX *ctx, EVP_PKEY *peer);
\& int EVP_PKEY_derive(EVP_PKEY_CTX *ctx, unsigned char *key, size_t *keylen);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
-The \fBEVP_PKEY_derive_init()\fR function initializes a public key algorithm
-context using key \fBpkey\fR for shared secret derivation.
+\&\fBEVP_PKEY_derive_init()\fR initializes a public key algorithm context \fIctx\fR for
+shared secret derivation using the algorithm given when the context was created
+using \fBEVP_PKEY_CTX_new\fR\|(3) or variants thereof. The algorithm is used to
+fetch a \fB\s-1EVP_KEYEXCH\s0\fR method implicitly, see \*(L"Implicit fetch\*(R" in \fBprovider\fR\|(7) for
+more information about implicit fetches.
+.PP
+\&\fBEVP_PKEY_derive_init_ex()\fR is the same as \fBEVP_PKEY_derive_init()\fR but additionally
+sets the passed parameters \fIparams\fR on the context before returning.
.PP
-The \fBEVP_PKEY_derive_set_peer()\fR function sets the peer key: this will normally
-be a public key.
+\&\fBEVP_PKEY_derive_set_peer_ex()\fR sets the peer key: this will normally
+be a public key. The \fIvalidate_peer\fR will validate the public key if this value
+is non zero.
.PP
-The \fBEVP_PKEY_derive()\fR derives a shared secret using \fBctx\fR.
-If \fBkey\fR is \fB\s-1NULL\s0\fR then the maximum size of the output buffer is written to
-the \fBkeylen\fR parameter. If \fBkey\fR is not \fB\s-1NULL\s0\fR then before the call the
-\&\fBkeylen\fR parameter should contain the length of the \fBkey\fR buffer, if the call
-is successful the shared secret is written to \fBkey\fR and the amount of data
-written to \fBkeylen\fR.
+\&\fBEVP_PKEY_derive_set_peer()\fR is similar to \fBEVP_PKEY_derive_set_peer_ex()\fR with
+\&\fIvalidate_peer\fR set to 1.
+.PP
+\&\fBEVP_PKEY_derive()\fR derives a shared secret using \fIctx\fR.
+If \fIkey\fR is \s-1NULL\s0 then the maximum size of the output buffer is written to the
+\&\fIkeylen\fR parameter. If \fIkey\fR is not \s-1NULL\s0 then before the call the \fIkeylen\fR
+parameter should contain the length of the \fIkey\fR buffer, if the call is
+successful the shared secret is written to \fIkey\fR and the amount of data
+written to \fIkeylen\fR.
.SH "NOTES"
.IX Header "NOTES"
-After the call to \fBEVP_PKEY_derive_init()\fR algorithm specific control
-operations can be performed to set any appropriate parameters for the
-operation.
+After the call to \fBEVP_PKEY_derive_init()\fR, algorithm
+specific control operations can be performed to set any appropriate parameters
+for the operation.
.PP
The function \fBEVP_PKEY_derive()\fR can be called more than once on the same
context if several operations are performed using the same parameters.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
-\&\fBEVP_PKEY_derive_init()\fR and \fBEVP_PKEY_derive()\fR 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.
+\&\fBEVP_PKEY_derive_init()\fR and \fBEVP_PKEY_derive()\fR 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"
.IX Header "EXAMPLES"
Derive shared secret (for example \s-1DH\s0 or \s-1EC\s0 keys):
@@ -221,14 +235,19 @@ Derive shared secret (for example \s-1DH\s0 or \s-1EC\s0 keys):
\&\fBEVP_PKEY_sign\fR\|(3),
\&\fBEVP_PKEY_verify\fR\|(3),
\&\fBEVP_PKEY_verify_recover\fR\|(3),
+\&\fBEVP_KEYEXCH_fetch\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
-These functions were added in OpenSSL 1.0.0.
+The \fBEVP_PKEY_derive_init()\fR, \fBEVP_PKEY_derive_set_peer()\fR and \fBEVP_PKEY_derive()\fR
+functions were originally added in OpenSSL 1.0.0.
+.PP
+The \fBEVP_PKEY_derive_init_ex()\fR and \fBEVP_PKEY_derive_set_peer_ex()\fR functions were
+added in OpenSSL 3.0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
-Copyright 2006\-2019 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2006\-2023 The OpenSSL Project Authors. All Rights Reserved.
.PP
-Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
+Licensed under the Apache License 2.0 (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.