1*b077aed3SPierre Pronchery=pod 2*b077aed3SPierre Pronchery 3*b077aed3SPierre Pronchery=head1 NAME 4*b077aed3SPierre Pronchery 5*b077aed3SPierre ProncheryEVP_KEYMGMT, 6*b077aed3SPierre ProncheryEVP_KEYMGMT_fetch, 7*b077aed3SPierre ProncheryEVP_KEYMGMT_up_ref, 8*b077aed3SPierre ProncheryEVP_KEYMGMT_free, 9*b077aed3SPierre ProncheryEVP_KEYMGMT_get0_provider, 10*b077aed3SPierre ProncheryEVP_KEYMGMT_is_a, 11*b077aed3SPierre ProncheryEVP_KEYMGMT_get0_description, 12*b077aed3SPierre ProncheryEVP_KEYMGMT_get0_name, 13*b077aed3SPierre ProncheryEVP_KEYMGMT_do_all_provided, 14*b077aed3SPierre ProncheryEVP_KEYMGMT_names_do_all, 15*b077aed3SPierre ProncheryEVP_KEYMGMT_gettable_params, 16*b077aed3SPierre ProncheryEVP_KEYMGMT_settable_params, 17*b077aed3SPierre ProncheryEVP_KEYMGMT_gen_settable_params 18*b077aed3SPierre Pronchery- EVP key management routines 19*b077aed3SPierre Pronchery 20*b077aed3SPierre Pronchery=head1 SYNOPSIS 21*b077aed3SPierre Pronchery 22*b077aed3SPierre Pronchery #include <openssl/evp.h> 23*b077aed3SPierre Pronchery 24*b077aed3SPierre Pronchery typedef struct evp_keymgmt_st EVP_KEYMGMT; 25*b077aed3SPierre Pronchery 26*b077aed3SPierre Pronchery EVP_KEYMGMT *EVP_KEYMGMT_fetch(OSSL_LIB_CTX *ctx, const char *algorithm, 27*b077aed3SPierre Pronchery const char *properties); 28*b077aed3SPierre Pronchery int EVP_KEYMGMT_up_ref(EVP_KEYMGMT *keymgmt); 29*b077aed3SPierre Pronchery void EVP_KEYMGMT_free(EVP_KEYMGMT *keymgmt); 30*b077aed3SPierre Pronchery const OSSL_PROVIDER *EVP_KEYMGMT_get0_provider(const EVP_KEYMGMT *keymgmt); 31*b077aed3SPierre Pronchery int EVP_KEYMGMT_is_a(const EVP_KEYMGMT *keymgmt, const char *name); 32*b077aed3SPierre Pronchery const char *EVP_KEYMGMT_get0_name(const EVP_KEYMGMT *keymgmt); 33*b077aed3SPierre Pronchery const char *EVP_KEYMGMT_get0_description(const EVP_KEYMGMT *keymgmt); 34*b077aed3SPierre Pronchery 35*b077aed3SPierre Pronchery void EVP_KEYMGMT_do_all_provided(OSSL_LIB_CTX *libctx, 36*b077aed3SPierre Pronchery void (*fn)(EVP_KEYMGMT *keymgmt, void *arg), 37*b077aed3SPierre Pronchery void *arg); 38*b077aed3SPierre Pronchery int EVP_KEYMGMT_names_do_all(const EVP_KEYMGMT *keymgmt, 39*b077aed3SPierre Pronchery void (*fn)(const char *name, void *data), 40*b077aed3SPierre Pronchery void *data); 41*b077aed3SPierre Pronchery const OSSL_PARAM *EVP_KEYMGMT_gettable_params(const EVP_KEYMGMT *keymgmt); 42*b077aed3SPierre Pronchery const OSSL_PARAM *EVP_KEYMGMT_settable_params(const EVP_KEYMGMT *keymgmt); 43*b077aed3SPierre Pronchery const OSSL_PARAM *EVP_KEYMGMT_gen_settable_params(const EVP_KEYMGMT *keymgmt); 44*b077aed3SPierre Pronchery 45*b077aed3SPierre Pronchery=head1 DESCRIPTION 46*b077aed3SPierre Pronchery 47*b077aed3SPierre ProncheryB<EVP_KEYMGMT> is a method object that represents key management 48*b077aed3SPierre Proncheryimplementations for different cryptographic algorithms. 49*b077aed3SPierre ProncheryThis method object provides functionality to have providers import key 50*b077aed3SPierre Proncherymaterial from the outside, as well as export key material to the 51*b077aed3SPierre Proncheryoutside. 52*b077aed3SPierre ProncheryMost of the functionality can only be used internally and has no 53*b077aed3SPierre Proncherypublic interface, this object is simply passed into other functions 54*b077aed3SPierre Proncherywhen needed. 55*b077aed3SPierre Pronchery 56*b077aed3SPierre ProncheryEVP_KEYMGMT_fetch() looks for an algorithm within the provider that 57*b077aed3SPierre Proncheryhas been loaded into the B<OSSL_LIB_CTX> given by I<ctx>, having the 58*b077aed3SPierre Proncheryname given by I<algorithm> and the properties given by I<properties>. 59*b077aed3SPierre Pronchery 60*b077aed3SPierre ProncheryEVP_KEYMGMT_up_ref() increments the reference count for the given 61*b077aed3SPierre ProncheryB<EVP_KEYMGMT> I<keymgmt>. 62*b077aed3SPierre Pronchery 63*b077aed3SPierre ProncheryEVP_KEYMGMT_free() decrements the reference count for the given 64*b077aed3SPierre ProncheryB<EVP_KEYMGMT> I<keymgmt>, and when the count reaches zero, frees it. 65*b077aed3SPierre Pronchery 66*b077aed3SPierre ProncheryEVP_KEYMGMT_get0_provider() returns the provider that has this particular 67*b077aed3SPierre Proncheryimplementation. 68*b077aed3SPierre Pronchery 69*b077aed3SPierre ProncheryEVP_KEYMGMT_is_a() checks if I<keymgmt> is an implementation of an 70*b077aed3SPierre Proncheryalgorithm that's identifiable with I<name>. 71*b077aed3SPierre Pronchery 72*b077aed3SPierre ProncheryEVP_KEYMGMT_get0_name() returns the algorithm name from the provided 73*b077aed3SPierre Proncheryimplementation for the given I<keymgmt>. Note that the I<keymgmt> may have 74*b077aed3SPierre Proncherymultiple synonyms associated with it. In this case the first name from the 75*b077aed3SPierre Proncheryalgorithm definition is returned. Ownership of the returned string is 76*b077aed3SPierre Proncheryretained by the I<keymgmt> object and should not be freed by the caller. 77*b077aed3SPierre Pronchery 78*b077aed3SPierre ProncheryEVP_KEYMGMT_names_do_all() traverses all names for the I<keymgmt>, and 79*b077aed3SPierre Proncherycalls I<fn> with each name and I<data>. 80*b077aed3SPierre Pronchery 81*b077aed3SPierre ProncheryEVP_KEYMGMT_get0_description() returns a description of the I<keymgmt>, meant 82*b077aed3SPierre Proncheryfor display and human consumption. The description is at the discretion 83*b077aed3SPierre Proncheryof the I<keymgmt> implementation. 84*b077aed3SPierre Pronchery 85*b077aed3SPierre ProncheryEVP_KEYMGMT_do_all_provided() traverses all key keymgmt implementations by 86*b077aed3SPierre Proncheryall activated providers in the library context I<libctx>, and for each 87*b077aed3SPierre Proncheryof the implementations, calls I<fn> with the implementation method and 88*b077aed3SPierre ProncheryI<data> as arguments. 89*b077aed3SPierre Pronchery 90*b077aed3SPierre ProncheryEVP_KEYMGMT_gettable_params() and EVP_KEYMGMT_settable_params() return a 91*b077aed3SPierre Proncheryconstant L<OSSL_PARAM(3)> array that describes the names and types of key 92*b077aed3SPierre Proncheryparameters that can be retrieved or set. 93*b077aed3SPierre ProncheryEVP_KEYMGMT_gettable_params() is used by L<EVP_PKEY_gettable_params(3)>. 94*b077aed3SPierre Pronchery 95*b077aed3SPierre ProncheryEVP_KEYMGMT_gen_settable_params() returns a constant L<OSSL_PARAM(3)> array that 96*b077aed3SPierre Proncherydescribes the names and types of key generation parameters that can be set via 97*b077aed3SPierre ProncheryL<EVP_PKEY_CTX_set_params(3)>. 98*b077aed3SPierre Pronchery 99*b077aed3SPierre Pronchery=head1 NOTES 100*b077aed3SPierre Pronchery 101*b077aed3SPierre ProncheryEVP_KEYMGMT_fetch() may be called implicitly by other fetching 102*b077aed3SPierre Proncheryfunctions, using the same library context and properties. 103*b077aed3SPierre ProncheryAny other API that uses keys will typically do this. 104*b077aed3SPierre Pronchery 105*b077aed3SPierre Pronchery=head1 RETURN VALUES 106*b077aed3SPierre Pronchery 107*b077aed3SPierre ProncheryEVP_KEYMGMT_fetch() returns a pointer to the key management 108*b077aed3SPierre Proncheryimplementation represented by an EVP_KEYMGMT object, or NULL on 109*b077aed3SPierre Proncheryerror. 110*b077aed3SPierre Pronchery 111*b077aed3SPierre ProncheryEVP_KEYMGMT_up_ref() returns 1 on success, or 0 on error. 112*b077aed3SPierre Pronchery 113*b077aed3SPierre ProncheryEVP_KEYMGMT_names_do_all() returns 1 if the callback was called for all 114*b077aed3SPierre Proncherynames. A return value of 0 means that the callback was not called for any names. 115*b077aed3SPierre Pronchery 116*b077aed3SPierre ProncheryEVP_KEYMGMT_free() doesn't return any value. 117*b077aed3SPierre Pronchery 118*b077aed3SPierre ProncheryEVP_KEYMGMT_get0_provider() returns a pointer to a provider object, or NULL 119*b077aed3SPierre Proncheryon error. 120*b077aed3SPierre Pronchery 121*b077aed3SPierre ProncheryEVP_KEYMGMT_is_a() returns 1 of I<keymgmt> was identifiable, 122*b077aed3SPierre Proncheryotherwise 0. 123*b077aed3SPierre Pronchery 124*b077aed3SPierre ProncheryEVP_KEYMGMT_get0_name() returns the algorithm name, or NULL on error. 125*b077aed3SPierre Pronchery 126*b077aed3SPierre ProncheryEVP_KEYMGMT_get0_description() returns a pointer to a decription, or NULL if 127*b077aed3SPierre Proncherythere isn't one. 128*b077aed3SPierre Pronchery 129*b077aed3SPierre ProncheryEVP_KEYMGMT_gettable_params(), EVP_KEYMGMT_settable_params() and 130*b077aed3SPierre ProncheryEVP_KEYMGMT_gen_settable_params() return a constant L<OSSL_PARAM(3)> array or 131*b077aed3SPierre ProncheryNULL on error. 132*b077aed3SPierre Pronchery 133*b077aed3SPierre Pronchery=head1 SEE ALSO 134*b077aed3SPierre Pronchery 135*b077aed3SPierre ProncheryL<EVP_MD_fetch(3)>, L<OSSL_LIB_CTX(3)> 136*b077aed3SPierre Pronchery 137*b077aed3SPierre Pronchery=head1 HISTORY 138*b077aed3SPierre Pronchery 139*b077aed3SPierre ProncheryThe functions described here were added in OpenSSL 3.0. 140*b077aed3SPierre Pronchery 141*b077aed3SPierre Pronchery=head1 COPYRIGHT 142*b077aed3SPierre Pronchery 143*b077aed3SPierre ProncheryCopyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved. 144*b077aed3SPierre Pronchery 145*b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 146*b077aed3SPierre Proncherythis file except in compliance with the License. You can obtain a copy 147*b077aed3SPierre Proncheryin the file LICENSE in the source distribution or at 148*b077aed3SPierre ProncheryL<https://www.openssl.org/source/license.html>. 149*b077aed3SPierre Pronchery 150*b077aed3SPierre Pronchery=cut 151