OLD | NEW |
(Empty) | |
| 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 -1. 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 plaint
ext 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 1.0.0. |
| 127 |
| 128 =cut |
OLD | NEW |