Introduce SSL_OP_SERVER_PREFERENCE to replace SSL_OP_CIPHER_SERVER_PREFERENCE misnomer

Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/27981)

diff --git a/CHANGES.md b/CHANGES.md
index 44503782db63a04c740ec0927cc38b5e8f81ce5b..e21a6e52edde5d1a2a754db66140dae81e082749 100644 (file)
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -31,6 +31,11 @@ OpenSSL 3.6
 
 ### Changes between 3.5 and 3.6 [xx XXX xxxx]
 
+ * Introduce SSL_OP_SERVER_PREFERENCE superceding misleadingly
+   named SSL_OP_CIPHER_SERVER_PREFERENCE.
+
+   *Michael Baentsch*
+
  * Introduces use of `<stdbool.h>` when handling JSON encoding in
    the OpenSSL codebase, replacing the previous use of `int` for
    these boolean values.

diff --git a/demos/guide/tls-server-block.c b/demos/guide/tls-server-block.c
index 45246ce4fe0fd854cdaeded0585e2995b94e7266..b2f548380af4c7217ed6977bec21c91497a7a934 100644 (file)
--- a/demos/guide/tls-server-block.c
+++ b/demos/guide/tls-server-block.c
@@ -127,10 +127,10 @@ int main(int argc, char *argv[])
     opts |= SSL_OP_NO_RENEGOTIATION;
 
     /*
-     * Most servers elect to use their own cipher preference rather than that of
-     * the client.
+     * Most servers elect to use their own cipher or group preference rather
+     * than that of the client.
      */
-    opts |= SSL_OP_CIPHER_SERVER_PREFERENCE;
+    opts |= SSL_OP_SERVER_PREFERENCE;
 
     /* Apply the selection options */
     SSL_CTX_set_options(ctx, opts);

diff --git a/doc/designs/quic-design/quic-api-ssl-funcs.md b/doc/designs/quic-design/quic-api-ssl-funcs.md
index 7bba549a67f80784924142c2d8fe0cb342a6cb97..6333bafab8509881ff108bcd43f8164fa7af367d 100644 (file)
--- a/doc/designs/quic-design/quic-api-ssl-funcs.md
+++ b/doc/designs/quic-design/quic-api-ssl-funcs.md
@@ -860,7 +860,7 @@ SECLEVEL; no changes are needed to facilitate this.
 
 Options we explicitly want to support:
 
-- `SSL_OP_CIPHER_SERVER_PREFERENCE`
+- `SSL_OP_SERVER_PREFERENCE`
 - `SSL_OP_DISABLE_TLSEXT_CA_NAMES`
 - `SSL_OP_NO_TX_CERTIFICATE_COMPRESSION`
 - `SSL_OP_NO_RX_CERTIFICATE_COMPRESSION`

diff --git a/doc/man3/SSL_CONF_cmd.pod b/doc/man3/SSL_CONF_cmd.pod
index 9338ffc01ddfe2c5f286906116b34e24af0e97c4..22baa9c192f3307df592b30b533d7fee3b9eeba1 100644 (file)
--- a/doc/man3/SSL_CONF_cmd.pod
+++ b/doc/man3/SSL_CONF_cmd.pod
@@ -59,7 +59,7 @@ Disables support for session tickets, same as setting B<SSL_OP_NO_TICKET>.
 
 Use server and not client preference order when determining which cipher suite,
 signature algorithm or elliptic curve to use for an incoming connection.
-Equivalent to B<SSL_OP_CIPHER_SERVER_PREFERENCE>. Only used by servers.
+Equivalent to B<SSL_OP_SERVER_PREFERENCE>. Only used by servers.
 
 =item B<-client_renegotiation>
 
@@ -570,7 +570,7 @@ B<SSL_OP_ECDH_SINGLE>. Only used by servers.
 B<ServerPreference>: use server and not client preference order when
 determining which cipher suite, signature algorithm or elliptic curve
 to use for an incoming connection.  Equivalent to
-B<SSL_OP_CIPHER_SERVER_PREFERENCE>. Only used by servers.
+B<SSL_OP_SERVER_PREFERENCE>. Only used by servers.
 
 B<PrioritizeChaCha>: prioritizes ChaCha ciphers when the client has a
 ChaCha20 cipher at the top of its preference list. This usually indicates

diff --git a/doc/man3/SSL_CTX_set1_curves.pod b/doc/man3/SSL_CTX_set1_curves.pod
index 017eefd3176a9f0ff8b104fd7ba3453d986f40bf..352fe343471ae54c6b807426b24f2700a2fb9ee3 100755 (executable)
--- a/doc/man3/SSL_CTX_set1_curves.pod
+++ b/doc/man3/SSL_CTX_set1_curves.pod
@@ -69,7 +69,7 @@ extension. The extension's preference order, to be evaluated by the server, is
 determined by the order of the elements in the array.
 
 For a TLS 1.2 server, the groups determine the selected group. If
-B<SSL_OP_CIPHER_SERVER_PREFERENCE> is set, the order of the elements in the
+B<SSL_OP_SERVER_PREFERENCE> is set, the order of the elements in the
 array determines the selected group. Otherwise, the order is ignored and the
 client's order determines the selection.
 
@@ -144,7 +144,7 @@ For a TLS 1.3 server, the groups in the string I<list> will be used to determine
 is used for the key agreement. The preference order of the group tuples is determined
 by the order of the tuples in the array, and the preference order of the groups within
 a group tuple is determined by the order of the groups in the tuple. Server preference
-can be enforced by setting B<SSL_OP_CIPHER_SERVER_PREFERENCE> using
+can be enforced by setting B<SSL_OP_SERVER_PREFERENCE> using
 B<SSL_set_options> (default: client preference).
 
 The server will select the group to be used for a key agreement using the following
@@ -156,7 +156,7 @@ pseudo-code algorithm:
              IF current key-share group is also part of current group tuple: SH, return success
          FOR each client supported groups
              IF current supported group is also part of current group tuple: HRR, return success
-     ELSE (= server preference = with SSL_OP_CIPHER_SERVER_PREFERENCE option set)
+     ELSE (= server preference = with SSL_OP_SERVER_PREFERENCE option set)
          FOR each group in current tuple
              IF current group is also part of client key-share groups: SH, return success
          FOR each group in current tuple

diff --git a/doc/man3/SSL_CTX_set1_sigalgs.pod b/doc/man3/SSL_CTX_set1_sigalgs.pod
index 0ab9654a34e7a4edb857e8c17c7fdea23a3bb02c..983371913f5067d96bd121cb77c0eb70691e00d5 100644 (file)
--- a/doc/man3/SSL_CTX_set1_sigalgs.pod
+++ b/doc/man3/SSL_CTX_set1_sigalgs.pod
@@ -61,8 +61,8 @@ signature algorithm in the client hello message.
 
 The supported signature algorithms set by a server are not sent to the
 client but are used to determine the set of shared signature algorithms
-and (if server preferences are set with SSL_OP_CIPHER_SERVER_PREFERENCE)
-their order.
+and (if server preferences are set with SSL_OP_SERVER_PREFERENCE) their
+order.
 
 The client authentication signature algorithms set by a server are sent
 in a certificate request message if client authentication is enabled,

diff --git a/doc/man3/SSL_CTX_set_options.pod b/doc/man3/SSL_CTX_set_options.pod
index 69a21570673a3a5e5951a602ffbc334e79d709a3..1e65ab8b3da98ae1de775fb7700ba096a64940cf 100644 (file)
--- a/doc/man3/SSL_CTX_set_options.pod
+++ b/doc/man3/SSL_CTX_set_options.pod
@@ -122,12 +122,14 @@ being set as well. Always ignored on the client.
 Allow legacy insecure renegotiation between OpenSSL and unpatched clients or
 servers. See the B<SECURE RENEGOTIATION> section for more details.
 
-=item SSL_OP_CIPHER_SERVER_PREFERENCE
+=item SSL_OP_SERVER_PREFERENCE
 
-When choosing a cipher, use the server's preferences instead of the client
-preferences. When not set, the SSL server will always follow the clients
-preferences. When set, the SSL/TLS server will choose following its
-own preferences.
+When choosing a cipher, signature, (TLS 1.2) curve or (TLS 1.3) group, use the
+server's preferences instead of the client preferences. When not set, the SSL
+server will always follow the clients preferences. When set, the SSL/TLS server
+will choose following its own preferences.
+Use of the old but somewhat misleading name SSL_OP_CIPHER_SERVER_PREFERENCE
+is still possible but discouraged.
 
 =item SSL_OP_CISCO_ANYCONNECT
 
@@ -349,12 +351,12 @@ L<SSL_set_num_tickets(3)>.
 
 =item SSL_OP_PRIORITIZE_CHACHA
 
-When SSL_OP_CIPHER_SERVER_PREFERENCE is set, temporarily reprioritize
+When SSL_OP_SERVER_PREFERENCE is set, temporarily reprioritize
 ChaCha20-Poly1305 ciphers to the top of the server cipher list if a
 ChaCha20-Poly1305 cipher is at the top of the client cipher list. This helps
 those clients (e.g. mobile) use ChaCha20-Poly1305 if that cipher is anywhere
 in the server cipher list; but still allows other clients to use AES and other
-ciphers. Requires B<SSL_OP_CIPHER_SERVER_PREFERENCE>.
+ciphers. Requires B<SSL_OP_SERVER_PREFERENCE>.
 
 =item SSL_OP_TLS_ROLLBACK_BUG
 
@@ -546,6 +548,10 @@ For that reason it is no longer possible use the B<SSL_OP_> macro values
 in preprocessor C<#if> conditions. However it is still possible to test
 whether these macros are defined or not.
 
+As of OpenSSL 3.6, use of the B<SSL_OP_CIPHER_SERVER_PREFERENCE> constant
+is discouraged and its semantics became available using the more aptly named
+B<SSL_OP_SERVER_PREFERENCE> constant.
+
 =head1 COPYRIGHT
 
 Copyright 2001-2023 The OpenSSL Project Authors. All Rights Reserved.

diff --git a/doc/man7/ossl-guide-tls-server-block.pod b/doc/man7/ossl-guide-tls-server-block.pod
index e6bd2b05ca425f874e003bb9272f66dbe79e29a4..a261f8990c8ed77e0f8ec221c24c232d67557426 100644 (file)
--- a/doc/man7/ossl-guide-tls-server-block.pod
+++ b/doc/man7/ossl-guide-tls-server-block.pod
@@ -89,10 +89,10 @@ Next we configure some option flags, see L<SSL_CTX_set_options(3)> for details:
     opts |= SSL_OP_NO_RENEGOTIATION;
 
     /*
-     * Most servers elect to use their own cipher preference rather than that of
-     * the client.
+     * Most servers elect to use their own cipher or group preference rather than
+     * that of the client.
      */
-    opts |= SSL_OP_CIPHER_SERVER_PREFERENCE;
+    opts |= SSL_OP_SERVER_PREFERENCE;
 
     /* Apply the selection options */
     SSL_CTX_set_options(ctx, opts);

diff --git a/include/openssl/ssl.h.in b/include/openssl/ssl.h.in
index f3c96fed164c795544cd3aadba6c2bf4bd74b216..05f6a1f0512b4acb9c4b81ec3218317924122e22 100644 (file)
--- a/include/openssl/ssl.h.in
+++ b/include/openssl/ssl.h.in
@@ -378,13 +378,16 @@ typedef int (*SSL_async_callback_fn)(SSL *s, void *arg);
 # define SSL_OP_ENABLE_MIDDLEBOX_COMPAT                  SSL_OP_BIT(20)
     /*
      * Prioritize Chacha20Poly1305 when client does.
-     * Modifies SSL_OP_CIPHER_SERVER_PREFERENCE
+     * Modifies SSL_OP_SERVER_PREFERENCE
      */
 # define SSL_OP_PRIORITIZE_CHACHA                        SSL_OP_BIT(21)
     /*
-     * Set on servers to choose the cipher according to server's preferences.
+     * Set on servers to choose cipher, curve or group according to server's
+     * preferences.
      */
-# define SSL_OP_CIPHER_SERVER_PREFERENCE                 SSL_OP_BIT(22)
+# define SSL_OP_SERVER_PREFERENCE                        SSL_OP_BIT(22)
+    /* Equivalent definition for backwards compatibility: */
+# define SSL_OP_CIPHER_SERVER_PREFERENCE SSL_OP_SERVER_PREFERENCE
     /*
      * If set, a server will allow a client to issue an SSLv3.0 version
      * number as latest version supported in the premaster secret, even when

diff --git a/ssl/s3_lib.c b/ssl/s3_lib.c
index 12c30f665eaea478c9e154270ddd94224c2a53ec..e82d921ae6403e32236b2f4a67b79b51d091abea 100644 (file)
--- a/ssl/s3_lib.c
+++ b/ssl/s3_lib.c
@@ -4353,7 +4353,7 @@ const SSL_CIPHER *ssl3_choose_cipher(SSL_CONNECTION *s, STACK_OF(SSL_CIPHER) *cl
     if (tls1_suiteb(s)) {
         prio = srvr;
         allow = clnt;
-    } else if (s->options & SSL_OP_CIPHER_SERVER_PREFERENCE) {
+    } else if (s->options & SSL_OP_SERVER_PREFERENCE) {
         prio = srvr;
         allow = clnt;
 

diff --git a/ssl/ssl_conf.c b/ssl/ssl_conf.c
index 070ab73f82b91f2adf66e8e03b514118285b3145..3d835ab33c92f1ad8b4145538b5dd06c6c1a2c04 100644 (file)
--- a/ssl/ssl_conf.c
+++ b/ssl/ssl_conf.c
@@ -382,7 +382,7 @@ static int cmd_Options(SSL_CONF_CTX *cctx, const char *value)
                          SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS),
         SSL_FLAG_TBL("Bugs", SSL_OP_ALL),
         SSL_FLAG_TBL_INV("Compression", SSL_OP_NO_COMPRESSION),
-        SSL_FLAG_TBL_SRV("ServerPreference", SSL_OP_CIPHER_SERVER_PREFERENCE),
+        SSL_FLAG_TBL_SRV("ServerPreference", SSL_OP_SERVER_PREFERENCE),
         SSL_FLAG_TBL_SRV("NoResumptionOnRenegotiation",
                          SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION),
         SSL_FLAG_TBL_SRV("DHSingle", SSL_OP_SINGLE_DH_USE),
@@ -842,7 +842,7 @@ static const ssl_switch_tbl ssl_cmd_switches[] = {
     {SSL_OP_NO_RX_CERTIFICATE_COMPRESSION, SSL_TFLAG_INV}, /* rx_cert_comp */
     {SSL_OP_SINGLE_ECDH_USE, 0}, /* ecdh_single */
     {SSL_OP_NO_TICKET, 0},      /* no_ticket */
-    {SSL_OP_CIPHER_SERVER_PREFERENCE, 0}, /* serverpref */
+    {SSL_OP_SERVER_PREFERENCE, 0}, /* serverpref */
     /* legacy_renegotiation */
     {SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION, 0},
     /* Allow client renegotiation */

diff --git a/ssl/ssl_local.h b/ssl/ssl_local.h
index c53ebc36ae9dfd4ebc5c7ac6456ff57cfaa9723b..b4e7d0ef7b346ac9611a6559e1b54773651234c8 100644 (file)
--- a/ssl/ssl_local.h
+++ b/ssl/ssl_local.h
@@ -3139,7 +3139,7 @@ long ossl_ctrl_internal(SSL *s, int cmd, long larg, void *parg, int no_quic);
 #define OSSL_QUIC_PERMITTED_OPTIONS_CONN        \
     (OSSL_LEGACY_SSL_OPTIONS                  | \
      OSSL_TLS1_2_OPTIONS                      | \
-     SSL_OP_CIPHER_SERVER_PREFERENCE          | \
+     SSL_OP_SERVER_PREFERENCE                 | \
      SSL_OP_DISABLE_TLSEXT_CA_NAMES           | \
      SSL_OP_NO_TX_CERTIFICATE_COMPRESSION     | \
      SSL_OP_NO_RX_CERTIFICATE_COMPRESSION     | \

diff --git a/ssl/statem/extensions_srvr.c b/ssl/statem/extensions_srvr.c
index 9a52164da39073f9860367b6fb3040ff7329db99..18fb5428176b24cc11a6055546689ddc35bfdb47 100644 (file)
--- a/ssl/statem/extensions_srvr.c
+++ b/ssl/statem/extensions_srvr.c
@@ -920,7 +920,7 @@ int tls_parse_ctos_key_share(SSL_CONNECTION *s, PACKET *pkt,
         int prio_group_idx = 0, candidate_group_idx = 0;
 
         /* Server or client preference ? */
-        if (s->options & SSL_OP_CIPHER_SERVER_PREFERENCE) {
+        if (s->options & SSL_OP_SERVER_PREFERENCE) {
             /* Server preference */
             /* Is there overlap with a key share group?  */
             check_overlap(s,

diff --git a/ssl/t1_lib.c b/ssl/t1_lib.c
index 1f873ed8ca1b710c0de7aa743065e5f6dcc488e1..96bbbdb8768b2e1656206c2a62c53156182da116 100644 (file)
--- a/ssl/t1_lib.c
+++ b/ssl/t1_lib.c
@@ -1038,7 +1038,7 @@ uint16_t tls1_shared_group(SSL_CONNECTION *s, int nmatch)
      * If server preference set, our groups are the preference order
      * otherwise peer decides.
      */
-    if (s->options & SSL_OP_CIPHER_SERVER_PREFERENCE) {
+    if (s->options & SSL_OP_SERVER_PREFERENCE) {
         tls1_get_supported_groups(s, &pref, &num_pref);
         tls1_get_peer_groups(s, &supp, &num_supp);
     } else {
@@ -3515,7 +3515,7 @@ static int tls1_set_shared_sigalgs(SSL_CONNECTION *s)
         conflen = c->conf_sigalgslen;
     } else
         conflen = tls12_get_psigalgs(s, 0, &conf);
-    if (s->options & SSL_OP_CIPHER_SERVER_PREFERENCE || is_suiteb) {
+    if (s->options & SSL_OP_SERVER_PREFERENCE || is_suiteb) {
         pref = conf;
         preflen = conflen;
         allow = s->s3.tmp.peer_sigalgs;

diff --git a/test/tls13groupselection_test.c b/test/tls13groupselection_test.c
index 01d1eded5f87ca85f6b9f036a9caa540bb10232b..4f971b600cc6e4eb97e4f0e5297f63892f1e1c08 100644 (file)
--- a/test/tls13groupselection_test.c
+++ b/test/tls13groupselection_test.c
@@ -441,7 +441,7 @@ static int test_groupnegotiation(const struct tls13groupselection_test_st *curre
         TEST_true_or_end(SSL_CTX_set_min_proto_version(client_ctx, TLS1_3_VERSION));
         TEST_true_or_end(SSL_CTX_set_min_proto_version(server_ctx, TLS1_3_VERSION));
         if (current_test_vector->preference == SERVER_PREFERENCE)
-            SSL_CTX_set_options(server_ctx, SSL_OP_CIPHER_SERVER_PREFERENCE);
+            SSL_CTX_set_options(server_ctx, SSL_OP_SERVER_PREFERENCE);
     }
     /* Creation of the SSL objects */
     if (!TEST_true(create_ssl_objects(server_ctx, client_ctx,
@@ -461,7 +461,7 @@ static int test_groupnegotiation(const struct tls13groupselection_test_st *curre
         TEST_true_or_end(SSL_set_min_proto_version(serverssl, TLS1_3_VERSION));
 
         if (current_test_vector->preference == SERVER_PREFERENCE)
-            SSL_set_options(serverssl, SSL_OP_CIPHER_SERVER_PREFERENCE);
+            SSL_set_options(serverssl, SSL_OP_SERVER_PREFERENCE);
     }
 
     /* We set the message callback on the client side (which checks SH/HRR) */