secure/lib/libcrypto/man/EVP_PKEY_set1_RSA.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 "EVP_PKEY_SET1_RSA 3"
 132 .TH EVP_PKEY_SET1_RSA 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 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 assignment functions
 139 .SH "SYNOPSIS"
 140 .IX Header "SYNOPSIS"
 141 .Vb 1
 142 \& #include <openssl/evp.h>
 143 \&
 144 \& int EVP_PKEY_set1_RSA(EVP_PKEY *pkey, RSA *key);
 145 \& int EVP_PKEY_set1_DSA(EVP_PKEY *pkey, DSA *key);
 146 \& int EVP_PKEY_set1_DH(EVP_PKEY *pkey, DH *key);
 147 \& int EVP_PKEY_set1_EC_KEY(EVP_PKEY *pkey, EC_KEY *key);
 148 \&
 149 \& RSA *EVP_PKEY_get1_RSA(EVP_PKEY *pkey);
 150 \& DSA *EVP_PKEY_get1_DSA(EVP_PKEY *pkey);
 151 \& DH *EVP_PKEY_get1_DH(EVP_PKEY *pkey);
 152 \& EC_KEY *EVP_PKEY_get1_EC_KEY(EVP_PKEY *pkey);
 153 \&
 154 \& const unsigned char *EVP_PKEY_get0_hmac(const EVP_PKEY *pkey, size_t *len);
 155 \& const unsigned char *EVP_PKEY_get0_poly1305(const EVP_PKEY *pkey, size_t *len);
 156 \& const unsigned char *EVP_PKEY_get0_siphash(const EVP_PKEY *pkey, size_t *len);
 157 \& RSA *EVP_PKEY_get0_RSA(EVP_PKEY *pkey);
 158 \& DSA *EVP_PKEY_get0_DSA(EVP_PKEY *pkey);
 159 \& DH *EVP_PKEY_get0_DH(EVP_PKEY *pkey);
 160 \& EC_KEY *EVP_PKEY_get0_EC_KEY(EVP_PKEY *pkey);
 161 \&
 162 \& int EVP_PKEY_assign_RSA(EVP_PKEY *pkey, RSA *key);
 163 \& int EVP_PKEY_assign_DSA(EVP_PKEY *pkey, DSA *key);
 164 \& int EVP_PKEY_assign_DH(EVP_PKEY *pkey, DH *key);
 165 \& int EVP_PKEY_assign_EC_KEY(EVP_PKEY *pkey, EC_KEY *key);
 166 \& int EVP_PKEY_assign_POLY1305(EVP_PKEY *pkey, ASN1_OCTET_STRING *key);
 167 \& int EVP_PKEY_assign_SIPHASH(EVP_PKEY *pkey, ASN1_OCTET_STRING *key);
 168 \&
 169 \& int EVP_PKEY_id(const EVP_PKEY *pkey);
 170 \& int EVP_PKEY_base_id(const EVP_PKEY *pkey);
 171 \& int EVP_PKEY_type(int type);
 172 \& int EVP_PKEY_set_alias_type(EVP_PKEY *pkey, int type);
 173 \&
 174 \& int EVP_PKEY_set1_engine(EVP_PKEY *pkey, ENGINE *engine);
 175 .Ve
 176 .SH "DESCRIPTION"
 177 .IX Header "DESCRIPTION"
 178 \&\fIEVP_PKEY_set1_RSA()\fR, \fIEVP_PKEY_set1_DSA()\fR, \fIEVP_PKEY_set1_DH()\fR and
 179 \&\fIEVP_PKEY_set1_EC_KEY()\fR set the key referenced by \fBpkey\fR to \fBkey\fR.
 180 .PP
 181 \&\fIEVP_PKEY_get1_RSA()\fR, \fIEVP_PKEY_get1_DSA()\fR, \fIEVP_PKEY_get1_DH()\fR and
 182 \&\fIEVP_PKEY_get1_EC_KEY()\fR return the referenced key in \fBpkey\fR or
 183 \&\fB\s-1NULL\s0\fR if the key is not of the correct type.
 184 .PP
 185 \&\fIEVP_PKEY_get0_hmac()\fR, \fIEVP_PKEY_get0_poly1305()\fR, \fIEVP_PKEY_get0_siphash()\fR,
 186 \&\fIEVP_PKEY_get0_RSA()\fR, \fIEVP_PKEY_get0_DSA()\fR, \fIEVP_PKEY_get0_DH()\fR
 187 and \fIEVP_PKEY_get0_EC_KEY()\fR also return the referenced key in \fBpkey\fR or \fB\s-1NULL\s0\fR
 188 if the key is not of the correct type but the reference count of the
 189 returned key is \fBnot\fR incremented and so must not be freed up after use.
 190 .PP
 191 \&\fIEVP_PKEY_assign_RSA()\fR, \fIEVP_PKEY_assign_DSA()\fR, \fIEVP_PKEY_assign_DH()\fR,
 192 \&\fIEVP_PKEY_assign_EC_KEY()\fR, \fIEVP_PKEY_assign_POLY1305()\fR and
 193 \&\fIEVP_PKEY_assign_SIPHASH()\fR also set the referenced key to \fBkey\fR
 194 however these use the supplied \fBkey\fR internally and so \fBkey\fR
 195 will be freed when the parent \fBpkey\fR is freed.
 196 .PP
 197 \&\fIEVP_PKEY_base_id()\fR returns the type of \fBpkey\fR. For example
 198 an \s-1RSA\s0 key will return \fB\s-1EVP_PKEY_RSA\s0\fR.
 199 .PP
 200 \&\fIEVP_PKEY_id()\fR returns the actual \s-1OID\s0 associated with \fBpkey\fR. Historically keys
 201 using the same algorithm could use different OIDs. For example an \s-1RSA\s0 key could
 202 use the OIDs corresponding to the NIDs \fBNID_rsaEncryption\fR (equivalent to
 203 \&\fB\s-1EVP_PKEY_RSA\s0\fR) or \fBNID_rsa\fR (equivalent to \fB\s-1EVP_PKEY_RSA2\s0\fR). The use of
 204 alternative non-standard OIDs is now rare so \fB\s-1EVP_PKEY_RSA2\s0\fR et al are not
 205 often seen in practice.
 206 .PP
 207 \&\fIEVP_PKEY_type()\fR returns the underlying type of the \s-1NID\s0 \fBtype\fR. For example
 208 EVP_PKEY_type(\s-1EVP_PKEY_RSA2\s0) will return \fB\s-1EVP_PKEY_RSA\s0\fR.
 209 .PP
 210 \&\fIEVP_PKEY_set1_engine()\fR sets the \s-1ENGINE\s0 handling \fBpkey\fR to \fBengine\fR. It
 211 must be called after the key algorithm and components are set up.
 212 If \fBengine\fR does not include an \fB\s-1EVP_PKEY_METHOD\s0\fR for \fBpkey\fR an
 213 error occurs.
 214 .PP
 215 \&\fIEVP_PKEY_set_alias_type()\fR allows modifying a \s-1EVP_PKEY\s0 to use a
 216 different set of algorithms than the default. This is currently used
 217 to support \s-1SM2\s0 keys, which use an identical encoding to \s-1ECDSA.\s0
 218 .SH "NOTES"
 219 .IX Header "NOTES"
 220 In accordance with the OpenSSL naming convention the key obtained
 221 from or assigned to the \fBpkey\fR using the \fB1\fR functions must be
 222 freed as well as \fBpkey\fR.
 223 .PP
 224 \&\fIEVP_PKEY_assign_RSA()\fR, \fIEVP_PKEY_assign_DSA()\fR, \fIEVP_PKEY_assign_DH()\fR,
 225 \&\fIEVP_PKEY_assign_EC_KEY()\fR, \fIEVP_PKEY_assign_POLY1305()\fR
 226 and \fIEVP_PKEY_assign_SIPHASH()\fR are implemented as macros.
 227 .PP
 228 Most applications wishing to know a key type will simply call
 229 \&\fIEVP_PKEY_base_id()\fR and will not care about the actual type:
 230 which will be identical in almost all cases.
 231 .PP
 232 Previous versions of this document suggested using EVP_PKEY_type(pkey\->type)
 233 to determine the type of a key. Since \fB\s-1EVP_PKEY\s0\fR is now opaque this
 234 is no longer possible: the equivalent is EVP_PKEY_base_id(pkey).
 235 .PP
 236 \&\fIEVP_PKEY_set1_engine()\fR is typically used by an \s-1ENGINE\s0 returning an \s-1HSM\s0
 237 key as part of its routine to load a private key.
 238 .SH "EXAMPLES"
 239 .IX Header "EXAMPLES"
 240 After loading an \s-1ECC\s0 key, it is possible to convert it to using \s-1SM2\s0
 241 algorithms with EVP_PKEY_set_alias_type:
 242 .PP
 243 .Vb 1
 244 \& EVP_PKEY_set_alias_type(pkey, EVP_PKEY_SM2);
 245 .Ve
 246 .SH "RETURN VALUES"
 247 .IX Header "RETURN VALUES"
 248 \&\fIEVP_PKEY_set1_RSA()\fR, \fIEVP_PKEY_set1_DSA()\fR, \fIEVP_PKEY_set1_DH()\fR and
 249 \&\fIEVP_PKEY_set1_EC_KEY()\fR return 1 for success or 0 for failure.
 250 .PP
 251 \&\fIEVP_PKEY_get1_RSA()\fR, \fIEVP_PKEY_get1_DSA()\fR, \fIEVP_PKEY_get1_DH()\fR and
 252 \&\fIEVP_PKEY_get1_EC_KEY()\fR return the referenced key or \fB\s-1NULL\s0\fR if
 253 an error occurred.
 254 .PP
 255 \&\fIEVP_PKEY_assign_RSA()\fR, \fIEVP_PKEY_assign_DSA()\fR, \fIEVP_PKEY_assign_DH()\fR,
 256 \&\fIEVP_PKEY_assign_EC_KEY()\fR, \fIEVP_PKEY_assign_POLY1305()\fR
 257 and \fIEVP_PKEY_assign_SIPHASH()\fR return 1 for success and 0 for failure.
 258 .PP
 259 \&\fIEVP_PKEY_base_id()\fR, \fIEVP_PKEY_id()\fR and \fIEVP_PKEY_type()\fR return a key
 260 type or \fBNID_undef\fR (equivalently \fB\s-1EVP_PKEY_NONE\s0\fR) on error.
 261 .PP
 262 \&\fIEVP_PKEY_set1_engine()\fR returns 1 for success and 0 for failure.
 263 .PP
 264 \&\fIEVP_PKEY_set_alias_type()\fR returns 1 for success and 0 for error.
 265 .SH "SEE ALSO"
 266 .IX Header "SEE ALSO"
 267 \&\fIEVP_PKEY_new\fR\|(3)
 268 .SH "COPYRIGHT"
 269 .IX Header "COPYRIGHT"
 270 Copyright 2002\-2018 The OpenSSL Project Authors. All Rights Reserved.
 271 .PP
 272 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 273 this file except in compliance with the License.  You can obtain a copy
 274 in the file \s-1LICENSE\s0 in the source distribution or at
 275 <https://www.openssl.org/source/license.html>.