doc/crypto/EVP_MD_meth_new.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 EVP_MD_meth_new, EVP_MD_meth_free, EVP_MD_meth_set_input_blocksize,
   6 EVP_MD_meth_set_result_size, EVP_MD_meth_set_app_datasize,
   7 EVP_MD_meth_set_flags, EVP_MD_meth_set_init, EVP_MD_meth_set_update,
   8 EVP_MD_meth_set_final, EVP_MD_meth_set_copy, EVP_MD_meth_set_cleanup,
   9 EVP_MD_meth_set_ctrl, EVP_MD_meth_get_input_blocksize,
  10 EVP_MD_meth_get_result_size, EVP_MD_meth_get_app_datasize,
  11 EVP_MD_meth_get_flags, EVP_MD_meth_get_init, EVP_MD_meth_get_update,
  12 EVP_MD_meth_get_final, EVP_MD_meth_get_copy, EVP_MD_meth_get_cleanup,
  13 EVP_MD_meth_get_ctrl, EVP_MD_meth_get_pkey_types,
  14 EVP_MD_meth_get_sign, EVP_MD_meth_get_verify - Routines to build up
  15 EVP_MD methods
  16
  17 =head1 SYNOPSIS
  18
  19  #include <openssl/evp.h>
  20
  21  EVP_MD *EVP_MD_meth_new(int md_type, int pkey_type);
  22  EVP_MD *EVP_MD_meth_dup(const EVP_MD *md);
  23  void EVP_MD_meth_free(EVP_MD *md);
  24
  25  int EVP_MD_meth_set_input_blocksize(EVP_MD *md, int blocksize);
  26  int EVP_MD_meth_set_result_size(EVP_MD *md, int resultsize);
  27  int EVP_MD_meth_set_app_datasize(EVP_MD *md, int datasize);
  28  int EVP_MD_meth_set_flags(EVP_MD *md, unsigned long flags);
  29  int EVP_MD_meth_set_init(EVP_MD *md, int (*init)(EVP_MD_CTX *ctx));
  30  int EVP_MD_meth_set_update(EVP_MD *md, int (*update)(EVP_MD_CTX *ctx,
  31                                                       const void *data,
  32                                                       size_t count));
  33  int EVP_MD_meth_set_final(EVP_MD *md, int (*final)(EVP_MD_CTX *ctx,
  34                                                     unsigned char *md));
  35  int EVP_MD_meth_set_copy(EVP_MD *md, int (*copy)(EVP_MD_CTX *to,
  36                                                   const EVP_MD_CTX *from));
  37  int EVP_MD_meth_set_cleanup(EVP_MD *md, int (*cleanup)(EVP_MD_CTX *ctx));
  38  int EVP_MD_meth_set_ctrl(EVP_MD *md, int (*ctrl)(EVP_MD_CTX *ctx, int cmd,
  39                                                   int p1, void *p2));
  40
  41  int EVP_MD_meth_get_input_blocksize(const EVP_MD *md);
  42  int EVP_MD_meth_get_result_size(const EVP_MD *md);
  43  int EVP_MD_meth_get_app_datasize(const EVP_MD *md);
  44  unsigned long EVP_MD_meth_get_flags(const EVP_MD *md);
  45  int (*EVP_MD_meth_get_init(const EVP_MD *md))(EVP_MD_CTX *ctx);
  46  int (*EVP_MD_meth_get_update(const EVP_MD *md))(EVP_MD_CTX *ctx,
  47                                                  const void *data,
  48                                                  size_t count);
  49  int (*EVP_MD_meth_get_final(const EVP_MD *md))(EVP_MD_CTX *ctx,
  50                                                 unsigned char *md);
  51  int (*EVP_MD_meth_get_copy(const EVP_MD *md))(EVP_MD_CTX *to,
  52                                                const EVP_MD_CTX *from);
  53  int (*EVP_MD_meth_get_cleanup(const EVP_MD *md))(EVP_MD_CTX *ctx);
  54  int (*EVP_MD_meth_get_ctrl(const EVP_MD *md))(EVP_MD_CTX *ctx, int cmd,
  55                                                int p1, void *p2);
  56
  57 =head1 DESCRIPTION
  58
  59 The B<EVP_MD> type is a structure for digest method implementation.
  60 It can also have associated public/private key signing and verifying
  61 routines.
  62
  63 EVP_MD_meth_new() creates a new B<EVP_MD> structure.
  64
  65 EVP_MD_meth_dup() creates a copy of B<md>.
  66
  67 EVP_MD_meth_free() destroys a B<EVP_MD> structure.
  68
  69 EVP_MD_meth_set_input_blocksize() sets the internal input block size
  70 for the method B<md> to B<blocksize> bytes.
  71
  72 EVP_MD_meth_set_result_size() sets the size of the result that the
  73 digest method in B<md> is expected to produce to B<resultsize> bytes.
  74
  75 The digest method may have its own private data, which OpenSSL will
  76 allocate for it.  EVP_MD_meth_set_app_datasize() should be used to
  77 set the size for it to B<datasize>.
  78
  79 EVP_MD_meth_set_flags() sets the flags to describe optional
  80 behaviours in the particular B<md>.  Several flags can be or'd
  81 together.  The available flags are:
  82
  83 =over 4
  84
  85 =item EVP_MD_FLAG_ONESHOT
  86
  87 This digest method can only handles one block of input.
  88
  89 =item EVP_MD_FLAG_DIGALGID_NULL
  90
  91 When setting up a DigestAlgorithmIdentifier, this flag will have the
  92 parameter set to NULL by default.  Use this for PKCS#1.  I<Note: if
  93 combined with EVP_MD_FLAG_DIGALGID_ABSENT, the latter will override.>
  94
  95 =item EVP_MD_FLAG_DIGALGID_ABSENT
  96
  97 When setting up a DigestAlgorithmIdentifier, this flag will have the
  98 parameter be left absent by default.  I<Note: if combined with
  99 EVP_MD_FLAG_DIGALGID_NULL, the latter will be overridden.>
 100
 101 =item EVP_MD_FLAG_DIGALGID_CUSTOM
 102
 103 Custom DigestAlgorithmIdentifier handling via ctrl, with
 104 B<EVP_MD_FLAG_DIGALGID_ABSENT> as default.  I<Note: if combined with
 105 EVP_MD_FLAG_DIGALGID_NULL, the latter will be overridden.>
 106 Currently unused.
 107
 108 =back
 109
 110 EVP_MD_meth_set_init() sets the digest init function for B<md>.
 111 The digest init function is called by EVP_DigestInit(),
 112 EVP_DigestInit_ex(), EVP_SignInit, EVP_SignInit_ex(), EVP_VerifyInit()
 113 and EVP_VerifyInit_ex().
 114
 115 EVP_MD_meth_set_update() sets the digest update function for B<md>.
 116 The digest update function is called by EVP_DigestUpdate(),
 117 EVP_SignUpdate().
 118
 119 EVP_MD_meth_set_final() sets the digest final function for B<md>.
 120 The digest final function is called by EVP_DigestFinal(),
 121 EVP_DigestFinal_ex(), EVP_SignFinal() and EVP_VerifyFinal().
 122
 123 EVP_MD_meth_set_copy() sets the function for B<md> to do extra
 124 computations after the method's private data structure has been copied
 125 from one B<EVP_MD_CTX> to another.  If all that's needed is to copy
 126 the data, there is no need for this copy function.
 127 Note that the copy function is passed two B<EVP_MD_CTX *>, the private
 128 data structure is then available with EVP_MD_CTX_md_data().
 129 This copy function is called by EVP_MD_CTX_copy() and
 130 EVP_MD_CTX_copy_ex().
 131
 132 EVP_MD_meth_set_cleanup() sets the function for B<md> to do extra
 133 cleanup before the method's privata data structure is cleaned out and
 134 freed.
 135 Note that the cleanup function is passed a B<EVP_MD_CTX *>, the
 136 private data structure is then available with EVP_MD_CTX_md_data().
 137 This cleanup function is called by EVP_MD_CTX_reset() and
 138 EVP_MD_CTX_free().
 139
 140 EVP_MD_meth_set_ctrl() sets the control function for B<md>.
 141
 142
 143 EVP_MD_meth_get_input_blocksize(), EVP_MD_meth_get_result_size(),
 144 EVP_MD_meth_get_app_datasize(), EVP_MD_meth_get_flags(),
 145 EVP_MD_meth_get_init(), EVP_MD_meth_get_update(),
 146 EVP_MD_meth_get_final(), EVP_MD_meth_get_copy(),
 147 EVP_MD_meth_get_cleanup() and EVP_MD_meth_get_ctrl() are all used
 148 to retrieve the method data given with the EVP_MD_meth_set_*()
 149 functions above.
 150
 151 =head1 SEE ALSO
 152
 153 L<EVP_DigestInit(3)>, L<EVP_SignInit(3)>, L<EVP_VerifyInit(3)>
 154
 155 =head1 HISTORY
 156
 157 The B<EVP_MD> structure was openly available in OpenSSL before version
 158 1.1.  The functions described here were added in OpenSSL version 1.1.
 159
 160 =head1 COPYRIGHT
 161
 162 Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
 163
 164 Licensed under the OpenSSL license (the "License").  You may not use
 165 this file except in compliance with the License.  You can obtain a copy
 166 in the file LICENSE in the source distribution or at
 167 L<https://www.openssl.org/source/license.html>.
 168
 169 =cut