From: Dr. Stephen Henson Date: Sun, 9 Jul 2006 10:51:03 +0000 (+0000) Subject: EVP_PKEY_CTX_ctrl() docs. X-Git-Tag: OpenSSL_0_9_8k^2~1211 X-Git-Url: https://git.openssl.org/gitweb/?p=openssl.git;a=commitdiff_plain;h=90ccf05f8276a6e289d8b49002d7ed470bf5d517 EVP_PKEY_CTX_ctrl() docs. --- diff --git a/doc/crypto/EVP_PKEY_CTX_ctrl.pod b/doc/crypto/EVP_PKEY_CTX_ctrl.pod new file mode 100644 index 0000000000..6deccfbf95 --- /dev/null +++ b/doc/crypto/EVP_PKEY_CTX_ctrl.pod @@ -0,0 +1,128 @@ +=pod + +=head1 NAME + +EVP_PKEY_ctrl, EVP_PKEY_ctrl_str - algorithm specific control operations + +=head1 SYNOPSIS + + #include + + int EVP_PKEY_CTX_ctrl(EVP_PKEY_CTX *ctx, int keytype, int optype, + int cmd, int p1, void *p2); + int EVP_PKEY_CTX_ctrl_str(EVP_PKEY_CTX *ctx, const char *type, + const char *value); + + int EVP_PKEY_get_default_digest_nid(EVP_PKEY *pkey, int *pnid); + + #include + + int EVP_PKEY_CTX_set_signature_md(EVP_PKEY_CTX *ctx, const EVP_MD *md); + + int EVP_PKEY_CTX_set_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_set_rsa_rsa_keygen_bits(EVP_PKEY_CTX *ctx, int mbits); + int EVP_PKEY_CTX_set_rsa_keygen_pubexp(EVP_PKEY_CTX *ctx, BIGNUM *pubexp); + + #include + int EVP_PKEY_CTX_set_dsa_paramgen_bits(EVP_PKEY_CTX *ctx, int nbits); + + #include + int EVP_PKEY_CTX_set_dh_paramgen_prime_len(EVP_PKEY_CTX *ctx, int len); + int EVP_PKEY_CTX_set_dh_paramgen_generator(EVP_PKEY_CTX *ctx, int gen); + + #include + int EVP_PKEY_CTX_set_ec_paramgen_curve_nid(EVP_PKEY_CTX *ctx, int nid); + +=head1 DESCRIPTION + +The function EVP_PKEY_CTX_ctrl() sends a control operation to the context +B. The key type used must match B if it is not zero. The parameter +B is a mask indicating which operations the control can be applied to. +The control command is indicated in B and any additional arguments in +B and B. + +Applications will not normally call EVP_PKEY_CTX_ctrl() directly but will +instead call one of the algorithm specific macros below. + +The function EVP_PKEY_ctrl_str() allows an application to send an algorithm +specific control operation to a context B 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 B<-pkeyopt> which is supported by the +B, B and B commands. + +All the remaining "functions" are implemented as macros. + +The EVP_PKEY_CTX_set_signature_md() macro sets the message digest type used +in a signature. It can be used with any public key algorithm supporting +signature operations. + +The macro EVP_PKEY_CTX_set_rsa_padding() sets the RSA padding mode for B. +The B parameter can take the value RSA_PKCS1_PADDING for PKCS#1 padding, +RSA_SSLV23_PADDING for SSLv23 padding, RSA_NO_PADDING for no padding, +RSA_PKCS1_OAEP_PADDING for OAEP padding (encrypt and decrypt only), +RSA_X931_PADDING for X9.31 padding (signature operations only) and +RSA_PKCS1_PSS_PADDING (sign and verify only). + +Two RSA padding modes behave differently if EVP_PKEY_CTX_set_signature_md() +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 RSA and PKCS#1 padding then the +supplied data is used directly and not encapsulated. In the case of X9.31 +padding for RSA 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. + +The EVP_PKEY_CTX_set_rsa_pss_saltlen() macro sets the RSA PSS salt length to +B as its name implies it is only supported for PSS padding. Two special +values are supported: -1 sets the salt length to the digest length. When +signing -2 sets the salt length to the maximum permissible value. When +verifying -2 causes the salt length to be automatically determined based on the +B block structure. If this macro is not called a salt length value of -2 +is used by default. + +The EVP_PKEY_CTX_set_rsa_rsa_keygen_bits() macro sets the RSA key length for +RSA key genration to B. If not specified 1024 bits is used. + +The EVP_PKEY_CTX_set_rsa_keygen_pubexp() macro sets the public exponent value +for RSA key generation to B currently it should be an odd integer. The +B pointer is used internally by this function so it should not be +modified or free after the call. If this macro is not called then 65537 is used. + +The macro EVP_PKEY_CTX_set_dsa_paramgen_bits() sets the number of bits used +for DSA parameter generation to B. If not specified 1024 is used. + +The macro EVP_PKEY_CTX_set_dh_paramgen_prime_len() sets the length of the DH +prime parameter B

for DH parameter generation. If this macro is not called +then 1024 is used. + +The EVP_PKEY_CTX_set_dh_paramgen_generator() macro sets DH generator to B +for DH parameter generation. If not specified 2 is used. + +The EVP_PKEY_CTX_set_ec_paramgen_curve_nid() sets the EC curve for EC parameter +generation to B. For EC parameter generation this macro must be called +or an error occurs because there is no default curve. + +=head1 RETURN VALUES + +EVP_PKEY_CTX_ctrl() 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. + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L, +L +L + +=head1 HISTORY + +These functions were first added to OpenSSL 0.9.9. + +=cut