doc/man3/EVP_CIPHER_CTX_get_original_iv.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 EVP_CIPHER_CTX_get_original_iv, EVP_CIPHER_CTX_get_updated_iv,
   6 EVP_CIPHER_CTX_iv, EVP_CIPHER_CTX_original_iv,
   7 EVP_CIPHER_CTX_iv_noconst - Routines to inspect EVP_CIPHER_CTX IV data
   8
   9 =head1 SYNOPSIS
  10
  11  #include <openssl/evp.h>
  12
  13  int EVP_CIPHER_CTX_get_original_iv(EVP_CIPHER_CTX *ctx, void *buf, size_t len);
  14  int EVP_CIPHER_CTX_get_updated_iv(EVP_CIPHER_CTX *ctx, void *buf, size_t len);
  15
  16 The following functions have been deprecated since OpenSSL 3.0, and can be
  17 hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value,
  18 see L<openssl_user_macros(7)>:
  19
  20  const unsigned char *EVP_CIPHER_CTX_iv(const EVP_CIPHER_CTX *ctx);
  21  const unsigned char *EVP_CIPHER_CTX_original_iv(const EVP_CIPHER_CTX *ctx);
  22  unsigned char *EVP_CIPHER_CTX_iv_noconst(EVP_CIPHER_CTX *ctx);
  23
  24 =head1 DESCRIPTION
  25
  26 EVP_CIPHER_CTX_get_original_iv() and EVP_CIPHER_CTX_get_updated_iv() copy
  27 initialization vector (IV) information from the B<EVP_CIPHER_CTX> into the
  28 caller-supplied buffer. L<EVP_CIPHER_CTX_get_iv_length(3)> can be used to
  29 determine an appropriate buffer size, and if the supplied buffer is too small,
  30 an error will be returned (and no data copied).
  31 EVP_CIPHER_CTX_get_original_iv() accesses the ("original") IV that was
  32 supplied when the B<EVP_CIPHER_CTX> was initialized, and
  33 EVP_CIPHER_CTX_get_updated_iv() accesses the current "IV state"
  34 of the cipher, which is updated during cipher operation for certain cipher modes
  35 (e.g., CBC and OFB).
  36
  37 The functions EVP_CIPHER_CTX_iv(), EVP_CIPHER_CTX_original_iv(), and
  38 EVP_CIPHER_CTX_iv_noconst() are deprecated functions that provide similar (at
  39 a conceptual level) functionality.  EVP_CIPHER_CTX_iv() returns a pointer to
  40 the beginning of the "IV state" as maintained internally in the
  41 B<EVP_CIPHER_CTX>; EVP_CIPHER_CTX_original_iv() returns a pointer to the
  42 beginning of the ("original") IV, as maintained by the B<EVP_CIPHER_CTX>, that
  43 was provided when the B<EVP_CIPHER_CTX> was initialized; and
  44 EVP_CIPHER_CTX_get_iv_noconst() is the same as EVP_CIPHER_CTX_iv() but has a
  45 different return type for the pointer.
  46
  47 =head1 RETURN VALUES
  48
  49 EVP_CIPHER_CTX_get_original_iv() and EVP_CIPHER_CTX_get_updated_iv() return 1
  50 on success and 0 on failure.
  51
  52 The functions EVP_CIPHER_CTX_iv(), EVP_CIPHER_CTX_original_iv(), and
  53 EVP_CIPHER_CTX_iv_noconst() return a pointer to an IV as an array of bytes on
  54 success, and NULL on failure.
  55
  56 =head1 HISTORY
  57
  58 EVP_CIPHER_CTX_get_original_iv() and EVP_CIPHER_CTX_get_updated_iv() were added
  59 in OpenSSL 3.0.0.
  60
  61 EVP_CIPHER_CTX_iv(), EVP_CIPHER_CTX_original_iv(), and
  62 EVP_CIPHER_CTX_iv_noconst() were added in OpenSSL 1.1.0, and were deprecated
  63 in OpenSSL 3.0.0.
  64
  65 =head1 COPYRIGHT
  66
  67 Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.
  68
  69 Licensed under the Apache License 2.0 (the "License").  You may not use
  70 this file except in compliance with the License.  You can obtain a copy
  71 in the file LICENSE in the source distribution or at
  72 L<https://www.openssl.org/source/license.html>.
  73
  74 =cut