doc/crypto/EVP_DigestSignInit.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 EVP_DigestSignInit, EVP_DigestSignUpdate, EVP_DigestSignFinal - EVP signing functions
   6
   7 =head1 SYNOPSIS
   8
   9  #include <openssl/evp.h>
  10
  11  int EVP_DigestSignInit(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx,
  12                         const EVP_MD *type, ENGINE *e, EVP_PKEY *pkey);
  13  int EVP_DigestSignUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt);
  14  int EVP_DigestSignFinal(EVP_MD_CTX *ctx, unsigned char *sig, size_t *siglen);
  15
  16 =head1 DESCRIPTION
  17
  18 The EVP signature routines are a high level interface to digital signatures.
  19
  20 EVP_DigestSignInit() sets up signing context B<ctx> to use digest B<type> from
  21 ENGINE B<impl> and private key B<pkey>. B<ctx> must be created with
  22 EVP_MD_CTX_new() before calling this function. If B<pctx> is not NULL the
  23 EVP_PKEY_CTX of the signing operation will be written to B<*pctx>: this can
  24 be used to set alternative signing options. The digest B<type> may be NULL if
  25 the signing algorithm supports it.
  26
  27 Only EVP_PKEY types that support signing can be used with these functions. This
  28 includes MAC algorithms where the MAC generation is considered as a form of
  29 "signing." Built-in EVP_PKEY types supported by these functions are CMAC, DSA,
  30 ECDSA, HMAC and RSA.
  31
  32 Not all digests can be used for all key types. The following combinations apply.
  33
  34 =over 4
  35
  36 =item DSA
  37
  38 Supports SHA1, SHA224, SHA256, SHA384 and SHA512
  39
  40 =item ECDSA
  41
  42 Supports SHA1, SHA224, SHA256, SHA384 and SHA512
  43
  44 =item RSA with no padding
  45
  46 Supports no digests (the digest B<type> must be NULL)
  47
  48 =item RSA with X931 padding
  49
  50 Supports SHA1, SHA256, SHA384 and SHA512
  51
  52 =item All other RSA padding types
  53
  54 Support SHA1, SHA224, SHA256, SHA384, SHA512, MD5, MD5_SHA1, MD2, MD4, MDC2,
  55 RIPEMD160
  56
  57 =item HMAC
  58
  59 Supports any digest
  60
  61 =item CMAC
  62
  63 Will ignore any digest provided.
  64
  65 =back
  66
  67 EVP_DigestSignUpdate() hashes B<cnt> bytes of data at B<d> into the
  68 signature context B<ctx>. This function can be called several times on the
  69 same B<ctx> to include additional data. This function is currently implemented
  70 using a macro.
  71
  72 EVP_DigestSignFinal() signs the data in B<ctx> places the signature in B<sig>.
  73 If B<sig> is B<NULL> then the maximum size of the output buffer is written to
  74 the B<siglen> parameter. If B<sig> is not B<NULL> then before the call the
  75 B<siglen> parameter should contain the length of the B<sig> buffer, if the
  76 call is successful the signature is written to B<sig> and the amount of data
  77 written to B<siglen>.
  78
  79 =head1 RETURN VALUES
  80
  81 EVP_DigestSignInit() EVP_DigestSignUpdate() and EVP_DigestSignaFinal() return
  82 1 for success and 0 or a negative value for failure. In particular a return
  83 value of -2 indicates the operation is not supported by the public key
  84 algorithm.
  85
  86 The error codes can be obtained from L<ERR_get_error(3)>.
  87
  88 =head1 NOTES
  89
  90 The B<EVP> interface to digital signatures should almost always be used in
  91 preference to the low level interfaces. This is because the code then becomes
  92 transparent to the algorithm used and much more flexible.
  93
  94 In previous versions of OpenSSL there was a link between message digest types
  95 and public key algorithms. This meant that "clone" digests such as EVP_dss1()
  96 needed to be used to sign using SHA1 and DSA. This is no longer necessary and
  97 the use of clone digest is now discouraged.
  98
  99 For some key types and parameters the random number generator must be seeded
 100 or the operation will fail.
 101
 102 The call to EVP_DigestSignFinal() internally finalizes a copy of the digest
 103 context. This means that calls to EVP_DigestSignUpdate() and
 104 EVP_DigestSignFinal() can be called later to digest and sign additional data.
 105
 106 Since only a copy of the digest context is ever finalized the context must
 107 be cleaned up after use by calling EVP_MD_CTX_cleanup() or a memory leak
 108 will occur.
 109
 110 The use of EVP_PKEY_size() with these functions is discouraged because some
 111 signature operations may have a signature length which depends on the
 112 parameters set. As a result EVP_PKEY_size() would have to return a value
 113 which indicates the maximum possible signature for any set of parameters.
 114
 115 =head1 SEE ALSO
 116
 117 L<EVP_DigestVerifyInit(3)>,
 118 L<EVP_DigestInit(3)>,
 119 L<evp(7)>, L<HMAC(3)>, L<MD2(3)>,
 120 L<MD5(3)>, L<MDC2(3)>, L<RIPEMD160(3)>,
 121 L<SHA1(3)>, L<dgst(1)>
 122
 123 =head1 HISTORY
 124
 125 EVP_DigestSignInit(), EVP_DigestSignUpdate() and EVP_DigestSignFinal()
 126 were first added to OpenSSL 1.0.0.
 127
 128 =head1 COPYRIGHT
 129
 130 Copyright 2006-2017 The OpenSSL Project Authors. All Rights Reserved.
 131
 132 Licensed under the OpenSSL license (the "License").  You may not use
 133 this file except in compliance with the License.  You can obtain a copy
 134 in the file LICENSE in the source distribution or at
 135 L<https://www.openssl.org/source/license.html>.
 136
 137 =cut