lib/libcrypto/man/RSA_check_key.3

   1 .\"     $OpenBSD: RSA_check_key.3,v 1.4 2016/12/11 12:21:48 schwarze 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: December 11 2016 $
  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
  65 This function validates RSA keys.
  66 It checks that
  67 .Fa rsa->p
  68 and
  69 .Fa rsa->q
  70 are in fact prime, and that
  71 .Fa rsa->n
  72 satifies n = p*q.
  73 .Pp
  74 It also checks that
  75 .Fa rsa->d
  76 and
  77 .Fa rsa->e
  78 satisfy d*e = 1 mod ((p-1)*(q-1)),
  79 and that
  80 .Fa rsa->dmp1 ,
  81 .Fa rsa->dmq1 ,
  82 and
  83 .Fa resa->iqmp
  84 are set correctly or are
  85 .Dv NULL .
  86 .Pp
  87 This function does not work on RSA public keys that have only the
  88 modulus and public exponent elements populated.
  89 It performs integrity checks on all the RSA key material, so the
  90 .Vt RSA
  91 key structure must contain all the private key data too.
  92 Therefore, it cannot be used with any arbitrary
  93 .Vt RSA
  94 key object, even if it is otherwise fit for regular RSA operation.
  95 .Pp
  96 Unlike most other RSA functions, this function does
  97 .Sy not
  98 work transparently with any underlying
  99 .Vt ENGINE
 100 implementation because it uses the key data in the
 101 .Vt RSA
 102 structure directly.
 103 An
 104 .Vt ENGINE
 105 implementation can override the way key data is stored and handled,
 106 and can even provide support for HSM keys - in which case the
 107 .Vt RSA
 108 structure may contain
 109 .Sy no
 110 key data at all!
 111 If the
 112 .Vt ENGINE
 113 in question is only being used for acceleration or analysis purposes,
 114 then in all likelihood the RSA key data is complete and untouched,
 115 but this can't be assumed in the general case.
 116 .Sh RETURN VALUES
 117 .Fn RSA_check_key
 118 returns 1 if
 119 .Fa rsa
 120 is a valid RSA key, and 0 otherwise.
 121 -1 is returned if an error occurs while checking the key.
 122 .Pp
 123 If the key is invalid or an error occurred, the reason code can be
 124 obtained using
 125 .Xr ERR_get_error 3 .
 126 .Sh SEE ALSO
 127 .Xr BN_is_prime_ex 3 ,
 128 .Xr ERR_get_error 3 ,
 129 .Xr RSA_new 3
 130 .Sh HISTORY
 131 .Fn RSA_check_key
 132 appeared in OpenSSL 0.9.4.
 133 .Sh BUGS
 134 A method of verifying the RSA key using opaque RSA API functions might
 135 need to be considered.
 136 Right now
 137 .Fn RSA_check_key
 138 simply uses the
 139 .Vt RSA
 140 structure elements directly, bypassing the
 141 .Vt RSA_METHOD
 142 table altogether (and completely violating encapsulation and
 143 object-orientation in the process).
 144 The best fix will probably be to introduce a check_key() handler
 145 to the
 146 .Vt RSA_METHOD
 147 function table so that alternative implementations can also provide
 148 their own verifiers.