secure/lib/libcrypto/man/EVP_PKEY_CTX_ctrl.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_CTX_CTRL 3"
 132 .TH EVP_PKEY_CTX_CTRL 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_CTX_ctrl, EVP_PKEY_CTX_ctrl_str, EVP_PKEY_CTX_set_signature_md, EVP_PKEY_CTX_get_signature_md, EVP_PKEY_CTX_set_mac_key, EVP_PKEY_CTX_set_rsa_padding, EVP_PKEY_CTX_set_rsa_pss_saltlen, EVP_PKEY_CTX_set_rsa_keygen_bits, EVP_PKEY_CTX_set_rsa_keygen_pubexp, EVP_PKEY_CTX_set_dsa_paramgen_bits, EVP_PKEY_CTX_set_dh_paramgen_prime_len, EVP_PKEY_CTX_set_dh_paramgen_generator, EVP_PKEY_CTX_set_dh_pad, EVP_PKEY_CTX_set_dh_nid, EVP_PKEY_CTX_set_ec_paramgen_curve_nid, EVP_PKEY_CTX_set_ec_param_enc, EVP_PKEY_CTX_set1_id, EVP_PKEY_CTX_get1_id, EVP_PKEY_CTX_get1_id_len \&\- algorithm specific control operations
 139 .SH "SYNOPSIS"
 140 .IX Header "SYNOPSIS"
 141 .Vb 1
 142 \& #include <openssl/evp.h>
 143 \&
 144 \& int EVP_PKEY_CTX_ctrl(EVP_PKEY_CTX *ctx, int keytype, int optype,
 145 \&                       int cmd, int p1, void *p2);
 146 \& int EVP_PKEY_CTX_ctrl_str(EVP_PKEY_CTX *ctx, const char *type,
 147 \&                           const char *value);
 148 \&
 149 \& int EVP_PKEY_CTX_set_signature_md(EVP_PKEY_CTX *ctx, const EVP_MD *md);
 150 \& int EVP_PKEY_CTX_get_signature_md(EVP_PKEY_CTX *ctx, const EVP_MD **pmd);
 151 \&
 152 \& int EVP_PKEY_CTX_set_mac_key(EVP_PKEY_CTX *ctx, unsigned char *key, int len);
 153 \&
 154 \& #include <openssl/rsa.h>
 155 \&
 156 \& int EVP_PKEY_CTX_set_rsa_padding(EVP_PKEY_CTX *ctx, int pad);
 157 \& int EVP_PKEY_CTX_set_rsa_pss_saltlen(EVP_PKEY_CTX *ctx, int len);
 158 \& int EVP_PKEY_CTX_set_rsa_keygen_bits(EVP_PKEY_CTX *ctx, int mbits);
 159 \& int EVP_PKEY_CTX_set_rsa_keygen_pubexp(EVP_PKEY_CTX *ctx, BIGNUM *pubexp);
 160 \&
 161 \& #include <openssl/dsa.h>
 162 \& int EVP_PKEY_CTX_set_dsa_paramgen_bits(EVP_PKEY_CTX *ctx, int nbits);
 163 \&
 164 \& #include <openssl/dh.h>
 165 \& int EVP_PKEY_CTX_set_dh_paramgen_prime_len(EVP_PKEY_CTX *ctx, int len);
 166 \& int EVP_PKEY_CTX_set_dh_paramgen_generator(EVP_PKEY_CTX *ctx, int gen);
 167 \& int EVP_PKEY_CTX_set_dh_pad(EVP_PKEY_CTX *ctx, int pad);
 168 \& int EVP_PKEY_CTX_set_dh_nid(EVP_PKEY_CTX *ctx, int nid);
 169 \&
 170 \& #include <openssl/ec.h>
 171 \& int EVP_PKEY_CTX_set_ec_paramgen_curve_nid(EVP_PKEY_CTX *ctx, int nid);
 172 \& int EVP_PKEY_CTX_set_ec_param_enc(EVP_PKEY_CTX *ctx, int param_enc);
 173 \&
 174 \& int EVP_PKEY_CTX_set1_id(EVP_PKEY_CTX *ctx, void *id, size_t id_len);
 175 \& int EVP_PKEY_CTX_get1_id(EVP_PKEY_CTX *ctx, void *id);
 176 \& int EVP_PKEY_CTX_get1_id_len(EVP_PKEY_CTX *ctx, size_t *id_len);
 177 .Ve
 178 .SH "DESCRIPTION"
 179 .IX Header "DESCRIPTION"
 180 The function \fIEVP_PKEY_CTX_ctrl()\fR sends a control operation to the context
 181 \&\fBctx\fR. The key type used must match \fBkeytype\fR if it is not \-1. The parameter
 182 \&\fBoptype\fR is a mask indicating which operations the control can be applied to.
 183 The control command is indicated in \fBcmd\fR and any additional arguments in
 184 \&\fBp1\fR and \fBp2\fR.
 185 .PP
 186 For \fBcmd\fR = \fB\s-1EVP_PKEY_CTRL_SET_MAC_KEY\s0\fR, \fBp1\fR is the length of the \s-1MAC\s0 key,
 187 and \fBp2\fR is \s-1MAC\s0 key. This is used by Poly1305, SipHash, \s-1HMAC\s0 and \s-1CMAC.\s0
 188 .PP
 189 Applications will not normally call \fIEVP_PKEY_CTX_ctrl()\fR directly but will
 190 instead call one of the algorithm specific macros below.
 191 .PP
 192 The function \fIEVP_PKEY_CTX_ctrl_str()\fR allows an application to send an algorithm
 193 specific control operation to a context \fBctx\fR in string form. This is
 194 intended to be used for options specified on the command line or in text
 195 files. The commands supported are documented in the openssl utility
 196 command line pages for the option \fB\-pkeyopt\fR which is supported by the
 197 \&\fBpkeyutl\fR, \fBgenpkey\fR and \fBreq\fR commands.
 198 .PP
 199 All the remaining \*(L"functions\*(R" are implemented as macros.
 200 .PP
 201 The \fIEVP_PKEY_CTX_set_signature_md()\fR macro sets the message digest type used
 202 in a signature. It can be used in the \s-1RSA, DSA\s0 and \s-1ECDSA\s0 algorithms.
 203 .PP
 204 The \fIEVP_PKEY_CTX_get_signature_md()\fR macro gets the message digest type used in a
 205 signature. It can be used in the \s-1RSA, DSA\s0 and \s-1ECDSA\s0 algorithms.
 206 .PP
 207 Key generation typically involves setting up parameters to be used and
 208 generating the private and public key data. Some algorithm implementations
 209 allow private key data to be set explicitly using the \fIEVP_PKEY_CTX_set_mac_key()\fR
 210 macro. In this case key generation is simply the process of setting up the
 211 parameters for the key and then setting the raw key data to the value explicitly
 212 provided by that macro. Normally applications would call
 213 \&\fIEVP_PKEY_new_raw_private_key\fR\|(3) or similar functions instead of this macro.
 214 .PP
 215 The \fIEVP_PKEY_CTX_set_mac_key()\fR macro can be used with any of the algorithms
 216 supported by the \fIEVP_PKEY_new_raw_private_key\fR\|(3) function.
 217 .PP
 218 The macro \fIEVP_PKEY_CTX_set_rsa_padding()\fR sets the \s-1RSA\s0 padding mode for \fBctx\fR.
 219 The \fBpad\fR parameter can take the value \s-1RSA_PKCS1_PADDING\s0 for PKCS#1 padding,
 220 \&\s-1RSA_SSLV23_PADDING\s0 for SSLv23 padding, \s-1RSA_NO_PADDING\s0 for no padding,
 221 \&\s-1RSA_PKCS1_OAEP_PADDING\s0 for \s-1OAEP\s0 padding (encrypt and decrypt only),
 222 \&\s-1RSA_X931_PADDING\s0 for X9.31 padding (signature operations only) and
 223 \&\s-1RSA_PKCS1_PSS_PADDING\s0 (sign and verify only).
 224 .PP
 225 Two \s-1RSA\s0 padding modes behave differently if \fIEVP_PKEY_CTX_set_signature_md()\fR
 226 is used. If this macro is called for PKCS#1 padding the plaintext buffer is
 227 an actual digest value and is encapsulated in a DigestInfo structure according
 228 to PKCS#1 when signing and this structure is expected (and stripped off) when
 229 verifying. If this control is not used with \s-1RSA\s0 and PKCS#1 padding then the
 230 supplied data is used directly and not encapsulated. In the case of X9.31
 231 padding for \s-1RSA\s0 the algorithm identifier byte is added or checked and removed
 232 if this control is called. If it is not called then the first byte of the plaintext
 233 buffer is expected to be the algorithm identifier byte.
 234 .PP
 235 The \fIEVP_PKEY_CTX_set_rsa_pss_saltlen()\fR macro sets the \s-1RSA PSS\s0 salt length to
 236 \&\fBlen\fR as its name implies it is only supported for \s-1PSS\s0 padding.  Three special
 237 values are supported: \s-1RSA_PSS_SALTLEN_DIGEST\s0 sets the salt length to the
 238 digest length, \s-1RSA_PSS_SALTLEN_MAX\s0 sets the salt length to the maximum
 239 permissible value. When verifying \s-1RSA_PSS_SALTLEN_AUTO\s0 causes the salt length
 240 to be automatically determined based on the \fB\s-1PSS\s0\fR block structure. If this
 241 macro is not called maximum salt length is used when signing and auto detection
 242 when verifying is used by default.
 243 .PP
 244 The \fIEVP_PKEY_CTX_set_rsa_keygen_bits()\fR macro sets the \s-1RSA\s0 key length for
 245 \&\s-1RSA\s0 key generation to \fBbits\fR. If not specified 1024 bits is used.
 246 .PP
 247 The \fIEVP_PKEY_CTX_set_rsa_keygen_pubexp()\fR macro sets the public exponent value
 248 for \s-1RSA\s0 key generation to \fBpubexp\fR currently it should be an odd integer. The
 249 \&\fBpubexp\fR pointer is used internally by this function so it should not be
 250 modified or free after the call. If this macro is not called then 65537 is used.
 251 .PP
 252 The macro \fIEVP_PKEY_CTX_set_dsa_paramgen_bits()\fR sets the number of bits used
 253 for \s-1DSA\s0 parameter generation to \fBbits\fR. If not specified 1024 is used.
 254 .PP
 255 The macro \fIEVP_PKEY_CTX_set_dh_paramgen_prime_len()\fR sets the length of the \s-1DH\s0
 256 prime parameter \fBp\fR for \s-1DH\s0 parameter generation. If this macro is not called
 257 then 1024 is used.
 258 .PP
 259 The \fIEVP_PKEY_CTX_set_dh_paramgen_generator()\fR macro sets \s-1DH\s0 generator to \fBgen\fR
 260 for \s-1DH\s0 parameter generation. If not specified 2 is used.
 261 .PP
 262 The \fIEVP_PKEY_CTX_set_dh_pad()\fR macro sets the \s-1DH\s0 padding mode. If \fBpad\fR is
 263 1 the shared secret is padded with zeroes up to the size of the \s-1DH\s0 prime \fBp\fR.
 264 If \fBpad\fR is zero (the default) then no padding is performed.
 265 .PP
 266 \&\fIEVP_PKEY_CTX_set_dh_nid()\fR sets the \s-1DH\s0 parameters to values corresponding to
 267 \&\fBnid\fR. The \fBnid\fR parameter must be \fBNID_ffdhe2048\fR, \fBNID_ffdhe3072\fR,
 268 \&\fBNID_ffdhe4096\fR, \fBNID_ffdhe6144\fR or \fBNID_ffdhe8192\fR.  This macro can be
 269 called during parameter or key generation.
 270 .PP
 271 The \fIEVP_PKEY_CTX_set_ec_paramgen_curve_nid()\fR sets the \s-1EC\s0 curve for \s-1EC\s0 parameter
 272 generation to \fBnid\fR. For \s-1EC\s0 parameter generation this macro must be called
 273 or an error occurs because there is no default curve.
 274 This function can also be called to set the curve explicitly when
 275 generating an \s-1EC\s0 key.
 276 .PP
 277 The \fIEVP_PKEY_CTX_set_ec_param_enc()\fR sets the \s-1EC\s0 parameter encoding to
 278 \&\fBparam_enc\fR when generating \s-1EC\s0 parameters or an \s-1EC\s0 key. The encoding can be
 279 \&\fB\s-1OPENSSL_EC_EXPLICIT_CURVE\s0\fR for explicit parameters (the default in versions
 280 of OpenSSL before 1.1.0) or \fB\s-1OPENSSL_EC_NAMED_CURVE\s0\fR to use named curve form.
 281 For maximum compatibility the named curve form should be used. Note: the
 282 \&\fB\s-1OPENSSL_EC_NAMED_CURVE\s0\fR value was only added to OpenSSL 1.1.0; previous
 283 versions should use 0 instead.
 284 .PP
 285 The \fIEVP_PKEY_CTX_set1_id()\fR, \fIEVP_PKEY_CTX_get1_id()\fR and \fIEVP_PKEY_CTX_get1_id_len()\fR
 286 macros are used to manipulate the special identifier field for specific signature
 287 algorithms such as \s-1SM2.\s0 The \fIEVP_PKEY_CTX_set1_id()\fR sets an \s-1ID\s0 pointed by \fBid\fR with
 288 the length \fBid_len\fR to the library. The library takes a copy of the id so that
 289 the caller can safely free the original memory pointed to by \fBid\fR. The
 290 \&\fIEVP_PKEY_CTX_get1_id_len()\fR macro returns the length of the \s-1ID\s0 set via a previous
 291 call to \fIEVP_PKEY_CTX_set1_id()\fR. The length is usually used to allocate adequate
 292 memory for further calls to \fIEVP_PKEY_CTX_get1_id()\fR. The \fIEVP_PKEY_CTX_get1_id()\fR
 293 macro returns the previously set \s-1ID\s0 value to caller in \fBid\fR. The caller should
 294 allocate adequate memory space for the \fBid\fR before calling \fIEVP_PKEY_CTX_get1_id()\fR.
 295 .SH "RETURN VALUES"
 296 .IX Header "RETURN VALUES"
 297 \&\fIEVP_PKEY_CTX_ctrl()\fR and its macros return a positive value for success and 0
 298 or a negative value for failure. In particular a return value of \-2
 299 indicates the operation is not supported by the public key algorithm.
 300 .SH "SEE ALSO"
 301 .IX Header "SEE ALSO"
 302 \&\fIEVP_PKEY_CTX_new\fR\|(3),
 303 \&\fIEVP_PKEY_encrypt\fR\|(3),
 304 \&\fIEVP_PKEY_decrypt\fR\|(3),
 305 \&\fIEVP_PKEY_sign\fR\|(3),
 306 \&\fIEVP_PKEY_verify\fR\|(3),
 307 \&\fIEVP_PKEY_verify_recover\fR\|(3),
 308 \&\fIEVP_PKEY_derive\fR\|(3)
 309 \&\fIEVP_PKEY_keygen\fR\|(3)
 310 .SH "HISTORY"
 311 .IX Header "HISTORY"
 312 \&\fIEVP_PKEY_CTX_set1_id()\fR, \fIEVP_PKEY_CTX_get1_id()\fR and \fIEVP_PKEY_CTX_get1_id_len()\fR
 313 macros were added in 1.1.1, other functions were first added to OpenSSL 1.0.0.
 314 .SH "COPYRIGHT"
 315 .IX Header "COPYRIGHT"
 316 Copyright 2006\-2018 The OpenSSL Project Authors. All Rights Reserved.
 317 .PP
 318 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 319 this file except in compliance with the License.  You can obtain a copy
 320 in the file \s-1LICENSE\s0 in the source distribution or at
 321 <https://www.openssl.org/source/license.html>.