]>
Commit | Line | Data |
---|---|---|
90ccf05f DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | EVP_PKEY_ctrl, EVP_PKEY_ctrl_str - algorithm specific control operations | |
6 | ||
7 | =head1 SYNOPSIS | |
8 | ||
9 | #include <openssl/evp.h> | |
10 | ||
11 | int EVP_PKEY_CTX_ctrl(EVP_PKEY_CTX *ctx, int keytype, int optype, | |
12 | int cmd, int p1, void *p2); | |
13 | int EVP_PKEY_CTX_ctrl_str(EVP_PKEY_CTX *ctx, const char *type, | |
14 | const char *value); | |
15 | ||
16 | int EVP_PKEY_get_default_digest_nid(EVP_PKEY *pkey, int *pnid); | |
17 | ||
18 | #include <openssl/rsa.h> | |
19 | ||
20 | int EVP_PKEY_CTX_set_signature_md(EVP_PKEY_CTX *ctx, const EVP_MD *md); | |
21 | ||
22 | int EVP_PKEY_CTX_set_rsa_padding(EVP_PKEY_CTX *ctx, int pad); | |
23 | int EVP_PKEY_CTX_set_rsa_pss_saltlen(EVP_PKEY_CTX *ctx, int len); | |
24 | int EVP_PKEY_CTX_set_rsa_rsa_keygen_bits(EVP_PKEY_CTX *ctx, int mbits); | |
25 | int EVP_PKEY_CTX_set_rsa_keygen_pubexp(EVP_PKEY_CTX *ctx, BIGNUM *pubexp); | |
26 | ||
27 | #include <openssl/dsa.h> | |
28 | int EVP_PKEY_CTX_set_dsa_paramgen_bits(EVP_PKEY_CTX *ctx, int nbits); | |
29 | ||
30 | #include <openssl/dh.h> | |
31 | int EVP_PKEY_CTX_set_dh_paramgen_prime_len(EVP_PKEY_CTX *ctx, int len); | |
32 | int EVP_PKEY_CTX_set_dh_paramgen_generator(EVP_PKEY_CTX *ctx, int gen); | |
33 | ||
34 | #include <openssl/ec.h> | |
35 | int EVP_PKEY_CTX_set_ec_paramgen_curve_nid(EVP_PKEY_CTX *ctx, int nid); | |
36 | ||
37 | =head1 DESCRIPTION | |
38 | ||
39 | The function EVP_PKEY_CTX_ctrl() sends a control operation to the context | |
40 | B<ctx>. The key type used must match B<keytype> if it is not zero. The parameter | |
41 | B<optype> is a mask indicating which operations the control can be applied to. | |
42 | The control command is indicated in B<cmd> and any additional arguments in | |
43 | B<p1> and B<p2>. | |
44 | ||
45 | Applications will not normally call EVP_PKEY_CTX_ctrl() directly but will | |
46 | instead call one of the algorithm specific macros below. | |
47 | ||
48 | The function EVP_PKEY_ctrl_str() allows an application to send an algorithm | |
49 | specific control operation to a context B<ctx> in string form. This is | |
50 | intended to be used for options specified on the command line or in text | |
51 | files. The commands supported are documented in the openssl utility | |
52 | command line pages for the option B<-pkeyopt> which is supported by the | |
53 | B<pkeyutl>, B<genpkey> and B<req> commands. | |
54 | ||
55 | All the remaining "functions" are implemented as macros. | |
56 | ||
57 | The EVP_PKEY_CTX_set_signature_md() macro sets the message digest type used | |
58 | in a signature. It can be used with any public key algorithm supporting | |
59 | signature operations. | |
60 | ||
61 | The macro EVP_PKEY_CTX_set_rsa_padding() sets the RSA padding mode for B<ctx>. | |
62 | The B<pad> parameter can take the value RSA_PKCS1_PADDING for PKCS#1 padding, | |
63 | RSA_SSLV23_PADDING for SSLv23 padding, RSA_NO_PADDING for no padding, | |
64 | RSA_PKCS1_OAEP_PADDING for OAEP padding (encrypt and decrypt only), | |
65 | RSA_X931_PADDING for X9.31 padding (signature operations only) and | |
66 | RSA_PKCS1_PSS_PADDING (sign and verify only). | |
67 | ||
68 | Two RSA padding modes behave differently if EVP_PKEY_CTX_set_signature_md() | |
69 | is used. If this macro is called for PKCS#1 padding the plaintext buffer is | |
70 | an actual digest value and is encapsulated in a DigestInfo structure according | |
71 | to PKCS#1 when signing and this structure is expected (and stripped off) when | |
72 | verifying. If this control is not used with RSA and PKCS#1 padding then the | |
73 | supplied data is used directly and not encapsulated. In the case of X9.31 | |
74 | padding for RSA the algorithm identifier byte is added or checked and removed | |
75 | 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. | |
76 | ||
77 | The EVP_PKEY_CTX_set_rsa_pss_saltlen() macro sets the RSA PSS salt length to | |
78 | B<len> as its name implies it is only supported for PSS padding. Two special | |
79 | values are supported: -1 sets the salt length to the digest length. When | |
80 | signing -2 sets the salt length to the maximum permissible value. When | |
81 | verifying -2 causes the salt length to be automatically determined based on the | |
82 | B<PSS> block structure. If this macro is not called a salt length value of -2 | |
83 | is used by default. | |
84 | ||
85 | The EVP_PKEY_CTX_set_rsa_rsa_keygen_bits() macro sets the RSA key length for | |
86 | RSA key genration to B<bits>. If not specified 1024 bits is used. | |
87 | ||
88 | The EVP_PKEY_CTX_set_rsa_keygen_pubexp() macro sets the public exponent value | |
89 | for RSA key generation to B<pubexp> currently it should be an odd integer. The | |
90 | B<pubexp> pointer is used internally by this function so it should not be | |
91 | modified or free after the call. If this macro is not called then 65537 is used. | |
92 | ||
93 | The macro EVP_PKEY_CTX_set_dsa_paramgen_bits() sets the number of bits used | |
94 | for DSA parameter generation to B<bits>. If not specified 1024 is used. | |
95 | ||
96 | The macro EVP_PKEY_CTX_set_dh_paramgen_prime_len() sets the length of the DH | |
97 | prime parameter B<p> for DH parameter generation. If this macro is not called | |
98 | then 1024 is used. | |
99 | ||
100 | The EVP_PKEY_CTX_set_dh_paramgen_generator() macro sets DH generator to B<gen> | |
101 | for DH parameter generation. If not specified 2 is used. | |
102 | ||
103 | The EVP_PKEY_CTX_set_ec_paramgen_curve_nid() sets the EC curve for EC parameter | |
104 | generation to B<nid>. For EC parameter generation this macro must be called | |
105 | or an error occurs because there is no default curve. | |
106 | ||
107 | =head1 RETURN VALUES | |
108 | ||
109 | EVP_PKEY_CTX_ctrl() and its macros return a positive value for success and 0 | |
110 | or a negative value for failure. In particular a return value of -2 | |
111 | indicates the operation is not supported by the public key algorithm. | |
112 | ||
113 | =head1 SEE ALSO | |
114 | ||
115 | L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>, | |
116 | L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>, | |
117 | L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>, | |
118 | L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>, | |
119 | L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>, | |
120 | L<EVP_PKEY_verifyrecover(3)|EVP_PKEY_verifyrecover(3)>, | |
121 | L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)> | |
122 | L<EVP_PKEY_keygen(3)|EVP_PKEY_keygen(3)> | |
123 | ||
124 | =head1 HISTORY | |
125 | ||
126 | These functions were first added to OpenSSL 0.9.9. | |
127 | ||
128 | =cut |