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)

diff --git a/doc/man3/EVP_PKEY_decapsulate.pod b/doc/man3/EVP_PKEY_decapsulate.pod
index 27532b4abbf7b08f6fa8898f3edd3d9a9011e786..12339dfb743b231a6f06b345aecfa9458becc6f3 100644 (file)
--- 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_auth_decapsulate_init, EVP_PKEY_decapsulate
-- Key decapsulation using a private key algorithm
+- Key decapsulation using a KEM algorithm with a private key
 
 =head1 SYNOPSIS
 
@@ -13,7 +13,7 @@ EVP_PKEY_decapsulate_init, EVP_PKEY_auth_decapsulate_init, EVP_PKEY_decapsulate
  int EVP_PKEY_auth_decapsulate_init(EVP_PKEY_CTX *ctx, EVP_PKEY *authpub,
                                    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
@@ -21,6 +21,8 @@ EVP_PKEY_decapsulate_init, EVP_PKEY_auth_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_auth_decapsulate_init() function is similar to
 EVP_PKEY_decapsulate_init() but also passes an I<authpub> authentication public
@@ -29,14 +31,14 @@ key that is used during decapsulation.
 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
@@ -86,7 +88,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)>, L<EVP_KEM-X25519(7)>, L<EVP_KEM-EC(7)>
 

diff --git a/doc/man3/EVP_PKEY_encapsulate.pod b/doc/man3/EVP_PKEY_encapsulate.pod
index 5da5a656b85c1054d1884ddb8f91291f2764e441..df1f948c8dd3c4dc94625e5d49c69dcd2a8e44d9 100644 (file)
--- 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_auth_encapsulate_init, EVP_PKEY_encapsulate
-- Key encapsulation using a public key algorithm
+- Key encapsulation using a KEM algorithm with a public key
 
 =head1 SYNOPSIS
 
@@ -13,7 +13,7 @@ EVP_PKEY_encapsulate_init, EVP_PKEY_auth_encapsulate_init, EVP_PKEY_encapsulate
  int EVP_PKEY_auth_encapsulate_init(EVP_PKEY_CTX *ctx, EVP_PKEY *authpriv,
                                    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
@@ -21,23 +21,31 @@ EVP_PKEY_encapsulate_init, EVP_PKEY_auth_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_auth_encapsulate_init() function is similar to
 EVP_PKEY_encapsulate_init() but also passes an I<authpriv> authentication private
 key that is used during encapsulation.
 
 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
@@ -89,7 +97,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)>, L<EVP_KEM-X25519(7)>, L<EVP_KEM-EC(7)>