1.\" $OpenBSD: RSA_check_key.3,v 1.8 2021/03/12 05:18:00 jsg Exp $ 2.\" OpenSSL 6859cf74 Sep 25 13:33:28 2002 +0000 3.\" 4.\" This file was written by Ulf Moeller <ulf@openssl.org> and 5.\" Geoff Thorpe <geoff@openssl.org>. 6.\" Copyright (c) 2000, 2002 The OpenSSL Project. 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 12 2021 $ 53.Dt RSA_CHECK_KEY 3 54.Os 55.Sh NAME 56.Nm RSA_check_key 57.Nd validate private RSA keys 58.Sh SYNOPSIS 59.In openssl/rsa.h 60.Ft int 61.Fo RSA_check_key 62.Fa "RSA *rsa" 63.Fc 64.Sh DESCRIPTION 65This function validates RSA keys. 66It checks that 67.Fa rsa->p 68and 69.Fa rsa->q 70are in fact prime, and that 71.Fa rsa->n 72satisfies n = p*q. 73.Pp 74It also checks that 75.Fa rsa->d 76and 77.Fa rsa->e 78satisfy d*e = 1 mod ((p-1)*(q-1)), 79and that 80.Fa rsa->dmp1 , 81.Fa rsa->dmq1 , 82and 83.Fa resa->iqmp 84are set correctly or are 85.Dv NULL . 86.Pp 87This function does not work on RSA public keys that have only the 88modulus and public exponent elements populated. 89It performs integrity checks on all the RSA key material, so the 90.Vt RSA 91key structure must contain all the private key data too. 92Therefore, it cannot be used with any arbitrary 93.Vt RSA 94key object, even if it is otherwise fit for regular RSA operation. 95.Pp 96Unlike most other RSA functions, this function does 97.Sy not 98work transparently with any underlying 99.Vt ENGINE 100implementation because it uses the key data in the 101.Vt RSA 102structure directly. 103An 104.Vt ENGINE 105implementation can override the way key data is stored and handled, 106and can even provide support for HSM keys - in which case the 107.Vt RSA 108structure may contain 109.Sy no 110key data at all! 111If the 112.Vt ENGINE 113in question is only being used for acceleration or analysis purposes, 114then in all likelihood the RSA key data is complete and untouched, 115but this can't be assumed in the general case. 116.Sh RETURN VALUES 117.Fn RSA_check_key 118returns 1 if 119.Fa rsa 120is a valid RSA key, and 0 otherwise. 121-1 is returned if an error occurs while checking the key. 122.Pp 123If the key is invalid or an error occurred, the reason code can be 124obtained using 125.Xr ERR_get_error 3 . 126.Sh SEE ALSO 127.Xr BN_is_prime_ex 3 , 128.Xr RSA_get0_key 3 , 129.Xr RSA_new 3 130.Sh HISTORY 131.Fn RSA_check_key 132first appeared in OpenSSL 0.9.4 and has been available since 133.Ox 2.6 . 134.Sh BUGS 135A method of verifying the RSA key using opaque RSA API functions might 136need to be considered. 137Right now 138.Fn RSA_check_key 139simply uses the 140.Vt RSA 141structure elements directly, bypassing the 142.Vt RSA_METHOD 143table altogether (and completely violating encapsulation and 144object-orientation in the process). 145The best fix will probably be to introduce a check_key() handler 146to the 147.Vt RSA_METHOD 148function table so that alternative implementations can also provide 149their own verifiers. 150