Add compile-time crypto callback async poll for record ciphers

A crypto callback that returns WC_PENDING_E for a TLS record cipher
silently corrupted records: Encrypt()/Decrypt() advance the cipher
state to CIPHER_STATE_END before the pending check, so on resume the
record is shipped without re-running the cipher.

WOLF_CRYPTO_CB_ASYNC_POLL gives crypto callback devices the QAT/Nitrox
"poll to fill output" completion model. On WC_PENDING_E the async event
stays queued; wolfSSL_AsyncPoll() re-enters the device with the new
WC_ALGO_TYPE_ASYNC_POLL (wc_CryptoCb_Poll) to finish the job and fill
the output buffer. Only the two async record ciphers (AES and 3DES
markers) are routed to poll completion; handshake PK keeps the
re-invoke model. The wolfSSL_AsyncPop eviction is gated for
poll-capable devices so the existing resume-at-CIPHER_STATE_END path
becomes correct with no record state-machine changes.

Without the feature (and without a software/QAT/Cavium backend) a
pending bulk cipher op now errors out with ASYNC_OP_E instead of
corrupting the record, and configure/cryptocb.c warn about the
unsupported combination.

Tests in tests/api/test_async.c cover direct AES-GCM/CBC/CCM and 3DES
poll completion at multiple pend depths, negative cases for cipher
types defined but not dispatched (ChaCha, single DES), and full TLS 1.3
handshake+echo including the no-poll failure path.

Author: julek-wolfssl

.github/workflows/async-examples.yml

@@ -188,3 +188,25 @@ jobs:
               cat "$f"
             fi
           done
+
+  # Crypto-callback record-cipher poll completion (WOLF_CRYPTO_CB_ASYNC_POLL):
+  # build the unit test with the feature macro and run the async test group.
+  cryptocb_async_poll:
+    if: ${{ (github.repository_owner == 'wolfssl') && (github.event_name != 'pull_request' || github.event.pull_request.draft == false) }}
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    name: Crypto-cb async poll completion
+    steps:
+      - uses: actions/checkout@v5
+        name: Checkout wolfSSL
+
+      - name: Build with WOLF_CRYPTO_CB_ASYNC_POLL
+        run: |
+          ./autogen.sh
+          ./configure --enable-asynccrypt --enable-cryptocb --enable-tls13 \
+            --enable-des3 --enable-aesccm --enable-aesctr \
+            CPPFLAGS=-DWOLF_CRYPTO_CB_ASYNC_POLL
+          make
+
+      - name: Run async unit tests
+        run: ./tests/unit.test --group async

.wolfssl_known_macro_extras

@@ -1066,6 +1066,7 @@ WOLFSSL_XILINX_PATCH
 WOLFSSL_XIL_MSG_NO_SLEEP
 WOLFSSL_ZEPHYR
 WOLF_ALLOW_BUILTIN
+WOLF_CRYPTO_CB_ASYNC_POLL
 WOLF_CRYPTO_CB_CMD
 WOLF_CRYPTO_DEV
 WOLF_NO_TRAILING_ENUM_COMMAS

configure.ac

@@ -11290,6 +11290,23 @@ then
     fi
 fi
 
+# Crypto callbacks with async crypt may not work for TLS unless
+# WOLF_CRYPTO_CB_ASYNC_POLL is defined. Warn once here and silence the
+# source-level #warning.
+if test "$ENABLED_ASYNCCRYPT" = "yes" && test "x$ENABLED_CRYPTOCB" != "xno" &&
+   test "x$ENABLED_ASYNCCRYPT_SW" != "xyes" &&
+   test "x$ENABLED_CAVIUM" != "xyes" && test "x$ENABLED_INTEL_QA" != "xyes"
+then
+    case "$CPPFLAGS $CFLAGS $AM_CFLAGS" in
+        *WOLF_CRYPTO_CB_ASYNC_POLL*)
+            ;;
+        *)
+            AC_MSG_WARN([crypto callbacks with async crypt may not work for TLS. Define WOLF_CRYPTO_CB_ASYNC_POLL to enable it.])
+            AM_CFLAGS="$AM_CFLAGS -DWOLF_CRYPTO_CB_ASYNC_NO_WARN"
+            ;;
+    esac
+fi
+
 # check for async if using Intel QuckAssist or Cavium
 if test "x$ENABLED_INTEL_QA" = "xyes" || test "x$ENABLED_CAVIUM" = "xyes" ; then
     if test "x$ENABLED_ASYNCCRYPT" = "xno" ; then

examples/async/user_settings.h

@@ -28,6 +28,11 @@
 #define NO_FILESYSTEM
 #define WOLFSSL_IGNORE_FILE_WARN
 
+#ifdef WOLF_CRYPTO_CB
+    /* PK-only offload: silence pending-bulk-cipher warning. */
+    #define WOLF_CRYPTO_CB_ASYNC_NO_WARN
+#endif
+
 #define HAVE_ECC
 #define WC_ECC_NONBLOCK
 #define WC_ECC_NONBLOCK_ONLY

src/internal.c

@@ -21583,7 +21583,16 @@ static WC_INLINE int Encrypt(WOLFSSL* ssl, byte* out, const byte* input,
         #ifdef WOLFSSL_ASYNC_CRYPT
             /* If pending, then leave and return will resume below */
             if (ret == WC_NO_ERR_TRACE(WC_PENDING_E)) {
+            #if defined(WOLF_CRYPTO_CB) && \
+                !defined(WOLF_CRYPTO_CB_ASYNC_POLL) && \
+                !defined(WOLFSSL_ASYNC_CRYPT_SW) && \
+                !defined(HAVE_INTEL_QA) && !defined(HAVE_CAVIUM)
+                /* No completion path for a pending bulk cipher op. */
+                WOLFSSL_ERROR_VERBOSE(ASYNC_OP_E);
+                return ASYNC_OP_E;
+            #else
                 return ret;
+            #endif
             }
         #endif
         }
@@ -22085,7 +22094,16 @@ static int DecryptTls(WOLFSSL* ssl, byte* plain, const byte* input, word16 sz)
         #ifdef WOLFSSL_ASYNC_CRYPT
             /* If pending, leave and return below */
             if (ret == WC_NO_ERR_TRACE(WC_PENDING_E)) {
+            #if defined(WOLF_CRYPTO_CB) && \
+                !defined(WOLF_CRYPTO_CB_ASYNC_POLL) && \
+                !defined(WOLFSSL_ASYNC_CRYPT_SW) && \
+                !defined(HAVE_INTEL_QA) && !defined(HAVE_CAVIUM)
+                /* No completion path for a pending bulk cipher op. */
+                WOLFSSL_ERROR_VERBOSE(ASYNC_OP_E);
+                return ASYNC_OP_E;
+            #else
                 return ret;
+            #endif
             }
         #endif
         }
@@ -27850,10 +27868,8 @@ int SendData(WOLFSSL* ssl, const void* data, size_t sz)
 #endif
         }
         if (sendSz < 0) {
-        #ifdef WOLFSSL_ASYNC_CRYPT
-            if (sendSz == WC_NO_ERR_TRACE(WC_PENDING_E))
-                ssl->error = sendSz;
-        #endif
+            /* Preserve the reason for wolfSSL_get_error(). */
+            ssl->error = sendSz;
             return BUILD_MSG_ERROR;
         }
 
@@ -43928,7 +43944,13 @@ int wolfSSL_AsyncPop(WOLFSSL* ssl, byte* state)
     #if (defined(WOLF_CRYPTO_CB) || defined(HAVE_PK_CALLBACKS)) && \
         !defined(WOLFSSL_ASYNC_CRYPT_SW) && !defined(HAVE_INTEL_QA) && \
         !defined(HAVE_CAVIUM)
-        else if (ret == WC_NO_ERR_TRACE(WC_PENDING_E)) {
+        else if (ret == WC_NO_ERR_TRACE(WC_PENDING_E)
+        #if defined(WOLF_CRYPTO_CB) && defined(WOLF_CRYPTO_CB_ASYNC_POLL)
+            /* Poll-completed ops stay queued until the poll fills the
+             * output buffer. */
+                 && asyncDev->cryptocb.devId == INVALID_DEVID
+        #endif
+        ) {
             /* Allow the underlying crypto API to be called again to trigger the
              * crypto or PK callback. The actual callback must be called, since
              * the completion is not detected in the poll like Intel QAT or

src/tls13.c

@@ -2818,6 +2818,14 @@ static int EncryptTls13(WOLFSSL* ssl, byte* output, const byte* input,
 
         #ifdef WOLFSSL_ASYNC_CRYPT
             if (ret == WC_NO_ERR_TRACE(WC_PENDING_E)) {
+            #if defined(WOLF_CRYPTO_CB) && \
+                !defined(WOLF_CRYPTO_CB_ASYNC_POLL) && \
+                !defined(WOLFSSL_ASYNC_CRYPT_SW) && \
+                !defined(HAVE_INTEL_QA) && !defined(HAVE_CAVIUM)
+                /* No completion path for a pending bulk cipher op. */
+                WOLFSSL_ERROR_VERBOSE(ASYNC_OP_E);
+                return ASYNC_OP_E;
+            #else
                 /* if async is not okay, then block */
                 if (!asyncOkay) {
                     ret = wc_AsyncWait(ret, asyncDev, event_flags);
@@ -2826,6 +2834,7 @@ static int EncryptTls13(WOLFSSL* ssl, byte* output, const byte* input,
                     /* If pending, then leave and return will resume below */
                     return wolfSSL_AsyncPush(ssl, asyncDev);
                 }
+            #endif
             }
         #endif
         }
@@ -3217,7 +3226,16 @@ int DecryptTls13(WOLFSSL* ssl, byte* output, const byte* input, word16 sz,
         #ifdef WOLFSSL_ASYNC_CRYPT
             /* If pending, leave now */
             if (ret == WC_NO_ERR_TRACE(WC_PENDING_E)) {
+            #if defined(WOLF_CRYPTO_CB) && \
+                !defined(WOLF_CRYPTO_CB_ASYNC_POLL) && \
+                !defined(WOLFSSL_ASYNC_CRYPT_SW) && \
+                !defined(HAVE_INTEL_QA) && !defined(HAVE_CAVIUM)
+                /* No completion path for a pending bulk cipher op. */
+                WOLFSSL_ERROR_VERBOSE(ASYNC_OP_E);
+                return ASYNC_OP_E;
+            #else
                 return ret;
+            #endif
             }
         #endif
         }

tests/api.c

@@ -214,6 +214,7 @@
 #include <tests/api/test_kdf.h>
 #include <tests/api/test_she.h>
 #include <tests/api/test_des3.h>
+#include <tests/api/test_async.h>
 #include <tests/api/test_chacha.h>
 #include <tests/api/test_poly1305.h>
 #include <tests/api/test_chacha20_poly1305.h>
@@ -37042,6 +37043,8 @@ TEST_CASE testCases[] = {
 #endif
 
     /* Cipher */
+    /* Crypto callback async poll completion */
+    TEST_ASYNC_DECLS,
     /* Triple-DES */
     TEST_DES3_DECLS,
     /* Chacha20 */

tests/api/include.am

@@ -22,6 +22,7 @@ tests_unit_test_SOURCES += tests/api/test_kdf.c
 # SHE
 tests_unit_test_SOURCES += tests/api/test_she.c
 # Cipher
+tests_unit_test_SOURCES += tests/api/test_async.c
 tests_unit_test_SOURCES += tests/api/test_des3.c
 tests_unit_test_SOURCES += tests/api/test_chacha.c
 tests_unit_test_SOURCES += tests/api/test_poly1305.c
@@ -145,6 +146,7 @@ EXTRA_DIST += tests/api/test_hmac.h
 EXTRA_DIST += tests/api/test_cmac.h
 EXTRA_DIST += tests/api/test_kdf.h
 EXTRA_DIST += tests/api/test_she.h
+EXTRA_DIST += tests/api/test_async.h
 EXTRA_DIST += tests/api/test_des3.h
 EXTRA_DIST += tests/api/test_chacha.h
 EXTRA_DIST += tests/api/test_poly1305.h