From: Pauli Date: Wed, 3 Mar 2021 01:02:42 +0000 (+1000) Subject: doc: update PKEY documentation to include the new init functions with params X-Git-Tag: openssl-3.0.0-alpha14~327 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=ee22fca5cec53c9775cbdf1c44677ba5ee9b5049;p=thirdparty%2Fopenssl.git doc: update PKEY documentation to include the new init functions with params Reviewed-by: Shane Lontis (Merged from https://github.com/openssl/openssl/pull/14383) --- diff --git a/doc/man3/EVP_PKEY_decapsulate.pod b/doc/man3/EVP_PKEY_decapsulate.pod index 7dd47a1e580..36e8f9c9d4c 100644 --- a/doc/man3/EVP_PKEY_decapsulate.pod +++ b/doc/man3/EVP_PKEY_decapsulate.pod @@ -9,7 +9,7 @@ EVP_PKEY_decapsulate_init, EVP_PKEY_decapsulate #include - int EVP_PKEY_decapsulate_init(EVP_PKEY_CTX *ctx); + int EVP_PKEY_decapsulate_init(EVP_PKEY_CTX *ctx, const OSSL_PARAM params[]); int EVP_PKEY_decapsulate(EVP_PKEY_CTX *ctx, unsigned char *secret, size_t *secretlen, const unsigned char *wrapped, size_t wrappedlen); @@ -17,7 +17,8 @@ EVP_PKEY_decapsulate_init, EVP_PKEY_decapsulate =head1 DESCRIPTION The EVP_PKEY_decapsulate_init() function initializes a private key algorithm -context I for a decapsulation operation. +context I for a decapsulation operation and then sets the I +on the context in the same way as calling L. The EVP_PKEY_decapsulate() function performs a private key decapsulation operation using I. The data to be decapsulated is specified using the @@ -30,8 +31,7 @@ the amount of data written to I. =head1 NOTES After the call to EVP_PKEY_decapsulate_init() algorithm specific parameters -for the operation may be set using L. There are no -settable parameters currently. +for the operation may be set or modified using L. =head1 RETURN VALUES @@ -57,7 +57,7 @@ Decapsulate data using RSA: ctx = EVP_PKEY_CTX_new_from_pkey(libctx, rsa_priv_key, NULL); if (ctx = NULL) /* Error */ - if (EVP_PKEY_decapsulate_init(ctx) <= 0) + if (EVP_PKEY_decapsulate_init(ctx, NULL) <= 0) /* Error */ /* Set the mode - only 'RSASVE' is currently supported */ diff --git a/doc/man3/EVP_PKEY_decrypt.pod b/doc/man3/EVP_PKEY_decrypt.pod index a78c1ee8e4c..f516489df4e 100644 --- a/doc/man3/EVP_PKEY_decrypt.pod +++ b/doc/man3/EVP_PKEY_decrypt.pod @@ -2,7 +2,8 @@ =head1 NAME -EVP_PKEY_decrypt_init, EVP_PKEY_decrypt - decrypt using a public key algorithm +EVP_PKEY_decrypt_init, EVP_PKEY_decrypt_init_ex, +EVP_PKEY_decrypt - decrypt using a public key algorithm =head1 SYNOPSIS diff --git a/doc/man3/EVP_PKEY_derive.pod b/doc/man3/EVP_PKEY_derive.pod index 5bfb316382c..be5cf3945e0 100644 --- a/doc/man3/EVP_PKEY_derive.pod +++ b/doc/man3/EVP_PKEY_derive.pod @@ -2,7 +2,8 @@ =head1 NAME -EVP_PKEY_derive_init, EVP_PKEY_derive_set_peer, EVP_PKEY_derive +EVP_PKEY_derive_init, EVP_PKEY_derive_init_ex, +EVP_PKEY_derive_set_peer, EVP_PKEY_derive - derive public key algorithm shared secret =head1 SYNOPSIS @@ -10,6 +11,7 @@ EVP_PKEY_derive_init, EVP_PKEY_derive_set_peer, EVP_PKEY_derive #include int EVP_PKEY_derive_init(EVP_PKEY_CTX *ctx); + int EVP_PKEY_derive_init_ex(EVP_PKEY_CTX *ctx, const OSSL_PARAM params[]); int EVP_PKEY_derive_set_peer(EVP_PKEY_CTX *ctx, EVP_PKEY *peer); int EVP_PKEY_derive(EVP_PKEY_CTX *ctx, unsigned char *key, size_t *keylen); @@ -21,6 +23,9 @@ using L or variants thereof. The algorithm is used to fetch a B method implicitly, see L for more information about implicit fetches. +EVP_PKEY_derive_init_ex() is the same as EVP_PKEY_derive_init() but additionally +sets the passed parameters I on the context before returning. + EVP_PKEY_derive_set_peer() sets the peer key: this will normally be a public key. @@ -95,7 +100,10 @@ L =head1 HISTORY -These functions were added in OpenSSL 1.0.0. +The EVP_PKEY_derive_init(), EVP_PKEY_derive_set_peer() and EVP_PKEY_derive() +functions were originally added in OpenSSL 1.0.0. + +The EVP_PKEY_derive_init_ex() function was added in OpenSSL 3.0. =head1 COPYRIGHT diff --git a/doc/man3/EVP_PKEY_encapsulate.pod b/doc/man3/EVP_PKEY_encapsulate.pod index 0e911f71cf8..7547c7ae34b 100644 --- a/doc/man3/EVP_PKEY_encapsulate.pod +++ b/doc/man3/EVP_PKEY_encapsulate.pod @@ -9,7 +9,7 @@ EVP_PKEY_encapsulate_init, EVP_PKEY_encapsulate #include - int EVP_PKEY_encapsulate_init(EVP_PKEY_CTX *ctx); + int EVP_PKEY_encapsulate_init(EVP_PKEY_CTX *ctx, const OSSL_PARAM params[]); int EVP_PKEY_encapsulate(EVP_PKEY_CTX *ctx, unsigned char *out, size_t *outlen, unsigned char *genkey, size_t *genkeylen); @@ -17,7 +17,8 @@ EVP_PKEY_encapsulate_init, EVP_PKEY_encapsulate =head1 DESCRIPTION The EVP_PKEY_encapsulate_init() function initializes a public key algorithm -context I for an encapsulation operation. +context I for an encapsulation operation and then sets the I +on the context in the same way as calling L. The EVP_PKEY_encapsulate() function performs a public key encapsulation operation using I with the name I. @@ -31,7 +32,7 @@ I and its size is written to I<*outlen>. =head1 NOTES After the call to EVP_PKEY_encapsulate_init() algorithm specific parameters -for the operation may be set using L. +for the operation may be set or modified using L. =head1 RETURN VALUES @@ -56,7 +57,7 @@ Encapsulate an RSASVE key (for RSA keys). ctx = EVP_PKEY_CTX_new_from_pkey(libctx, rsa_pub_key, NULL); if (ctx = NULL) /* Error */ - if (EVP_PKEY_encapsulate_init(ctx) <= 0) + if (EVP_PKEY_encapsulate_init(ctx, NULL) <= 0) /* Error */ /* Set the mode - only 'RSASVE' is currently supported */ diff --git a/doc/man3/EVP_PKEY_sign.pod b/doc/man3/EVP_PKEY_sign.pod index bd65bd92376..1e2f71862a7 100644 --- a/doc/man3/EVP_PKEY_sign.pod +++ b/doc/man3/EVP_PKEY_sign.pod @@ -2,7 +2,7 @@ =head1 NAME -EVP_PKEY_sign_init, EVP_PKEY_sign +EVP_PKEY_sign_init, EVP_PKEY_sign_init_ex, EVP_PKEY_sign - sign using a public key algorithm =head1 SYNOPSIS @@ -10,6 +10,7 @@ EVP_PKEY_sign_init, EVP_PKEY_sign #include int EVP_PKEY_sign_init(EVP_PKEY_CTX *ctx); + int EVP_PKEY_sign_init_ex(EVP_PKEY_CTX *ctx, const OSSL_PARAM params[]); int EVP_PKEY_sign(EVP_PKEY_CTX *ctx, unsigned char *sig, size_t *siglen, const unsigned char *tbs, size_t tbslen); @@ -22,6 +23,9 @@ using L or variants thereof. The algorithm is used to fetch a B method implicitly, see L for more information about implicit fetches. +EVP_PKEY_sign_init_ex() is the same as EVP_PKEY_sign_init() but additionally +sets the passed parameters I on the context before returning. + The EVP_PKEY_sign() function performs a public key signing operation using I. The data to be signed is specified using the I and I parameters. If I is NULL then the maximum size of the output @@ -105,7 +109,10 @@ L =head1 HISTORY -These functions were added in OpenSSL 1.0.0. +The EVP_PKEY_sign_init() and EVP_PKEY_sign() functions were added in +OpenSSL 1.0.0. + +The EVP_PKEY_sign_init_ex() function was added in OpenSSL 3.0. =head1 COPYRIGHT diff --git a/doc/man3/EVP_PKEY_verify.pod b/doc/man3/EVP_PKEY_verify.pod index c41525246ab..972c5c54b97 100644 --- a/doc/man3/EVP_PKEY_verify.pod +++ b/doc/man3/EVP_PKEY_verify.pod @@ -2,7 +2,7 @@ =head1 NAME -EVP_PKEY_verify_init, EVP_PKEY_verify +EVP_PKEY_verify_init, EVP_PKEY_verify_init_ex, EVP_PKEY_verify - signature verification using a public key algorithm =head1 SYNOPSIS @@ -10,6 +10,7 @@ EVP_PKEY_verify_init, EVP_PKEY_verify #include int EVP_PKEY_verify_init(EVP_PKEY_CTX *ctx); + int EVP_PKEY_verify_init_ex(EVP_PKEY_CTX *ctx, const OSSL_PARAM params[]); int EVP_PKEY_verify(EVP_PKEY_CTX *ctx, const unsigned char *sig, size_t siglen, const unsigned char *tbs, size_t tbslen); @@ -22,6 +23,9 @@ using L or variants thereof. The algorithm is used to fetch a B method implicitly, see L for more information about implicit fetches. +EVP_PKEY_verify_init_ex() is the same as EVP_PKEY_verify_init() but additionally +sets the passed parameters I on the context before returning. + The EVP_PKEY_verify() function performs a public key verification operation using I. The signature is specified using the I and I parameters. The verified data (i.e. the data believed originally @@ -93,7 +97,10 @@ L =head1 HISTORY -These functions were added in OpenSSL 1.0.0. +The EVP_PKEY_verify_init() and EVP_PKEY_verify() functions were added in +OpenSSL 1.0.0. + +The EVP_PKEY_verify_init_ex() function was added in OpenSSL 3.0. =head1 COPYRIGHT diff --git a/doc/man3/EVP_PKEY_verify_recover.pod b/doc/man3/EVP_PKEY_verify_recover.pod index e8acd6ab8d0..5b7535007cf 100644 --- a/doc/man3/EVP_PKEY_verify_recover.pod +++ b/doc/man3/EVP_PKEY_verify_recover.pod @@ -2,7 +2,8 @@ =head1 NAME -EVP_PKEY_verify_recover_init, EVP_PKEY_verify_recover +EVP_PKEY_verify_recover_init, EVP_PKEY_verify_recover_init_ex, +EVP_PKEY_verify_recover - recover signature using a public key algorithm =head1 SYNOPSIS @@ -10,6 +11,8 @@ EVP_PKEY_verify_recover_init, EVP_PKEY_verify_recover #include int EVP_PKEY_verify_recover_init(EVP_PKEY_CTX *ctx); + int EVP_PKEY_verify_recover_init_ex(EVP_PKEY_CTX *ctx, + const OSSL_PARAM params[]); int EVP_PKEY_verify_recover(EVP_PKEY_CTX *ctx, unsigned char *rout, size_t *routlen, const unsigned char *sig, size_t siglen); @@ -22,6 +25,10 @@ using L or variants thereof. The algorithm is used to fetch a B method implicitly, see L for more information about implicit fetches. +EVP_PKEY_verify_recover_init_ex() is the same as +EVP_PKEY_verify_recover_init() but additionally sets the passed parameters +I on the context before returning. + The EVP_PKEY_verify_recover() function recovers signed data using I. The signature is specified using the I and I parameters. If I is NULL then the maximum size of the output @@ -104,7 +111,10 @@ L =head1 HISTORY -These functions were added in OpenSSL 1.0.0. +The EVP_PKEY_verify_recover_init() and EVP_PKEY_verify_recover() +functions were added in OpenSSL 1.0.0. + +The EVP_PKEY_verify_recover_init_ex() function was added in OpenSSL 3.0. =head1 COPYRIGHT