Add some documentation to describe the encap/decap requirements

Document the fact that we now require unwrappedlen/wrappedlen to be set
to the size of the unwrapped/wrapped buffers

Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
Reviewed-by: Viktor Dukhovni <viktor@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/25522)

diff --git a/doc/man3/EVP_PKEY_decapsulate.pod b/doc/man3/EVP_PKEY_decapsulate.pod
index c18427e411574b59e3b31ab32acbf6b9a5f8c136..286e956400fee7afb727313bd95762b7d8666ecb 100644 (file)
--- a/doc/man3/EVP_PKEY_decapsulate.pod
+++ b/doc/man3/EVP_PKEY_decapsulate.pod
@@ -31,10 +31,13 @@ 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<unwrapped> is NULL then the maximum size of the output secret buffer
+If I<unwrapped> is NULL then the 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>.
+and the amount of data written to I<*unwrappedlen>.  Note that, if I<unwrappedlen>
+is not NULL in this call, the value it points to must be initialised to the length of
+I<unwrapped>, so that the call can validate it is of sufficient size to hold the
+result of the operation.
 
 =head1 NOTES
 

diff --git a/doc/man3/EVP_PKEY_encapsulate.pod b/doc/man3/EVP_PKEY_encapsulate.pod
index 042b169a175f79561c5b32a5d65a24c1d85fffcc..04025592d9a6c10445da84db238a0c6ac89dfadd 100644 (file)
--- a/doc/man3/EVP_PKEY_encapsulate.pod
+++ b/doc/man3/EVP_PKEY_encapsulate.pod
@@ -41,7 +41,10 @@ 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<wrappedkey> and its size is written to I<*wrappedkeylen>.
+I<wrappedkey> and its size is written to I<*wrappedkeylen>.  Note that if
+I<wrappedlen> is not NULL, then the value it points to must initially hold the size of
+the  I<unwrapped> buffer so that its size can be validated by the call, ensuring
+it is large enough to hold the result written to I<wrapped>.
 
 =head1 NOTES
 

diff --git a/providers/implementations/kem/rsa_kem.c b/providers/implementations/kem/rsa_kem.c
index c39a48e1a4a95eabc014d183aab98aee93f1a3fa..0ac400cbe09967b4d39541788d745303702262fd 100644 (file)
--- a/providers/implementations/kem/rsa_kem.c
+++ b/providers/implementations/kem/rsa_kem.c
@@ -298,6 +298,11 @@ static int rsasve_generate(PROV_RSA_CTX *prsactx,
         return 1;
     }
 
+    /*
+     * If outlen is specified, then it must report the length
+     * of the out buffer on input so that we can confirm
+     * its size is sufficent for encapsulation
+     */
     if (outlen != NULL && *outlen < nlen) {
         ERR_raise(ERR_LIB_PROV, PROV_R_INVALID_OUTPUT_LENGTH);
         return 0;
@@ -372,6 +377,12 @@ static int rsasve_recover(PROV_RSA_CTX *prsactx,
         ERR_raise(ERR_LIB_PROV, PROV_R_BAD_LENGTH);
         return 0;
     }
+
+    /*
+     * If outlen is specified, then it must report the length
+     * of the out buffer, so that we can confirm that it is of
+     * sufficient size to hold the output of decapsulation
+     */
     if (outlen != NULL && *outlen < nlen) {
         ERR_raise(ERR_LIB_PROV, PROV_R_INVALID_OUTPUT_LENGTH);
         return 0;