]>
Commit | Line | Data |
---|---|---|
90ccf05f DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
d45a97f4 MC |
5 | EVP_PKEY_CTX_ctrl, |
6 | EVP_PKEY_CTX_ctrl_str, | |
7 | EVP_PKEY_CTX_set_signature_md, | |
8 | EVP_PKEY_CTX_get_signature_md, | |
9 | EVP_PKEY_CTX_set_mac_key, | |
10 | EVP_PKEY_CTX_set_rsa_padding, | |
11 | EVP_PKEY_CTX_set_rsa_pss_saltlen, | |
12 | EVP_PKEY_CTX_set_rsa_keygen_bits, | |
13 | EVP_PKEY_CTX_set_rsa_keygen_pubexp, | |
14 | EVP_PKEY_CTX_set_dsa_paramgen_bits, | |
aafbe1cc MC |
15 | EVP_PKEY_CTX_set_dh_paramgen_prime_len, |
16 | EVP_PKEY_CTX_set_dh_paramgen_generator, | |
d45a97f4 MC |
17 | EVP_PKEY_CTX_set_dh_pad, |
18 | EVP_PKEY_CTX_set_dh_nid, | |
146ca72c DSH |
19 | EVP_PKEY_CTX_set_ec_paramgen_curve_nid, |
20 | EVP_PKEY_CTX_set_ec_param_enc - algorithm specific control operations | |
90ccf05f DSH |
21 | |
22 | =head1 SYNOPSIS | |
23 | ||
24 | #include <openssl/evp.h> | |
25 | ||
26 | int EVP_PKEY_CTX_ctrl(EVP_PKEY_CTX *ctx, int keytype, int optype, | |
e9b77246 | 27 | int cmd, int p1, void *p2); |
90ccf05f | 28 | int EVP_PKEY_CTX_ctrl_str(EVP_PKEY_CTX *ctx, const char *type, |
e9b77246 | 29 | const char *value); |
90ccf05f | 30 | |
90ccf05f | 31 | int EVP_PKEY_CTX_set_signature_md(EVP_PKEY_CTX *ctx, const EVP_MD *md); |
d45a97f4 MC |
32 | int EVP_PKEY_CTX_get_signature_md(EVP_PKEY_CTX *ctx, const EVP_MD **pmd); |
33 | ||
34 | int EVP_PKEY_CTX_set_mac_key(EVP_PKEY_CTX *ctx, unsigned char *key, int len); | |
35 | ||
36 | #include <openssl/rsa.h> | |
90ccf05f DSH |
37 | |
38 | int EVP_PKEY_CTX_set_rsa_padding(EVP_PKEY_CTX *ctx, int pad); | |
39 | int EVP_PKEY_CTX_set_rsa_pss_saltlen(EVP_PKEY_CTX *ctx, int len); | |
1722496f | 40 | int EVP_PKEY_CTX_set_rsa_keygen_bits(EVP_PKEY_CTX *ctx, int mbits); |
90ccf05f DSH |
41 | int EVP_PKEY_CTX_set_rsa_keygen_pubexp(EVP_PKEY_CTX *ctx, BIGNUM *pubexp); |
42 | ||
43 | #include <openssl/dsa.h> | |
44 | int EVP_PKEY_CTX_set_dsa_paramgen_bits(EVP_PKEY_CTX *ctx, int nbits); | |
45 | ||
46 | #include <openssl/dh.h> | |
47 | int EVP_PKEY_CTX_set_dh_paramgen_prime_len(EVP_PKEY_CTX *ctx, int len); | |
48 | int EVP_PKEY_CTX_set_dh_paramgen_generator(EVP_PKEY_CTX *ctx, int gen); | |
5368bf05 DSH |
49 | int EVP_PKEY_CTX_set_dh_pad(EVP_PKEY_CTX *ctx, int pad); |
50 | int EVP_PKEY_CTX_set_dh_nid(EVP_PKEY_CTX *ctx, int nid); | |
90ccf05f DSH |
51 | |
52 | #include <openssl/ec.h> | |
53 | int EVP_PKEY_CTX_set_ec_paramgen_curve_nid(EVP_PKEY_CTX *ctx, int nid); | |
146ca72c | 54 | int EVP_PKEY_CTX_set_ec_param_enc(EVP_PKEY_CTX *ctx, int param_enc); |
90ccf05f DSH |
55 | |
56 | =head1 DESCRIPTION | |
57 | ||
58 | The function EVP_PKEY_CTX_ctrl() sends a control operation to the context | |
f0288f05 | 59 | B<ctx>. The key type used must match B<keytype> if it is not -1. The parameter |
90ccf05f DSH |
60 | B<optype> is a mask indicating which operations the control can be applied to. |
61 | The control command is indicated in B<cmd> and any additional arguments in | |
62 | B<p1> and B<p2>. | |
63 | ||
52ad5b60 | 64 | For B<cmd> = B<EVP_PKEY_CTRL_SET_MAC_KEY>, B<p1> is the length of the MAC key, |
3f5616d7 | 65 | and B<p2> is MAC key. This is used by Poly1305, SipHash, HMAC and CMAC. |
52ad5b60 | 66 | |
90ccf05f DSH |
67 | Applications will not normally call EVP_PKEY_CTX_ctrl() directly but will |
68 | instead call one of the algorithm specific macros below. | |
69 | ||
aafbe1cc | 70 | The function EVP_PKEY_CTX_ctrl_str() allows an application to send an algorithm |
90ccf05f DSH |
71 | specific control operation to a context B<ctx> in string form. This is |
72 | intended to be used for options specified on the command line or in text | |
73 | files. The commands supported are documented in the openssl utility | |
74 | command line pages for the option B<-pkeyopt> which is supported by the | |
75 | B<pkeyutl>, B<genpkey> and B<req> commands. | |
76 | ||
77 | All the remaining "functions" are implemented as macros. | |
78 | ||
79 | The EVP_PKEY_CTX_set_signature_md() macro sets the message digest type used | |
d45a97f4 MC |
80 | in a signature. It can be used in the RSA, DSA and ECDSA algorithms. |
81 | ||
82 | The EVP_PKEY_CTX_get_signature_md() macro gets the message digest type used in a | |
83 | signature. It can be used in the RSA, DSA and ECDSA algorithms. | |
84 | ||
85 | Key generation typically involves setting up parameters to be used and | |
86 | generating the private and public key data. Some algorithm implementations | |
87 | allow private key data to be set explicitly using the EVP_PKEY_CTX_set_mac_key() | |
88 | macro. In this case key generation is simply the process of setting up the | |
89 | parameters for the key and then setting the raw key data to the value explicitly | |
90 | provided by that macro. Normally applications would call | |
f929439f | 91 | L<EVP_PKEY_new_raw_private_key(3)> or similar functions instead of this macro. |
d45a97f4 MC |
92 | |
93 | The EVP_PKEY_CTX_set_mac_key() macro can be used with any of the algorithms | |
f929439f | 94 | supported by the L<EVP_PKEY_new_raw_private_key(3)> function. |
90ccf05f DSH |
95 | |
96 | The macro EVP_PKEY_CTX_set_rsa_padding() sets the RSA padding mode for B<ctx>. | |
97 | The B<pad> parameter can take the value RSA_PKCS1_PADDING for PKCS#1 padding, | |
98 | RSA_SSLV23_PADDING for SSLv23 padding, RSA_NO_PADDING for no padding, | |
99 | RSA_PKCS1_OAEP_PADDING for OAEP padding (encrypt and decrypt only), | |
146ca72c | 100 | RSA_X931_PADDING for X9.31 padding (signature operations only) and |
90ccf05f DSH |
101 | RSA_PKCS1_PSS_PADDING (sign and verify only). |
102 | ||
103 | Two RSA padding modes behave differently if EVP_PKEY_CTX_set_signature_md() | |
104 | is used. If this macro is called for PKCS#1 padding the plaintext buffer is | |
105 | an actual digest value and is encapsulated in a DigestInfo structure according | |
106 | to PKCS#1 when signing and this structure is expected (and stripped off) when | |
107 | verifying. If this control is not used with RSA and PKCS#1 padding then the | |
108 | supplied data is used directly and not encapsulated. In the case of X9.31 | |
109 | padding for RSA the algorithm identifier byte is added or checked and removed | |
9d22666e F |
110 | if this control is called. If it is not called then the first byte of the plaintext |
111 | buffer is expected to be the algorithm identifier byte. | |
90ccf05f DSH |
112 | |
113 | The EVP_PKEY_CTX_set_rsa_pss_saltlen() macro sets the RSA PSS salt length to | |
137096a7 DSH |
114 | B<len> as its name implies it is only supported for PSS padding. Three special |
115 | values are supported: RSA_PSS_SALTLEN_DIGEST sets the salt length to the | |
116 | digest length, RSA_PSS_SALTLEN_MAX sets the salt length to the maximum | |
117 | permissible value. When verifying RSA_PSS_SALTLEN_AUTO causes the salt length | |
118 | to be automatically determined based on the B<PSS> block structure. If this | |
119 | macro is not called maximum salt length is used when signing and auto detection | |
120 | when verifying is used by default. | |
90ccf05f | 121 | |
1722496f | 122 | The EVP_PKEY_CTX_set_rsa_keygen_bits() macro sets the RSA key length for |
186bb907 | 123 | RSA key generation to B<bits>. If not specified 1024 bits is used. |
90ccf05f DSH |
124 | |
125 | The EVP_PKEY_CTX_set_rsa_keygen_pubexp() macro sets the public exponent value | |
126 | for RSA key generation to B<pubexp> currently it should be an odd integer. The | |
146ca72c | 127 | B<pubexp> pointer is used internally by this function so it should not be |
90ccf05f DSH |
128 | modified or free after the call. If this macro is not called then 65537 is used. |
129 | ||
130 | The macro EVP_PKEY_CTX_set_dsa_paramgen_bits() sets the number of bits used | |
131 | for DSA parameter generation to B<bits>. If not specified 1024 is used. | |
132 | ||
133 | The macro EVP_PKEY_CTX_set_dh_paramgen_prime_len() sets the length of the DH | |
134 | prime parameter B<p> for DH parameter generation. If this macro is not called | |
135 | then 1024 is used. | |
136 | ||
137 | The EVP_PKEY_CTX_set_dh_paramgen_generator() macro sets DH generator to B<gen> | |
138 | for DH parameter generation. If not specified 2 is used. | |
139 | ||
5368bf05 DSH |
140 | The EVP_PKEY_CTX_set_dh_pad() macro sets the DH padding mode. If B<pad> is |
141 | 1 the shared secret is padded with zeroes up to the size of the DH prime B<p>. | |
142 | If B<pad> is zero (the default) then no padding is performed. | |
143 | ||
144 | EVP_PKEY_CTX_set_dh_nid() sets the DH parameters to values corresponding to | |
145 | B<nid>. The B<nid> parameter must be B<NID_ffdhe2048>, B<NID_ffdhe3072>, | |
146 | B<NID_ffdhe4096>, B<NID_ffdhe6144> or B<NID_ffdhe8192>. This macro can be | |
147 | called during parameter or key generation. | |
148 | ||
90ccf05f DSH |
149 | The EVP_PKEY_CTX_set_ec_paramgen_curve_nid() sets the EC curve for EC parameter |
150 | generation to B<nid>. For EC parameter generation this macro must be called | |
a528d4f0 RS |
151 | or an error occurs because there is no default curve. |
152 | This function can also be called to set the curve explicitly when | |
146ca72c DSH |
153 | generating an EC key. |
154 | ||
155 | The EVP_PKEY_CTX_set_ec_param_enc() sets the EC parameter encoding to | |
156 | B<param_enc> when generating EC parameters or an EC key. The encoding can be | |
157 | B<OPENSSL_EC_EXPLICIT_CURVE> for explicit parameters (the default in versions | |
158 | of OpenSSL before 1.1.0) or B<OPENSSL_EC_NAMED_CURVE> to use named curve form. | |
159 | For maximum compatibility the named curve form should be used. Note: the | |
a528d4f0 | 160 | B<OPENSSL_EC_NAMED_CURVE> value was only added to OpenSSL 1.1.0; previous |
146ca72c | 161 | versions should use 0 instead. |
90ccf05f DSH |
162 | |
163 | =head1 RETURN VALUES | |
164 | ||
165 | EVP_PKEY_CTX_ctrl() and its macros return a positive value for success and 0 | |
166 | or a negative value for failure. In particular a return value of -2 | |
167 | indicates the operation is not supported by the public key algorithm. | |
168 | ||
169 | =head1 SEE ALSO | |
170 | ||
9b86974e RS |
171 | L<EVP_PKEY_CTX_new(3)>, |
172 | L<EVP_PKEY_encrypt(3)>, | |
173 | L<EVP_PKEY_decrypt(3)>, | |
174 | L<EVP_PKEY_sign(3)>, | |
175 | L<EVP_PKEY_verify(3)>, | |
176 | L<EVP_PKEY_verify_recover(3)>, | |
177 | L<EVP_PKEY_derive(3)> | |
178 | L<EVP_PKEY_keygen(3)> | |
90ccf05f DSH |
179 | |
180 | =head1 HISTORY | |
181 | ||
fb552ac6 | 182 | These functions were first added to OpenSSL 1.0.0. |
90ccf05f | 183 | |
e2f92610 RS |
184 | =head1 COPYRIGHT |
185 | ||
b0edda11 | 186 | Copyright 2006-2018 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 RS |
187 | |
188 | Licensed under the OpenSSL license (the "License"). You may not use | |
189 | this file except in compliance with the License. You can obtain a copy | |
190 | in the file LICENSE in the source distribution or at | |
191 | L<https://www.openssl.org/source/license.html>. | |
192 | ||
193 | =cut |