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)

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.

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);

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`

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

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

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,

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.

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);

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

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;
 

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 */

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     | \

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,

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;

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) */