1*b077aed3SPierre Pronchery=pod 2*b077aed3SPierre Pronchery 3*b077aed3SPierre Pronchery=head1 NAME 4*b077aed3SPierre Pronchery 5*b077aed3SPierre ProncheryEVP_PKEY_missing_parameters, EVP_PKEY_copy_parameters, EVP_PKEY_parameters_eq, 6*b077aed3SPierre ProncheryEVP_PKEY_cmp_parameters, EVP_PKEY_eq, 7*b077aed3SPierre ProncheryEVP_PKEY_cmp - public key parameter and comparison functions 8*b077aed3SPierre Pronchery 9*b077aed3SPierre Pronchery=head1 SYNOPSIS 10*b077aed3SPierre Pronchery 11*b077aed3SPierre Pronchery #include <openssl/evp.h> 12*b077aed3SPierre Pronchery 13*b077aed3SPierre Pronchery int EVP_PKEY_missing_parameters(const EVP_PKEY *pkey); 14*b077aed3SPierre Pronchery int EVP_PKEY_copy_parameters(EVP_PKEY *to, const EVP_PKEY *from); 15*b077aed3SPierre Pronchery 16*b077aed3SPierre Pronchery int EVP_PKEY_parameters_eq(const EVP_PKEY *a, const EVP_PKEY *b); 17*b077aed3SPierre Pronchery int EVP_PKEY_eq(const EVP_PKEY *a, const EVP_PKEY *b); 18*b077aed3SPierre Pronchery 19*b077aed3SPierre ProncheryThe following functions have been deprecated since OpenSSL 3.0, and can be 20*b077aed3SPierre Proncheryhidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value, 21*b077aed3SPierre Proncherysee L<openssl_user_macros(7)>: 22*b077aed3SPierre Pronchery 23*b077aed3SPierre Pronchery int EVP_PKEY_cmp_parameters(const EVP_PKEY *a, const EVP_PKEY *b); 24*b077aed3SPierre Pronchery int EVP_PKEY_cmp(const EVP_PKEY *a, const EVP_PKEY *b); 25*b077aed3SPierre Pronchery 26*b077aed3SPierre Pronchery=head1 DESCRIPTION 27*b077aed3SPierre Pronchery 28*b077aed3SPierre ProncheryThe function EVP_PKEY_missing_parameters() returns 1 if the public key 29*b077aed3SPierre Proncheryparameters of B<pkey> are missing and 0 if they are present or the algorithm 30*b077aed3SPierre Proncherydoesn't use parameters. 31*b077aed3SPierre Pronchery 32*b077aed3SPierre ProncheryThe function EVP_PKEY_copy_parameters() copies the parameters from key 33*b077aed3SPierre ProncheryB<from> to key B<to>. An error is returned if the parameters are missing in 34*b077aed3SPierre ProncheryB<from> or present in both B<from> and B<to> and mismatch. If the parameters 35*b077aed3SPierre Proncheryin B<from> and B<to> are both present and match this function has no effect. 36*b077aed3SPierre Pronchery 37*b077aed3SPierre ProncheryThe function EVP_PKEY_parameters_eq() checks the parameters of keys 38*b077aed3SPierre ProncheryB<a> and B<b> for equality. 39*b077aed3SPierre Pronchery 40*b077aed3SPierre ProncheryThe function EVP_PKEY_eq() checks the keys B<a> and B<b> for equality, 41*b077aed3SPierre Proncheryincluding their parameters if they are available. 42*b077aed3SPierre Pronchery 43*b077aed3SPierre Pronchery=head1 NOTES 44*b077aed3SPierre Pronchery 45*b077aed3SPierre ProncheryThe main purpose of the functions EVP_PKEY_missing_parameters() and 46*b077aed3SPierre ProncheryEVP_PKEY_copy_parameters() is to handle public keys in certificates where the 47*b077aed3SPierre Proncheryparameters are sometimes omitted from a public key if they are inherited from 48*b077aed3SPierre Proncherythe CA that signed it. 49*b077aed3SPierre Pronchery 50*b077aed3SPierre ProncheryThe deprecated functions EVP_PKEY_cmp() and EVP_PKEY_cmp_parameters() differ in 51*b077aed3SPierre Proncherytheir return values compared to other _cmp() functions. They are aliases for 52*b077aed3SPierre ProncheryEVP_PKEY_eq() and EVP_PKEY_parameters_eq(). 53*b077aed3SPierre Pronchery 54*b077aed3SPierre ProncheryThe function EVP_PKEY_cmp() previously only checked the key parameters 55*b077aed3SPierre Pronchery(if there are any) and the public key, assuming that there always was 56*b077aed3SPierre Proncherya public key and that private key equality could be derived from that. 57*b077aed3SPierre ProncheryBecause it's no longer assumed that the private key in an L<EVP_PKEY(3)> is 58*b077aed3SPierre Proncheryalways accompanied by a public key, the comparison can not rely on public 59*b077aed3SPierre Proncherykey comparison alone. 60*b077aed3SPierre Pronchery 61*b077aed3SPierre ProncheryInstead, EVP_PKEY_eq() (and therefore also EVP_PKEY_cmp()) now compares: 62*b077aed3SPierre Pronchery 63*b077aed3SPierre Pronchery=over 4 64*b077aed3SPierre Pronchery 65*b077aed3SPierre Pronchery=item 1. 66*b077aed3SPierre Pronchery 67*b077aed3SPierre Proncherythe key parameters (if there are any) 68*b077aed3SPierre Pronchery 69*b077aed3SPierre Pronchery=item 2. 70*b077aed3SPierre Pronchery 71*b077aed3SPierre Proncherythe public keys or the private keys of the two B<EVP_PKEY>s, depending on 72*b077aed3SPierre Proncherywhat they both contain. 73*b077aed3SPierre Pronchery 74*b077aed3SPierre Pronchery=back 75*b077aed3SPierre Pronchery 76*b077aed3SPierre Pronchery=begin comment 77*b077aed3SPierre Pronchery 78*b077aed3SPierre ProncheryExactly what is compared is ultimately at the discretion of the provider 79*b077aed3SPierre Proncherythat holds the key, as they will compare what makes sense to them that fits 80*b077aed3SPierre Proncherythe selector bits they are passed. 81*b077aed3SPierre Pronchery 82*b077aed3SPierre Pronchery=end comment 83*b077aed3SPierre Pronchery 84*b077aed3SPierre Pronchery=head1 RETURN VALUES 85*b077aed3SPierre Pronchery 86*b077aed3SPierre ProncheryThe function EVP_PKEY_missing_parameters() returns 1 if the public key 87*b077aed3SPierre Proncheryparameters of B<pkey> are missing and 0 if they are present or the algorithm 88*b077aed3SPierre Proncherydoesn't use parameters. 89*b077aed3SPierre Pronchery 90*b077aed3SPierre ProncheryThese functions EVP_PKEY_copy_parameters() returns 1 for success and 0 for 91*b077aed3SPierre Proncheryfailure. 92*b077aed3SPierre Pronchery 93*b077aed3SPierre ProncheryThe functions EVP_PKEY_cmp_parameters(), EVP_PKEY_parameters_eq(), 94*b077aed3SPierre ProncheryEVP_PKEY_cmp() and EVP_PKEY_eq() return 1 if their 95*b077aed3SPierre Proncheryinputs match, 0 if they don't match, -1 if the key types are different and 96*b077aed3SPierre Pronchery-2 if the operation is not supported. 97*b077aed3SPierre Pronchery 98*b077aed3SPierre Pronchery=head1 SEE ALSO 99*b077aed3SPierre Pronchery 100*b077aed3SPierre ProncheryL<EVP_PKEY_CTX_new(3)>, 101*b077aed3SPierre ProncheryL<EVP_PKEY_keygen(3)> 102*b077aed3SPierre Pronchery 103*b077aed3SPierre Pronchery=head1 HISTORY 104*b077aed3SPierre Pronchery 105*b077aed3SPierre ProncheryThe EVP_PKEY_cmp() and EVP_PKEY_cmp_parameters() functions were deprecated in 106*b077aed3SPierre ProncheryOpenSSL 3.0. 107*b077aed3SPierre Pronchery 108*b077aed3SPierre ProncheryThe EVP_PKEY_eq() and EVP_PKEY_parameters_eq() were added in OpenSSL 3.0 to 109*b077aed3SPierre Proncheryreplace EVP_PKEY_cmp() and EVP_PKEY_cmp_parameters(). 110*b077aed3SPierre Pronchery 111*b077aed3SPierre Pronchery=head1 COPYRIGHT 112*b077aed3SPierre Pronchery 113*b077aed3SPierre ProncheryCopyright 2006-2021 The OpenSSL Project Authors. All Rights Reserved. 114*b077aed3SPierre Pronchery 115*b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 116*b077aed3SPierre Proncherythis file except in compliance with the License. You can obtain a copy 117*b077aed3SPierre Proncheryin the file LICENSE in the source distribution or at 118*b077aed3SPierre ProncheryL<https://www.openssl.org/source/license.html>. 119*b077aed3SPierre Pronchery 120*b077aed3SPierre Pronchery=cut 121