lib/libcrypto/man/EVP_VerifyInit.3

   1 .\"     $OpenBSD: EVP_VerifyInit.3,v 1.4 2016/11/26 20:55:26 schwarze Exp $
   2 .\"     OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100
   3 .\"
   4 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
   5 .\" Copyright (c) 2000, 2001, 2006, 2016 The OpenSSL Project.
   6 .\" All rights reserved.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\"
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\"
  15 .\" 2. Redistributions in binary form must reproduce the above copyright
  16 .\"    notice, this list of conditions and the following disclaimer in
  17 .\"    the documentation and/or other materials provided with the
  18 .\"    distribution.
  19 .\"
  20 .\" 3. All advertising materials mentioning features or use of this
  21 .\"    software must display the following acknowledgment:
  22 .\"    "This product includes software developed by the OpenSSL Project
  23 .\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
  24 .\"
  25 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
  26 .\"    endorse or promote products derived from this software without
  27 .\"    prior written permission. For written permission, please contact
  28 .\"    openssl-core@openssl.org.
  29 .\"
  30 .\" 5. Products derived from this software may not be called "OpenSSL"
  31 .\"    nor may "OpenSSL" appear in their names without prior written
  32 .\"    permission of the OpenSSL Project.
  33 .\"
  34 .\" 6. Redistributions of any form whatsoever must retain the following
  35 .\"    acknowledgment:
  36 .\"    "This product includes software developed by the OpenSSL Project
  37 .\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
  38 .\"
  39 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
  40 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  41 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  42 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
  43 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  44 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  45 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  46 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  47 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  48 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  49 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  50 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
  51 .\"
  52 .Dd $Mdocdate: November 26 2016 $
  53 .Dt EVP_VERIFYINIT 3
  54 .Os
  55 .Sh NAME
  56 .Nm EVP_VerifyInit_ex ,
  57 .Nm EVP_VerifyUpdate ,
  58 .Nm EVP_VerifyFinal ,
  59 .Nm EVP_VerifyInit
  60 .Nd EVP signature verification functions
  61 .Sh SYNOPSIS
  62 .In openssl/evp.h
  63 .Ft int
  64 .Fo EVP_VerifyInit_ex
  65 .Fa "EVP_MD_CTX *ctx"
  66 .Fa "const EVP_MD *type"
  67 .Fa "ENGINE *impl"
  68 .Fc
  69 .Ft int
  70 .Fo EVP_VerifyUpdate
  71 .Fa "EVP_MD_CTX *ctx"
  72 .Fa "const void *d"
  73 .Fa "unsigned int cnt"
  74 .Fc
  75 .Ft int
  76 .Fo EVP_VerifyFinal
  77 .Fa "EVP_MD_CTX *ctx"
  78 .Fa "unsigned char *sigbuf"
  79 .Fa "unsigned int siglen"
  80 .Fa "EVP_PKEY *pkey"
  81 .Fc
  82 .Ft int
  83 .Fo EVP_VerifyInit
  84 .Fa "EVP_MD_CTX *ctx"
  85 .Fa "const EVP_MD *type"
  86 .Fc
  87 .Sh DESCRIPTION
  88 The EVP signature verification routines are a high level interface to
  89 digital signatures.
  90 .Pp
  91 .Fn EVP_VerifyInit_ex
  92 sets up a verification context
  93 .Fa ctx
  94 to use the digest
  95 .Fa type
  96 from
  97 .Vt ENGINE
  98 .Fa impl .
  99 .Fa ctx
 100 must be initialized by calling
 101 .Xr EVP_MD_CTX_init 3
 102 before calling this function.
 103 .Pp
 104 .Fn EVP_VerifyUpdate
 105 hashes
 106 .Fa cnt
 107 bytes of data at
 108 .Fa d
 109 into the verification context
 110 .Fa ctx .
 111 This function can be called several times on the same
 112 .Fa ctx
 113 to include additional data.
 114 .Pp
 115 .Fn EVP_VerifyFinal
 116 verifies the data in
 117 .Fa ctx
 118 using the public key
 119 .Fa pkey
 120 and against the
 121 .Fa siglen
 122 bytes at
 123 .Fa sigbuf .
 124 .Pp
 125 .Fn EVP_VerifyInit
 126 initializes a verification context
 127 .Fa ctx
 128 to use the default implementation of digest
 129 .Fa type .
 130 .Pp
 131 The EVP interface to digital signatures should almost always be
 132 used in preference to the low level interfaces.
 133 This is because the code then becomes transparent to the algorithm used
 134 and much more flexible.
 135 .Pp
 136 Due to the link between message digests and public key algorithms, the
 137 correct digest algorithm must be used with the correct public key type.
 138 A list of algorithms and associated public key algorithms appears in
 139 .Xr EVP_DigestInit 3 .
 140 .Pp
 141 The call to
 142 .Fn EVP_VerifyFinal
 143 internally finalizes a copy of the digest context.
 144 This means that calls to
 145 .Fn EVP_VerifyUpdate
 146 and
 147 .Fn EVP_VerifyFinal
 148 can be called later to digest and verify additional data.
 149 .Pp
 150 Since only a copy of the digest context is ever finalized, the context
 151 must be cleaned up after use by calling
 152 .Xr EVP_MD_CTX_cleanup 3 ,
 153 or a memory leak will occur.
 154 .Sh RETURN VALUES
 155 .Fn EVP_VerifyInit_ex
 156 and
 157 .Fn EVP_VerifyUpdate
 158 return 1 for success and 0 for failure.
 159 .Pp
 160 .Fn EVP_VerifyFinal
 161 returns 1 for a correct signature, 0 for failure, and -1 if some other
 162 error occurred.
 163 .Pp
 164 The error codes can be obtained by
 165 .Xr ERR_get_error 3 .
 166 .Sh SEE ALSO
 167 .Xr ERR 3 ,
 168 .Xr evp 3 ,
 169 .Xr EVP_DigestInit 3 ,
 170 .Xr EVP_SignInit 3
 171 .Sh HISTORY
 172 .Fn EVP_VerifyInit ,
 173 .Fn EVP_VerifyUpdate ,
 174 and
 175 .Fn EVP_VerifyFinal
 176 are available in all versions of SSLeay and OpenSSL.
 177 .Pp
 178 .Fn EVP_VerifyInit_ex
 179 was added in OpenSSL 0.9.7.
 180 .Sh BUGS
 181 Older versions of this documentation wrongly stated that calls to
 182 .Fn EVP_VerifyUpdate
 183 could not be made after calling
 184 .Fn EVP_VerifyFinal .
 185 .Pp
 186 Since the public key is passed in the call to
 187 .Xr EVP_SignFinal 3 ,
 188 any error relating to the private key (for example an unsuitable key and
 189 digest combination) will not be indicated until after potentially large
 190 amounts of data have been passed through
 191 .Xr EVP_SignUpdate 3 .
 192 .Pp
 193 It is not possible to change the signing parameters using these
 194 functions.
 195 .Pp
 196 The previous two bugs are fixed in the newer functions of the
 197 .Xr EVP_DigestVerifyInit 3
 198 family.