539 lines
28 KiB
Groff
539 lines
28 KiB
Groff
.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.40)
|
|
.\"
|
|
.\" Standard preamble:
|
|
.\" ========================================================================
|
|
.de Sp \" Vertical space (when we can't use .PP)
|
|
.if t .sp .5v
|
|
.if n .sp
|
|
..
|
|
.de Vb \" Begin verbatim text
|
|
.ft CW
|
|
.nf
|
|
.ne \\$1
|
|
..
|
|
.de Ve \" End verbatim text
|
|
.ft R
|
|
.fi
|
|
..
|
|
.\" Set up some character translations and predefined strings. \*(-- will
|
|
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
|
|
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
|
|
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
|
|
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
|
|
.\" nothing in troff, for use with C<>.
|
|
.tr \(*W-
|
|
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
|
|
.ie n \{\
|
|
. ds -- \(*W-
|
|
. ds PI pi
|
|
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
|
|
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
|
|
. ds L" ""
|
|
. ds R" ""
|
|
. ds C` ""
|
|
. ds C' ""
|
|
'br\}
|
|
.el\{\
|
|
. ds -- \|\(em\|
|
|
. ds PI \(*p
|
|
. ds L" ``
|
|
. ds R" ''
|
|
. ds C`
|
|
. ds C'
|
|
'br\}
|
|
.\"
|
|
.\" Escape single quotes in literal strings from groff's Unicode transform.
|
|
.ie \n(.g .ds Aq \(aq
|
|
.el .ds Aq '
|
|
.\"
|
|
.\" If the F register is >0, we'll generate index entries on stderr for
|
|
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
|
|
.\" entries marked with X<> in POD. Of course, you'll have to process the
|
|
.\" output yourself in some meaningful fashion.
|
|
.\"
|
|
.\" Avoid warning from groff about undefined register 'F'.
|
|
.de IX
|
|
..
|
|
.nr rF 0
|
|
.if \n(.g .if rF .nr rF 1
|
|
.if (\n(rF:(\n(.g==0)) \{\
|
|
. if \nF \{\
|
|
. de IX
|
|
. tm Index:\\$1\t\\n%\t"\\$2"
|
|
..
|
|
. if !\nF==2 \{\
|
|
. nr % 0
|
|
. nr F 2
|
|
. \}
|
|
. \}
|
|
.\}
|
|
.rr rF
|
|
.\"
|
|
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
|
|
.\" Fear. Run. Save yourself. No user-serviceable parts.
|
|
. \" fudge factors for nroff and troff
|
|
.if n \{\
|
|
. ds #H 0
|
|
. ds #V .8m
|
|
. ds #F .3m
|
|
. ds #[ \f1
|
|
. ds #] \fP
|
|
.\}
|
|
.if t \{\
|
|
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
|
|
. ds #V .6m
|
|
. ds #F 0
|
|
. ds #[ \&
|
|
. ds #] \&
|
|
.\}
|
|
. \" simple accents for nroff and troff
|
|
.if n \{\
|
|
. ds ' \&
|
|
. ds ` \&
|
|
. ds ^ \&
|
|
. ds , \&
|
|
. ds ~ ~
|
|
. ds /
|
|
.\}
|
|
.if t \{\
|
|
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
|
|
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
|
|
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
|
|
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
|
|
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
|
|
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
|
|
.\}
|
|
. \" troff and (daisy-wheel) nroff accents
|
|
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
|
|
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
|
|
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
|
|
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
|
|
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
|
|
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
|
|
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
|
|
.ds ae a\h'-(\w'a'u*4/10)'e
|
|
.ds Ae A\h'-(\w'A'u*4/10)'E
|
|
. \" corrections for vroff
|
|
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
|
|
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
|
|
. \" for low resolution devices (crt and lpr)
|
|
.if \n(.H>23 .if \n(.V>19 \
|
|
\{\
|
|
. ds : e
|
|
. ds 8 ss
|
|
. ds o a
|
|
. ds d- d\h'-1'\(ga
|
|
. ds D- D\h'-1'\(hy
|
|
. ds th \o'bp'
|
|
. ds Th \o'LP'
|
|
. ds ae ae
|
|
. ds Ae AE
|
|
.\}
|
|
.rm #[ #] #H #V #F C
|
|
.\" ========================================================================
|
|
.\"
|
|
.IX Title "EVP_PKEY_CTX_CTRL 3"
|
|
.TH EVP_PKEY_CTX_CTRL 3 "2020-04-21" "1.1.1g" "OpenSSL"
|
|
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
|
|
.\" way too many mistakes in technical documents.
|
|
.if n .ad l
|
|
.nh
|
|
.SH "NAME"
|
|
EVP_PKEY_CTX_ctrl, EVP_PKEY_CTX_ctrl_str, EVP_PKEY_CTX_ctrl_uint64, EVP_PKEY_CTX_md, 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_get_rsa_padding, EVP_PKEY_CTX_set_rsa_pss_saltlen, EVP_PKEY_CTX_get_rsa_pss_saltlen, EVP_PKEY_CTX_set_rsa_keygen_bits, EVP_PKEY_CTX_set_rsa_keygen_pubexp, EVP_PKEY_CTX_set_rsa_keygen_primes, EVP_PKEY_CTX_set_rsa_mgf1_md, EVP_PKEY_CTX_get_rsa_mgf1_md, EVP_PKEY_CTX_set_rsa_oaep_md, EVP_PKEY_CTX_get_rsa_oaep_md, EVP_PKEY_CTX_set0_rsa_oaep_label, EVP_PKEY_CTX_get0_rsa_oaep_label, EVP_PKEY_CTX_set_dsa_paramgen_bits, EVP_PKEY_CTX_set_dsa_paramgen_q_bits, EVP_PKEY_CTX_set_dsa_paramgen_md, EVP_PKEY_CTX_set_dh_paramgen_prime_len, EVP_PKEY_CTX_set_dh_paramgen_subprime_len, EVP_PKEY_CTX_set_dh_paramgen_generator, EVP_PKEY_CTX_set_dh_paramgen_type, EVP_PKEY_CTX_set_dh_rfc5114, EVP_PKEY_CTX_set_dhx_rfc5114, EVP_PKEY_CTX_set_dh_pad, EVP_PKEY_CTX_set_dh_nid, EVP_PKEY_CTX_set_dh_kdf_type, EVP_PKEY_CTX_get_dh_kdf_type, EVP_PKEY_CTX_set0_dh_kdf_oid, EVP_PKEY_CTX_get0_dh_kdf_oid, EVP_PKEY_CTX_set_dh_kdf_md, EVP_PKEY_CTX_get_dh_kdf_md, EVP_PKEY_CTX_set_dh_kdf_outlen, EVP_PKEY_CTX_get_dh_kdf_outlen, EVP_PKEY_CTX_set0_dh_kdf_ukm, EVP_PKEY_CTX_get0_dh_kdf_ukm, EVP_PKEY_CTX_set_ec_paramgen_curve_nid, EVP_PKEY_CTX_set_ec_param_enc, EVP_PKEY_CTX_set_ecdh_cofactor_mode, EVP_PKEY_CTX_get_ecdh_cofactor_mode, EVP_PKEY_CTX_set_ecdh_kdf_type, EVP_PKEY_CTX_get_ecdh_kdf_type, EVP_PKEY_CTX_set_ecdh_kdf_md, EVP_PKEY_CTX_get_ecdh_kdf_md, EVP_PKEY_CTX_set_ecdh_kdf_outlen, EVP_PKEY_CTX_get_ecdh_kdf_outlen, EVP_PKEY_CTX_set0_ecdh_kdf_ukm, EVP_PKEY_CTX_get0_ecdh_kdf_ukm, EVP_PKEY_CTX_set1_id, EVP_PKEY_CTX_get1_id, EVP_PKEY_CTX_get1_id_len \&\- algorithm specific control operations
|
|
.SH "SYNOPSIS"
|
|
.IX Header "SYNOPSIS"
|
|
.Vb 1
|
|
\& #include <openssl/evp.h>
|
|
\&
|
|
\& int EVP_PKEY_CTX_ctrl(EVP_PKEY_CTX *ctx, int keytype, int optype,
|
|
\& int cmd, int p1, void *p2);
|
|
\& int EVP_PKEY_CTX_ctrl_uint64(EVP_PKEY_CTX *ctx, int keytype, int optype,
|
|
\& int cmd, uint64_t value);
|
|
\& int EVP_PKEY_CTX_ctrl_str(EVP_PKEY_CTX *ctx, const char *type,
|
|
\& const char *value);
|
|
\&
|
|
\& int EVP_PKEY_CTX_md(EVP_PKEY_CTX *ctx, int optype, int cmd, const char *md);
|
|
\&
|
|
\& int EVP_PKEY_CTX_set_signature_md(EVP_PKEY_CTX *ctx, const EVP_MD *md);
|
|
\& int EVP_PKEY_CTX_get_signature_md(EVP_PKEY_CTX *ctx, const EVP_MD **pmd);
|
|
\&
|
|
\& int EVP_PKEY_CTX_set_mac_key(EVP_PKEY_CTX *ctx, unsigned char *key, int len);
|
|
\&
|
|
\& #include <openssl/rsa.h>
|
|
\&
|
|
\& int EVP_PKEY_CTX_set_rsa_padding(EVP_PKEY_CTX *ctx, int pad);
|
|
\& int EVP_PKEY_CTX_get_rsa_padding(EVP_PKEY_CTX *ctx, int *pad);
|
|
\& int EVP_PKEY_CTX_set_rsa_pss_saltlen(EVP_PKEY_CTX *ctx, int len);
|
|
\& int EVP_PKEY_CTX_get_rsa_pss_saltlen(EVP_PKEY_CTX *ctx, int *len);
|
|
\& int EVP_PKEY_CTX_set_rsa_keygen_bits(EVP_PKEY_CTX *ctx, int mbits);
|
|
\& int EVP_PKEY_CTX_set_rsa_keygen_pubexp(EVP_PKEY_CTX *ctx, BIGNUM *pubexp);
|
|
\& int EVP_PKEY_CTX_set_rsa_keygen_primes(EVP_PKEY_CTX *ctx, int primes);
|
|
\& int EVP_PKEY_CTX_set_rsa_mgf1_md(EVP_PKEY_CTX *ctx, const EVP_MD *md);
|
|
\& int EVP_PKEY_CTX_get_rsa_mgf1_md(EVP_PKEY_CTX *ctx, const EVP_MD **md);
|
|
\& int EVP_PKEY_CTX_set_rsa_oaep_md(EVP_PKEY_CTX *ctx, const EVP_MD *md);
|
|
\& int EVP_PKEY_CTX_get_rsa_oaep_md(EVP_PKEY_CTX *ctx, const EVP_MD **md);
|
|
\& int EVP_PKEY_CTX_set0_rsa_oaep_label(EVP_PKEY_CTX *ctx, unsigned char *label, int len);
|
|
\& int EVP_PKEY_CTX_get0_rsa_oaep_label(EVP_PKEY_CTX *ctx, unsigned char **label);
|
|
\&
|
|
\& #include <openssl/dsa.h>
|
|
\&
|
|
\& int EVP_PKEY_CTX_set_dsa_paramgen_bits(EVP_PKEY_CTX *ctx, int nbits);
|
|
\& int EVP_PKEY_CTX_set_dsa_paramgen_q_bits(EVP_PKEY_CTX *ctx, int qbits);
|
|
\& int EVP_PKEY_CTX_set_dsa_paramgen_md(EVP_PKEY_CTX *ctx, const EVP_MD *md);
|
|
\&
|
|
\& #include <openssl/dh.h>
|
|
\&
|
|
\& int EVP_PKEY_CTX_set_dh_paramgen_prime_len(EVP_PKEY_CTX *ctx, int len);
|
|
\& int EVP_PKEY_CTX_set_dh_paramgen_subprime_len(EVP_PKEY_CTX *ctx, int len);
|
|
\& int EVP_PKEY_CTX_set_dh_paramgen_generator(EVP_PKEY_CTX *ctx, int gen);
|
|
\& int EVP_PKEY_CTX_set_dh_paramgen_type(EVP_PKEY_CTX *ctx, int type);
|
|
\& int EVP_PKEY_CTX_set_dh_pad(EVP_PKEY_CTX *ctx, int pad);
|
|
\& int EVP_PKEY_CTX_set_dh_nid(EVP_PKEY_CTX *ctx, int nid);
|
|
\& int EVP_PKEY_CTX_set_dh_rfc5114(EVP_PKEY_CTX *ctx, int rfc5114);
|
|
\& int EVP_PKEY_CTX_set_dhx_rfc5114(EVP_PKEY_CTX *ctx, int rfc5114);
|
|
\& int EVP_PKEY_CTX_set_dh_kdf_type(EVP_PKEY_CTX *ctx, int kdf);
|
|
\& int EVP_PKEY_CTX_get_dh_kdf_type(EVP_PKEY_CTX *ctx);
|
|
\& int EVP_PKEY_CTX_set0_dh_kdf_oid(EVP_PKEY_CTX *ctx, ASN1_OBJECT *oid);
|
|
\& int EVP_PKEY_CTX_get0_dh_kdf_oid(EVP_PKEY_CTX *ctx, ASN1_OBJECT **oid);
|
|
\& int EVP_PKEY_CTX_set_dh_kdf_md(EVP_PKEY_CTX *ctx, const EVP_MD *md);
|
|
\& int EVP_PKEY_CTX_get_dh_kdf_md(EVP_PKEY_CTX *ctx, const EVP_MD **md);
|
|
\& int EVP_PKEY_CTX_set_dh_kdf_outlen(EVP_PKEY_CTX *ctx, int len);
|
|
\& int EVP_PKEY_CTX_get_dh_kdf_outlen(EVP_PKEY_CTX *ctx, int *len);
|
|
\& int EVP_PKEY_CTX_set0_dh_kdf_ukm(EVP_PKEY_CTX *ctx, unsigned char *ukm, int len);
|
|
\& int EVP_PKEY_CTX_get0_dh_kdf_ukm(EVP_PKEY_CTX *ctx, unsigned char **ukm);
|
|
\&
|
|
\& #include <openssl/ec.h>
|
|
\&
|
|
\& int EVP_PKEY_CTX_set_ec_paramgen_curve_nid(EVP_PKEY_CTX *ctx, int nid);
|
|
\& int EVP_PKEY_CTX_set_ec_param_enc(EVP_PKEY_CTX *ctx, int param_enc);
|
|
\& int EVP_PKEY_CTX_set_ecdh_cofactor_mode(EVP_PKEY_CTX *ctx, int cofactor_mode);
|
|
\& int EVP_PKEY_CTX_get_ecdh_cofactor_mode(EVP_PKEY_CTX *ctx);
|
|
\& int EVP_PKEY_CTX_set_ecdh_kdf_type(EVP_PKEY_CTX *ctx, int kdf);
|
|
\& int EVP_PKEY_CTX_get_ecdh_kdf_type(EVP_PKEY_CTX *ctx);
|
|
\& int EVP_PKEY_CTX_set_ecdh_kdf_md(EVP_PKEY_CTX *ctx, const EVP_MD *md);
|
|
\& int EVP_PKEY_CTX_get_ecdh_kdf_md(EVP_PKEY_CTX *ctx, const EVP_MD **md);
|
|
\& int EVP_PKEY_CTX_set_ecdh_kdf_outlen(EVP_PKEY_CTX *ctx, int len);
|
|
\& int EVP_PKEY_CTX_get_ecdh_kdf_outlen(EVP_PKEY_CTX *ctx, int *len);
|
|
\& int EVP_PKEY_CTX_set0_ecdh_kdf_ukm(EVP_PKEY_CTX *ctx, unsigned char *ukm, int len);
|
|
\& int EVP_PKEY_CTX_get0_ecdh_kdf_ukm(EVP_PKEY_CTX *ctx, unsigned char **ukm);
|
|
\&
|
|
\& int EVP_PKEY_CTX_set1_id(EVP_PKEY_CTX *ctx, void *id, size_t id_len);
|
|
\& int EVP_PKEY_CTX_get1_id(EVP_PKEY_CTX *ctx, void *id);
|
|
\& int EVP_PKEY_CTX_get1_id_len(EVP_PKEY_CTX *ctx, size_t *id_len);
|
|
.Ve
|
|
.SH "DESCRIPTION"
|
|
.IX Header "DESCRIPTION"
|
|
The function \fBEVP_PKEY_CTX_ctrl()\fR sends a control operation to the context
|
|
\&\fBctx\fR. The key type used must match \fBkeytype\fR if it is not \-1. The parameter
|
|
\&\fBoptype\fR is a mask indicating which operations the control can be applied to.
|
|
The control command is indicated in \fBcmd\fR and any additional arguments in
|
|
\&\fBp1\fR and \fBp2\fR.
|
|
.PP
|
|
For \fBcmd\fR = \fB\s-1EVP_PKEY_CTRL_SET_MAC_KEY\s0\fR, \fBp1\fR is the length of the \s-1MAC\s0 key,
|
|
and \fBp2\fR is \s-1MAC\s0 key. This is used by Poly1305, SipHash, \s-1HMAC\s0 and \s-1CMAC.\s0
|
|
.PP
|
|
Applications will not normally call \fBEVP_PKEY_CTX_ctrl()\fR directly but will
|
|
instead call one of the algorithm specific macros below.
|
|
.PP
|
|
The function \fBEVP_PKEY_CTX_ctrl_uint64()\fR is a wrapper that directly passes a
|
|
uint64 value as \fBp2\fR to \fBEVP_PKEY_CTX_ctrl()\fR.
|
|
.PP
|
|
The function \fBEVP_PKEY_CTX_ctrl_str()\fR allows an application to send an algorithm
|
|
specific control operation to a context \fBctx\fR in string form. This is
|
|
intended to be used for options specified on the command line or in text
|
|
files. The commands supported are documented in the openssl utility
|
|
command line pages for the option \fB\-pkeyopt\fR which is supported by the
|
|
\&\fBpkeyutl\fR, \fBgenpkey\fR and \fBreq\fR commands.
|
|
.PP
|
|
The function \fBEVP_PKEY_CTX_md()\fR sends a message digest control operation
|
|
to the context \fBctx\fR. The message digest is specified by its name \fBmd\fR.
|
|
.PP
|
|
All the remaining \*(L"functions\*(R" are implemented as macros.
|
|
.PP
|
|
The \fBEVP_PKEY_CTX_set_signature_md()\fR macro sets the message digest type used
|
|
in a signature. It can be used in the \s-1RSA, DSA\s0 and \s-1ECDSA\s0 algorithms.
|
|
.PP
|
|
The \fBEVP_PKEY_CTX_get_signature_md()\fR macro gets the message digest type used in a
|
|
signature. It can be used in the \s-1RSA, DSA\s0 and \s-1ECDSA\s0 algorithms.
|
|
.PP
|
|
Key generation typically involves setting up parameters to be used and
|
|
generating the private and public key data. Some algorithm implementations
|
|
allow private key data to be set explicitly using the \fBEVP_PKEY_CTX_set_mac_key()\fR
|
|
macro. In this case key generation is simply the process of setting up the
|
|
parameters for the key and then setting the raw key data to the value explicitly
|
|
provided by that macro. Normally applications would call
|
|
\&\fBEVP_PKEY_new_raw_private_key\fR\|(3) or similar functions instead of this macro.
|
|
.PP
|
|
The \fBEVP_PKEY_CTX_set_mac_key()\fR macro can be used with any of the algorithms
|
|
supported by the \fBEVP_PKEY_new_raw_private_key\fR\|(3) function.
|
|
.SS "\s-1RSA\s0 parameters"
|
|
.IX Subsection "RSA parameters"
|
|
The \fBEVP_PKEY_CTX_set_rsa_padding()\fR macro sets the \s-1RSA\s0 padding mode for \fBctx\fR.
|
|
The \fBpad\fR parameter can take the value \fB\s-1RSA_PKCS1_PADDING\s0\fR for PKCS#1
|
|
padding, \fB\s-1RSA_SSLV23_PADDING\s0\fR for SSLv23 padding, \fB\s-1RSA_NO_PADDING\s0\fR for
|
|
no padding, \fB\s-1RSA_PKCS1_OAEP_PADDING\s0\fR for \s-1OAEP\s0 padding (encrypt and
|
|
decrypt only), \fB\s-1RSA_X931_PADDING\s0\fR for X9.31 padding (signature operations
|
|
only) and \fB\s-1RSA_PKCS1_PSS_PADDING\s0\fR (sign and verify only).
|
|
.PP
|
|
Two \s-1RSA\s0 padding modes behave differently if \fBEVP_PKEY_CTX_set_signature_md()\fR
|
|
is used. If this macro is called for PKCS#1 padding the plaintext buffer is
|
|
an actual digest value and is encapsulated in a DigestInfo structure according
|
|
to PKCS#1 when signing and this structure is expected (and stripped off) when
|
|
verifying. If this control is not used with \s-1RSA\s0 and PKCS#1 padding then the
|
|
supplied data is used directly and not encapsulated. In the case of X9.31
|
|
padding for \s-1RSA\s0 the algorithm identifier byte is added or checked and removed
|
|
if this control is called. If it is not called then the first byte of the plaintext
|
|
buffer is expected to be the algorithm identifier byte.
|
|
.PP
|
|
The \fBEVP_PKEY_CTX_get_rsa_padding()\fR macro gets the \s-1RSA\s0 padding mode for \fBctx\fR.
|
|
.PP
|
|
The \fBEVP_PKEY_CTX_set_rsa_pss_saltlen()\fR macro sets the \s-1RSA PSS\s0 salt length to
|
|
\&\fBlen\fR. As its name implies it is only supported for \s-1PSS\s0 padding. Three special
|
|
values are supported: \fB\s-1RSA_PSS_SALTLEN_DIGEST\s0\fR sets the salt length to the
|
|
digest length, \fB\s-1RSA_PSS_SALTLEN_MAX\s0\fR sets the salt length to the maximum
|
|
permissible value. When verifying \fB\s-1RSA_PSS_SALTLEN_AUTO\s0\fR causes the salt length
|
|
to be automatically determined based on the \fB\s-1PSS\s0\fR block structure. If this
|
|
macro is not called maximum salt length is used when signing and auto detection
|
|
when verifying is used by default.
|
|
.PP
|
|
The \fBEVP_PKEY_CTX_get_rsa_pss_saltlen()\fR macro gets the \s-1RSA PSS\s0 salt length
|
|
for \fBctx\fR. The padding mode must have been set to \fB\s-1RSA_PKCS1_PSS_PADDING\s0\fR.
|
|
.PP
|
|
The \fBEVP_PKEY_CTX_set_rsa_keygen_bits()\fR macro sets the \s-1RSA\s0 key length for
|
|
\&\s-1RSA\s0 key generation to \fBbits\fR. If not specified 1024 bits is used.
|
|
.PP
|
|
The \fBEVP_PKEY_CTX_set_rsa_keygen_pubexp()\fR macro sets the public exponent value
|
|
for \s-1RSA\s0 key generation to \fBpubexp\fR. Currently it should be an odd integer. The
|
|
\&\fBpubexp\fR pointer is used internally by this function so it should not be
|
|
modified or freed after the call. If not specified 65537 is used.
|
|
.PP
|
|
The \fBEVP_PKEY_CTX_set_rsa_keygen_primes()\fR macro sets the number of primes for
|
|
\&\s-1RSA\s0 key generation to \fBprimes\fR. If not specified 2 is used.
|
|
.PP
|
|
The \fBEVP_PKEY_CTX_set_rsa_mgf1_md()\fR macro sets the \s-1MGF1\s0 digest for \s-1RSA\s0 padding
|
|
schemes to \fBmd\fR. If not explicitly set the signing digest is used. The
|
|
padding mode must have been set to \fB\s-1RSA_PKCS1_OAEP_PADDING\s0\fR
|
|
or \fB\s-1RSA_PKCS1_PSS_PADDING\s0\fR.
|
|
.PP
|
|
The \fBEVP_PKEY_CTX_get_rsa_mgf1_md()\fR macro gets the \s-1MGF1\s0 digest for \fBctx\fR.
|
|
If not explicitly set the signing digest is used. The padding mode must have
|
|
been set to \fB\s-1RSA_PKCS1_OAEP_PADDING\s0\fR or \fB\s-1RSA_PKCS1_PSS_PADDING\s0\fR.
|
|
.PP
|
|
The \fBEVP_PKEY_CTX_set_rsa_oaep_md()\fR macro sets the message digest type used
|
|
in \s-1RSA OAEP\s0 to \fBmd\fR. The padding mode must have been set to
|
|
\&\fB\s-1RSA_PKCS1_OAEP_PADDING\s0\fR.
|
|
.PP
|
|
The \fBEVP_PKEY_CTX_get_rsa_oaep_md()\fR macro gets the message digest type used
|
|
in \s-1RSA OAEP\s0 to \fBmd\fR. The padding mode must have been set to
|
|
\&\fB\s-1RSA_PKCS1_OAEP_PADDING\s0\fR.
|
|
.PP
|
|
The \fBEVP_PKEY_CTX_set0_rsa_oaep_label()\fR macro sets the \s-1RSA OAEP\s0 label to
|
|
\&\fBlabel\fR and its length to \fBlen\fR. If \fBlabel\fR is \s-1NULL\s0 or \fBlen\fR is 0,
|
|
the label is cleared. The library takes ownership of the label so the
|
|
caller should not free the original memory pointed to by \fBlabel\fR.
|
|
The padding mode must have been set to \fB\s-1RSA_PKCS1_OAEP_PADDING\s0\fR.
|
|
.PP
|
|
The \fBEVP_PKEY_CTX_get0_rsa_oaep_label()\fR macro gets the \s-1RSA OAEP\s0 label to
|
|
\&\fBlabel\fR. The return value is the label length. The padding mode
|
|
must have been set to \fB\s-1RSA_PKCS1_OAEP_PADDING\s0\fR. The resulting pointer is owned
|
|
by the library and should not be freed by the caller.
|
|
.SS "\s-1DSA\s0 parameters"
|
|
.IX Subsection "DSA parameters"
|
|
The \fBEVP_PKEY_CTX_set_dsa_paramgen_bits()\fR macro sets the number of bits used
|
|
for \s-1DSA\s0 parameter generation to \fBnbits\fR. If not specified, 1024 is used.
|
|
.PP
|
|
The \fBEVP_PKEY_CTX_set_dsa_paramgen_q_bits()\fR macro sets the number of bits in the
|
|
subprime parameter \fBq\fR for \s-1DSA\s0 parameter generation to \fBqbits\fR. If not
|
|
specified, 160 is used. If a digest function is specified below, this parameter
|
|
is ignored and instead, the number of bits in \fBq\fR matches the size of the
|
|
digest.
|
|
.PP
|
|
The \fBEVP_PKEY_CTX_set_dsa_paramgen_md()\fR macro sets the digest function used for
|
|
\&\s-1DSA\s0 parameter generation to \fBmd\fR. If not specified, one of \s-1SHA\-1, SHA\-224,\s0 or
|
|
\&\s-1SHA\-256\s0 is selected to match the bit length of \fBq\fR above.
|
|
.SS "\s-1DH\s0 parameters"
|
|
.IX Subsection "DH parameters"
|
|
The \fBEVP_PKEY_CTX_set_dh_paramgen_prime_len()\fR macro sets the length of the \s-1DH\s0
|
|
prime parameter \fBp\fR for \s-1DH\s0 parameter generation. If this macro is not called
|
|
then 1024 is used. Only accepts lengths greater than or equal to 256.
|
|
.PP
|
|
The \fBEVP_PKEY_CTX_set_dh_paramgen_subprime_len()\fR macro sets the length of the \s-1DH\s0
|
|
optional subprime parameter \fBq\fR for \s-1DH\s0 parameter generation. The default is
|
|
256 if the prime is at least 2048 bits long or 160 otherwise. The \s-1DH\s0
|
|
paramgen type must have been set to x9.42.
|
|
.PP
|
|
The \fBEVP_PKEY_CTX_set_dh_paramgen_generator()\fR macro sets \s-1DH\s0 generator to \fBgen\fR
|
|
for \s-1DH\s0 parameter generation. If not specified 2 is used.
|
|
.PP
|
|
The \fBEVP_PKEY_CTX_set_dh_paramgen_type()\fR macro sets the key type for \s-1DH\s0
|
|
parameter generation. Use 0 for PKCS#3 \s-1DH\s0 and 1 for X9.42 \s-1DH.\s0
|
|
The default is 0.
|
|
.PP
|
|
The \fBEVP_PKEY_CTX_set_dh_pad()\fR macro sets the \s-1DH\s0 padding mode. If \fBpad\fR is
|
|
1 the shared secret is padded with zeroes up to the size of the \s-1DH\s0 prime \fBp\fR.
|
|
If \fBpad\fR is zero (the default) then no padding is performed.
|
|
.PP
|
|
\&\fBEVP_PKEY_CTX_set_dh_nid()\fR sets the \s-1DH\s0 parameters to values corresponding to
|
|
\&\fBnid\fR as defined in \s-1RFC7919.\s0 The \fBnid\fR parameter must be \fBNID_ffdhe2048\fR,
|
|
\&\fBNID_ffdhe3072\fR, \fBNID_ffdhe4096\fR, \fBNID_ffdhe6144\fR, \fBNID_ffdhe8192\fR
|
|
or \fBNID_undef\fR to clear the stored value. This macro can be called during
|
|
parameter or key generation.
|
|
The nid parameter and the rfc5114 parameter are mutually exclusive.
|
|
.PP
|
|
The \fBEVP_PKEY_CTX_set_dh_rfc5114()\fR and \fBEVP_PKEY_CTX_set_dhx_rfc5114()\fR macros are
|
|
synonymous. They set the \s-1DH\s0 parameters to the values defined in \s-1RFC5114.\s0 The
|
|
\&\fBrfc5114\fR parameter must be 1, 2 or 3 corresponding to \s-1RFC5114\s0 sections
|
|
2.1, 2.2 and 2.3. or 0 to clear the stored value. This macro can be called
|
|
during parameter generation. The \fBctx\fR must have a key type of
|
|
\&\fB\s-1EVP_PKEY_DHX\s0\fR.
|
|
The rfc5114 parameter and the nid parameter are mutually exclusive.
|
|
.SS "\s-1DH\s0 key derivation function parameters"
|
|
.IX Subsection "DH key derivation function parameters"
|
|
Note that all of the following functions require that the \fBctx\fR parameter has
|
|
a private key type of \fB\s-1EVP_PKEY_DHX\s0\fR. When using key derivation, the output of
|
|
\&\fBEVP_PKEY_derive()\fR is the output of the \s-1KDF\s0 instead of the \s-1DH\s0 shared secret.
|
|
The \s-1KDF\s0 output is typically used as a Key Encryption Key (\s-1KEK\s0) that in turn
|
|
encrypts a Content Encryption Key (\s-1CEK\s0).
|
|
.PP
|
|
The \fBEVP_PKEY_CTX_set_dh_kdf_type()\fR macro sets the key derivation function type
|
|
to \fBkdf\fR for \s-1DH\s0 key derivation. Possible values are \fB\s-1EVP_PKEY_DH_KDF_NONE\s0\fR
|
|
and \fB\s-1EVP_PKEY_DH_KDF_X9_42\s0\fR which uses the key derivation specified in \s-1RFC2631\s0
|
|
(based on the keying algorithm described in X9.42). When using key derivation,
|
|
the \fBkdf_oid\fR, \fBkdf_md\fR and \fBkdf_outlen\fR parameters must also be specified.
|
|
.PP
|
|
The \fBEVP_PKEY_CTX_get_dh_kdf_type()\fR macro gets the key derivation function type
|
|
for \fBctx\fR used for \s-1DH\s0 key derivation. Possible values are \fB\s-1EVP_PKEY_DH_KDF_NONE\s0\fR
|
|
and \fB\s-1EVP_PKEY_DH_KDF_X9_42\s0\fR.
|
|
.PP
|
|
The \fBEVP_PKEY_CTX_set0_dh_kdf_oid()\fR macro sets the key derivation function
|
|
object identifier to \fBoid\fR for \s-1DH\s0 key derivation. This \s-1OID\s0 should identify
|
|
the algorithm to be used with the Content Encryption Key.
|
|
The library takes ownership of the object identifier so the caller should not
|
|
free the original memory pointed to by \fBoid\fR.
|
|
.PP
|
|
The \fBEVP_PKEY_CTX_get0_dh_kdf_oid()\fR macro gets the key derivation function oid
|
|
for \fBctx\fR used for \s-1DH\s0 key derivation. The resulting pointer is owned by the
|
|
library and should not be freed by the caller.
|
|
.PP
|
|
The \fBEVP_PKEY_CTX_set_dh_kdf_md()\fR macro sets the key derivation function
|
|
message digest to \fBmd\fR for \s-1DH\s0 key derivation. Note that \s-1RFC2631\s0 specifies
|
|
that this digest should be \s-1SHA1\s0 but OpenSSL tolerates other digests.
|
|
.PP
|
|
The \fBEVP_PKEY_CTX_get_dh_kdf_md()\fR macro gets the key derivation function
|
|
message digest for \fBctx\fR used for \s-1DH\s0 key derivation.
|
|
.PP
|
|
The \fBEVP_PKEY_CTX_set_dh_kdf_outlen()\fR macro sets the key derivation function
|
|
output length to \fBlen\fR for \s-1DH\s0 key derivation.
|
|
.PP
|
|
The \fBEVP_PKEY_CTX_get_dh_kdf_outlen()\fR macro gets the key derivation function
|
|
output length for \fBctx\fR used for \s-1DH\s0 key derivation.
|
|
.PP
|
|
The \fBEVP_PKEY_CTX_set0_dh_kdf_ukm()\fR macro sets the user key material to
|
|
\&\fBukm\fR and its length to \fBlen\fR for \s-1DH\s0 key derivation. This parameter is optional
|
|
and corresponds to the partyAInfo field in \s-1RFC2631\s0 terms. The specification
|
|
requires that it is 512 bits long but this is not enforced by OpenSSL.
|
|
The library takes ownership of the user key material so the caller should not
|
|
free the original memory pointed to by \fBukm\fR.
|
|
.PP
|
|
The \fBEVP_PKEY_CTX_get0_dh_kdf_ukm()\fR macro gets the user key material for \fBctx\fR.
|
|
The return value is the user key material length. The resulting pointer is owned
|
|
by the library and should not be freed by the caller.
|
|
.SS "\s-1EC\s0 parameters"
|
|
.IX Subsection "EC parameters"
|
|
The \fBEVP_PKEY_CTX_set_ec_paramgen_curve_nid()\fR sets the \s-1EC\s0 curve for \s-1EC\s0 parameter
|
|
generation to \fBnid\fR. For \s-1EC\s0 parameter generation this macro must be called
|
|
or an error occurs because there is no default curve.
|
|
This function can also be called to set the curve explicitly when
|
|
generating an \s-1EC\s0 key.
|
|
.PP
|
|
The \fBEVP_PKEY_CTX_set_ec_param_enc()\fR macro sets the \s-1EC\s0 parameter encoding to
|
|
\&\fBparam_enc\fR when generating \s-1EC\s0 parameters or an \s-1EC\s0 key. The encoding can be
|
|
\&\fB\s-1OPENSSL_EC_EXPLICIT_CURVE\s0\fR for explicit parameters (the default in versions
|
|
of OpenSSL before 1.1.0) or \fB\s-1OPENSSL_EC_NAMED_CURVE\s0\fR to use named curve form.
|
|
For maximum compatibility the named curve form should be used. Note: the
|
|
\&\fB\s-1OPENSSL_EC_NAMED_CURVE\s0\fR value was added in OpenSSL 1.1.0; previous
|
|
versions should use 0 instead.
|
|
.SS "\s-1ECDH\s0 parameters"
|
|
.IX Subsection "ECDH parameters"
|
|
The \fBEVP_PKEY_CTX_set_ecdh_cofactor_mode()\fR macro sets the cofactor mode to
|
|
\&\fBcofactor_mode\fR for \s-1ECDH\s0 key derivation. Possible values are 1 to enable
|
|
cofactor key derivation, 0 to disable it and \-1 to clear the stored cofactor
|
|
mode and fallback to the private key cofactor mode.
|
|
.PP
|
|
The \fBEVP_PKEY_CTX_get_ecdh_cofactor_mode()\fR macro returns the cofactor mode for
|
|
\&\fBctx\fR used for \s-1ECDH\s0 key derivation. Possible values are 1 when cofactor key
|
|
derivation is enabled and 0 otherwise.
|
|
.SS "\s-1ECDH\s0 key derivation function parameters"
|
|
.IX Subsection "ECDH key derivation function parameters"
|
|
The \fBEVP_PKEY_CTX_set_ecdh_kdf_type()\fR macro sets the key derivation function type
|
|
to \fBkdf\fR for \s-1ECDH\s0 key derivation. Possible values are \fB\s-1EVP_PKEY_ECDH_KDF_NONE\s0\fR
|
|
and \fB\s-1EVP_PKEY_ECDH_KDF_X9_63\s0\fR which uses the key derivation specified in X9.63.
|
|
When using key derivation, the \fBkdf_md\fR and \fBkdf_outlen\fR parameters must
|
|
also be specified.
|
|
.PP
|
|
The \fBEVP_PKEY_CTX_get_ecdh_kdf_type()\fR macro returns the key derivation function
|
|
type for \fBctx\fR used for \s-1ECDH\s0 key derivation. Possible values are
|
|
\&\fB\s-1EVP_PKEY_ECDH_KDF_NONE\s0\fR and \fB\s-1EVP_PKEY_ECDH_KDF_X9_63\s0\fR.
|
|
.PP
|
|
The \fBEVP_PKEY_CTX_set_ecdh_kdf_md()\fR macro sets the key derivation function
|
|
message digest to \fBmd\fR for \s-1ECDH\s0 key derivation. Note that X9.63 specifies
|
|
that this digest should be \s-1SHA1\s0 but OpenSSL tolerates other digests.
|
|
.PP
|
|
The \fBEVP_PKEY_CTX_get_ecdh_kdf_md()\fR macro gets the key derivation function
|
|
message digest for \fBctx\fR used for \s-1ECDH\s0 key derivation.
|
|
.PP
|
|
The \fBEVP_PKEY_CTX_set_ecdh_kdf_outlen()\fR macro sets the key derivation function
|
|
output length to \fBlen\fR for \s-1ECDH\s0 key derivation.
|
|
.PP
|
|
The \fBEVP_PKEY_CTX_get_ecdh_kdf_outlen()\fR macro gets the key derivation function
|
|
output length for \fBctx\fR used for \s-1ECDH\s0 key derivation.
|
|
.PP
|
|
The \fBEVP_PKEY_CTX_set0_ecdh_kdf_ukm()\fR macro sets the user key material to \fBukm\fR
|
|
for \s-1ECDH\s0 key derivation. This parameter is optional and corresponds to the
|
|
shared info in X9.63 terms. The library takes ownership of the user key material
|
|
so the caller should not free the original memory pointed to by \fBukm\fR.
|
|
.PP
|
|
The \fBEVP_PKEY_CTX_get0_ecdh_kdf_ukm()\fR macro gets the user key material for \fBctx\fR.
|
|
The return value is the user key material length. The resulting pointer is owned
|
|
by the library and should not be freed by the caller.
|
|
.SS "Other parameters"
|
|
.IX Subsection "Other parameters"
|
|
The \fBEVP_PKEY_CTX_set1_id()\fR, \fBEVP_PKEY_CTX_get1_id()\fR and \fBEVP_PKEY_CTX_get1_id_len()\fR
|
|
macros are used to manipulate the special identifier field for specific signature
|
|
algorithms such as \s-1SM2.\s0 The \fBEVP_PKEY_CTX_set1_id()\fR sets an \s-1ID\s0 pointed by \fBid\fR with
|
|
the length \fBid_len\fR to the library. The library takes a copy of the id so that
|
|
the caller can safely free the original memory pointed to by \fBid\fR. The
|
|
\&\fBEVP_PKEY_CTX_get1_id_len()\fR macro returns the length of the \s-1ID\s0 set via a previous
|
|
call to \fBEVP_PKEY_CTX_set1_id()\fR. The length is usually used to allocate adequate
|
|
memory for further calls to \fBEVP_PKEY_CTX_get1_id()\fR. The \fBEVP_PKEY_CTX_get1_id()\fR
|
|
macro returns the previously set \s-1ID\s0 value to caller in \fBid\fR. The caller should
|
|
allocate adequate memory space for the \fBid\fR before calling \fBEVP_PKEY_CTX_get1_id()\fR.
|
|
.SH "RETURN VALUES"
|
|
.IX Header "RETURN VALUES"
|
|
\&\fBEVP_PKEY_CTX_ctrl()\fR and its macros return a positive value for success and 0
|
|
or a negative value for failure. In particular a return value of \-2
|
|
indicates the operation is not supported by the public key algorithm.
|
|
.SH "SEE ALSO"
|
|
.IX Header "SEE ALSO"
|
|
\&\fBEVP_PKEY_CTX_new\fR\|(3),
|
|
\&\fBEVP_PKEY_encrypt\fR\|(3),
|
|
\&\fBEVP_PKEY_decrypt\fR\|(3),
|
|
\&\fBEVP_PKEY_sign\fR\|(3),
|
|
\&\fBEVP_PKEY_verify\fR\|(3),
|
|
\&\fBEVP_PKEY_verify_recover\fR\|(3),
|
|
\&\fBEVP_PKEY_derive\fR\|(3),
|
|
\&\fBEVP_PKEY_keygen\fR\|(3)
|
|
.SH "HISTORY"
|
|
.IX Header "HISTORY"
|
|
The
|
|
\&\fBEVP_PKEY_CTX_set1_id()\fR, \fBEVP_PKEY_CTX_get1_id()\fR and \fBEVP_PKEY_CTX_get1_id_len()\fR
|
|
macros were added in 1.1.1, other functions were added in OpenSSL 1.0.0.
|
|
.SH "COPYRIGHT"
|
|
.IX Header "COPYRIGHT"
|
|
Copyright 2006\-2018 The OpenSSL Project Authors. All Rights Reserved.
|
|
.PP
|
|
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
|
|
this file except in compliance with the License. You can obtain a copy
|
|
in the file \s-1LICENSE\s0 in the source distribution or at
|
|
<https://www.openssl.org/source/license.html>.
|