aboutsummaryrefslogtreecommitdiff
path: root/secure/lib/libcrypto/man/man3/EVP_PKEY_CTX_new.3
diff options
context:
space:
mode:
Diffstat (limited to 'secure/lib/libcrypto/man/man3/EVP_PKEY_CTX_new.3')
-rw-r--r--secure/lib/libcrypto/man/man3/EVP_PKEY_CTX_new.399
1 files changed, 80 insertions, 19 deletions
diff --git a/secure/lib/libcrypto/man/man3/EVP_PKEY_CTX_new.3 b/secure/lib/libcrypto/man/man3/EVP_PKEY_CTX_new.3
index 030e9f56691a..da3aa0b1da56 100644
--- a/secure/lib/libcrypto/man/man3/EVP_PKEY_CTX_new.3
+++ b/secure/lib/libcrypto/man/man3/EVP_PKEY_CTX_new.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,14 +130,17 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
-.IX Title "EVP_PKEY_CTX_NEW 3"
-.TH EVP_PKEY_CTX_NEW 3 "2022-06-21" "1.1.1p" "OpenSSL"
+.IX Title "EVP_PKEY_CTX_NEW 3ossl"
+.TH EVP_PKEY_CTX_NEW 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_CTX_new, EVP_PKEY_CTX_new_id, EVP_PKEY_CTX_dup, EVP_PKEY_CTX_free \- public key algorithm context functions
+EVP_PKEY_CTX_new, EVP_PKEY_CTX_new_id, EVP_PKEY_CTX_new_from_name,
+EVP_PKEY_CTX_new_from_pkey, EVP_PKEY_CTX_dup, EVP_PKEY_CTX_free,
+EVP_PKEY_CTX_is_a
+\&\- public key algorithm context functions
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
@@ -147,46 +148,106 @@ EVP_PKEY_CTX_new, EVP_PKEY_CTX_new_id, EVP_PKEY_CTX_dup, EVP_PKEY_CTX_free \- pu
\&
\& EVP_PKEY_CTX *EVP_PKEY_CTX_new(EVP_PKEY *pkey, ENGINE *e);
\& EVP_PKEY_CTX *EVP_PKEY_CTX_new_id(int id, ENGINE *e);
-\& EVP_PKEY_CTX *EVP_PKEY_CTX_dup(EVP_PKEY_CTX *ctx);
+\& EVP_PKEY_CTX *EVP_PKEY_CTX_new_from_name(OSSL_LIB_CTX *libctx,
+\& const char *name,
+\& const char *propquery);
+\& EVP_PKEY_CTX *EVP_PKEY_CTX_new_from_pkey(OSSL_LIB_CTX *libctx,
+\& EVP_PKEY *pkey,
+\& const char *propquery);
+\& EVP_PKEY_CTX *EVP_PKEY_CTX_dup(const EVP_PKEY_CTX *ctx);
\& void EVP_PKEY_CTX_free(EVP_PKEY_CTX *ctx);
+\& int EVP_PKEY_CTX_is_a(EVP_PKEY_CTX *ctx, const char *keytype);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \fBEVP_PKEY_CTX_new()\fR function allocates public key algorithm context using
-the algorithm specified in \fBpkey\fR and \s-1ENGINE\s0 \fBe\fR.
+the \fIpkey\fR key type and \s-1ENGINE\s0 \fIe\fR.
.PP
The \fBEVP_PKEY_CTX_new_id()\fR function allocates public key algorithm context
-using the algorithm specified by \fBid\fR and \s-1ENGINE\s0 \fBe\fR. It is normally used
-when no \fB\s-1EVP_PKEY\s0\fR structure is associated with the operations, for example
-during parameter generation of key generation for some algorithms.
+using the key type specified by \fIid\fR and \s-1ENGINE\s0 \fIe\fR.
+.PP
+The \fBEVP_PKEY_CTX_new_from_name()\fR function allocates a public key algorithm
+context using the library context \fIlibctx\fR (see \s-1\fBOSSL_LIB_CTX\s0\fR\|(3)), the
+key type specified by \fIname\fR and the property query \fIpropquery\fR. None
+of the arguments are duplicated, so they must remain unchanged for the
+lifetime of the returned \fB\s-1EVP_PKEY_CTX\s0\fR or of any of its duplicates. Read
+further about the possible names in \*(L"\s-1NOTES\*(R"\s0 below.
+.PP
+The \fBEVP_PKEY_CTX_new_from_pkey()\fR function allocates a public key algorithm
+context using the library context \fIlibctx\fR (see \s-1\fBOSSL_LIB_CTX\s0\fR\|(3)) and the
+algorithm specified by \fIpkey\fR and the property query \fIpropquery\fR. None of the
+arguments are duplicated, so they must remain unchanged for the lifetime of the
+returned \fB\s-1EVP_PKEY_CTX\s0\fR or any of its duplicates.
+.PP
+\&\fBEVP_PKEY_CTX_new_id()\fR and \fBEVP_PKEY_CTX_new_from_name()\fR are normally
+used when no \fB\s-1EVP_PKEY\s0\fR structure is associated with the operations,
+for example during parameter generation or key generation for some
+algorithms.
.PP
-\&\fBEVP_PKEY_CTX_dup()\fR duplicates the context \fBctx\fR.
+\&\fBEVP_PKEY_CTX_dup()\fR duplicates the context \fIctx\fR. It is not supported for a
+keygen operation.
.PP
-\&\fBEVP_PKEY_CTX_free()\fR frees up the context \fBctx\fR.
-If \fBctx\fR is \s-1NULL,\s0 nothing is done.
+\&\fBEVP_PKEY_CTX_free()\fR frees up the context \fIctx\fR.
+If \fIctx\fR is \s-1NULL,\s0 nothing is done.
+.PP
+\&\fBEVP_PKEY_is_a()\fR checks if the key type associated with \fIctx\fR is \fIkeytype\fR.
.SH "NOTES"
.IX Header "NOTES"
+.SS "On \fB\s-1EVP_PKEY_CTX\s0\fP"
+.IX Subsection "On EVP_PKEY_CTX"
The \fB\s-1EVP_PKEY_CTX\s0\fR structure is an opaque public key algorithm context used
by the OpenSSL high-level public key \s-1API.\s0 Contexts \fB\s-1MUST NOT\s0\fR be shared between
threads: that is it is not permissible to use the same context simultaneously
in two threads.
+.SS "On Key Types"
+.IX Subsection "On Key Types"
+We mention \*(L"key type\*(R" in this manual, which is the same
+as \*(L"algorithm\*(R" in most cases, allowing either term to be used
+interchangeably. There are algorithms where the \fIkey type\fR and the
+\&\fIalgorithm\fR of the operations that use the keys are not the same,
+such as \s-1EC\s0 keys being used for \s-1ECDSA\s0 and \s-1ECDH\s0 operations.
+.PP
+Key types are given in two different manners:
+.IP "Legacy \s-1NID\s0 or \s-1EVP_PKEY\s0 type" 4
+.IX Item "Legacy NID or EVP_PKEY type"
+This is the \fIid\fR used with \fBEVP_PKEY_CTX_new_id()\fR.
+.Sp
+These are \fB\s-1EVP_PKEY_RSA\s0\fR, \fB\s-1EVP_PKEY_RSA_PSS\s0\fR, \fB\s-1EVP_PKEY_DSA\s0\fR,
+\&\fB\s-1EVP_PKEY_DH\s0\fR, \fB\s-1EVP_PKEY_EC\s0\fR, \fB\s-1EVP_PKEY_SM2\s0\fR, \fB\s-1EVP_PKEY_X25519\s0\fR,
+\&\fB\s-1EVP_PKEY_X448\s0\fR, and are used by legacy methods.
+.IP "Name strings" 4
+.IX Item "Name strings"
+This is the \fIname\fR used with \fBEVP_PKEY_CTX_new_from_name()\fR.
+.Sp
+These are names like \*(L"\s-1RSA\*(R", \*(L"DSA\*(R",\s0 and what's available depends on what
+providers are currently accessible.
+.Sp
+The OpenSSL providers offer a set of key types available this way, please
+see \s-1\fBOSSL_PROVIDER\-FIPS\s0\fR\|(7) and \fBOSSL_PROVIDER\-default\fR\|(7) and related
+documentation for more information.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
-\&\fBEVP_PKEY_CTX_new()\fR, \fBEVP_PKEY_CTX_new_id()\fR, \fBEVP_PKEY_CTX_dup()\fR returns either
-the newly allocated \fB\s-1EVP_PKEY_CTX\s0\fR structure of \fB\s-1NULL\s0\fR if an error occurred.
+\&\fBEVP_PKEY_CTX_new()\fR, \fBEVP_PKEY_CTX_new_id()\fR and \fBEVP_PKEY_CTX_dup()\fR return either
+the newly allocated \fB\s-1EVP_PKEY_CTX\s0\fR structure or \fB\s-1NULL\s0\fR if an error occurred.
.PP
\&\fBEVP_PKEY_CTX_free()\fR does not return a value.
+.PP
+\&\fBEVP_PKEY_CTX_is_a()\fR returns 1 for true and 0 for false.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBEVP_PKEY_new\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
-These functions were added in OpenSSL 1.0.0.
+The \fBEVP_PKEY_CTX_new()\fR, \fBEVP_PKEY_CTX_new_id()\fR, \fBEVP_PKEY_CTX_dup()\fR and
+\&\fBEVP_PKEY_CTX_free()\fR functions were added in OpenSSL 1.0.0.
+.PP
+The \fBEVP_PKEY_CTX_new_from_name()\fR and \fBEVP_PKEY_CTX_new_from_pkey()\fR functions were
+added in OpenSSL 3.0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
-Copyright 2006\-2020 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2006\-2021 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>.