Add RFC8701 GREASE Support

This adds support for RFC8701, which can be used in testing to ensure
TLS extensibility and proper processing. This is different from fuzzing
in that this can be done on both the client and the server, and
allows the connection to complete.

The API is public to allow end-users to do their own testing with GREASE.

Author: tmshort

CHANGES.md

@@ -878,6 +878,13 @@ OpenSSL 3.2
 
    *Richard Levitte*
 
+ * Add support for RFC8701 GREASE. Extra values can be added to known
+   extensions and cipher lists in the ClientHello. Additional extensions can
+   also be added. This is intended for testing unknown values in extensions
+   and cipher lists, and not for implementing custom extensions or ciphers.
+
+   *Todd Short*
+
  * The BLAKE2b hash algorithm supports a configurable output length
    by setting the "size" parameter.
 

doc/build.info

@@ -2235,6 +2235,10 @@ DEPEND[html/man3/SSL_CTX_add_session.html]=man3/SSL_CTX_add_session.pod
 GENERATE[html/man3/SSL_CTX_add_session.html]=man3/SSL_CTX_add_session.pod
 DEPEND[man/man3/SSL_CTX_add_session.3]=man3/SSL_CTX_add_session.pod
 GENERATE[man/man3/SSL_CTX_add_session.3]=man3/SSL_CTX_add_session.pod
+DEPEND[html/man3/SSL_CTX_clean_grease.html]=man3/SSL_CTX_clean_grease.pod
+GENERATE[html/man3/SSL_CTX_clean_grease.html]=man3/SSL_CTX_clean_grease.pod
+DEPEND[man/man3/SSL_CTX_clean_grease.3]=man3/SSL_CTX_clean_grease.pod
+GENERATE[man/man3/SSL_CTX_clean_grease.3]=man3/SSL_CTX_clean_grease.pod
 DEPEND[html/man3/SSL_CTX_config.html]=man3/SSL_CTX_config.pod
 GENERATE[html/man3/SSL_CTX_config.html]=man3/SSL_CTX_config.pod
 DEPEND[man/man3/SSL_CTX_config.3]=man3/SSL_CTX_config.pod
@@ -3604,6 +3608,7 @@ html/man3/SSL_CONF_cmd_argv.html \
 html/man3/SSL_CTX_add1_chain_cert.html \
 html/man3/SSL_CTX_add_extra_chain_cert.html \
 html/man3/SSL_CTX_add_session.html \
+html/man3/SSL_CTX_clean_grease.html \
 html/man3/SSL_CTX_config.html \
 html/man3/SSL_CTX_ctrl.html \
 html/man3/SSL_CTX_dane_enable.html \
@@ -4276,6 +4281,7 @@ man/man3/SSL_CONF_cmd_argv.3 \
 man/man3/SSL_CTX_add1_chain_cert.3 \
 man/man3/SSL_CTX_add_extra_chain_cert.3 \
 man/man3/SSL_CTX_add_session.3 \
+man/man3/SSL_CTX_clean_grease.3 \
 man/man3/SSL_CTX_config.3 \
 man/man3/SSL_CTX_ctrl.3 \
 man/man3/SSL_CTX_dane_enable.3 \

doc/man3/SSL_CTX_clean_grease.pod

@@ -0,0 +1,129 @@
+=pod
+
+=head1 NAME
+
+SSL_CTX_add_grease_to_extension,
+SSL_CTX_add_grease_to_ciphers,
+SSL_CTX_add_grease_extension,
+SSL_CTX_clean_grease - Add GREASE (RFC8701) to the TLS handshake
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_CTX_add_grease_to_extension(SSL_CTX *ctx, unsigned int extension,
+                                     unsigned int value);
+ int SSL_CTX_add_grease_to_ciphers(SSL_CTX *ctx, unsigned int value);
+ int SSL_CTX_add_grease_extension(SSL_CTX *ctx, unsigned int extension,
+                                  unsigned char* value, size_t length);
+ void SSL_CTX_clean_grease(SSL_CTX *ctx);
+
+=head1 DESCRIPTION
+
+SSL_CTX_add_grease_to_extension() adds a GREASE value to a known extension.
+If the extension cannot support GREASE values, an error is returned.
+These GREASE values only apply to the ClientHello.
+
+SSL_CTX_add_grease_to_ciphers() adds a 16-bit GREASE value to the list of ciphers.
+These GREASE values only apply to the ClientHello.
+
+SSL_CTX_add_grease_extension() adds a new GREASE extionsion with the given
+payload. If the extension is a known, supported extension, an error is returned.
+
+SSL_CTX_clean_grease() removes GREASE values from the b<ctx>.
+
+=head1 NOTES
+
+GREASE is defined in RFC8701 "Applying Generate Random Extensions And Sustain
+Extensibility" to TLS Extensibility. It is a method of adding unsupported
+values to extensions and other fields to ensure that breakage (in terms of
+protocol or program) does not occur.
+
+These functions store these GREASE values to an SSL_CTX object, which are then
+added to the handshake of any SSL object that refereces the SSL_CTX object.
+
+A set of GREASE values are defined as reserved: two-byte values where the lower
+nibble of each byte is 0xA. These values may not be used by other RFCs.
+This API does not require that only these values are used; any value may be used
+as a GREASE value, as long as it doesn't conflict with an existing extension
+number.
+
+GREASE values are prepended to the normal extension values.
+
+The SSL_CTX_add_grease_to_extension() function supports the following extensions:
+
+=over 4
+
+=item TLSEXT_TYPE_supported_versions
+
+=item TLSEXT_TYPE_signature_algorithms
+
+=item TLSEXT_TYPE_supported_groups
+
+=item TLSEXT_TYPE_compress_certificate
+
+The above extensions support 16-bit GREASE values.
+
+=item TLSEXT_TYPE_psk_kex_modes
+
+The above extension supports 8-bit GREASE values.
+
+=item TLSEXT_TYPE_key_share
+
+The above extension adds a 16-bit GREASE encoded-point type (lower 16-bits of
+b<value>) with the whole contents of b<value> (sizeof(unsigned int)) used as
+the encoded-point value.
+
+=back
+
+The SSL_CTX_add_grease_extension() function will add all configuted GREASE
+extentions to the following handshake messages:
+
+=over 4
+
+=item Client Hello
+
+This applies only to the client.
+
+=item Server Hello
+
+This applies only to the server.
+
+=item Certificate Request
+
+This applies only to the server when doing TLSv1.3.
+
+=back
+
+GREASE values are not (supposed to be) processed by servers and clients. They
+are present to ensure TLS extensibility.
+
+=head1 RETURN VALUES
+
+The SSL_CTX_add_grease_to_extension(), SSL_CTX_add_grease_to_ciphers(),
+and SSL_CTX_add_grease_extension() functions
+return 1 on success and 0 on failure.
+
+Success means that the GREASE value was stored.
+
+=head1 SEE ALSO
+
+L<SSL_CTX_new(3)>, L<SSL_new(3)>
+
+=head1 HISTORY
+
+The SSL_CTX_add_grease_to_extension(),
+SSL_CTX_add_grease_to_ciphers(),
+SSL_CTX_add_grease_extension(), and
+SSL_CTX_clean_grease() functions were added in Openssl 3.6.
+
+=head1 COPYRIGHT
+
+Copyright 2025 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut

include/openssl/ssl.h.in

@@ -2880,6 +2880,14 @@ int SSL_set_quic_tls_transport_params(SSL *s,
 
 int SSL_set_quic_tls_early_data_enabled(SSL *s, int enabled);
 
+/* RFC 8701 GREASE support */
+
+int SSL_CTX_add_grease_to_extension(SSL_CTX *ctx, unsigned int extension, unsigned int value);
+int SSL_CTX_add_grease_to_ciphers(SSL_CTX *ctx, unsigned int value);
+int SSL_CTX_add_grease_extension(SSL_CTX *ctx, unsigned int extension, unsigned char *value,
+                                 size_t length);
+void SSL_CTX_clean_grease(SSL_CTX *ctx);
+
 # ifdef  __cplusplus
 }
 # endif

ssl/ssl_lib.c

@@ -4360,6 +4360,7 @@ void SSL_CTX_free(SSL_CTX *a)
 
     X509_VERIFY_PARAM_free(a->param);
     dane_ctx_final(&a->dane);
+    SSL_CTX_clean_grease(a);
 
     /*
      * Free internal session cache. However: the remove_cb() may reference
@@ -8321,3 +8322,108 @@ int SSL_CTX_get0_server_cert_type(const SSL_CTX *ctx, unsigned char **t, size_t
     *len = ctx->server_cert_type_len;
     return 1;
 }
+
+static int ossl_grease_common(SSL_CTX *ctx, unsigned int extension,
+                              int new_extension,
+                              unsigned int value,
+                              unsigned char *data, size_t length)
+{
+    OSSL_GREASE *g;
+    OSSL_GREASE *newg = NULL;
+    int ret = 0;
+
+    if (!CRYPTO_THREAD_write_lock(ctx->lock))
+        return 0;
+    /* Duplicate check */
+    for (g = ctx->grease; g != NULL; g = g->next) {
+        if (g->extension == extension && g->value == value) {
+            /* don't care about the data contents */
+            goto err;
+        }
+    }
+    if ((newg = OPENSSL_zalloc(sizeof(*newg))) == NULL)
+        goto err;
+    newg->extension = extension;
+    newg->value = value;
+    newg->new_extension = new_extension;
+    if (data != NULL) {
+        if ((newg->data = OPENSSL_memdup(data, length)) == NULL)
+            goto err;
+        newg->length = length;
+    }
+    newg->next = ctx->grease;
+    ctx->grease = newg;
+    ret = 1;
+    newg = NULL;
+
+ err:
+    if (newg != NULL) {
+        OPENSSL_free(newg->data);
+        OPENSSL_free(newg);
+    }
+    CRYPTO_THREAD_unlock(ctx->lock);
+    return ret;
+}
+
+int SSL_CTX_add_grease_to_extension(SSL_CTX *ctx, unsigned int extension, unsigned int value)
+{
+    /* Add an entry for a known (supported) extension */
+    if (!SSL_extension_supported(extension))
+        return 0;
+
+    /* Not all extensions support grease though */
+    switch (extension) {
+    case TLSEXT_TYPE_supported_versions:
+    case TLSEXT_TYPE_signature_algorithms:
+    case TLSEXT_TYPE_supported_groups:
+    case TLSEXT_TYPE_psk_kex_modes:
+    case TLSEXT_TYPE_key_share:
+    case TLSEXT_TYPE_compress_certificate:
+    case TLSEXT_TYPE_server_cert_type:
+    case TLSEXT_TYPE_client_cert_type:
+        break;
+    default:
+        return 0;
+    }
+
+    /* Does not apply to servers */
+    return ossl_grease_common(ctx, extension, 0, value, NULL, 0);
+}
+
+int SSL_CTX_add_grease_to_ciphers(SSL_CTX *ctx, unsigned int cipher)
+{
+    /* Add an entry for ciphers - not an extension! */
+    /* Does not apply to servers */
+    return ossl_grease_common(ctx, OSSL_GREASE_CIPHER, 0, cipher, NULL, 0);
+}
+
+/* Could this just be done via a custom extension instead, or is this easier? */
+int SSL_CTX_add_grease_extension(SSL_CTX *ctx, unsigned int extension, unsigned char *value,
+                                 size_t length)
+{
+    /* Add an entry for a (new) extension */
+    /* Invalid extension */
+    if (extension > 0xFFFF)
+        return 0;
+    /* This is the real limit, but not really a practical one */
+    if (length > 0xFFFF)
+        return 0;
+    /* Check to make sure it's not a pre-existing/supported extension */
+    if (SSL_extension_supported(extension))
+        return 0;
+
+    return ossl_grease_common(ctx, extension, 1, 0, value, length);
+}
+
+void SSL_CTX_clean_grease(SSL_CTX *ctx)
+{
+    /* Delete all GREASE entries */
+    OSSL_GREASE *g;
+
+    while (ctx->grease) {
+        g = ctx->grease;
+        ctx->grease = g->next;
+        OPENSSL_free(g->data);
+        OPENSSL_free(g);
+    }
+}

ssl/ssl_local.h

@@ -1216,6 +1216,8 @@ struct ssl_ctx_st {
 # ifndef OPENSSL_NO_QLOG
     char *qlog_title; /* Session title for qlog */
 # endif
+
+    struct ossl_grease_st *grease;
 };
 
 typedef struct ossl_quic_tls_callbacks_st {
@@ -3171,4 +3173,17 @@ long ossl_ctrl_internal(SSL *s, int cmd, long larg, void *parg, int no_quic);
      SSL_DOMAIN_FLAG_BLOCKING |                 \
      SSL_DOMAIN_FLAG_LEGACY_BLOCKING)
 
+/* EXTENSION < 0xFFFF is the actual extension value */
+# define OSSL_GREASE_CIPHER 0x10001
+
+struct ossl_grease_st {
+    struct ossl_grease_st *next;
+    unsigned int extension;
+    int new_extension;
+    unsigned int value;
+    unsigned char *data;
+    size_t length;
+};
+typedef struct ossl_grease_st OSSL_GREASE;
+
 #endif

ssl/statem/extensions.c

@@ -890,6 +890,25 @@ int tls_construct_extensions(SSL_CONNECTION *s, WPACKET *pkt,
         /* SSLfatal() already called */
         return 0;
     }
+    /* Add GREASE extensions */
+    if ((context & (SSL_EXT_CLIENT_HELLO
+                    | SSL_EXT_TLS1_3_CERTIFICATE_REQUEST
+                    | SSL_EXT_TLS1_2_SERVER_HELLO
+                    | SSL_EXT_TLS1_3_SERVER_HELLO
+                    | SSL_EXT_TLS1_3_NEW_SESSION_TICKET)) != 0) {
+        SSL_CTX *ctx = SSL_CONNECTION_GET_CTX(s);
+        OSSL_GREASE *g;
+
+        for (g = ctx->grease; g != NULL; g = g->next) {
+            if (g->new_extension) {
+                if (!WPACKET_put_bytes_u16(pkt, g->extension)
+                        || !WPACKET_sub_memcpy_u16(pkt, g->data, g->length)) {
+                    SSLfatal(s, SSL_AD_INTERNAL_ERROR, ERR_R_INTERNAL_ERROR);
+                    return 0;
+                }
+            }
+        }
+    }
 
     for (i = 0, thisexd = ext_defs; i < OSSL_NELEM(ext_defs); i++, thisexd++) {
         EXT_RETURN (*construct)(SSL_CONNECTION *s, WPACKET *pkt,
@@ -1813,7 +1832,8 @@ static EXT_RETURN tls_construct_compress_certificate(SSL_CONNECTION *sc, WPACKET
 
     if (!WPACKET_put_bytes_u16(pkt, TLSEXT_TYPE_compress_certificate)
             || !WPACKET_start_sub_packet_u16(pkt)
-            || !WPACKET_start_sub_packet_u8(pkt))
+            || !WPACKET_start_sub_packet_u8(pkt)
+            || !tls_add_grease16_to_packet(sc, pkt, TLSEXT_TYPE_compress_certificate))
         goto err;
 
     for (i = 0; sc->cert_comp_prefs[i] != TLSEXT_comp_cert_none; i++) {