EVP_PKEY_{en,de}capsulate.pod: fix glitches and add some detail and hints

Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Paul Dale <pauli@openssl.org>
Reviewed-by: David von Oheimb <david.von.oheimb@siemens.com>
(Merged from https://github.com/openssl/openssl/pull/21397)

(cherry picked from commit 5be8233d2be306a2906d3da16e59aa15a4559dd2)

2 files changed, 27 insertions, 17 deletions

diff --git a/doc/man3/EVP_PKEY_decapsulate.pod b/doc/man3/EVP_PKEY_decapsulate.pod
index 529e318f9e..f9ddad7dff 100644
--- a/doc/man3/EVP_PKEY_decapsulate.pod
+++ b/doc/man3/EVP_PKEY_decapsulate.pod
@@ -3,7 +3,7 @@
 =head1 NAME
 
 EVP_PKEY_decapsulate_init, EVP_PKEY_decapsulate
-- Key decapsulation using a private key algorithm
+- Key decapsulation using a KEM algorithm with a private key
 
 =head1 SYNOPSIS
 
@@ -11,7 +11,7 @@ EVP_PKEY_decapsulate_init, EVP_PKEY_decapsulate
 
  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,
+                          unsigned char *unwrapped, size_t *unwrappedlen,
                           const unsigned char *wrapped, size_t wrappedlen);
 
 =head1 DESCRIPTION
@@ -19,18 +19,20 @@ EVP_PKEY_decapsulate_init, EVP_PKEY_decapsulate
 The EVP_PKEY_decapsulate_init() function initializes a private key algorithm
 context I<ctx> for a decapsulation operation and then sets the I<params>
 on the context in the same way as calling L<EVP_PKEY_CTX_set_params(3)>.
+Note that I<ctx> usually is produced using L<EVP_PKEY_CTX_new_from_pkey(3)>,
+specifying the private key to use.
 
 The EVP_PKEY_decapsulate() function performs a private key decapsulation
 operation using I<ctx>. The data to be decapsulated is specified using the
 I<wrapped> and I<wrappedlen> parameters.
-If I<secret> is I<NULL> then the maximum size of the output secret buffer
-is written to the I<*secretlen> parameter. If I<secret> is not B<NULL> and the
-call is successful then the decapsulated secret data is written to I<secret> and
-the amount of data written to I<secretlen>.
+If I<unwrapped> is NULL then the maximum size of the output secret buffer
+is written to I<*unwrappedlen>. If I<unwrapped> is not NULL and the
+call is successful then the decapsulated secret data is written to I<unwrapped>
+and the amount of data written to I<*unwrappedlen>.
 
 =head1 NOTES
 
-After the call to EVP_PKEY_decapsulate_init() algorithm specific parameters
+After the call to EVP_PKEY_decapsulate_init() algorithm-specific parameters
 for the operation may be set or modified using L<EVP_PKEY_CTX_set_params(3)>.
 
 =head1 RETURN VALUES
@@ -79,7 +81,7 @@ Decapsulate data using RSA:
 
 =head1 SEE ALSO
 
-L<EVP_PKEY_CTX_new(3)>,
+L<EVP_PKEY_CTX_new_from_pkey(3)>,
 L<EVP_PKEY_encapsulate(3)>,
 L<EVP_KEM-RSA(7)>,
 
diff --git a/doc/man3/EVP_PKEY_encapsulate.pod b/doc/man3/EVP_PKEY_encapsulate.pod
index 9baf88d07b..338ed0ea52 100644
--- a/doc/man3/EVP_PKEY_encapsulate.pod
+++ b/doc/man3/EVP_PKEY_encapsulate.pod
@@ -3,7 +3,7 @@
 =head1 NAME
 
 EVP_PKEY_encapsulate_init, EVP_PKEY_encapsulate
-- Key encapsulation using a public key algorithm
+- Key encapsulation using a KEM algorithm with a public key
 
 =head1 SYNOPSIS
 
@@ -11,7 +11,7 @@ EVP_PKEY_encapsulate_init, EVP_PKEY_encapsulate
 
  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 *wrappedkey, size_t *wrappedkeylen,
                           unsigned char *genkey, size_t *genkeylen);
 
 =head1 DESCRIPTION
@@ -19,19 +19,27 @@ EVP_PKEY_encapsulate_init, EVP_PKEY_encapsulate
 The EVP_PKEY_encapsulate_init() function initializes a public key algorithm
 context I<ctx> for an encapsulation operation and then sets the I<params>
 on the context in the same way as calling L<EVP_PKEY_CTX_set_params(3)>.
+Note that I<ctx> is usually is produced using L<EVP_PKEY_CTX_new_from_pkey(3)>,
+specifying the public key to use.
 
 The EVP_PKEY_encapsulate() function performs a public key encapsulation
-operation using I<ctx> with the name I<name>.
-If I<out> is B<NULL> then the maximum size of the output buffer is written to the
-I<*outlen> parameter and the maximum size of the generated key buffer is written
-to I<*genkeylen>. If I<out> is not B<NULL> and the call is successful then the
+operation using I<ctx>.
+The symmetric secret generated in I<genkey> can be used as key material.
+The ciphertext in I<wrappedkey> is its encapsulated form, which can be sent
+to another party, who can use L<EVP_PKEY_decapsulate(3)> to retrieve it
+using their private key.
+If I<wrappedkey> is NULL then the maximum size of the output buffer
+is written to the I<*wrappedkeylen> parameter unless I<wrappedkeylen> is NULL
+and the maximum size of the generated key buffer is written to I<*genkeylen>
+unless I<genkeylen> is NULL.
+If I<wrappedkey> is not NULL and the call is successful then the
 internally generated key is written to I<genkey> and its size is written to
 I<*genkeylen>. The encapsulated version of the generated key is written to
-I<out> and its size is written to I<*outlen>.
+I<wrappedkey> and its size is written to I<*wrappedkeylen>.
 
 =head1 NOTES
 
-After the call to EVP_PKEY_encapsulate_init() algorithm specific parameters
+After the call to EVP_PKEY_encapsulate_init() algorithm-specific parameters
 for the operation may be set or modified using L<EVP_PKEY_CTX_set_params(3)>.
 
 =head1 RETURN VALUES
@@ -82,7 +90,7 @@ Encapsulate an RSASVE key (for RSA keys).
 
 =head1 SEE ALSO
 
-L<EVP_PKEY_CTX_new(3)>,
+L<EVP_PKEY_CTX_new_from_pkey(3)>,
 L<EVP_PKEY_decapsulate(3)>,
 L<EVP_KEM-RSA(7)>,