Merge pull request #10132 from douzzer/20260404-default_rng_bank

20260404-default_rng_bank

wolfcrypt/src/error.c

@@ -37,6 +37,9 @@ const char* wc_GetErrorString(int error)
 {
     switch ((enum wolfCrypt_ErrorCodes)error) {
 
+    case WC_SUCCESS:
+        return "wolfCrypt generic success";
+
     case WC_FAILURE:
         return "wolfCrypt generic failure";
 

wolfcrypt/src/rng_bank.c

@@ -187,6 +187,8 @@ WOLFSSL_API int wc_rng_bank_fini(struct wc_rng_bank *ctx) {
 
     if (wolfSSL_RefCur(ctx->refcount) > 1)
         return BUSY_E;
+    else if (wolfSSL_RefCur(ctx->refcount) < 1)
+        return BAD_STATE_E;
 
 #ifndef WC_RNG_BANK_STATIC
     if (ctx->rngs)
@@ -247,6 +249,123 @@ WOLFSSL_API int wc_rng_bank_free(struct wc_rng_bank **ctx) {
 }
 #endif /* !WC_RNG_BANK_STATIC */
 
+#ifdef WC_RNG_BANK_DEFAULT_SUPPORT
+
+/* The default_rng_bank facility is used by the Linux kernel module as a global
+ * resource for wc_rng_bank_checkout(),
+ * wc_local_rng_bank_checkout_for_bankref(), and wc_InitRng_BankRef(), and can
+ * be similarly used by any application, to cache DRBG seeding at application
+ * startup.
+ */
+
+static struct wc_rng_bank * volatile default_rng_bank;
+
+WOLFSSL_API int wc_rng_bank_default_set(struct wc_rng_bank *bank) {
+    int ret;
+    struct wc_rng_bank *cur_default_rng_bank = NULL;
+    int new_refcount;
+
+    if (bank == NULL)
+        return BAD_FUNC_ARG;
+
+    if ((! (bank->flags & WC_RNG_BANK_FLAG_INITED)) ||
+        (wolfSSL_RefCur(bank->refcount) < 1))
+    {
+        return BAD_STATE_E;
+    }
+
+    wolfSSL_RefInc2(&bank->refcount, &new_refcount, &ret);
+    if (ret != 0)
+        return ret;
+#ifdef WC_VERBOSE_RNG
+    if (new_refcount < 2)
+        WOLFSSL_DEBUG_PRINTF(
+        "BUG: wc_rng_bank_default_set() new_refcount %d.\n", new_refcount);
+#else
+    (void)new_refcount;
+#endif
+    if (wolfSSL_Atomic_Ptr_CompareExchange((void * volatile *)&default_rng_bank, (void **)&cur_default_rng_bank, bank))
+        return 0;
+    else {
+        wolfSSL_RefDec2(&bank->refcount, &new_refcount, &ret);
+#ifdef WC_VERBOSE_RNG
+        if (new_refcount <= 0)
+            WOLFSSL_DEBUG_PRINTF(
+            "BUG: wc_rng_bank_default_set() cleanup popped refcount to %d.\n", new_refcount);
+#else
+        (void)new_refcount;
+#endif
+        return BUSY_E;
+    }
+}
+
+/* Note wc_rng_bank_default_checkout() must not be called before
+ * wc_rng_bank_default_set() returns, or after wc_rng_bank_default_clear() is
+ * called -- it is the caller's responsibility to assure this.
+ */
+WOLFSSL_API int wc_rng_bank_default_checkout(struct wc_rng_bank **bank) {
+    int ret;
+    struct wc_rng_bank *cur_default_rng_bank = default_rng_bank;
+    if (bank == NULL)
+        return BAD_FUNC_ARG;
+    if (cur_default_rng_bank == NULL)
+        return BAD_STATE_E;
+    wolfSSL_RefInc(&cur_default_rng_bank->refcount, &ret);
+    if (ret == 0)
+        *bank = cur_default_rng_bank;
+    return ret;
+}
+
+WOLFSSL_API int wc_rng_bank_default_checkin(struct wc_rng_bank **bank) {
+    int ret;
+    int new_refcount;
+    if ((bank == NULL) || (*bank == NULL))
+        return BAD_FUNC_ARG;
+    wolfSSL_RefDec2(&(*bank)->refcount, &new_refcount, &ret);
+#ifdef WC_VERBOSE_RNG
+    if (new_refcount <= 0)
+        WOLFSSL_DEBUG_PRINTF(
+        "BUG: wc_rng_bank_default_checkin() popped refcount to %d.\n", new_refcount);
+#else
+    (void)new_refcount;
+#endif
+    *bank = NULL;
+    return ret;
+}
+
+/* Note, wc_rng_bank_default_clear() should only be called at module or
+ * application shutdown to avoid races with wc_rng_bank_default_checkout(), and
+ * must be called before wc_rng_bank_fini() on a bank previously passed to
+ * wc_rng_bank_default_set().
+ */
+WOLFSSL_API int wc_rng_bank_default_clear(struct wc_rng_bank *bank) {
+    if ((bank != default_rng_bank) || (bank == NULL))
+        return BAD_FUNC_ARG;
+    if (wolfSSL_Atomic_Ptr_CompareExchange((void * volatile *)&default_rng_bank, (void **)&bank, NULL)) {
+        int ret;
+        int new_refcount;
+        wolfSSL_RefDec2(&bank->refcount, &new_refcount, &ret);
+#ifdef WC_VERBOSE_RNG
+        /* wc_rng_bank_fini() is the sole responsibility of the context that
+         * called wc_rng_bank_default_set() for this wc_rng_bank.
+         */
+        if (new_refcount < 1)
+            WOLFSSL_DEBUG_PRINTF(
+                "BUG: wc_rng_bank_default_clear() popped refcount to %d.\n", new_refcount);
+        if (! (bank->flags & WC_RNG_BANK_FLAG_INITED))
+            WOLFSSL_DEBUG_PRINTF(
+                "BUG: wc_rng_bank_default_clear() bank is already uninited.\n");
+#else
+        (void)new_refcount;
+#endif
+        return ret;
+    }
+    else
+        return BUSY_E;
+}
+
+#endif /* WC_RNG_BANK_DEFAULT_SUPPORT */
+
 /* wc_rng_bank_checkout() uses atomic operations to get exclusive ownership of a
  * DRBG without delay.  It expects to be called in uninterruptible context,
  * though works fine in any context.  When _PREFER_AFFINITY_INST, it starts by
@@ -268,13 +387,23 @@ WOLFSSL_API int wc_rng_bank_checkout(
     time_t ts1, ts2;
     int n_rngs_tried = 0;
 
+#ifdef WC_RNG_BANK_DEFAULT_SUPPORT
+    if (bank == NULL)
+        bank = default_rng_bank;
+#endif
+
     if ((bank == NULL) ||
-        (! (bank->flags & WC_RNG_BANK_FLAG_INITED)) ||
         (rng_inst == NULL))
     {
         return BAD_FUNC_ARG;
     }
 
+    if ((! (bank->flags & WC_RNG_BANK_FLAG_INITED)) ||
+        (wolfSSL_RefCur(bank->refcount) < 1))
+    {
+        return BAD_STATE_E;
+    }
+
     if ((flags & WC_RNG_BANK_FLAG_PREFER_AFFINITY_INST) &&
         (bank->affinity_get_id_cb == NULL))
     {
@@ -446,15 +575,46 @@ WOLFSSL_LOCAL int wc_local_rng_bank_checkout_for_bankref(
 }
 #endif /* WC_DRBG_BANKREF */
 
+static WC_INLINE int rng_inst_matches_bank(
+    struct wc_rng_bank *bank,
+    struct wc_rng_bank_inst *rng_inst)
+{
+    if ((bank == NULL) || (rng_inst == NULL))
+        return BAD_FUNC_ARG;
+#ifdef WC_RNG_BANK_STATIC
+    if ((rng_inst >= &bank->rngs[0]) &&
+        (rng_inst <= &bank->rngs[WC_RNG_BANK_STATIC_SIZE - 1]))
+        return 1;
+    else
+        return BAD_FUNC_ARG;
+#else
+    if ((rng_inst >= bank->rngs) &&
+        (rng_inst <= bank->rngs + bank->n_rngs - 1))
+        return 1;
+    else
+        return BAD_FUNC_ARG;
+#endif
+}
+
 WOLFSSL_API int wc_rng_bank_checkin(
     struct wc_rng_bank *bank,
     struct wc_rng_bank_inst **rng_inst)
 {
     int lockval;
+    int ret;
 
-    if ((bank == NULL) || (rng_inst == NULL) || (*rng_inst == NULL))
+    if (rng_inst == NULL)
         return BAD_FUNC_ARG;
 
+#ifdef WC_RNG_BANK_DEFAULT_SUPPORT
+    if (bank == NULL)
+        bank = default_rng_bank;
+#endif
+
+    ret = rng_inst_matches_bank(bank, *rng_inst);
+    if (ret < 0)
+        return ret;
+
     lockval = (int)WOLFSSL_ATOMIC_LOAD((*rng_inst)->lock);
 
     WOLFSSL_ATOMIC_STORE((*rng_inst)->lock, WC_RNG_BANK_INST_LOCK_FREE);
@@ -483,8 +643,16 @@ WOLFSSL_API int wc_rng_bank_inst_reinit(
     time_t ts1 = 0;
     int devId;
 
-    if ((rng_inst == NULL) ||
-        (rng_inst->rng.drbg == NULL))
+#ifdef WC_RNG_BANK_DEFAULT_SUPPORT
+    if (bank == NULL)
+        bank = default_rng_bank;
+#endif
+
+    ret = rng_inst_matches_bank(bank, rng_inst);
+    if (ret < 0)
+        return BAD_FUNC_ARG;
+
+    if (rng_inst->rng.drbg == NULL)
     {
         return BAD_FUNC_ARG;
     }
@@ -538,6 +706,11 @@ WOLFSSL_API int wc_rng_bank_seed(struct wc_rng_bank *bank,
     int ret = 0;
     int n;
 
+#ifdef WC_RNG_BANK_DEFAULT_SUPPORT
+    if (bank == NULL)
+        bank = default_rng_bank;
+#endif
+
     if ((bank == NULL) ||
         (! (bank->flags & WC_RNG_BANK_FLAG_INITED)))
     {
@@ -595,8 +768,16 @@ WOLFSSL_API int wc_rng_bank_reseed(struct wc_rng_bank *bank,
     int ret;
     time_t ts1 = 0;
 
-    if (! bank)
+#ifdef WC_RNG_BANK_DEFAULT_SUPPORT
+    if (bank == NULL)
+        bank = default_rng_bank;
+#endif
+
+    if ((bank == NULL) ||
+        (! (bank->flags & WC_RNG_BANK_FLAG_INITED)))
+    {
         return BAD_FUNC_ARG;
+    }
 
     if (flags & (WC_RNG_BANK_FLAG_CAN_FAIL_OVER_INST |
                  WC_RNG_BANK_FLAG_PREFER_AFFINITY_INST))
@@ -667,13 +848,23 @@ WOLFSSL_API int wc_InitRng_BankRef(struct wc_rng_bank *bank, WC_RNG *rng)
 {
     int ret;
 
+#ifdef WC_RNG_BANK_DEFAULT_SUPPORT
+    if (bank == NULL)
+        bank = default_rng_bank;
+#endif
+
     if ((bank == NULL) ||
-        (! (bank->flags & WC_RNG_BANK_FLAG_INITED)) ||
         (rng == NULL))
     {
         return BAD_FUNC_ARG;
     }
 
+    if ((! (bank->flags & WC_RNG_BANK_FLAG_INITED)) ||
+        (wolfSSL_RefCur(bank->refcount) < 1))
+    {
+        return BAD_STATE_E;
+    }
+
     XMEMSET(rng, 0, sizeof(*rng));
 
     wolfSSL_RefInc(&bank->refcount, &ret);
@@ -712,13 +903,23 @@ WOLFSSL_API int wc_BankRef_Release(WC_RNG *rng)
 WOLFSSL_API int wc_rng_new_bankref(struct wc_rng_bank *bank, WC_RNG **rng) {
     int ret;
 
+#ifdef WC_RNG_BANK_DEFAULT_SUPPORT
+    if (bank == NULL)
+        bank = default_rng_bank;
+#endif
+
     if ((bank == NULL) ||
-        (! (bank->flags & WC_RNG_BANK_FLAG_INITED)) ||
         (rng == NULL))
     {
         return BAD_FUNC_ARG;
     }
 
+    if ((! (bank->flags & WC_RNG_BANK_FLAG_INITED)) ||
+        (wolfSSL_RefCur(bank->refcount) < 1))
+    {
+        return BAD_STATE_E;
+    }
+
     *rng = (WC_RNG*)XMALLOC(sizeof(WC_RNG), bank->heap, DYNAMIC_TYPE_RNG);
     if (*rng == NULL) {
         return MEMORY_E;

wolfcrypt/src/wc_port.c

@@ -1835,6 +1835,21 @@ void wolfSSL_RefWithMutexInc(wolfSSL_RefWithMutex* ref, int* err)
     *err = ret;
 }
 
+void wolfSSL_RefWithMutexInc2(wolfSSL_RefWithMutex* ref, int *new_count,
+                              int* err)
+{
+    int ret = wc_LockMutex(&ref->mutex);
+    if (ret != 0) {
+        WOLFSSL_MSG("Failed to lock mutex for reference increment!");
+        *new_count = -1;
+    }
+    else {
+        *new_count = ++ref->count;
+        wc_UnLockMutex(&ref->mutex);
+    }
+    *err = ret;
+}
+
 int wolfSSL_RefWithMutexLock(wolfSSL_RefWithMutex* ref)
 {
     return wc_LockMutex(&ref->mutex);
@@ -1862,6 +1877,24 @@ void wolfSSL_RefWithMutexDec(wolfSSL_RefWithMutex* ref, int* isZero, int* err)
     }
     *err = ret;
 }
+
+void wolfSSL_RefWithMutexDec2(wolfSSL_RefWithMutex* ref, int* new_count,
+                              int* err)
+{
+    int ret = wc_LockMutex(&ref->mutex);
+    if (ret != 0) {
+        WOLFSSL_MSG("Failed to lock mutex for reference decrement!");
+        *new_count = -1;
+    }
+    else {
+        if (ref->count > 0) {
+            ref->count--;
+        }
+        *new_count = ref->count;
+        wc_UnLockMutex(&ref->mutex);
+    }
+    *err = ret;
+}
 #endif /* ! SINGLE_THREADED */
 
 #if WOLFSSL_CRYPT_HW_MUTEX