doc/man3/EVP_PKEY_copy_parameters.pod

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