secure/lib/libcrypto/man/EVP_PKEY_set1_RSA.3

   1 .\" Automatically generated by Pod::Man 4.10 (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 .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 "2019-02-26" "1.1.1b" "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 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 \& int EVP_PKEY_set1_engine(EVP_PKEY *pkey, ENGINE *engine);
 179 .Ve
 180 .SH "DESCRIPTION"
 181 .IX Header "DESCRIPTION"
 182 \&\fBEVP_PKEY_set1_RSA()\fR, \fBEVP_PKEY_set1_DSA()\fR, \fBEVP_PKEY_set1_DH()\fR and
 183 \&\fBEVP_PKEY_set1_EC_KEY()\fR set the key referenced by \fBpkey\fR to \fBkey\fR.
 184 .PP
 185 \&\fBEVP_PKEY_get1_RSA()\fR, \fBEVP_PKEY_get1_DSA()\fR, \fBEVP_PKEY_get1_DH()\fR and
 186 \&\fBEVP_PKEY_get1_EC_KEY()\fR return the referenced key in \fBpkey\fR or
 187 \&\fB\s-1NULL\s0\fR if the key is not of the correct type.
 188 .PP
 189 \&\fBEVP_PKEY_get0_hmac()\fR, \fBEVP_PKEY_get0_poly1305()\fR, \fBEVP_PKEY_get0_siphash()\fR,
 190 \&\fBEVP_PKEY_get0_RSA()\fR, \fBEVP_PKEY_get0_DSA()\fR, \fBEVP_PKEY_get0_DH()\fR
 191 and \fBEVP_PKEY_get0_EC_KEY()\fR also return the referenced key in \fBpkey\fR or \fB\s-1NULL\s0\fR
 192 if the key is not of the correct type but the reference count of the
 193 returned key is \fBnot\fR incremented and so must not be freed up after use.
 194 .PP
 195 \&\fBEVP_PKEY_assign_RSA()\fR, \fBEVP_PKEY_assign_DSA()\fR, \fBEVP_PKEY_assign_DH()\fR,
 196 \&\fBEVP_PKEY_assign_EC_KEY()\fR, \fBEVP_PKEY_assign_POLY1305()\fR and
 197 \&\fBEVP_PKEY_assign_SIPHASH()\fR also set the referenced key to \fBkey\fR
 198 however these use the supplied \fBkey\fR internally and so \fBkey\fR
 199 will be freed when the parent \fBpkey\fR is freed.
 200 .PP
 201 \&\fBEVP_PKEY_base_id()\fR returns the type of \fBpkey\fR. For example
 202 an \s-1RSA\s0 key will return \fB\s-1EVP_PKEY_RSA\s0\fR.
 203 .PP
 204 \&\fBEVP_PKEY_id()\fR returns the actual \s-1OID\s0 associated with \fBpkey\fR. Historically keys
 205 using the same algorithm could use different OIDs. For example an \s-1RSA\s0 key could
 206 use the OIDs corresponding to the NIDs \fBNID_rsaEncryption\fR (equivalent to
 207 \&\fB\s-1EVP_PKEY_RSA\s0\fR) or \fBNID_rsa\fR (equivalent to \fB\s-1EVP_PKEY_RSA2\s0\fR). The use of
 208 alternative non-standard OIDs is now rare so \fB\s-1EVP_PKEY_RSA2\s0\fR et al are not
 209 often seen in practice.
 210 .PP
 211 \&\fBEVP_PKEY_type()\fR returns the underlying type of the \s-1NID\s0 \fBtype\fR. For example
 212 EVP_PKEY_type(\s-1EVP_PKEY_RSA2\s0) will return \fB\s-1EVP_PKEY_RSA\s0\fR.
 213 .PP
 214 \&\fBEVP_PKEY_set1_engine()\fR sets the \s-1ENGINE\s0 handling \fBpkey\fR to \fBengine\fR. It
 215 must be called after the key algorithm and components are set up.
 216 If \fBengine\fR does not include an \fB\s-1EVP_PKEY_METHOD\s0\fR for \fBpkey\fR an
 217 error occurs.
 218 .PP
 219 \&\fBEVP_PKEY_set_alias_type()\fR allows modifying a \s-1EVP_PKEY\s0 to use a
 220 different set of algorithms than the default. This is currently used
 221 to support \s-1SM2\s0 keys, which use an identical encoding to \s-1ECDSA.\s0
 222 .SH "NOTES"
 223 .IX Header "NOTES"
 224 In accordance with the OpenSSL naming convention the key obtained
 225 from or assigned to the \fBpkey\fR using the \fB1\fR functions must be
 226 freed as well as \fBpkey\fR.
 227 .PP
 228 \&\fBEVP_PKEY_assign_RSA()\fR, \fBEVP_PKEY_assign_DSA()\fR, \fBEVP_PKEY_assign_DH()\fR,
 229 \&\fBEVP_PKEY_assign_EC_KEY()\fR, \fBEVP_PKEY_assign_POLY1305()\fR
 230 and \fBEVP_PKEY_assign_SIPHASH()\fR are implemented as macros.
 231 .PP
 232 Most applications wishing to know a key type will simply call
 233 \&\fBEVP_PKEY_base_id()\fR and will not care about the actual type:
 234 which will be identical in almost all cases.
 235 .PP
 236 Previous versions of this document suggested using EVP_PKEY_type(pkey\->type)
 237 to determine the type of a key. Since \fB\s-1EVP_PKEY\s0\fR is now opaque this
 238 is no longer possible: the equivalent is EVP_PKEY_base_id(pkey).
 239 .PP
 240 \&\fBEVP_PKEY_set1_engine()\fR is typically used by an \s-1ENGINE\s0 returning an \s-1HSM\s0
 241 key as part of its routine to load a private key.
 242 .SH "EXAMPLES"
 243 .IX Header "EXAMPLES"
 244 After loading an \s-1ECC\s0 key, it is possible to convert it to using \s-1SM2\s0
 245 algorithms with EVP_PKEY_set_alias_type:
 246 .PP
 247 .Vb 1
 248 \& EVP_PKEY_set_alias_type(pkey, EVP_PKEY_SM2);
 249 .Ve
 250 .SH "RETURN VALUES"
 251 .IX Header "RETURN VALUES"
 252 \&\fBEVP_PKEY_set1_RSA()\fR, \fBEVP_PKEY_set1_DSA()\fR, \fBEVP_PKEY_set1_DH()\fR and
 253 \&\fBEVP_PKEY_set1_EC_KEY()\fR return 1 for success or 0 for failure.
 254 .PP
 255 \&\fBEVP_PKEY_get1_RSA()\fR, \fBEVP_PKEY_get1_DSA()\fR, \fBEVP_PKEY_get1_DH()\fR and
 256 \&\fBEVP_PKEY_get1_EC_KEY()\fR return the referenced key or \fB\s-1NULL\s0\fR if
 257 an error occurred.
 258 .PP
 259 \&\fBEVP_PKEY_assign_RSA()\fR, \fBEVP_PKEY_assign_DSA()\fR, \fBEVP_PKEY_assign_DH()\fR,
 260 \&\fBEVP_PKEY_assign_EC_KEY()\fR, \fBEVP_PKEY_assign_POLY1305()\fR
 261 and \fBEVP_PKEY_assign_SIPHASH()\fR return 1 for success and 0 for failure.
 262 .PP
 263 \&\fBEVP_PKEY_base_id()\fR, \fBEVP_PKEY_id()\fR and \fBEVP_PKEY_type()\fR return a key
 264 type or \fBNID_undef\fR (equivalently \fB\s-1EVP_PKEY_NONE\s0\fR) on error.
 265 .PP
 266 \&\fBEVP_PKEY_set1_engine()\fR returns 1 for success and 0 for failure.
 267 .PP
 268 \&\fBEVP_PKEY_set_alias_type()\fR returns 1 for success and 0 for error.
 269 .SH "SEE ALSO"
 270 .IX Header "SEE ALSO"
 271 \&\fBEVP_PKEY_new\fR\|(3)
 272 .SH "COPYRIGHT"
 273 .IX Header "COPYRIGHT"
 274 Copyright 2002\-2018 The OpenSSL Project Authors. All Rights Reserved.
 275 .PP
 276 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 277 this file except in compliance with the License.  You can obtain a copy
 278 in the file \s-1LICENSE\s0 in the source distribution or at
 279 <https://www.openssl.org/source/license.html>.