X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=doc%2Fman3%2FEVP_PKEY_CTX_ctrl.pod;h=18b984162e5709dbaeacc57595ae092b00315462;hb=9c45222ddc36124b8826d98dc0794f3eef1e5f0b;hp=9d1812f6bd65a38e7855a7433d5bd8edd8342ed8;hpb=21fb7067228e39633755aeba251e925634e64870;p=oweals%2Fopenssl.git diff --git a/doc/man3/EVP_PKEY_CTX_ctrl.pod b/doc/man3/EVP_PKEY_CTX_ctrl.pod index 9d1812f6bd..18b984162e 100644 --- a/doc/man3/EVP_PKEY_CTX_ctrl.pod +++ b/doc/man3/EVP_PKEY_CTX_ctrl.pod @@ -2,7 +2,10 @@ =head1 NAME +EVP_PKEY_CTX_get_params, +EVP_PKEY_CTX_gettable_params, EVP_PKEY_CTX_set_params, +EVP_PKEY_CTX_settable_params, EVP_PKEY_CTX_ctrl, EVP_PKEY_CTX_ctrl_str, EVP_PKEY_CTX_ctrl_uint64, @@ -63,7 +66,10 @@ EVP_PKEY_CTX_set1_id, EVP_PKEY_CTX_get1_id, EVP_PKEY_CTX_get1_id_len #include + int EVP_PKEY_CTX_get_params(EVP_PKEY_CTX *ctx, OSSL_PARAM *params); + const OSSL_PARAM *EVP_PKEY_CTX_gettable_params(EVP_PKEY_CTX *ctx); int EVP_PKEY_CTX_set_params(EVP_PKEY_CTX *ctx, OSSL_PARAM *params); + const OSSL_PARAM *EVP_PKEY_CTX_settable_params(EVP_PKEY_CTX *ctx); int EVP_PKEY_CTX_ctrl(EVP_PKEY_CTX *ctx, int keytype, int optype, int cmd, int p1, void *p2); @@ -144,16 +150,20 @@ EVP_PKEY_CTX_set1_id, EVP_PKEY_CTX_get1_id, EVP_PKEY_CTX_get1_id_len =head1 DESCRIPTION -The EVP_PKEY_CTX_set_params() function sends arbitrary parameters to the -algorithm implementation. +The EVP_PKEY_CTX_get_params() and EVP_PKEY_CTX_set_params() functions get and +send arbitrary parameters from and to the algorithm implementation respectively. Not all parameters may be supported by all providers. See L for more information on providers. See L for more information on parameters. +These functions must only be called after the EVP_PKEY_CTX has been initialised +for use in an operation (for example by L, +L or other similar functions). + The parameters currently supported by the default provider are: =over 4 -=item OSSL_EXCHANGE_PARAM_PAD (uint type) +=item "exchange-pad" (B) Sets the DH padding mode. If B is 1 then the shared secret is padded with zeroes @@ -161,19 +171,29 @@ up to the size of the DH prime B

. If B is zero (the default) then no padding is performed. -=item OSSL_SIGNATURE_PARAM_DIGEST (UTF8 string type) +=item "digest" (B) -Sets the name of the digest algorithm used for the input to the signature -functions. +Gets and sets the name of the digest algorithm used for the input to the +signature functions. -=item OSSL_SIGNATURE_PARAM_DIGEST_SIZE (size_t type) +=item "digest-size" (B) -Sets the output size of the digest algorithm used for the input to the signature -functions. +Gets and sets the output size of the digest algorithm used for the input to the +signature functions. The internal algorithm that supports this parameter is DSA. =back +EVP_PKEY_CTX_gettable_params() and EVP_PKEY_CTX_settable_params() gets a +constant B array that decribes the gettable and +settable parameters for the current algorithm implementation, i.e. parameters +that can be used with EVP_PKEY_CTX_get_params() and EVP_PKEY_CTX_set_params() +respectively. +See L for the use of B as parameter descriptor. +These functions must only be called after the EVP_PKEY_CTX has been initialised +for use in an operation (for example by L, +L or other similar functions). + 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 -1. The parameter B is a mask indicating which operations the control can be applied to. @@ -199,13 +219,13 @@ B, B and B commands. The function EVP_PKEY_CTX_md() sends a message digest control operation to the context B. The message digest is specified by its name B. -All the remaining "functions" are implemented as macros. +The EVP_PKEY_CTX_set_signature_md() function sets the message digest type used +in a signature. It can be used in the RSA, DSA and ECDSA algorithms. -The EVP_PKEY_CTX_set_signature_md() macro sets the message digest type used +The EVP_PKEY_CTX_get_signature_md() function gets the message digest type used in a signature. It can be used in the RSA, DSA and ECDSA algorithms. -The EVP_PKEY_CTX_get_signature_md() macro gets the message digest type used in a -signature. It can be used in the RSA, DSA and ECDSA algorithms. +All the remaining "functions" are implemented as macros. Key generation typically involves setting up parameters to be used and generating the private and public key data. Some algorithm implementations @@ -471,9 +491,15 @@ allocate adequate memory space for the B before calling EVP_PKEY_CTX_get1_id =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. +EVP_PKEY_CTX_set_params() returns 1 for success or 0 otherwise. +EVP_PKEY_CTX_settable_params() returns an OSSL_PARAM array on success or NULL on +error. +It may also return NULL if there are no settable parameters available. + +EVP_PKEY_CTX_set_signature_md(), EVP_PKEY_CTX_set_dh_pad(), 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 @@ -492,8 +518,9 @@ The EVP_PKEY_CTX_set1_id(), EVP_PKEY_CTX_get1_id() and EVP_PKEY_CTX_get1_id_len() macros were added in 1.1.1, other functions were added in OpenSSL 1.0.0. -EVP_PKEY_CTX_set_dh_pad() was a macro in OpenSSL 1.1.1 and below. -From OpenSSL 3.0 it is a function. +EVP_PKEY_CTX_get_signature_md(), EVP_PKEY_CTX_set_signature_md() and +EVP_PKEY_CTX_set_dh_pad() were macros in OpenSSL 1.1.1 and below. From OpenSSL +3.0 they are functions. =head1 COPYRIGHT