| 1 | =pod
|
|---|
| 2 |
|
|---|
| 3 | =head1 NAME
|
|---|
| 4 |
|
|---|
| 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,
|
|---|
| 7 | EVP_PKEY_CTX_is_a
|
|---|
| 8 | - public key algorithm context functions
|
|---|
| 9 |
|
|---|
| 10 | =head1 SYNOPSIS
|
|---|
| 11 |
|
|---|
| 12 | #include <openssl/evp.h>
|
|---|
| 13 |
|
|---|
| 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,
|
|---|
| 17 | const char *name,
|
|---|
| 18 | const char *propquery);
|
|---|
| 19 | EVP_PKEY_CTX *EVP_PKEY_CTX_new_from_pkey(OSSL_LIB_CTX *libctx,
|
|---|
| 20 | EVP_PKEY *pkey,
|
|---|
| 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);
|
|---|
| 25 |
|
|---|
| 26 | =head1 DESCRIPTION
|
|---|
| 27 |
|
|---|
| 28 | The EVP_PKEY_CTX_new() function allocates public key algorithm context using
|
|---|
| 29 | the I<pkey> key type and ENGINE I<e>.
|
|---|
| 30 |
|
|---|
| 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>.
|
|---|
| 33 |
|
|---|
| 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.
|
|---|
| 40 |
|
|---|
| 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.
|
|---|
| 46 |
|
|---|
| 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
|
|---|
| 50 | algorithms.
|
|---|
| 51 |
|
|---|
| 52 | EVP_PKEY_CTX_dup() duplicates the context I<ctx>. It is not supported for a
|
|---|
| 53 | keygen operation.
|
|---|
| 54 |
|
|---|
| 55 | EVP_PKEY_CTX_free() frees up the context I<ctx>.
|
|---|
| 56 | If I<ctx> is NULL, nothing is done.
|
|---|
| 57 |
|
|---|
| 58 | EVP_PKEY_is_a() checks if the key type associated with I<ctx> is I<keytype>.
|
|---|
| 59 |
|
|---|
| 60 | =head1 NOTES
|
|---|
| 61 |
|
|---|
| 62 | =head2 On B<EVP_PKEY_CTX>
|
|---|
| 63 |
|
|---|
| 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
|
|---|
| 67 | in two threads.
|
|---|
| 68 |
|
|---|
| 69 | =head2 On Key Types
|
|---|
| 70 |
|
|---|
| 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.
|
|---|
| 76 |
|
|---|
| 77 | Key types are given in two different manners:
|
|---|
| 78 |
|
|---|
| 79 | =over 4
|
|---|
| 80 |
|
|---|
| 81 | =item Legacy NID or EVP_PKEY type
|
|---|
| 82 |
|
|---|
| 83 | This is the I<id> used with EVP_PKEY_CTX_new_id().
|
|---|
| 84 |
|
|---|
| 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.
|
|---|
| 88 |
|
|---|
| 89 | =item Name strings
|
|---|
| 90 |
|
|---|
| 91 | This is the I<name> used with EVP_PKEY_CTX_new_from_name().
|
|---|
| 92 |
|
|---|
| 93 | These are names like "RSA", "DSA", and what's available depends on what
|
|---|
| 94 | providers are currently accessible.
|
|---|
| 95 |
|
|---|
| 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.
|
|---|
| 99 |
|
|---|
| 100 | =back
|
|---|
| 101 |
|
|---|
| 102 | =head1 RETURN VALUES
|
|---|
| 103 |
|
|---|
| 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.
|
|---|
| 106 |
|
|---|
| 107 | EVP_PKEY_CTX_free() does not return a value.
|
|---|
| 108 |
|
|---|
| 109 | EVP_PKEY_CTX_is_a() returns 1 for true and 0 for false.
|
|---|
| 110 |
|
|---|
| 111 | =head1 SEE ALSO
|
|---|
| 112 |
|
|---|
| 113 | L<EVP_PKEY_new(3)>
|
|---|
| 114 |
|
|---|
| 115 | =head1 HISTORY
|
|---|
| 116 |
|
|---|
| 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.
|
|---|
| 119 |
|
|---|
| 120 | The EVP_PKEY_CTX_new_from_name() and EVP_PKEY_CTX_new_from_pkey() functions were
|
|---|
| 121 | added in OpenSSL 3.0.
|
|---|
| 122 |
|
|---|
| 123 | =head1 COPYRIGHT
|
|---|
| 124 |
|
|---|
| 125 | Copyright 2006-2021 The OpenSSL Project Authors. All Rights Reserved.
|
|---|
| 126 |
|
|---|
| 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>.
|
|---|
| 131 |
|
|---|
| 132 | =cut
|
|---|
