lib/libcrypto/man/RSA_generate_key.3

   1 .\"     $OpenBSD: RSA_generate_key.3,v 1.11 2018/03/27 17:35:50 schwarze Exp $
   2 .\"     OpenSSL RSA_generate_key.pod bb6c5e7f Feb 5 10:29:22 2017 -0500
   3 .\"
   4 .\" This file was written by Ulf Moeller <ulf@openssl.org>.
   5 .\" Copyright (c) 2000, 2002, 2013 The OpenSSL Project.  All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\"
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\"
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in
  16 .\"    the documentation and/or other materials provided with the
  17 .\"    distribution.
  18 .\"
  19 .\" 3. All advertising materials mentioning features or use of this
  20 .\"    software must display the following acknowledgment:
  21 .\"    "This product includes software developed by the OpenSSL Project
  22 .\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
  23 .\"
  24 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
  25 .\"    endorse or promote products derived from this software without
  26 .\"    prior written permission. For written permission, please contact
  27 .\"    openssl-core@openssl.org.
  28 .\"
  29 .\" 5. Products derived from this software may not be called "OpenSSL"
  30 .\"    nor may "OpenSSL" appear in their names without prior written
  31 .\"    permission of the OpenSSL Project.
  32 .\"
  33 .\" 6. Redistributions of any form whatsoever must retain the following
  34 .\"    acknowledgment:
  35 .\"    "This product includes software developed by the OpenSSL Project
  36 .\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
  37 .\"
  38 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
  39 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  40 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  41 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
  42 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  43 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  44 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  45 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  46 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  47 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  48 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  49 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
  50 .\"
  51 .Dd $Mdocdate: March 27 2018 $
  52 .Dt RSA_GENERATE_KEY 3
  53 .Os
  54 .Sh NAME
  55 .Nm RSA_generate_key_ex ,
  56 .Nm RSA_generate_key
  57 .Nd generate RSA key pair
  58 .Sh SYNOPSIS
  59 .In openssl/rsa.h
  60 .Ft int
  61 .Fo RSA_generate_key_ex
  62 .Fa "RSA *rsa"
  63 .Fa "int bits"
  64 .Fa "BIGNUM *e"
  65 .Fa "BN_GENCB *cb"
  66 .Fc
  67 .Pp
  68 Deprecated:
  69 .Pp
  70 .Ft RSA *
  71 .Fo RSA_generate_key
  72 .Fa "int num"
  73 .Fa "unsigned long e"
  74 .Fa "void (*callback)(int, int, void *)"
  75 .Fa "void *cb_arg"
  76 .Fc
  77 .Sh DESCRIPTION
  78 .Fn RSA_generate_key_ex
  79 generates a key pair and stores it in
  80 .Fa rsa .
  81 .Pp
  82 The modulus size will be of length
  83 .Fa bits ,
  84 and the public exponent will be
  85 .Fa e .
  86 Key sizes with
  87 .Fa num
  88 < 1024 should be considered insecure.
  89 The exponent is an odd number, typically 3, 17 or 65537.
  90 .Pp
  91 A callback function may be used to provide feedback about the progress
  92 of the key generation.
  93 If
  94 .Fa cb
  95 is not
  96 .Dv NULL ,
  97 it will be called as follows using the
  98 .Xr BN_GENCB_call 3
  99 function:
 100 .Bl -bullet
 101 .It
 102 While a random prime number is generated, it is called as described in
 103 .Xr BN_generate_prime 3 .
 104 .It
 105 When the
 106 .Fa n Ns -th
 107 randomly generated prime is rejected as not suitable for
 108 the key,
 109 .Fn BN_GENCB_call cb 2 n
 110 is called.
 111 .It
 112 When a random p has been found with p-1 relatively prime to
 113 .Fa e ,
 114 it is called as
 115 .Fn BN_GENCB_call cb 3 0 .
 116 .El
 117 .Pp
 118 The process is then repeated for prime q with
 119 .Fn BN_GENCB_call cb 3 1 .
 120 .Pp
 121 .Fn RSA_generate_key
 122 is deprecated.
 123 New applications should use
 124 .Fn RSA_generate_key_ex
 125 instead.
 126 .Fn RSA_generate_key
 127 works in the same way as
 128 .Fn RSA_generate_key_ex
 129 except it uses "old style" call backs.
 130 See
 131 .Xr BN_generate_prime 3
 132 for further details.
 133 .Sh RETURN VALUES
 134 .Fn RSA_generate_key_ex
 135 returns 1 on success or 0 on error.
 136 .Fn RSA_generate_key
 137 returns the key on success or
 138 .Dv NULL
 139 on error.
 140 .Pp
 141 The error codes can be obtained by
 142 .Xr ERR_get_error 3 .
 143 .Sh SEE ALSO
 144 .Xr BN_generate_prime 3 ,
 145 .Xr ERR_get_error 3 ,
 146 .Xr RSA_get0_key 3 ,
 147 .Xr RSA_new 3
 148 .Sh HISTORY
 149 .Fn RSA_generate_key
 150 appeared in SSLeay 0.4 or earlier and had its
 151 .Fa cb_arg
 152 argument added in SSLeay 0.9.0.
 153 It has been available since
 154 .Ox 2.4 .
 155 .Pp
 156 .Fn RSA_generate_key_ex
 157 first appeared in OpenSSL 0.9.8 and has been available since
 158 .Ox 4.5 .
 159 .Sh BUGS
 160 .Fn BN_GENCB_call cb 2 x
 161 is used with two different meanings.
 162 .Pp
 163 .Fn RSA_generate_key
 164 goes into an infinite loop for illegal input values.