5 EVP_PKEY_CTX_new, EVP_PKEY_CTX_new_id, EVP_PKEY_CTX_new_from_name,
6 EVP_PKEY_CTX_new_from_pkey, EVP_PKEY_CTX_dup, EVP_PKEY_CTX_free,
8 - public key algorithm context functions
12 #include <openssl/evp.h>
14 EVP_PKEY_CTX *EVP_PKEY_CTX_new(EVP_PKEY *pkey, ENGINE *e);
15 EVP_PKEY_CTX *EVP_PKEY_CTX_new_id(int id, ENGINE *e);
16 EVP_PKEY_CTX *EVP_PKEY_CTX_new_from_name(OSSL_LIB_CTX *libctx,
18 const char *propquery);
19 EVP_PKEY_CTX *EVP_PKEY_CTX_new_from_pkey(OSSL_LIB_CTX *libctx,
21 const char *propquery);
22 EVP_PKEY_CTX *EVP_PKEY_CTX_dup(const EVP_PKEY_CTX *ctx);
23 void EVP_PKEY_CTX_free(EVP_PKEY_CTX *ctx);
24 int EVP_PKEY_CTX_is_a(EVP_PKEY_CTX *ctx, const char *keytype);
28 The EVP_PKEY_CTX_new() function allocates public key algorithm context using
29 the I<pkey> key type and ENGINE I<e>.
31 The EVP_PKEY_CTX_new_id() function allocates public key algorithm context
32 using the key type specified by I<id> and ENGINE I<e>.
34 The EVP_PKEY_CTX_new_from_name() function allocates a public key algorithm
35 context using the library context I<libctx> (see L<OSSL_LIB_CTX(3)>), the
36 key type specified by I<name> and the property query I<propquery>. None
37 of the arguments are duplicated, so they must remain unchanged for the
38 lifetime of the returned B<EVP_PKEY_CTX> or of any of its duplicates. Read
39 further about the possible names in L</NOTES> below.
41 The EVP_PKEY_CTX_new_from_pkey() function allocates a public key algorithm
42 context using the library context I<libctx> (see L<OSSL_LIB_CTX(3)>) and the
43 algorithm specified by I<pkey> and the property query I<propquery>. None of the
44 arguments are duplicated, so they must remain unchanged for the lifetime of the
45 returned B<EVP_PKEY_CTX> or any of its duplicates.
47 EVP_PKEY_CTX_new_id() and EVP_PKEY_CTX_new_from_name() are normally
48 used when no B<EVP_PKEY> structure is associated with the operations,
49 for example during parameter generation or key generation for some
52 EVP_PKEY_CTX_dup() duplicates the context I<ctx>. It is not supported for a
55 EVP_PKEY_CTX_free() frees up the context I<ctx>.
56 If I<ctx> is NULL, nothing is done.
58 EVP_PKEY_is_a() checks if the key type associated with I<ctx> is I<keytype>.
62 =head2 On B<EVP_PKEY_CTX>
64 The B<EVP_PKEY_CTX> structure is an opaque public key algorithm context used
65 by the OpenSSL high-level public key API. Contexts B<MUST NOT> be shared between
66 threads: that is it is not permissible to use the same context simultaneously
71 We mention "key type" in this manual, which is the same
72 as "algorithm" in most cases, allowing either term to be used
73 interchangeably. There are algorithms where the I<key type> and the
74 I<algorithm> of the operations that use the keys are not the same,
75 such as EC keys being used for ECDSA and ECDH operations.
77 Key types are given in two different manners:
81 =item Legacy NID or EVP_PKEY type
83 This is the I<id> used with EVP_PKEY_CTX_new_id().
85 These are B<EVP_PKEY_RSA>, B<EVP_PKEY_RSA_PSS>, B<EVP_PKEY_DSA>,
86 B<EVP_PKEY_DH>, B<EVP_PKEY_EC>, B<EVP_PKEY_SM2>, B<EVP_PKEY_X25519>,
87 B<EVP_PKEY_X448>, and are used by legacy methods.
91 This is the I<name> used with EVP_PKEY_CTX_new_from_name().
93 These are names like "RSA", "DSA", and what's available depends on what
94 providers are currently accessible.
96 The OpenSSL providers offer a set of key types available this way, please
97 see L<OSSL_PROVIDER-FIPS(7)> and L<OSSL_PROVIDER-default(7)> and related
98 documentation for more information.
104 EVP_PKEY_CTX_new(), EVP_PKEY_CTX_new_id() and EVP_PKEY_CTX_dup() return either
105 the newly allocated B<EVP_PKEY_CTX> structure or B<NULL> if an error occurred.
107 EVP_PKEY_CTX_free() does not return a value.
109 EVP_PKEY_CTX_is_a() returns 1 for true and 0 for false.
117 The EVP_PKEY_CTX_new(), EVP_PKEY_CTX_new_id(), EVP_PKEY_CTX_dup() and
118 EVP_PKEY_CTX_free() functions were added in OpenSSL 1.0.0.
120 The EVP_PKEY_CTX_new_from_name() and EVP_PKEY_CTX_new_from_pkey() functions were
121 added in OpenSSL 3.0.
125 Copyright 2006-2021 The OpenSSL Project Authors. All Rights Reserved.
127 Licensed under the Apache License 2.0 (the "License"). You may not use
128 this file except in compliance with the License. You can obtain a copy
129 in the file LICENSE in the source distribution or at
130 L<https://www.openssl.org/source/license.html>.