doc/man3/EVP_PKEY_size.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 EVP_PKEY_size, EVP_PKEY_bits, EVP_PKEY_security_bits
   6 - EVP_PKEY information functions
   7
   8 =head1 SYNOPSIS
   9
  10  #include <openssl/evp.h>
  11
  12  int EVP_PKEY_size(const EVP_PKEY *pkey);
  13  int EVP_PKEY_bits(const EVP_PKEY *pkey);
  14  int EVP_PKEY_security_bits(const EVP_PKEY *pkey);
  15
  16 =head1 DESCRIPTION
  17
  18 EVP_PKEY_size() returns the maximum suitable size for the output
  19 buffers for almost all operations that can be done with I<pkey>.
  20 The primary documented use is with L<EVP_SignFinal(3)> and
  21 L<EVP_SealInit(3)>, but it isn't limited there.  The returned size is
  22 also large enough for the output buffer of L<EVP_PKEY_sign(3)>,
  23 L<EVP_PKEY_encrypt(3)>, L<EVP_PKEY_decrypt(3)>, L<EVP_PKEY_derive(3)>.
  24
  25 It must be stressed that, unless the documentation for the operation
  26 that's being performed says otherwise, the size returned by
  27 EVP_PKEY_size() is only preliminary and not exact, so the final
  28 contents of the target buffer may be smaller.  It is therefore crucial
  29 to take note of the size given back by the function that performs the
  30 operation, such as L<EVP_PKEY_sign(3)> (the I<siglen> argument will
  31 receive that length), to avoid bugs.
  32
  33 EVP_PKEY_bits() returns the cryptographic length of the cryptosystem
  34 to which the key in I<pkey> belongs, in bits.  Note that the definition
  35 of cryptographic length is specific to the key cryptosystem.
  36
  37 EVP_PKEY_security_bits() returns the number of security bits of the given
  38 I<pkey>, bits of security is defined in NIST SP800-57.
  39
  40 =head1 RETURN VALUES
  41
  42 EVP_PKEY_size(), EVP_PKEY_bits() and EVP_PKEY_security_bits() return a
  43 positive number, or 0 if this size isn't available.
  44
  45 =head1 NOTES
  46
  47 Most functions that have an output buffer and are mentioned with
  48 EVP_PKEY_size() have a functionality where you can pass NULL for the
  49 buffer and still pass a pointer to an integer and get the exact size
  50 that this function call delivers in the context that it's called in.
  51 This allows those functions to be called twice, once to find out the
  52 exact buffer size, then allocate the buffer in between, and call that
  53 function again actually output the data.  For those functions, it
  54 isn't strictly necessary to call EVP_PKEY_size() to find out the
  55 buffer size, but may be useful in cases where it's desirable to know
  56 the upper limit in advance.
  57
  58 It should also be especially noted that EVP_PKEY_size() shouldn't be
  59 used to get the output size for EVP_DigestSignFinal(), according to
  60 L<EVP_DigestSignFinal(3)/NOTES>.
  61
  62 =head1 SEE ALSO
  63
  64 L<EVP_SignFinal(3)>,
  65 L<EVP_SealInit(3)>,
  66 L<EVP_PKEY_sign(3)>,
  67 L<EVP_PKEY_encrypt(3)>,
  68 L<EVP_PKEY_decrypt(3)>,
  69 L<EVP_PKEY_derive(3)>
  70
  71 =head1 COPYRIGHT
  72
  73 Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
  74
  75 Licensed under the Apache License 2.0 (the "License").  You may not use
  76 this file except in compliance with the License.  You can obtain a copy
  77 in the file LICENSE in the source distribution or at
  78 L<https://www.openssl.org/source/license.html>.
  79
  80 =cut