secure/lib/libcrypto/man/man3/EVP_PKEY_set1_RSA.3

   1 .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
   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 .nr rF 0
  58 .if \n(.g .if rF .nr rF 1
  59 .if (\n(rF:(\n(.g==0)) \{\
  60 .    if \nF \{\
  61 .        de IX
  62 .        tm Index:\\$1\t\\n%\t"\\$2"
  63 ..
  64 .        if !\nF==2 \{\
  65 .            nr % 0
  66 .            nr F 2
  67 .        \}
  68 .    \}
  69 .\}
  70 .rr rF
  71 .\"
  72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  74 .    \" fudge factors for nroff and troff
  75 .if n \{\
  76 .    ds #H 0
  77 .    ds #V .8m
  78 .    ds #F .3m
  79 .    ds #[ \f1
  80 .    ds #] \fP
  81 .\}
  82 .if t \{\
  83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  84 .    ds #V .6m
  85 .    ds #F 0
  86 .    ds #[ \&
  87 .    ds #] \&
  88 .\}
  89 .    \" simple accents for nroff and troff
  90 .if n \{\
  91 .    ds ' \&
  92 .    ds ` \&
  93 .    ds ^ \&
  94 .    ds , \&
  95 .    ds ~ ~
  96 .    ds /
  97 .\}
  98 .if t \{\
  99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 105 .\}
 106 .    \" troff and (daisy-wheel) nroff accents
 107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 114 .ds ae a\h'-(\w'a'u*4/10)'e
 115 .ds Ae A\h'-(\w'A'u*4/10)'E
 116 .    \" corrections for vroff
 117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 119 .    \" for low resolution devices (crt and lpr)
 120 .if \n(.H>23 .if \n(.V>19 \
 121 \{\
 122 .    ds : e
 123 .    ds 8 ss
 124 .    ds o a
 125 .    ds d- d\h'-1'\(ga
 126 .    ds D- D\h'-1'\(hy
 127 .    ds th \o'bp'
 128 .    ds Th \o'LP'
 129 .    ds ae ae
 130 .    ds Ae AE
 131 .\}
 132 .rm #[ #] #H #V #F C
 133 .\" ========================================================================
 134 .\"
 135 .IX Title "EVP_PKEY_SET1_RSA 3"
 136 .TH EVP_PKEY_SET1_RSA 3 "2022-05-03" "1.1.1o" "OpenSSL"
 137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 138 .\" way too many mistakes in technical documents.
 139 .if n .ad l
 140 .nh
 141 .SH "NAME"
 142 EVP_PKEY_set1_RSA, EVP_PKEY_set1_DSA, EVP_PKEY_set1_DH, EVP_PKEY_set1_EC_KEY, EVP_PKEY_get1_RSA, EVP_PKEY_get1_DSA, EVP_PKEY_get1_DH, EVP_PKEY_get1_EC_KEY, EVP_PKEY_get0_RSA, EVP_PKEY_get0_DSA, EVP_PKEY_get0_DH, EVP_PKEY_get0_EC_KEY, EVP_PKEY_assign_RSA, EVP_PKEY_assign_DSA, EVP_PKEY_assign_DH, EVP_PKEY_assign_EC_KEY, EVP_PKEY_assign_POLY1305, EVP_PKEY_assign_SIPHASH, EVP_PKEY_get0_hmac, EVP_PKEY_get0_poly1305, EVP_PKEY_get0_siphash, EVP_PKEY_type, EVP_PKEY_id, EVP_PKEY_base_id, EVP_PKEY_set_alias_type, EVP_PKEY_set1_engine, EVP_PKEY_get0_engine \- EVP_PKEY assignment functions
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/evp.h>
 147 \&
 148 \& int EVP_PKEY_set1_RSA(EVP_PKEY *pkey, RSA *key);
 149 \& int EVP_PKEY_set1_DSA(EVP_PKEY *pkey, DSA *key);
 150 \& int EVP_PKEY_set1_DH(EVP_PKEY *pkey, DH *key);
 151 \& int EVP_PKEY_set1_EC_KEY(EVP_PKEY *pkey, EC_KEY *key);
 152 \&
 153 \& RSA *EVP_PKEY_get1_RSA(EVP_PKEY *pkey);
 154 \& DSA *EVP_PKEY_get1_DSA(EVP_PKEY *pkey);
 155 \& DH *EVP_PKEY_get1_DH(EVP_PKEY *pkey);
 156 \& EC_KEY *EVP_PKEY_get1_EC_KEY(EVP_PKEY *pkey);
 157 \&
 158 \& const unsigned char *EVP_PKEY_get0_hmac(const EVP_PKEY *pkey, size_t *len);
 159 \& const unsigned char *EVP_PKEY_get0_poly1305(const EVP_PKEY *pkey, size_t *len);
 160 \& const unsigned char *EVP_PKEY_get0_siphash(const EVP_PKEY *pkey, size_t *len);
 161 \& RSA *EVP_PKEY_get0_RSA(EVP_PKEY *pkey);
 162 \& DSA *EVP_PKEY_get0_DSA(EVP_PKEY *pkey);
 163 \& DH *EVP_PKEY_get0_DH(EVP_PKEY *pkey);
 164 \& EC_KEY *EVP_PKEY_get0_EC_KEY(EVP_PKEY *pkey);
 165 \&
 166 \& int EVP_PKEY_assign_RSA(EVP_PKEY *pkey, RSA *key);
 167 \& int EVP_PKEY_assign_DSA(EVP_PKEY *pkey, DSA *key);
 168 \& int EVP_PKEY_assign_DH(EVP_PKEY *pkey, DH *key);
 169 \& int EVP_PKEY_assign_EC_KEY(EVP_PKEY *pkey, EC_KEY *key);
 170 \& int EVP_PKEY_assign_POLY1305(EVP_PKEY *pkey, ASN1_OCTET_STRING *key);
 171 \& int EVP_PKEY_assign_SIPHASH(EVP_PKEY *pkey, ASN1_OCTET_STRING *key);
 172 \&
 173 \& int EVP_PKEY_id(const EVP_PKEY *pkey);
 174 \& int EVP_PKEY_base_id(const EVP_PKEY *pkey);
 175 \& int EVP_PKEY_type(int type);
 176 \& int EVP_PKEY_set_alias_type(EVP_PKEY *pkey, int type);
 177 \&
 178 \& ENGINE *EVP_PKEY_get0_engine(const EVP_PKEY *pkey);
 179 \& int EVP_PKEY_set1_engine(EVP_PKEY *pkey, ENGINE *engine);
 180 .Ve
 181 .SH "DESCRIPTION"
 182 .IX Header "DESCRIPTION"
 183 \&\fBEVP_PKEY_set1_RSA()\fR, \fBEVP_PKEY_set1_DSA()\fR, \fBEVP_PKEY_set1_DH()\fR and
 184 \&\fBEVP_PKEY_set1_EC_KEY()\fR set the key referenced by \fBpkey\fR to \fBkey\fR.
 185 .PP
 186 \&\fBEVP_PKEY_get1_RSA()\fR, \fBEVP_PKEY_get1_DSA()\fR, \fBEVP_PKEY_get1_DH()\fR and
 187 \&\fBEVP_PKEY_get1_EC_KEY()\fR return the referenced key in \fBpkey\fR or
 188 \&\fB\s-1NULL\s0\fR if the key is not of the correct type.
 189 .PP
 190 \&\fBEVP_PKEY_get0_hmac()\fR, \fBEVP_PKEY_get0_poly1305()\fR, \fBEVP_PKEY_get0_siphash()\fR,
 191 \&\fBEVP_PKEY_get0_RSA()\fR, \fBEVP_PKEY_get0_DSA()\fR, \fBEVP_PKEY_get0_DH()\fR
 192 and \fBEVP_PKEY_get0_EC_KEY()\fR also return the referenced key in \fBpkey\fR or \fB\s-1NULL\s0\fR
 193 if the key is not of the correct type but the reference count of the
 194 returned key is \fBnot\fR incremented and so must not be freed up after use.
 195 .PP
 196 \&\fBEVP_PKEY_assign_RSA()\fR, \fBEVP_PKEY_assign_DSA()\fR, \fBEVP_PKEY_assign_DH()\fR,
 197 \&\fBEVP_PKEY_assign_EC_KEY()\fR, \fBEVP_PKEY_assign_POLY1305()\fR and
 198 \&\fBEVP_PKEY_assign_SIPHASH()\fR also set the referenced key to \fBkey\fR
 199 however these use the supplied \fBkey\fR internally and so \fBkey\fR
 200 will be freed when the parent \fBpkey\fR is freed.
 201 .PP
 202 \&\fBEVP_PKEY_base_id()\fR returns the type of \fBpkey\fR. For example
 203 an \s-1RSA\s0 key will return \fB\s-1EVP_PKEY_RSA\s0\fR.
 204 .PP
 205 \&\fBEVP_PKEY_id()\fR returns the actual \s-1OID\s0 associated with \fBpkey\fR. Historically keys
 206 using the same algorithm could use different OIDs. For example an \s-1RSA\s0 key could
 207 use the OIDs corresponding to the NIDs \fBNID_rsaEncryption\fR (equivalent to
 208 \&\fB\s-1EVP_PKEY_RSA\s0\fR) or \fBNID_rsa\fR (equivalent to \fB\s-1EVP_PKEY_RSA2\s0\fR). The use of
 209 alternative non-standard OIDs is now rare so \fB\s-1EVP_PKEY_RSA2\s0\fR et al are not
 210 often seen in practice.
 211 .PP
 212 \&\fBEVP_PKEY_type()\fR returns the underlying type of the \s-1NID\s0 \fBtype\fR. For example
 213 EVP_PKEY_type(\s-1EVP_PKEY_RSA2\s0) will return \fB\s-1EVP_PKEY_RSA\s0\fR.
 214 .PP
 215 \&\fBEVP_PKEY_get0_engine()\fR returns a reference to the \s-1ENGINE\s0 handling \fBpkey\fR.
 216 .PP
 217 \&\fBEVP_PKEY_set1_engine()\fR sets the \s-1ENGINE\s0 handling \fBpkey\fR to \fBengine\fR. It
 218 must be called after the key algorithm and components are set up.
 219 If \fBengine\fR does not include an \fB\s-1EVP_PKEY_METHOD\s0\fR for \fBpkey\fR an
 220 error occurs.
 221 .PP
 222 \&\fBEVP_PKEY_set_alias_type()\fR allows modifying a \s-1EVP_PKEY\s0 to use a
 223 different set of algorithms than the default. This is currently used
 224 to support \s-1SM2\s0 keys, which use an identical encoding to \s-1ECDSA.\s0
 225 .SH "NOTES"
 226 .IX Header "NOTES"
 227 In accordance with the OpenSSL naming convention the key obtained
 228 from or assigned to the \fBpkey\fR using the \fB1\fR functions must be
 229 freed as well as \fBpkey\fR.
 230 .PP
 231 \&\fBEVP_PKEY_assign_RSA()\fR, \fBEVP_PKEY_assign_DSA()\fR, \fBEVP_PKEY_assign_DH()\fR,
 232 \&\fBEVP_PKEY_assign_EC_KEY()\fR, \fBEVP_PKEY_assign_POLY1305()\fR
 233 and \fBEVP_PKEY_assign_SIPHASH()\fR are implemented as macros.
 234 .PP
 235 Most applications wishing to know a key type will simply call
 236 \&\fBEVP_PKEY_base_id()\fR and will not care about the actual type:
 237 which will be identical in almost all cases.
 238 .PP
 239 Previous versions of this document suggested using EVP_PKEY_type(pkey\->type)
 240 to determine the type of a key. Since \fB\s-1EVP_PKEY\s0\fR is now opaque this
 241 is no longer possible: the equivalent is EVP_PKEY_base_id(pkey).
 242 .PP
 243 \&\fBEVP_PKEY_set1_engine()\fR is typically used by an \s-1ENGINE\s0 returning an \s-1HSM\s0
 244 key as part of its routine to load a private key.
 245 .SH "RETURN VALUES"
 246 .IX Header "RETURN VALUES"
 247 \&\fBEVP_PKEY_set1_RSA()\fR, \fBEVP_PKEY_set1_DSA()\fR, \fBEVP_PKEY_set1_DH()\fR and
 248 \&\fBEVP_PKEY_set1_EC_KEY()\fR return 1 for success or 0 for failure.
 249 .PP
 250 \&\fBEVP_PKEY_get1_RSA()\fR, \fBEVP_PKEY_get1_DSA()\fR, \fBEVP_PKEY_get1_DH()\fR and
 251 \&\fBEVP_PKEY_get1_EC_KEY()\fR return the referenced key or \fB\s-1NULL\s0\fR if
 252 an error occurred.
 253 .PP
 254 \&\fBEVP_PKEY_assign_RSA()\fR, \fBEVP_PKEY_assign_DSA()\fR, \fBEVP_PKEY_assign_DH()\fR,
 255 \&\fBEVP_PKEY_assign_EC_KEY()\fR, \fBEVP_PKEY_assign_POLY1305()\fR
 256 and \fBEVP_PKEY_assign_SIPHASH()\fR return 1 for success and 0 for failure.
 257 .PP
 258 \&\fBEVP_PKEY_base_id()\fR, \fBEVP_PKEY_id()\fR and \fBEVP_PKEY_type()\fR return a key
 259 type or \fBNID_undef\fR (equivalently \fB\s-1EVP_PKEY_NONE\s0\fR) on error.
 260 .PP
 261 \&\fBEVP_PKEY_set1_engine()\fR returns 1 for success and 0 for failure.
 262 .PP
 263 \&\fBEVP_PKEY_set_alias_type()\fR returns 1 for success and 0 for error.
 264 .SH "EXAMPLES"
 265 .IX Header "EXAMPLES"
 266 After loading an \s-1ECC\s0 key, it is possible to convert it to using \s-1SM2\s0
 267 algorithms with EVP_PKEY_set_alias_type:
 268 .PP
 269 .Vb 1
 270 \& EVP_PKEY_set_alias_type(pkey, EVP_PKEY_SM2);
 271 .Ve
 272 .SH "SEE ALSO"
 273 .IX Header "SEE ALSO"
 274 \&\fBEVP_PKEY_new\fR\|(3)
 275 .SH "COPYRIGHT"
 276 .IX Header "COPYRIGHT"
 277 Copyright 2002\-2019 The OpenSSL Project Authors. All Rights Reserved.
 278 .PP
 279 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 280 this file except in compliance with the License.  You can obtain a copy
 281 in the file \s-1LICENSE\s0 in the source distribution or at
 282 <https://www.openssl.org/source/license.html>.