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