Make the KEM operating mode optional

There is only one operating mode supported for each of RSA, EC and ECX.
We should not require an explicit setting for the obvious default.

Reviewed-by: Tim Hudson <tjh@openssl.org>
Reviewed-by: Dmitry Belyavskiy <beldmit@gmail.com>
(Merged from https://github.com/openssl/openssl/pull/26872)

diff --git a/doc/man1/openssl-pkeyutl.pod.in b/doc/man1/openssl-pkeyutl.pod.in
index 9d030935448a274cdbc4701d93ab9385dc122d2b..2a6a4d8814d080932edecd9d144471ed408bfc0c 100644 (file)
--- a/doc/man1/openssl-pkeyutl.pod.in
+++ b/doc/man1/openssl-pkeyutl.pod.in
@@ -33,7 +33,7 @@ B<openssl> B<pkeyutl>
 [B<-decap>]
 [B<-kdf> I<algorithm>]
 [B<-kdflen> I<length>]
-[B<-kemop> I<operation>]
+[B<-kemop> I<mode>]
 [B<-pkeyopt> I<opt>:I<value>]
 [B<-pkeyopt_passin> I<opt>[:I<passarg>]]
 [B<-hexdump>]
@@ -212,8 +212,8 @@ and
 L<EC|EVP_KEM-EC(7)>.
 The ECX and EC algorithms use the
 L<RFC9180|https://www.rfc-editor.org/rfc/rfc9180> DHKEM construction.
-Encapsulation is also supported with L<RSA|EVP_KEM-RSA(7)> keys with the use of
-an additional B<-kemop> option.
+Encapsulation is also supported with L<RSA|EVP_KEM-RSA(7)> keys via the
+B<RSASVE> construction.
 
 At the API level, encapsulation and decapsulation are also supported for a few
 hybrid ECDHE (no DHKEM) plus B<ML-KEM> algorithms, but these are intended
@@ -238,17 +238,16 @@ and
 L<EC|EVP_KEM-EC(7)>.
 The ECX and EC algorithms use the
 L<RFC9180|https://www.rfc-editor.org/rfc/rfc9180> DHKEM construction.
-Encapsulation is also supported with L<RSA|EVP_KEM-RSA(7)> keys with the use of
-an additional B<-kemop> option.
+Decapsulation is also supported with L<RSA|EVP_KEM-RSA(7)> keys via the
+B<RSASVE> construction.
 
-=item B<-kemop> I<operation>
+=item B<-kemop> I<mode>
 
 This option is used with the I<-encap>/I<-decap> commands and specifies the KEM
-operation (mode) specific for the key algorithm when there is no default way
-to encapsulate and decapsulate shared secrets with the chosen key type.
-This is needed only for RSA, where B<RSASVE>, is not the default mode, even
-though it is presently the only RSA KEM supported.
-See L<EVP_PKEY_CTX_set_kem_op(3)>, L<EVP_KEM-RSA(7)> and L<EVP_KEM-ML-KEM(7)>.
+I<mode> specific for the key algorithm when there is no default way to
+encapsulate and decapsulate shared secrets with the chosen key type.
+All the supported algorithms presently support only their default I<mode>, and
+this option, though available, is not required.
 
 =item B<-kdf> I<algorithm>
 
@@ -569,6 +568,9 @@ Since OpenSSL 3.5,
 the B<-digest> option implies B<-rawin>, and these two options are
 no longer required when signing or verifying with an Ed25519 or Ed448 key.
 
+Also since OpenSSL 3.5, the B<-kemop> option is no longer required for any of
+the supported algorithms, the only supported B<mode> is now the default.
+
 The B<-engine> option was deprecated in OpenSSL 3.0.
 
 =head1 COPYRIGHT

diff --git a/doc/man7/EVP_KEM-EC.pod b/doc/man7/EVP_KEM-EC.pod
index 8877d7fb218c408fe02ca930dc8e3d51bc0a7ed8..27035e5124e326d626be8fff9a48f83e9d06e6d3 100644 (file)
--- a/doc/man7/EVP_KEM-EC.pod
+++ b/doc/man7/EVP_KEM-EC.pod
@@ -17,7 +17,7 @@ See L<EVP_PKEY_encapsulate(3)> and L<EVP_PKEY_decapsulate(3)> for more info.
 =item "operation" (B<OSSL_KEM_PARAM_OPERATION>)<UTF8 string>
 
 The OpenSSL EC Key Encapsulation Mechanisms only supports the
-following operation:
+following default operation (operating mode):
 
 =over 4
 
@@ -70,6 +70,10 @@ L<provider-keymgmt(7)>
 
 This functionality was added in OpenSSL 3.2.
 
+The C<operation> (operating mode) was a required parameter prior to OpenSSL 3.5.
+As of OpenSSL 3.5, C<DHKEM> is the default operating mode, and no explicit value
+need be specified.
+
 =head1 COPYRIGHT
 
 Copyright 2022 The OpenSSL Project Authors. All Rights Reserved.

diff --git a/doc/man7/EVP_KEM-RSA.pod b/doc/man7/EVP_KEM-RSA.pod
index 8d54875690e8ba38655392952125caf700138396..c6496f71c2e09e742913fdc3ecfa158aeb672d6e 100644 (file)
--- a/doc/man7/EVP_KEM-RSA.pod
+++ b/doc/man7/EVP_KEM-RSA.pod
@@ -17,7 +17,7 @@ See L<EVP_PKEY_encapsulate(3)> and L<EVP_PKEY_decapsulate(3)> for more info.
 =item "operation" (B<OSSL_KEM_PARAM_OPERATION>) <UTF8 string>
 
 The OpenSSL RSA Key Encapsulation Mechanism only currently supports the
-following operation
+following default operation (operating mode):
 
 =over 4
 
@@ -63,6 +63,10 @@ L<provider-keymgmt(7)>
 
 This functionality was added in OpenSSL 3.0.
 
+The C<operation> (operating mode) was a required parameter prior to OpenSSL 3.5.
+As of OpenSSL 3.5, C<RSASVE> is the default operating mode, and no explicit
+value need be specified.
+
 =head1 COPYRIGHT
 
 Copyright 2020-2024 The OpenSSL Project Authors. All Rights Reserved.

diff --git a/doc/man7/EVP_KEM-X25519.pod b/doc/man7/EVP_KEM-X25519.pod
index a9dcd3a27ac710ee9cc59767581b672d7c2aa7d7..940a8cab068cd6b5891b3ede265bdfbb04d97de6 100644 (file)
--- a/doc/man7/EVP_KEM-X25519.pod
+++ b/doc/man7/EVP_KEM-X25519.pod
@@ -18,7 +18,7 @@ See L<EVP_PKEY_encapsulate(3)> and L<EVP_PKEY_decapsulate(3)> for more info.
 =item "operation" (B<OSSL_KEM_PARAM_OPERATION>)<UTF8 string>
 
 The OpenSSL X25519 and X448 Key Encapsulation Mechanisms only support the
-following operation:
+following default operation (operating mode):
 
 =over 4
 
@@ -69,6 +69,10 @@ L<provider-keymgmt(7)>
 
 This functionality was added in OpenSSL 3.2.
 
+The C<operation> (operating mode) was a required parameter prior to OpenSSL 3.5.
+As of OpenSSL 3.5, C<DHKEM> is the default operating mode, and no explicit value
+need be specified.
+
 =head1 COPYRIGHT
 
 Copyright 2022 The OpenSSL Project Authors. All Rights Reserved.

diff --git a/providers/implementations/kem/ec_kem.c b/providers/implementations/kem/ec_kem.c
index c58727c9e2f7bd2079357febcc93db6c5db3d03c..040bdaff018f81c66785709c1aa13c50a52b72b5 100644 (file)
--- a/providers/implementations/kem/ec_kem.c
+++ b/providers/implementations/kem/ec_kem.c
@@ -197,6 +197,7 @@ static void *eckem_newctx(void *provctx)
     if (ctx == NULL)
         return NULL;
     ctx->libctx = PROV_LIBCTX_OF(provctx);
+    ctx->mode = KEM_MODE_DHKEM;
 
     return ctx;
 }

diff --git a/providers/implementations/kem/ecx_kem.c b/providers/implementations/kem/ecx_kem.c
index b611a21fbf46fe517d17e9304ae6571c3ea74048..b9ac8669d1b2ab3175a0083bbdc4905e872675e7 100644 (file)
--- a/providers/implementations/kem/ecx_kem.c
+++ b/providers/implementations/kem/ecx_kem.c
@@ -162,6 +162,7 @@ static void *ecxkem_newctx(void *provctx)
     if (ctx == NULL)
         return NULL;
     ctx->libctx = PROV_LIBCTX_OF(provctx);
+    ctx->mode = KEM_MODE_DHKEM;
 
     return ctx;
 }

diff --git a/providers/implementations/kem/rsa_kem.c b/providers/implementations/kem/rsa_kem.c
index 0ae34a5ee3128c3779248d2e8e4cb7ef0c21cff6..e1c607c7dd5ea7c0727b19f62d4fe6d741b51b3d 100644 (file)
--- a/providers/implementations/kem/rsa_kem.c
+++ b/providers/implementations/kem/rsa_kem.c
@@ -92,7 +92,7 @@ static void *rsakem_newctx(void *provctx)
     if (prsactx == NULL)
         return NULL;
     prsactx->libctx = PROV_LIBCTX_OF(provctx);
-    prsactx->op = KEM_OP_UNDEFINED;
+    prsactx->op = KEM_OP_RSASVE;
     OSSL_FIPS_IND_INIT(prsactx)
 
     return prsactx;

diff --git a/test/evp_libctx_test.c b/test/evp_libctx_test.c
index 9940599b50d5ab5f15d3f96092a5eef123b3fdec..9efe64ac6dafd08a5ae59133ddbb4419898cc566 100644 (file)
--- a/test/evp_libctx_test.c
+++ b/test/evp_libctx_test.c
@@ -684,9 +684,12 @@ static int kem_rsa_params(void)
         && TEST_int_eq(EVP_PKEY_decapsulate(pubctx, secret, &secretlen, ct,
                                             sizeof(ct)), 0)
         && TEST_uchar_eq(secret[0], 0)
-        /* Test encapsulate fails if the mode is not set */
+        /* Test encapsulate succeeds even if the mode is not set */
         && TEST_int_eq(EVP_PKEY_encapsulate_init(pubctx, NULL), 1)
-        && TEST_int_eq(EVP_PKEY_encapsulate(pubctx, ct, &ctlen, secret, &secretlen), -2)
+        && TEST_int_eq(EVP_PKEY_encapsulate(pubctx, NULL, &ctlen, NULL, &secretlen), 1)
+        && TEST_true(ctlen <= sizeof(ct))
+        && TEST_true(secretlen <= sizeof(secret))
+        && TEST_int_eq(EVP_PKEY_encapsulate(pubctx, ct, &ctlen, secret, &secretlen), 1)
         /* Test setting a bad kem ops fail */
         && TEST_int_eq(EVP_PKEY_CTX_set_kem_op(pubctx, "RSA"), 0)
         && TEST_int_eq(EVP_PKEY_CTX_set_kem_op(pubctx, NULL), 0)

diff --git a/test/evp_pkey_dhkem_test.c b/test/evp_pkey_dhkem_test.c
index 97d40a27723c82a07cd81822ea11269aeaaef185..9aaa8e80d1cec4999ff62afd7cd1e15eec79b056 100644 (file)
--- a/test/evp_pkey_dhkem_test.c
+++ b/test/evp_pkey_dhkem_test.c
@@ -164,7 +164,7 @@ err:
     return ret;
 }
 
-/* Fail if the operation parameter is not set */
+/* Succeed even if the operation parameter is not set */
 static int test_no_operation_set(int tstid)
 {
     EVP_PKEY_CTX *ctx = rctx[tstid];
@@ -172,11 +172,11 @@ static int test_no_operation_set(int tstid)
     size_t len = 0;
 
     return TEST_int_eq(EVP_PKEY_encapsulate_init(ctx, NULL), 1)
-           && TEST_int_eq(EVP_PKEY_encapsulate(ctx, NULL, &len, NULL, NULL), -2)
+           && TEST_int_eq(EVP_PKEY_encapsulate(ctx, NULL, &len, NULL, NULL), 1)
            && TEST_int_eq(EVP_PKEY_decapsulate_init(ctx, NULL), 1)
            && TEST_int_eq(EVP_PKEY_decapsulate(ctx, NULL, &len,
                                                t->expected_enc,
-                                               t->expected_enclen), -2);
+                                               t->expected_enclen), 1);
 }
 
 /* Fail if the ikm is too small */

diff --git a/test/recipes/20-test_pkeyutl.t b/test/recipes/20-test_pkeyutl.t
index 7b600979a3a31150bcc097223a32ca288cf8151c..7c012c989e2a0230cf90c8aba79ccc59bfb90bea 100644 (file)
--- a/test/recipes/20-test_pkeyutl.t
+++ b/test/recipes/20-test_pkeyutl.t
@@ -241,17 +241,17 @@ SKIP: {
         if disabled("rsa"); # Note "rsa" isn't (yet?) disablable.
 
     # Self-compat
-    ok(run(app(([ 'openssl', 'pkeyutl', '-encap', '-kemop', 'RSASVE',
+    ok(run(app(([ 'openssl', 'pkeyutl', '-encap',
                   '-inkey', srctop_file('test', 'testrsa2048pub.pem'),
                   '-out', 'encap_out.bin', '-secret', 'secret.bin']))),
                   "RSA pubkey encapsulation");
-    ok(run(app(([ 'openssl', 'pkeyutl', '-decap', '-kemop', 'RSASVE',
+    ok(run(app(([ 'openssl', 'pkeyutl', '-decap',
                   '-inkey', srctop_file('test', 'testrsa2048.pem'),
                   '-in', 'encap_out.bin', '-secret', 'decap_secret.bin']))),
                   "RSA pubkey decapsulation");
     is(compare("secret.bin", "decap_secret.bin"), 0, "Secret is correctly decapsulated");
 
-    # Legacy CLI with decap output written to '-out'
+    # Legacy CLI with decap output written to '-out' and with '-kemop` specified
     ok(run(app(([ 'openssl', 'pkeyutl', '-decap', '-kemop', 'RSASVE',
                   '-inkey', srctop_file('test', 'testrsa2048.pem'),
                   '-in', 'encap_out.bin', '-out', 'decap_out.bin']))),