lib/libcrypto/man/EVP_PKEY_verify_recover.3

   1 .\"     $OpenBSD: EVP_PKEY_verify_recover.3,v 1.6 2017/01/06 02:43:14 schwarze Exp $
   2 .\"     OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
   3 .\"
   4 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
   5 .\" Copyright (c) 2006, 2009, 2010, 2013 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: January 6 2017 $
  53 .Dt EVP_PKEY_VERIFY_RECOVER 3
  54 .Os
  55 .Sh NAME
  56 .Nm EVP_PKEY_verify_recover_init ,
  57 .Nm EVP_PKEY_verify_recover
  58 .Nd recover signature using a public key algorithm
  59 .Sh SYNOPSIS
  60 .In openssl/evp.h
  61 .Ft int
  62 .Fo EVP_PKEY_verify_recover_init
  63 .Fa "EVP_PKEY_CTX *ctx"
  64 .Fc
  65 .Ft int
  66 .Fo EVP_PKEY_verify_recover
  67 .Fa "EVP_PKEY_CTX *ctx"
  68 .Fa "unsigned char *rout"
  69 .Fa "size_t *routlen"
  70 .Fa "const unsigned char *sig"
  71 .Fa "size_t siglen"
  72 .Fc
  73 .Sh DESCRIPTION
  74 The
  75 .Fn EVP_PKEY_verify_recover_init
  76 function initializes a public key algorithm context using key
  77 .Fa ctx->pkey
  78 for a verify recover operation.
  79 .Pp
  80 The
  81 .Fn EVP_PKEY_verify_recover
  82 function recovers signed data using
  83 .Fa ctx .
  84 The signature is specified using the
  85 .Fa sig
  86 and
  87 .Fa siglen
  88 parameters.
  89 If
  90 .Fa rout
  91 is
  92 .Dv NULL ,
  93 then the maximum size of the output buffer is written to the
  94 .Fa routlen
  95 parameter.
  96 If
  97 .Fa rout
  98 is not
  99 .Dv NULL ,
 100 then before the call the
 101 .Fa routlen
 102 parameter should contain the length of the
 103 .Fa rout
 104 buffer.
 105 If the call is successful, recovered data is written to
 106 .Fa rout
 107 and the amount of data written to
 108 .Fa routlen .
 109 .Pp
 110 Normally an application is only interested in whether a signature
 111 verification operation is successful.
 112 In those cases, the
 113 .Xr EVP_PKEY_verify 3
 114 function should be used.
 115 .Pp
 116 Sometimes however it is useful to obtain the data originally signed
 117 using a signing operation.
 118 Only certain public key algorithms can recover a signature in this way
 119 (for example RSA in PKCS padding mode).
 120 .Pp
 121 After the call to
 122 .Fn EVP_PKEY_verify_recover_init ,
 123 algorithm specific control operations can be performed to set any
 124 appropriate parameters for the operation.
 125 .Pp
 126 The function
 127 .Fn EVP_PKEY_verify_recover
 128 can be called more than once on the same context if several operations
 129 are performed using the same parameters.
 130 .Sh RETURN VALUES
 131 .Fn EVP_PKEY_verify_recover_init
 132 and
 133 .Fn EVP_PKEY_verify_recover
 134 return 1 for success and 0 or a negative value for failure.
 135 In particular, a return value of -2 indicates the operation is not
 136 supported by the public key algorithm.
 137 .Sh EXAMPLES
 138 Recover digest originally signed using PKCS#1 and SHA256 digest:
 139 .Bd -literal -offset indent
 140 #include <openssl/evp.h>
 141 #include <openssl/rsa.h>
 142
 143 EVP_PKEY_CTX *ctx;
 144 unsigned char *rout, *sig;
 145 size_t routlen, siglen;
 146 EVP_PKEY *verify_key;
 147 /* NB: assumes verify_key, sig and siglen are already set up
 148  * and that verify_key is an RSA public key
 149  */
 150 ctx = EVP_PKEY_CTX_new(verify_key);
 151 if (!ctx)
 152         /* Error occurred */
 153 if (EVP_PKEY_verify_recover_init(ctx) <= 0)
 154         /* Error */
 155 if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_PADDING) <= 0)
 156         /* Error */
 157 if (EVP_PKEY_CTX_set_signature_md(ctx, EVP_sha256()) <= 0)
 158         /* Error */
 159
 160 /* Determine buffer length */
 161 if (EVP_PKEY_verify_recover(ctx, NULL, &routlen, sig, siglen) <= 0)
 162         /* Error */
 163
 164 rout = malloc(routlen);
 165
 166 if (!rout)
 167         /* malloc failure */
 168
 169 if (EVP_PKEY_verify_recover(ctx, rout, &routlen, sig, siglen) <= 0)
 170         /* Error */
 171
 172 /* Recovered data is routlen bytes written to buffer rout */
 173 .Ed
 174 .Sh SEE ALSO
 175 .Xr EVP_PKEY_CTX_new 3 ,
 176 .Xr EVP_PKEY_decrypt 3 ,
 177 .Xr EVP_PKEY_derive 3 ,
 178 .Xr EVP_PKEY_encrypt 3 ,
 179 .Xr EVP_PKEY_sign 3 ,
 180 .Xr EVP_PKEY_verify 3
 181 .Sh HISTORY
 182 These functions were first added to OpenSSL 1.0.0.