doc/man3/EVP_CIPHER_CTX_get_iv.pod

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