TLS 1.3 certificate_authorities extension in ClientHello

.gitignore

@@ -115,6 +115,8 @@ android/wolfssljni-ndk-sample/proguard-project.txt
 /tls/server-tls-uart
 /tls/server-tls-verifycallback
 /tls/server-tls-writedup
+/tls/client-tls13-certauth-clienthello
+/tls/server-tls13-certauth-clienthello
 /tls/client-ech
 /tls/client-ech-local
 /tls/server-ech-local

tls/README.md

@@ -1413,6 +1413,35 @@ Execute them like so:
 ./server-tls-posthsauth 127.0.0.1
 ```
 
+## TLS Example with certificate_authorities extension in ClientHello message
+
+See `client-tls13-certauth-clienthello.c` and `server-tls13-certauth-clienthello.c`. These applications show how to use the TLS 1.3 [certificate_authorities](https://datatracker.ietf.org/doc/html/rfc8446#section-4.2.4) extension to let the client send the names of its supported certificate authorities inside the ClientHello message, so that the server can perform certificate selection based on them. This can be useful in scenarios where the server has multiple certificates issued by separate CAs.
+
+To use this example, you must enable full OpenSSL compatibility. Build and install wolfSSL like so:
+
+```
+$ ./autogen.sh
+$ ./configure --enable-opensslall
+$ make
+$ sudo make install
+```
+
+Then build the examples as follows:
+
+```
+make client-tls13-certauth-clienthello server-tls13-certauth-clienthello
+```
+
+Execute them like so:
+
+```
+./server-tls13-certauth-clienthello
+```
+
+```
+./client-tls13-certauth-clienthello 127.0.0.1
+```
+
 ## Support
 
 Please contact wolfSSL at [email protected] with any questions, bug fixes,

tls/client-tls13-certauth-clienthello.c

@@ -0,0 +1,223 @@
+/* client-tls13-certauth-clienthello.c
+ *
+ * Copyright (C) 2006-2025 wolfSSL Inc.
+ *
+ * This file is part of wolfSSL. (formerly known as CyaSSL)
+ *
+ * wolfSSL is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * wolfSSL is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
+ */
+
+/* This example showcases the usage of the TLS 1.3 certificate_authorities
+ * extension in the ClientHello message, to indicate to the server which
+ * certificate authorities the client supports, guiding certificate selection.
+ *
+ * Example wolfSSL config for this example: ./configure --enable-opensslall
+ */
+
+/* the usual suspects */
+#include <stdlib.h>
+#include <stdio.h>
+#include <string.h>
+
+/* socket includes */
+#include <sys/socket.h>
+#include <arpa/inet.h>
+#include <netinet/in.h>
+#include <unistd.h>
+
+/* wolfSSL */
+#ifndef WOLFSSL_USER_SETTINGS
+    #include <wolfssl/options.h>
+#endif
+#include <wolfssl/ssl.h>
+#include <wolfssl/wolfio.h>
+#include <wolfssl/wolfcrypt/error-crypt.h>
+
+#define DEFAULT_PORT 11111
+
+#define CERT_FILE "../certs/client-cert.pem"
+#define KEY_FILE  "../certs/client-key.pem"
+#define CA_FILE   "../certs/ca-cert.pem"
+
+int main(int argc, char** argv)
+{
+    int ret = 0;
+#if !defined(NO_WOLFSSL_CLIENT) && !defined(NO_WOLFSSL_SERVER) && \
+    !defined(WOLFSSL_NO_CA_NAMES) && !defined(NO_CERTS) && \
+    defined(WOLFSSL_TLS13) && (defined(OPENSSL_EXTRA) || \
+    defined(OPENSSL_EXTRA_X509_SMALL)) && (defined(OPENSSL_ALL) || \
+    defined(WOLFSSL_NGINX) || defined(HAVE_LIGHTY))
+
+    int                sockfd = SOCKET_INVALID;
+    struct sockaddr_in servAddr;
+    char               buff[256];
+    size_t             len;
+
+    /* declare wolfSSL objects */
+    WOLFSSL_CTX* ctx = NULL;
+    WOLFSSL*     ssl = NULL;
+
+    /* Declare CA name object */
+    WOLF_STACK_OF(WOLFSSL_X509_NAME)* caName = NULL;
+
+    /* Check for proper calling convention */
+    if (argc != 2) {
+        printf("usage: %s <IPv4 address>\n", argv[0]);
+        return 0;
+    }
+
+    /* Create a socket that uses an internet IPv4 address,
+     * Sets the socket to be stream based (TCP),
+     * 0 means choose the default protocol. */
+    if ((sockfd = socket(AF_INET, SOCK_STREAM, 0)) == -1) {
+        fprintf(stderr, "ERROR: failed to create the socket\n");
+        ret = -1; goto exit;
+    }
+
+    /* Initialize the server address struct with zeros */
+    memset(&servAddr, 0, sizeof(servAddr));
+
+    /* Fill in the server address */
+    servAddr.sin_family = AF_INET;             /* using IPv4      */
+    servAddr.sin_port   = htons(DEFAULT_PORT); /* on DEFAULT_PORT */
+
+    /* Get the server IPv4 address from the command line call */
+    if (inet_pton(AF_INET, argv[1], &servAddr.sin_addr) != 1) {
+        fprintf(stderr, "ERROR: invalid address\n");
+        ret = -1; goto exit;
+    }
+
+    /* Connect to the server */
+    if ((ret = connect(sockfd, (struct sockaddr*) &servAddr, sizeof(servAddr)))
+         == -1) {
+        fprintf(stderr, "ERROR: failed to connect\n");
+        goto exit;
+    }
+
+    /*---------------------------------*/
+    /* Start of wolfSSL initialization and configuration */
+    /*---------------------------------*/
+
+    /* Initialize wolfSSL */
+    if ((ret = wolfSSL_Init()) != WOLFSSL_SUCCESS) {
+        fprintf(stderr, "ERROR: Failed to initialize the library\n");
+        goto exit;
+    }
+
+    /* Create and initialize WOLFSSL_CTX */
+    if ((ctx = wolfSSL_CTX_new(wolfTLSv1_3_client_method())) == NULL) {
+        fprintf(stderr, "ERROR: failed to create WOLFSSL_CTX\n");
+        ret = -1; goto exit;
+    }
+
+    /* Load client certificate into WOLFSSL_CTX */
+    if ((ret = wolfSSL_CTX_use_certificate_file(ctx, CERT_FILE, WOLFSSL_FILETYPE_PEM))
+        != WOLFSSL_SUCCESS) {
+        fprintf(stderr, "ERROR: failed to load %s, please check the file.\n",
+                CERT_FILE);
+        goto exit;
+    }
+
+    /* Load client key into WOLFSSL_CTX */
+    if ((ret = wolfSSL_CTX_use_PrivateKey_file(ctx, KEY_FILE, WOLFSSL_FILETYPE_PEM))
+        != WOLFSSL_SUCCESS) {
+        fprintf(stderr, "ERROR: failed to load %s, please check the file.\n",
+                KEY_FILE);
+        goto exit;
+    }
+
+    /* Load CA certificate into WOLFSSL_CTX */
+    if ((ret = wolfSSL_CTX_load_verify_locations(ctx, CA_FILE, NULL))
+         != WOLFSSL_SUCCESS) {
+        fprintf(stderr, "ERROR: failed to load %s, please check the file.\n",
+                CA_FILE);
+        goto exit;
+    }
+
+    /* Load the CA certificate name to send in certificate_authorities extension
+     */
+    if ((caName = wolfSSL_load_client_CA_file(CA_FILE)) == NULL) {
+        fprintf(stderr, "ERROR: failed to load CA name from %s, please check "
+                "the file.\n", CA_FILE);
+        goto exit;
+    }
+
+    /* Set CA name to send in certificate_authorities extension */
+    wolfSSL_CTX_set0_CA_list(ctx, caName);
+
+    /* Create a WOLFSSL object */
+    if ((ssl = wolfSSL_new(ctx)) == NULL) {
+        fprintf(stderr, "ERROR: failed to create WOLFSSL object\n");
+        ret = -1; goto exit;
+    }
+
+    /* Attach wolfSSL to the socket */
+    if ((ret = wolfSSL_set_fd(ssl, sockfd)) != WOLFSSL_SUCCESS) {
+        fprintf(stderr, "ERROR: Failed to set the file descriptor\n");
+        goto exit;
+    }
+
+    /* Connect to wolfSSL on the server side */
+    if ((ret = wolfSSL_connect(ssl)) != WOLFSSL_SUCCESS) {
+        fprintf(stderr, "ERROR: failed to connect to wolfSSL\n");
+        goto exit;
+    }
+
+    /* Get a message for the server from stdin */
+    printf("Message for server: ");
+    memset(buff, 0, sizeof(buff));
+    if (fgets(buff, sizeof(buff), stdin) == NULL) {
+        fprintf(stderr, "ERROR: failed to get message for server\n");
+        ret = -1; goto exit;
+    }
+    len = strnlen(buff, sizeof(buff));
+
+    /* Send the message to the server */
+    if ((ret = wolfSSL_write(ssl, buff, len)) != len) {
+        fprintf(stderr, "ERROR: failed to write entire message\n");
+        fprintf(stderr, "%d bytes of %d bytes were sent", ret, (int) len);
+        goto exit;
+    }
+
+    /* Read the server data into our buff array */
+    memset(buff, 0, sizeof(buff));
+    if ((ret = wolfSSL_read(ssl, buff, sizeof(buff)-1)) < 0) {
+        fprintf(stderr, "ERROR: failed to read\n");
+        goto exit;
+    }
+
+    /* Print to stdout any data the server sends */
+    printf("Server: %s\n", buff);
+
+    /* Return reporting a success */
+    ret = 0;
+
+exit:
+    /* Cleanup and return */
+    if (sockfd != SOCKET_INVALID)
+        close(sockfd);          /* Close the connection to the server       */
+    if (ssl)
+        wolfSSL_free(ssl);      /* Free the wolfSSL object                  */
+    if (ctx)
+        wolfSSL_CTX_free(ctx);  /* Free the wolfSSL context object          */
+    wolfSSL_Cleanup();          /* Cleanup the wolfSSL environment          */
+#else
+    printf("Example requires specific wolfSSL features\n");
+#endif
+    (void)argc;
+    (void)argv;
+
+    return ret;
+}