Tag SSL_CREDENTIALs with an id and record the selected id at handshake completion

Author: Alex Choulos

boringssl-static/src/test/java/io/netty/internal/tcnative/SSLCredentialIdTest.java

@@ -0,0 +1,98 @@
+/*
+ * Copyright 2026 The Netty Project
+ *
+ * The Netty Project licenses this file to you under the Apache License,
+ * version 2.0 (the "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at:
+ *
+ *   https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations
+ * under the License.
+ */
+package io.netty.internal.tcnative;
+
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.Test;
+
+import java.io.File;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+public class SSLCredentialIdTest {
+
+    @BeforeAll
+    public static void loadNativeLib() throws Exception {
+        String testClassesRoot = SSLCredentialIdTest.class.getProtectionDomain().getCodeSource().getLocation().getFile();
+        File[] directories = new File(testClassesRoot + File.separator + "META-INF" + File.separator + "native")
+                .listFiles();
+        if (directories == null || directories.length != 1) {
+            throw new IllegalStateException("Could not find platform specific native directory");
+        }
+        String libName = System.mapLibraryName("netty_tcnative")
+                // Fix the filename (this is needed for macOS).
+                .replace(".dylib", ".jnilib");
+        System.load(directories[0].getAbsoluteFile() + File.separator + libName);
+        Library.initialize();
+    }
+
+    @Test
+    public void newCredentialsHavePositiveDistinctIds() throws Exception {
+        long x509 = SSLCredential.newX509();
+        long delegated = SSLCredential.newDelegated();
+        try {
+            long x509Id = SSLCredential.getId(x509);
+            long delegatedId = SSLCredential.getId(delegated);
+            assertTrue(x509Id > 0);
+            assertTrue(delegatedId > 0);
+            assertNotEquals(x509Id, delegatedId);
+        } finally {
+            SSLCredential.free(x509);
+            SSLCredential.free(delegated);
+        }
+    }
+
+    @Test
+    public void idCannotBeReassigned() throws Exception {
+        long cred = SSLCredential.newX509();
+        try {
+            long id = SSLCredential.getId(cred);
+            assertThrows(IllegalStateException.class, () -> SSLCredential.setId0(cred, id + 1));
+            assertEquals(id, SSLCredential.getId(cred));
+        } finally {
+            SSLCredential.free(cred);
+        }
+    }
+
+    @Test
+    public void nonPositiveIdIsRejected() throws Exception {
+        long cred = SSLCredential.newX509();
+        try {
+            assertThrows(IllegalArgumentException.class, () -> SSLCredential.setId0(cred, 0));
+            assertThrows(IllegalArgumentException.class, () -> SSLCredential.setId0(cred, -1));
+        } finally {
+            SSLCredential.free(cred);
+        }
+    }
+
+    @Test
+    public void freshSslHasNoSelectedCredentialId() throws Exception {
+        long ctx = SSLContext.make(SSL.SSL_PROTOCOL_TLSV1_2, SSL.SSL_MODE_SERVER);
+        try {
+            long ssl = SSL.newSSL(ctx, true);
+            try {
+                assertEquals(0, SSL.getSelectedCredentialId(ssl));
+            } finally {
+                SSL.freeSSL(ssl);
+            }
+        } finally {
+            SSLContext.free(ctx);
+        }
+    }
+}

openssl-classes/src/main/java/io/netty/internal/tcnative/SSL.java

@@ -1004,6 +1004,26 @@ public static AsyncTask getAsyncTask(long ssl) {
      */
     public static native long getSelectedCredential(long ssl) throws Exception;
 
+    /**
+     * Get the id of the credential selected for an SSL instance, as assigned by {@link SSLCredential#newX509()} or
+     * {@link SSLCredential#newDelegated()}.
+     *
+     * <p>Returns:
+     * <ul>
+     *   <li>during a handshake that has already selected a credential, the id of that credential;</li>
+     *   <li>otherwise, the id recorded by the most recent completed handshake;</li>
+     *   <li>{@code 0} when no credential was selected, when the credential came from a legacy API, or when no
+     *   handshake has completed yet.</li>
+     * </ul>
+     *
+     * <p>This is a BoringSSL-specific feature.</p>
+     *
+     * @param ssl the SSL instance (SSL *)
+     * @return the selected credential id, or {@code 0}
+     * @throws Exception if an error occurred
+     */
+    public static native long getSelectedCredentialId(long ssl) throws Exception;
+
     /**
      * Get the name of the group used by ssl's most recently completed handshake, or {@code null} if not applicable.
      *

openssl-classes/src/main/java/io/netty/internal/tcnative/SSLCredential.java

@@ -15,6 +15,8 @@
  */
 package io.netty.internal.tcnative;
 
+import java.util.concurrent.atomic.AtomicLong;
+
 /**
  * SSL_CREDENTIAL management for BoringSSL.
  * 
@@ -32,6 +34,8 @@
  */
 public final class SSLCredential {
 
+    private static final AtomicLong NEXT_ID = new AtomicLong();
+
     private SSLCredential() { }
 
     /**
@@ -44,7 +48,43 @@ private SSLCredential() { }
      * @return the SSL_CREDENTIAL instance (SSL_CREDENTIAL *)
      * @throws Exception if an error occurred
      */
-    public static native long newX509() throws Exception;
+    public static long newX509() throws Exception {
+        return assignId(newX509Native());
+    }
+
+    private static native long newX509Native() throws Exception;
+
+    private static long assignId(long cred) throws Exception {
+        try {
+            setId0(cred, NEXT_ID.incrementAndGet());
+        } catch (Throwable t) {
+            // Don't leak the credential if tagging fails.
+            free(cred);
+            throw t;
+        }
+        return cred;
+    }
+
+    /**
+     * Assign the id of an SSL_CREDENTIAL. A credential can only be assigned an id once.
+     *
+     * @param cred the SSL_CREDENTIAL instance (SSL_CREDENTIAL *)
+     * @param id the id, which must be positive
+     * @throws IllegalArgumentException if {@code id} is not positive
+     * @throws IllegalStateException if the credential already has an id
+     */
+    static native void setId0(long cred, long id);
+
+    /**
+     * Get the id that was assigned to an SSL_CREDENTIAL when it was created by {@link #newX509()} or
+     * {@link #newDelegated()}.
+     *
+     * <p>This is a BoringSSL-specific feature.</p>
+     *
+     * @param cred the SSL_CREDENTIAL instance (SSL_CREDENTIAL *)
+     * @return the id, or {@code 0} if none was assigned
+     */
+    public static native long getId(long cred);
 
     /**
      * Increment the reference count of an SSL_CREDENTIAL.
@@ -184,7 +224,11 @@ private SSLCredential() { }
      * @return the delegated SSL_CREDENTIAL instance (SSL_CREDENTIAL *)
      * @throws Exception if an error occurred
      */
-    public static native long newDelegated() throws Exception;
+    public static long newDelegated() throws Exception {
+        return assignId(newDelegatedNative());
+    }
+
+    private static native long newDelegatedNative() throws Exception;
 
     /**
      * Set the delegated credential for an SSL_CREDENTIAL.

openssl-dynamic/src/main/c/ssl.c

@@ -44,6 +44,7 @@
 #include "apr_portable.h"
 #include "ssl_private.h"
 #include "ssl.h"
+#include "sslcredential.h"
 
 #define SSL_CLASSNAME  "io/netty/internal/tcnative/SSL"
 
@@ -2773,6 +2774,23 @@ TCN_IMPLEMENT_CALL(jlong, SSL, getSelectedCredential)(TCN_STDARGS, jlong ssl) {
 #endif
 }
 
+TCN_IMPLEMENT_CALL(jlong, SSL, getSelectedCredentialId)(TCN_STDARGS, jlong ssl) {
+#ifdef OPENSSL_IS_BORINGSSL
+    SSL *ssl_ = J2P(ssl, SSL *);
+    TCN_CHECK_NULL(ssl_, ssl, 0);
+    const SSL_CREDENTIAL* credential = SSL_get0_selected_credential(ssl_);
+    if (credential != NULL) {
+        // Handshake in progress: report the live selection.
+        return tcn_SSL_CREDENTIAL_get_id(credential);
+    }
+    tcn_ssl_state_t* state = tcn_SSL_get_app_state(ssl_);
+    return state == NULL ? 0 : state->selected_credential_id;
+#else
+    tcn_ThrowUnsupportedOperationException(e, "SSL_CREDENTIAL API not available.");
+    return 0;
+#endif
+}
+
 // JNI Method Registration Table Begin
 static const JNINativeMethod method_table[] = {
   { TCN_METHOD_TABLE_ENTRY(bioLengthByteBuffer, (J)I, SSL) },
@@ -2854,6 +2872,7 @@ static const JNINativeMethod method_table[] = {
   { TCN_METHOD_TABLE_ENTRY(setRenegotiateMode, (JI)V, SSL) },
   { TCN_METHOD_TABLE_ENTRY(addCredential, (JJ)V, SSL) },
   { TCN_METHOD_TABLE_ENTRY(getSelectedCredential, (J)J, SSL) },
+  { TCN_METHOD_TABLE_ENTRY(getSelectedCredentialId, (J)J, SSL) },
   { TCN_METHOD_TABLE_ENTRY(getGroupName, (J)Ljava/lang/String;, SSL) }
 };
 

openssl-dynamic/src/main/c/ssl_private.h

@@ -411,6 +411,9 @@ struct tcn_ssl_state_t {
     // len < sk_CRYPTO_BUFFER_num(chain) check (both locals are 0/NULL there).
     int task_array_len;
     int task_chain_num;
+#ifdef OPENSSL_IS_BORINGSSL
+    jlong selected_credential_id;
+#endif
 };
 
 #define TCN_GET_SSL_CTX(ssl, C)                             \

openssl-dynamic/src/main/c/sslcontext.c

@@ -37,6 +37,7 @@
 #include "ssl_private.h"
 #include <stdint.h>
 #include "sslcontext.h"
+#include "sslcredential.h"
 #include "cert_compress.h"
 
 #define SSLCONTEXT_CLASSNAME "io/netty/internal/tcnative/SSLContext"
@@ -189,6 +190,15 @@ static void ssl_info_callback(const SSL *ssl, int where, int ret) {
             state->handshakeCount++;
         }
     }
+#ifdef OPENSSL_IS_BORINGSSL
+    if (0 != (where & SSL_CB_HANDSHAKE_DONE)) {
+        // BoringSSL frees the handshake state (and its selected credential) before SSL_do_handshake returns,
+        // so record the selection here. Assign unconditionally so a later handshake without one clears it.
+        if ((state = tcn_SSL_get_app_state(ssl)) != NULL) {
+            state->selected_credential_id = tcn_SSL_CREDENTIAL_get_id(SSL_get0_selected_credential(ssl));
+        }
+    }
+#endif
 }
 
 /* Initialize server context */

openssl-dynamic/src/main/c/sslcredential.c

@@ -37,12 +37,24 @@ static void throw_openssl_error(JNIEnv* env, const char* msg) {
     ERR_error_string_n(err, err_buf, sizeof(err_buf));
     tcn_Throw(env, "%s: %s", msg, err_buf);
 }
+
+static int tcn_SSL_CREDENTIAL_id_idx = -1;
+
+typedef char tcn_SSL_CREDENTIAL_id_requires_64bit_pointers[sizeof(void*) >= sizeof(jlong) ? 1 : -1];
+
+// The id is a scalar packed into the ex_data slot, so no free callback is needed.
+jlong tcn_SSL_CREDENTIAL_get_id(const SSL_CREDENTIAL* cred) {
+    if (cred == NULL || tcn_SSL_CREDENTIAL_id_idx < 0) {
+        return 0;
+    }
+    return (jlong)(intptr_t) SSL_CREDENTIAL_get_ex_data(cred, tcn_SSL_CREDENTIAL_id_idx);
+}
 #endif
 
 
 
 // Core SSL_CREDENTIAL functions
-TCN_IMPLEMENT_CALL(jlong, SSLCredential, newX509)(TCN_STDARGS) {
+TCN_IMPLEMENT_CALL(jlong, SSLCredential, newX509Native)(TCN_STDARGS) {
 #ifdef OPENSSL_IS_BORINGSSL
     SSL_CREDENTIAL* cred = SSL_CREDENTIAL_new_x509();
     TCN_CHECK_NULL(cred, credential, 0);
@@ -74,6 +86,40 @@ TCN_IMPLEMENT_CALL(void, SSLCredential, free)(TCN_STDARGS, jlong cred) {
 #endif
 }
 
+TCN_IMPLEMENT_CALL(void, SSLCredential, setId0)(TCN_STDARGS, jlong cred, jlong id) {
+#ifdef OPENSSL_IS_BORINGSSL
+    SSL_CREDENTIAL* c = (SSL_CREDENTIAL*)(intptr_t)cred;
+    TCN_CHECK_NULL(c, credential, /* void */);
+    if (id <= 0) {
+        tcn_ThrowIllegalArgumentException(e, "credential id must be positive");
+        return;
+    }
+    if (tcn_SSL_CREDENTIAL_get_id(c) != 0) {
+        jclass ise = (*e)->FindClass(e, "java/lang/IllegalStateException");
+        if (ise != NULL) {
+            (*e)->ThrowNew(e, ise, "credential already has an id");
+        }
+        return;
+    }
+    if (!SSL_CREDENTIAL_set_ex_data(c, tcn_SSL_CREDENTIAL_id_idx, (void*)(intptr_t) id)) {
+        throw_openssl_error(e, "Failed to set SSL_CREDENTIAL id");
+    }
+#else
+    tcn_ThrowUnsupportedOperationException(e, "SSL_CREDENTIAL API not available.");
+#endif
+}
+
+TCN_IMPLEMENT_CALL(jlong, SSLCredential, getId)(TCN_STDARGS, jlong cred) {
+#ifdef OPENSSL_IS_BORINGSSL
+    SSL_CREDENTIAL* c = (SSL_CREDENTIAL*)(intptr_t)cred;
+    TCN_CHECK_NULL(c, credential, 0);
+    return tcn_SSL_CREDENTIAL_get_id(c);
+#else
+    tcn_ThrowUnsupportedOperationException(e, "SSL_CREDENTIAL API not available.");
+    return 0;
+#endif
+}
+
 // SSL_CREDENTIAL configuration methods
 TCN_IMPLEMENT_CALL(void, SSLCredential, setPrivateKey)(TCN_STDARGS, jlong cred, jlong key) {
 #ifdef OPENSSL_IS_BORINGSSL
@@ -294,7 +340,7 @@ TCN_IMPLEMENT_CALL(void, SSLCredential, setTrustAnchorId)(TCN_STDARGS, jlong cre
 }
 
 // Delegated credentials
-TCN_IMPLEMENT_CALL(jlong, SSLCredential, newDelegated)(TCN_STDARGS) {
+TCN_IMPLEMENT_CALL(jlong, SSLCredential, newDelegatedNative)(TCN_STDARGS) {
 #ifdef OPENSSL_IS_BORINGSSL
     SSL_CREDENTIAL* credential = SSL_CREDENTIAL_new_delegated();
     if (credential == NULL) {
@@ -343,9 +389,11 @@ TCN_IMPLEMENT_CALL(void, SSLCredential, setDelegatedCredential)(TCN_STDARGS, jlo
 // JNI Method Registration Table Begin
 static const JNINativeMethod method_table[] = {
     // Core functions
-    { TCN_METHOD_TABLE_ENTRY(newX509, ()J, SSLCredential) },
+    { TCN_METHOD_TABLE_ENTRY(newX509Native, ()J, SSLCredential) },
     { TCN_METHOD_TABLE_ENTRY(upRef, (J)V, SSLCredential) },
     { TCN_METHOD_TABLE_ENTRY(free, (J)V, SSLCredential) },
+    { TCN_METHOD_TABLE_ENTRY(setId0, (JJ)V, SSLCredential) },
+    { TCN_METHOD_TABLE_ENTRY(getId, (J)J, SSLCredential) },
 
     // Configuration
     { TCN_METHOD_TABLE_ENTRY(setPrivateKey, (JJ)V, SSLCredential) },
@@ -360,7 +408,7 @@ static const JNINativeMethod method_table[] = {
     { TCN_METHOD_TABLE_ENTRY(setTrustAnchorId, (J[B)V, SSLCredential) },
 
     // Delegated credentials
-    { TCN_METHOD_TABLE_ENTRY(newDelegated, ()J, SSLCredential) },
+    { TCN_METHOD_TABLE_ENTRY(newDelegatedNative, ()J, SSLCredential) },
     { TCN_METHOD_TABLE_ENTRY(setDelegatedCredential, (J[B)V, SSLCredential) }
 };
 
@@ -371,6 +419,12 @@ static const jint method_table_size = sizeof(method_table) / sizeof(method_table
 // IMPORTANT: If you add any NETTY_JNI_UTIL_LOAD_CLASS or NETTY_JNI_UTIL_FIND_CLASS calls you also need to update
 //            Library to reflect that.
 jint netty_internal_tcnative_SSLCredential_JNI_OnLoad(JNIEnv* env, const char* packagePrefix) {
+#ifdef OPENSSL_IS_BORINGSSL
+    tcn_SSL_CREDENTIAL_id_idx = SSL_CREDENTIAL_get_ex_new_index(0, NULL, NULL, NULL, NULL);
+    if (tcn_SSL_CREDENTIAL_id_idx < 0) {
+        return JNI_ERR;
+    }
+#endif
     if (netty_jni_util_register_natives(env,
              packagePrefix,
              SSLCREDENTIAL_CLASSNAME,

openssl-dynamic/src/main/c/sslcredential.h

@@ -27,6 +27,10 @@ extern "C" {
 jint netty_internal_tcnative_SSLCredential_JNI_OnLoad(JNIEnv* env, const char* packagePrefix);
 void netty_internal_tcnative_SSLCredential_JNI_OnUnLoad(JNIEnv* env, const char* packagePrefix);
 
+#ifdef OPENSSL_IS_BORINGSSL
+jlong tcn_SSL_CREDENTIAL_get_id(const SSL_CREDENTIAL* cred);
+#endif
+
 #ifdef __cplusplus
 }
 #endif