lib/libcrypto/man/RSA_get0_key.3

   1 .\" $OpenBSD: RSA_get0_key.3,v 1.4 2018/03/23 23:18:17 schwarze Exp $
   2 .\" selective merge up to: OpenSSL 665d899f Aug 2 02:19:43 2017 +0800
   3 .\"
   4 .\" This file was written by Richard Levitte <levitte@openssl.org>
   5 .\" Copyright (c) 2016 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 23 2018 $
  52 .Dt RSA_GET0_KEY 3
  53 .Os
  54 .Sh NAME
  55 .Nm RSA_get0_key ,
  56 .Nm RSA_set0_key ,
  57 .Nm RSA_get0_factors ,
  58 .Nm RSA_set0_factors ,
  59 .Nm RSA_get0_crt_params ,
  60 .Nm RSA_set0_crt_params ,
  61 .Nm RSA_clear_flags ,
  62 .Nm RSA_test_flags ,
  63 .Nm RSA_set_flags
  64 .Nd get and set data in an RSA object
  65 .Sh SYNOPSIS
  66 .In openssl/rsa.h
  67 .Ft void
  68 .Fo RSA_get0_key
  69 .Fa "const RSA *r"
  70 .Fa "const BIGNUM **n"
  71 .Fa "const BIGNUM **e"
  72 .Fa "const BIGNUM **d"
  73 .Fc
  74 .Ft int
  75 .Fo RSA_set0_key
  76 .Fa "RSA *r"
  77 .Fa "BIGNUM *n"
  78 .Fa "BIGNUM *e"
  79 .Fa "BIGNUM *d"
  80 .Fc
  81 .Ft void
  82 .Fo RSA_get0_factors
  83 .Fa "const RSA *r"
  84 .Fa "const BIGNUM **p"
  85 .Fa "const BIGNUM **q"
  86 .Fc
  87 .Ft int
  88 .Fo RSA_set0_factors
  89 .Fa "RSA *r"
  90 .Fa "BIGNUM *p"
  91 .Fa "BIGNUM *q"
  92 .Fc
  93 .Ft void
  94 .Fo RSA_get0_crt_params
  95 .Fa "const RSA *r"
  96 .Fa "const BIGNUM **dmp1"
  97 .Fa "const BIGNUM **dmq1"
  98 .Fa "const BIGNUM **iqmp"
  99 .Fc
 100 .Ft int
 101 .Fo RSA_set0_crt_params
 102 .Fa "RSA *r"
 103 .Fa "BIGNUM *dmp1"
 104 .Fa "BIGNUM *dmq1"
 105 .Fa "BIGNUM *iqmp"
 106 .Fc
 107 .Ft void
 108 .Fo RSA_clear_flags
 109 .Fa "RSA *r"
 110 .Fa "int flags"
 111 .Fc
 112 .Ft int
 113 .Fo RSA_test_flags
 114 .Fa "const RSA *r"
 115 .Fa "int flags"
 116 .Fc
 117 .Ft void
 118 .Fo RSA_set_flags
 119 .Fa "RSA *r"
 120 .Fa "int flags"
 121 .Fc
 122 .Sh DESCRIPTION
 123 An
 124 .Vt RSA
 125 object contains the components for the public and private key.
 126 .Fa n
 127 is the modulus common to both public and private key,
 128 .Fa e
 129 is the public exponent and
 130 .Fa d
 131 is the private exponent.
 132 .Fa p ,
 133 .Fa q ,
 134 .Fa dmp1 ,
 135 .Fa dmq1 ,
 136 and
 137 .Fa iqmp
 138 are the factors for the second representation of a private key
 139 (see PKCS#1 section 3 Key Types), where
 140 .Fa p
 141 and
 142 .Fa q
 143 are the first and second factor of
 144 .Fa n .
 145 .Fa dmp1 ,
 146 .Fa dmq1 ,
 147 and
 148 .Fa iqmp
 149 are the exponents and coefficient for CRT calculations.
 150 .Pp
 151 The
 152 .Fa n ,
 153 .Fa e ,
 154 and
 155 .Fa d
 156 parameters can be obtained by calling
 157 .Fn RSA_get0_key .
 158 If they have not been set yet, then
 159 .Pf * Fa n ,
 160 .Pf * Fa e ,
 161 and
 162 .Pf * Fa d
 163 are set to
 164 .Dv NULL .
 165 Otherwise, they are set to pointers to the internal representations
 166 of the values that should not be freed by the caller.
 167 .Pp
 168 The
 169 .Fa n ,
 170 .Fa e ,
 171 and
 172 .Fa d
 173 parameter values can be set by calling
 174 .Fn RSA_set0_key .
 175 The values
 176 .Fa n
 177 and
 178 .Fa e
 179 must be
 180 .Pf non- Dv NULL
 181 the first time this function is called on a given
 182 .Vt RSA
 183 object.
 184 The value
 185 .Fa d
 186 may be
 187 .Dv NULL .
 188 On subsequent calls, any of these values may be
 189 .Dv NULL ,
 190 which means that the corresponding field is left untouched.
 191 Calling this function transfers the memory management of the values to
 192 the RSA object.
 193 Therefore, the values that have been passed in
 194 should not be freed by the caller.
 195 .Pp
 196 In a similar fashion, the
 197 .Fa p
 198 and
 199 .Fa q
 200 parameters can be obtained and set with
 201 .Fn RSA_get0_factors
 202 and
 203 .Fn RSA_set0_factors ,
 204 and the
 205 .Fa dmp1 ,
 206 .Fa dmq1 ,
 207 and
 208 .Fa iqmp
 209 parameters can be obtained and set with
 210 .Fn RSA_get0_crt_params
 211 and
 212 .Fn RSA_set0_crt_params .
 213 .Pp
 214 For
 215 .Fn RSA_get0_key ,
 216 .Fn RSA_get0_factors ,
 217 and
 218 .Fn RSA_get0_crt_params ,
 219 .Dv NULL
 220 value
 221 .Vt BIGNUM **
 222 output arguments are permitted.
 223 The functions
 224 ignore
 225 .Dv NULL
 226 arguments but return values for other,
 227 .Pf non- Dv NULL ,
 228 arguments.
 229 .Pp
 230 Values retrieved with
 231 .Fn RSA_get0_key ,
 232 .Fn RSA_get0_factors ,
 233 and
 234 .Fn RSA_get0_crt_params
 235 are owned by the
 236 .Vt RSA
 237 object used in the call and may therefore
 238 .Em not
 239 be passed to
 240 .Fn RSA_set0_key ,
 241 .Fn RSA_set0_factors ,
 242 or
 243 .Fn RSA_set0_crt_params .
 244 If needed, duplicate the received value using
 245 .Xr BN_dup 3
 246 and pass the duplicate.
 247 .Pp
 248 .Fn RSA_clear_flags
 249 clears the specified
 250 .Fa flags
 251 in
 252 .Fa r .
 253 .Fn RSA_test_flags
 254 tests the
 255 .Fa flags
 256 in
 257 .Fa r .
 258 .Fn RSA_set_flags
 259 sets the
 260 .Fa flags
 261 in
 262 .Fa r ;
 263 any flags already set remain set.
 264 For all three functions, multiple flags can be passed in one call,
 265 OR'ed together bitwise.
 266 .Sh RETURN VALUES
 267 .Fn RSA_set0_key ,
 268 .Fn RSA_set0_factors ,
 269 and
 270 .Fn RSA_set0_crt_params
 271 return 1 on success or 0 on failure.
 272 .Pp
 273 .Fn RSA_test_flags
 274 returns those of the given
 275 .Fa flags
 276 currently set in
 277 .Fa r
 278 or 0 if none of the given
 279 .Fa flags
 280 are set.
 281 .Sh SEE ALSO
 282 .Xr RSA_check_key 3 ,
 283 .Xr RSA_generate_key 3 ,
 284 .Xr RSA_new 3 ,
 285 .Xr RSA_print 3 ,
 286 .Xr RSA_size 3
 287 .Sh HISTORY
 288 These functions first appeared in OpenSSL 1.1.0
 289 and have been available since
 290 .Ox 6.3 .