1.\" $OpenBSD: EVP_PKEY_verify_recover.3,v 1.9 2018/03/23 04:34:23 schwarze Exp $ 2.\" full merge up to: OpenSSL 48e5119a Jan 19 10:49:22 2018 +0100 3.\" 4.\" This file was written by Dr. Stephen Henson <steve@openssl.org>. 5.\" Copyright (c) 2006, 2009, 2010, 2013, 2018 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: March 23 2018 $ 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 74The 75.Fn EVP_PKEY_verify_recover_init 76function initializes a public key algorithm context using key 77.Fa ctx->pkey 78for a verify recover operation. 79.Pp 80The 81.Fn EVP_PKEY_verify_recover 82function recovers signed data using 83.Fa ctx . 84The signature is specified using the 85.Fa sig 86and 87.Fa siglen 88parameters. 89If 90.Fa rout 91is 92.Dv NULL , 93then the maximum size of the output buffer is written to the 94.Fa routlen 95parameter. 96If 97.Fa rout 98is not 99.Dv NULL , 100then before the call the 101.Fa routlen 102parameter should contain the length of the 103.Fa rout 104buffer. 105If the call is successful, recovered data is written to 106.Fa rout 107and the amount of data written to 108.Fa routlen . 109.Pp 110Normally an application is only interested in whether a signature 111verification operation is successful. 112In those cases, the 113.Xr EVP_PKEY_verify 3 114function should be used. 115.Pp 116Sometimes however it is useful to obtain the data originally signed 117using a signing operation. 118Only certain public key algorithms can recover a signature in this way 119(for example RSA in PKCS padding mode). 120.Pp 121After the call to 122.Fn EVP_PKEY_verify_recover_init , 123algorithm specific control operations can be performed to set any 124appropriate parameters for the operation. 125.Pp 126The function 127.Fn EVP_PKEY_verify_recover 128can be called more than once on the same context if several operations 129are performed using the same parameters. 130.Sh RETURN VALUES 131.Fn EVP_PKEY_verify_recover_init 132and 133.Fn EVP_PKEY_verify_recover 134return 1 for success and 0 or a negative value for failure. 135In particular, a return value of -2 indicates the operation is not 136supported by the public key algorithm. 137.Sh EXAMPLES 138Recover 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 143EVP_PKEY_CTX *ctx; 144unsigned char *rout, *sig; 145size_t routlen, siglen; 146EVP_PKEY *verify_key; 147 148/* 149 * Assumes that verify_key, sig, and siglen are already set up 150 * and that verify_key is an RSA public key. 151 */ 152ctx = EVP_PKEY_CTX_new(verify_key, NULL); 153if (!ctx) 154 /* Error occurred */ 155if (EVP_PKEY_verify_recover_init(ctx) <= 0) 156 /* Error */ 157if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_PADDING) <= 0) 158 /* Error */ 159if (EVP_PKEY_CTX_set_signature_md(ctx, EVP_sha256()) <= 0) 160 /* Error */ 161 162/* Determine buffer length */ 163if (EVP_PKEY_verify_recover(ctx, NULL, &routlen, sig, siglen) <= 0) 164 /* Error */ 165 166rout = malloc(routlen); 167 168if (!rout) 169 /* malloc failure */ 170 171if (EVP_PKEY_verify_recover(ctx, rout, &routlen, sig, siglen) <= 0) 172 /* Error */ 173 174/* Recovered data is routlen bytes written to buffer rout */ 175.Ed 176.Sh SEE ALSO 177.Xr EVP_PKEY_CTX_new 3 , 178.Xr EVP_PKEY_decrypt 3 , 179.Xr EVP_PKEY_derive 3 , 180.Xr EVP_PKEY_encrypt 3 , 181.Xr EVP_PKEY_meth_set_verify_recover 3 , 182.Xr EVP_PKEY_sign 3 , 183.Xr EVP_PKEY_verify 3 184.Sh HISTORY 185.Fn EVP_PKEY_verify_recover_init 186and 187.Fn EVP_PKEY_verify_recover 188first appeared in OpenSSL 1.0.0 and have been available since 189.Ox 4.9 . 190