secure/lib/libcrypto/man/RSA_get0_key.3

   1 .\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is >0, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .if !\nF .nr F 0
  58 .if \nF>0 \{\
  59 .    de IX
  60 .    tm Index:\\$1\t\\n%\t"\\$2"
  61 ..
  62 .    if !\nF==2 \{\
  63 .        nr % 0
  64 .        nr F 2
  65 .    \}
  66 .\}
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "RSA_GET0_KEY 3"
 132 .TH RSA_GET0_KEY 3 "2018-11-20" "1.1.1a" "OpenSSL"
 133 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 134 .\" way too many mistakes in technical documents.
 135 .if n .ad l
 136 .nh
 137 .SH "NAME"
 138 RSA_set0_key, RSA_set0_factors, RSA_set0_crt_params, RSA_get0_key, RSA_get0_factors, RSA_get0_crt_params, RSA_get0_n, RSA_get0_e, RSA_get0_d, RSA_get0_p, RSA_get0_q, RSA_get0_dmp1, RSA_get0_dmq1, RSA_get0_iqmp, RSA_clear_flags, RSA_test_flags, RSA_set_flags, RSA_get0_engine, RSA_get_multi_prime_extra_count, RSA_get0_multi_prime_factors, RSA_get0_multi_prime_crt_params, RSA_set0_multi_prime_params, RSA_get_version \&\- Routines for getting and setting data in an RSA object
 139 .SH "SYNOPSIS"
 140 .IX Header "SYNOPSIS"
 141 .Vb 1
 142 \& #include <openssl/rsa.h>
 143 \&
 144 \& int RSA_set0_key(RSA *r, BIGNUM *n, BIGNUM *e, BIGNUM *d);
 145 \& int RSA_set0_factors(RSA *r, BIGNUM *p, BIGNUM *q);
 146 \& int RSA_set0_crt_params(RSA *r, BIGNUM *dmp1, BIGNUM *dmq1, BIGNUM *iqmp);
 147 \& void RSA_get0_key(const RSA *r,
 148 \&                   const BIGNUM **n, const BIGNUM **e, const BIGNUM **d);
 149 \& void RSA_get0_factors(const RSA *r, const BIGNUM **p, const BIGNUM **q);
 150 \& void RSA_get0_crt_params(const RSA *r,
 151 \&                          const BIGNUM **dmp1, const BIGNUM **dmq1,
 152 \&                          const BIGNUM **iqmp);
 153 \& const BIGNUM *RSA_get0_n(const RSA *d);
 154 \& const BIGNUM *RSA_get0_e(const RSA *d);
 155 \& const BIGNUM *RSA_get0_d(const RSA *d);
 156 \& const BIGNUM *RSA_get0_p(const RSA *d);
 157 \& const BIGNUM *RSA_get0_q(const RSA *d);
 158 \& const BIGNUM *RSA_get0_dmp1(const RSA *r);
 159 \& const BIGNUM *RSA_get0_dmq1(const RSA *r);
 160 \& const BIGNUM *RSA_get0_iqmp(const RSA *r);
 161 \& void RSA_clear_flags(RSA *r, int flags);
 162 \& int RSA_test_flags(const RSA *r, int flags);
 163 \& void RSA_set_flags(RSA *r, int flags);
 164 \& ENGINE *RSA_get0_engine(RSA *r);
 165 \& int RSA_get_multi_prime_extra_count(const RSA *r);
 166 \& int RSA_get0_multi_prime_factors(const RSA *r, const BIGNUM *primes[]);
 167 \& int RSA_get0_multi_prime_crt_params(const RSA *r, const BIGNUM *exps[],
 168 \&                                     const BIGNUM *coeffs[]);
 169 \& int RSA_set0_multi_prime_params(RSA *r, BIGNUM *primes[], BIGNUM *exps[],
 170 \&                                BIGNUM *coeffs[], int pnum);
 171 \& int RSA_get_version(RSA *r);
 172 .Ve
 173 .SH "DESCRIPTION"
 174 .IX Header "DESCRIPTION"
 175 An \s-1RSA\s0 object contains the components for the public and private key,
 176 \&\fBn\fR, \fBe\fR, \fBd\fR, \fBp\fR, \fBq\fR, \fBdmp1\fR, \fBdmq1\fR and \fBiqmp\fR.  \fBn\fR is
 177 the modulus common to both public and private key, \fBe\fR is the public
 178 exponent and \fBd\fR is the private exponent.  \fBp\fR, \fBq\fR, \fBdmp1\fR,
 179 \&\fBdmq1\fR and \fBiqmp\fR are the factors for the second representation of a
 180 private key (see PKCS#1 section 3 Key Types), where \fBp\fR and \fBq\fR are
 181 the first and second factor of \fBn\fR and \fBdmp1\fR, \fBdmq1\fR and \fBiqmp\fR
 182 are the exponents and coefficient for \s-1CRT\s0 calculations.
 183 .PP
 184 For multi-prime \s-1RSA\s0 (defined in \s-1RFC 8017\s0), there are also one or more
 185 \&'triplet' in an \s-1RSA\s0 object. A triplet contains three members, \fBr\fR, \fBd\fR
 186 and \fBt\fR. \fBr\fR is the additional prime besides \fBp\fR and \fBq\fR. \fBd\fR and
 187 \&\fBt\fR are the exponent and coefficient for \s-1CRT\s0 calculations.
 188 .PP
 189 The \fBn\fR, \fBe\fR and \fBd\fR parameters can be obtained by calling
 190 \&\fIRSA_get0_key()\fR.  If they have not been set yet, then \fB*n\fR, \fB*e\fR and
 191 \&\fB*d\fR will be set to \s-1NULL.\s0  Otherwise, they are set to pointers to
 192 their respective values. These point directly to the internal
 193 representations of the values and therefore should not be freed
 194 by the caller.
 195 .PP
 196 The \fBn\fR, \fBe\fR and \fBd\fR parameter values can be set by calling
 197 \&\fIRSA_set0_key()\fR and passing the new values for \fBn\fR, \fBe\fR and \fBd\fR as
 198 parameters to the function.  The values \fBn\fR and \fBe\fR must be non-NULL
 199 the first time this function is called on a given \s-1RSA\s0 object. The
 200 value \fBd\fR may be \s-1NULL.\s0 On subsequent calls any of these values may be
 201 \&\s-1NULL\s0 which means the corresponding \s-1RSA\s0 field is left untouched.
 202 Calling this function transfers the memory management of the values to
 203 the \s-1RSA\s0 object, and therefore the values that have been passed in
 204 should not be freed by the caller after this function has been called.
 205 .PP
 206 In a similar fashion, the \fBp\fR and \fBq\fR parameters can be obtained and
 207 set with \fIRSA_get0_factors()\fR and \fIRSA_set0_factors()\fR, and the \fBdmp1\fR,
 208 \&\fBdmq1\fR and \fBiqmp\fR parameters can be obtained and set with
 209 \&\fIRSA_get0_crt_params()\fR and \fIRSA_set0_crt_params()\fR.
 210 .PP
 211 For \fIRSA_get0_key()\fR, \fIRSA_get0_factors()\fR, and \fIRSA_get0_crt_params()\fR,
 212 \&\s-1NULL\s0 value \s-1BIGNUM\s0 ** output parameters are permitted. The functions
 213 ignore \s-1NULL\s0 parameters but return values for other, non-NULL, parameters.
 214 .PP
 215 For multi-prime \s-1RSA,\s0 \fIRSA_get0_multi_prime_factors()\fR and \fIRSA_get0_multi_prime_params()\fR
 216 can be used to obtain other primes and related \s-1CRT\s0 parameters. The
 217 return values are stored in an array of \fB\s-1BIGNUM\s0 *\fR. \fIRSA_set0_multi_prime_params()\fR
 218 sets a collect of multi-prime 'triplet' members (prime, exponent and coefficient)
 219 into an \s-1RSA\s0 object.
 220 .PP
 221 Any of the values \fBn\fR, \fBe\fR, \fBd\fR, \fBp\fR, \fBq\fR, \fBdmp1\fR, \fBdmq1\fR, and \fBiqmp\fR can also be
 222 retrieved separately by the corresponding function
 223 \&\fIRSA_get0_n()\fR, \fIRSA_get0_e()\fR, \fIRSA_get0_d()\fR, \fIRSA_get0_p()\fR, \fIRSA_get0_q()\fR,
 224 \&\fIRSA_get0_dmp1()\fR, \fIRSA_get0_dmq1()\fR, and \fIRSA_get0_iqmp()\fR, respectively.
 225 .PP
 226 \&\fIRSA_set_flags()\fR sets the flags in the \fBflags\fR parameter on the \s-1RSA\s0
 227 object. Multiple flags can be passed in one go (bitwise ORed together).
 228 Any flags that are already set are left set. \fIRSA_test_flags()\fR tests to
 229 see whether the flags passed in the \fBflags\fR parameter are currently
 230 set in the \s-1RSA\s0 object. Multiple flags can be tested in one go. All
 231 flags that are currently set are returned, or zero if none of the
 232 flags are set. \fIRSA_clear_flags()\fR clears the specified flags within the
 233 \&\s-1RSA\s0 object.
 234 .PP
 235 \&\fIRSA_get0_engine()\fR returns a handle to the \s-1ENGINE\s0 that has been set for
 236 this \s-1RSA\s0 object, or \s-1NULL\s0 if no such \s-1ENGINE\s0 has been set.
 237 .PP
 238 \&\fIRSA_get_version()\fR returns the version of an \s-1RSA\s0 object \fBr\fR.
 239 .SH "NOTES"
 240 .IX Header "NOTES"
 241 Values retrieved with \fIRSA_get0_key()\fR are owned by the \s-1RSA\s0 object used
 242 in the call and may therefore \fInot\fR be passed to \fIRSA_set0_key()\fR.  If
 243 needed, duplicate the received value using \fIBN_dup()\fR and pass the
 244 duplicate.  The same applies to \fIRSA_get0_factors()\fR and \fIRSA_set0_factors()\fR
 245 as well as \fIRSA_get0_crt_params()\fR and \fIRSA_set0_crt_params()\fR.
 246 .PP
 247 The caller should obtain the size by calling \fIRSA_get_multi_prime_extra_count()\fR
 248 in advance and allocate sufficient buffer to store the return values before
 249 calling \fIRSA_get0_multi_prime_factors()\fR and \fIRSA_get0_multi_prime_params()\fR.
 250 .PP
 251 \&\fIRSA_set0_multi_prime_params()\fR always clears the original multi-prime
 252 triplets in \s-1RSA\s0 object \fBr\fR and assign the new set of triplets into it.
 253 .SH "RETURN VALUES"
 254 .IX Header "RETURN VALUES"
 255 \&\fIRSA_set0_key()\fR, \fIRSA_set0_factors()\fR, \fIRSA_set0_crt_params()\fR and
 256 \&\fIRSA_set0_multi_prime_params()\fR return 1 on success or 0 on failure.
 257 .PP
 258 \&\fIRSA_get0_n()\fR, \fIRSA_get0_e()\fR, \fIRSA_get0_d()\fR, \fIRSA_get0_p()\fR, \fIRSA_get0_q()\fR,
 259 \&\fIRSA_get0_dmp1()\fR, \fIRSA_get0_dmq1()\fR, and \fIRSA_get0_iqmp()\fR
 260 return the respective value.
 261 .PP
 262 \&\fIRSA_get0_multi_prime_factors()\fR and \fIRSA_get0_multi_prime_crt_params()\fR return
 263 1 on success or 0 on failure.
 264 .PP
 265 \&\fIRSA_get_multi_prime_extra_count()\fR returns two less than the number of primes
 266 in use, which is 0 for traditional \s-1RSA\s0 and the number of extra primes for
 267 multi-prime \s-1RSA.\s0
 268 .PP
 269 \&\fIRSA_get_version()\fR returns \fB\s-1RSA_ASN1_VERSION_MULTI\s0\fR for multi-prime \s-1RSA\s0 and
 270 \&\fB\s-1RSA_ASN1_VERSION_DEFAULT\s0\fR for normal two-prime \s-1RSA,\s0 as defined in \s-1RFC 8017.\s0
 271 .PP
 272 \&\fIRSA_test_flags()\fR returns the current state of the flags in the \s-1RSA\s0 object.
 273 .PP
 274 \&\fIRSA_get0_engine()\fR returns the \s-1ENGINE\s0 set for the \s-1RSA\s0 object or \s-1NULL\s0 if no
 275 \&\s-1ENGINE\s0 has been set.
 276 .SH "SEE ALSO"
 277 .IX Header "SEE ALSO"
 278 \&\fIRSA_new\fR\|(3), \fIRSA_size\fR\|(3)
 279 .SH "HISTORY"
 280 .IX Header "HISTORY"
 281 \&\fIRSA_get_multi_prime_extra_count()\fR, \fIRSA_get0_multi_prime_factors()\fR,
 282 \&\fIRSA_get0_multi_prime_crt_params()\fR, \fIRSA_set0_multi_prime_params()\fR,
 283 and \fIRSA_get_version()\fR functions were added in OpenSSL 1.1.1.
 284 .PP
 285 Other functions described here were added in OpenSSL 1.1.0.
 286 .SH "COPYRIGHT"
 287 .IX Header "COPYRIGHT"
 288 Copyright 2016\-2018 The OpenSSL Project Authors. All Rights Reserved.
 289 .PP
 290 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 291 this file except in compliance with the License.  You can obtain a copy
 292 in the file \s-1LICENSE\s0 in the source distribution or at
 293 <https://www.openssl.org/source/license.html>.