Skip to content

Add initial support for crypto callbacks. #114

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
roberthdevries wants to merge 16 commits into
base: master
Choose a base branch
from
Open

Add initial support for crypto callbacks. #114

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
e57bcfe
Add initial support for crypto callbacks.
roberthdevries Apr 8, 2026
6a0a525
Addressed review comments
roberthdevries Apr 28, 2026
7412dd1
Address review comments
roberthdevries May 18, 2026
97820a5
Address review comments.
roberthdevries Jun 17, 2026
e943b88
Fix ruff errors and add type info.
roberthdevries Jul 6, 2026
26041b7
Addressed review comments
roberthdevries Jul 9, 2026
3ba3def
INVALID_DEVID is also needed when the CRYPTO_CB feature is enabled.
roberthdevries Jul 9, 2026
a62c87a
INVALID_DEVID is always needed as default argument value.
roberthdevries Jul 10, 2026
d884b75
Address review comments
roberthdevries Jul 10, 2026
483b532
Add more tests.
roberthdevries Jul 15, 2026
2b042fa
Declare CRYPTOCB_UNAVAILABLE and WC_HW_E without ERROR_STRINGS and re…
dgarske Oct 19, 2026
42fcbc8
Track crypto callback device ownership, require full hash overrides a…
dgarske Oct 19, 2026
3da4b6d
Add crypto callback tests for error, fallback, re-registration and de…
dgarske Oct 19, 2026
db57784
Log crypto callback tracebacks, fail closed on handler errors and doc…
dgarske Oct 19, 2026
cdfeacd
Give each hash object its own crypto callback context across copy and…
dgarske Oct 19, 2026
f0e3918
Deep copy crypto callback hashes with wolfCrypt copy functions and us…
dgarske Oct 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 60 additions & 3 deletions .github/workflows/python-app.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,9 +40,8 @@ jobs:
uv run --no-sync pytest tests

build-no-pqc:
# Regression coverage for issue #2659: INVALID_DEVID is only declared
# in the CFFI cdef when ML_KEM or ML_DSA is enabled, so a wolfSSL build
# without those features must still import wolfcrypt.random successfully.
# Regression coverage for issue #2659: a wolfSSL build without ML-KEM
# and ML-DSA must still import wolfcrypt.random successfully.

runs-on: ubuntu-latest
env:
Expand Down Expand Up @@ -97,3 +96,61 @@ jobs:
run: uv run --no-sync python -c "from wolfcrypt.random import Random; Random()"
- name: Run tests
run: uv run --no-sync pytest tests

build-cryptocb-smallstack:
# Crypto callback hash copies must keep wolfCrypt's native resource
# ownership; SMALL_STACK_CACHE allocates per-object buffers that a byte
# copy would share and free twice.
runs-on: ubuntu-latest
env:
USE_LOCAL_WOLFSSL: ${{ github.workspace }}/wolfssl-install

steps:
- uses: actions/checkout@v7
with:
submodules: recursive
- name: Set up Python 3.10
uses: actions/setup-python@v6
with:
python-version: "3.10"
- name: Install uv
uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
with:
# Install a specific version of uv.
version: "0.11.26"
- name: Install build deps
run: |
sudo apt-get update
sudo apt-get install -y autoconf automake libtool
- name: Build wolfSSL with crypto callbacks and SMALL_STACK_CACHE
run: |
cd lib/wolfssl
./autogen.sh
./configure --enable-cryptonly --disable-shared \
--enable-cryptocb --enable-cryptocbutils=copy,free \
--enable-smallstack --enable-smallstackcache \
--enable-aes --enable-aesgcm --enable-aessiv \
--enable-aesctr --enable-aesgcm-stream \
--enable-des3 --enable-chacha --enable-poly1305 \
--enable-sha --enable-sha384 --enable-sha512 --enable-sha3 \
--enable-hkdf --enable-rsa --enable-rsapss --enable-ecc \
--enable-ed25519 --enable-ed448 --enable-curve25519 \
--enable-keygen --enable-pwdbased --enable-pkcs7 \
--disable-md5 --disable-sha224 --disable-dh \
--disable-oldtls --disable-oldnames --disable-extended-master \
CFLAGS=-fPIC \
--prefix=$GITHUB_WORKSPACE/wolfssl-install
make
make install
- name: Install wolfcrypt-py against the local wolfSSL
run: |
uv venv
uv pip install pytest
uv pip install -e .
- name: Check crypto callback support
run: |
uv run --no-sync python -c "from wolfcrypt._ffi import lib as _lib; assert _lib.CRYPTO_CB_COPY_ENABLED and _lib.CRYPTO_CB_FREE_ENABLED, 'copy and free callbacks should be enabled'"
- name: Run tests
env:
MALLOC_CHECK_: "3"
run: uv run --no-sync pytest tests
205 changes: 194 additions & 11 deletions scripts/build_ffi.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -238,6 +238,12 @@ def make_flags(prefix, fips):
# ML-DSA (note: to be able to use the legacy option of signing without context, pass `yes,no-ctx` as argument)
flags.append("--enable-mldsa=yes")

# Crypto Callbacks
flags.append("--enable-cryptocb")
# Hash callbacks track per-object state across wc_*Copy and wc_*Free
flags.append("--enable-cryptocbutils=copy,free")
# flags.append("EXTRACPPFLAGS=-DDEBUG_CRYPTOCB")

# disabling other configs enabled by default
flags.append("--disable-oldtls")
flags.append("--disable-oldnames")
Expand Down Expand Up @@ -394,6 +400,18 @@ def get_features(local_wolfssl, features):
# Unlike the other fatures, HASHDRBG is enabled by default in random.h, unless WC_NO_HASHDRBG or
# CUSTOM_RAND_GENERATE_BLOCK is defined.
features["HASHDRBG"] = 0 if ("#define WC_NO_HASHDRBG" in defines or "#define CUSTOM_RAND_GENERATE_BLOCK" in defines) else 1
features["CRYPTO_CB"] = 1 if "#define WOLF_CRYPTO_CB" in defines else 0
features["CRYPTO_CB_COPY"] = 1 if "#define WOLF_CRYPTO_CB_COPY" in defines else 0
features["CRYPTO_CB_FREE"] = 1 if "#define WOLF_CRYPTO_CB_FREE" in defines else 0
# wc_HmacCopy was added in wolfSSL 5.9.0 and has no feature define.
features["HMAC_COPY"] = 0
if features["HMAC"]:
for d in include_dirs:
hmac_h = os.path.join(d, "wolfssl", "wolfcrypt", "hmac.h")
if os.path.exists(hmac_h):
with open(hmac_h) as f:
if "wc_HmacCopy" in f.read():
features["HMAC_COPY"] = 1

if '#define HAVE_FIPS' in defines:
if not fips:
Expand Down Expand Up @@ -471,6 +489,7 @@ def build_ffi(local_wolfssl, features):
#include <wolfssl/wolfcrypt/chacha20_poly1305.h>
#include <wolfssl/wolfcrypt/wc_mlkem.h>
#include <wolfssl/wolfcrypt/wc_mldsa.h>
#include <wolfssl/wolfcrypt/cryptocb.h>
"""

init_source_string = f"""
Expand Down Expand Up @@ -515,6 +534,10 @@ def build_ffi(local_wolfssl, features):
int ML_DSA_NO_CTX_ENABLED = {features["ML_DSA_NO_CTX"]};
int HKDF_ENABLED = {features["HKDF"]};
int HASHDRBG_ENABLED = {features["HASHDRBG"]};
int CRYPTO_CB_ENABLED = {features["CRYPTO_CB"]};
int CRYPTO_CB_COPY_ENABLED = {features["CRYPTO_CB_COPY"]};
int CRYPTO_CB_FREE_ENABLED = {features["CRYPTO_CB_FREE"]};
int HMAC_COPY_ENABLED = {features["HMAC_COPY"]};
"""

ffibuilder.set_source( "wolfcrypt._ffi", init_source_string,
Expand Down Expand Up @@ -558,13 +581,23 @@ def build_ffi(local_wolfssl, features):
extern int ML_DSA_NO_CTX_ENABLED;
extern int HKDF_ENABLED;
extern int HASHDRBG_ENABLED;
extern int CRYPTO_CB_ENABLED;
extern int CRYPTO_CB_COPY_ENABLED;
extern int CRYPTO_CB_FREE_ENABLED;
extern int HMAC_COPY_ENABLED;

static const int INVALID_DEVID;
static const int WC_HW_E;
static const int CRYPTOCB_UNAVAILABLE;

typedef unsigned char byte;
typedef unsigned int word32;

typedef struct { ...; } WC_RNG;
typedef struct { ...; } OS_Seed;

int wolfCrypt_Init(void);

int wc_InitRng(WC_RNG*);
int wc_InitRngNonce(WC_RNG*, byte*, word32);
int wc_InitRngNonce_ex(WC_RNG*, byte*, word32, void*, int);
Expand Down Expand Up @@ -759,7 +792,6 @@ def build_ffi(local_wolfssl, features):

static const int ECC_PRIVATEONLY_E;
static const int EXTKEYUSAGE_E;
static const int WC_HW_E;
static const int WC_HW_WAIT_E;

static const int PSS_SALTLEN_E;
Expand Down Expand Up @@ -787,7 +819,6 @@ def build_ffi(local_wolfssl, features):
static const int PKCS7_NO_SIGNER_E;
static const int WC_PKCS7_WANT_READ_E;

static const int CRYPTOCB_UNAVAILABLE;
static const int PKCS7_SIGNEEDS_CHECK;
static const int PSS_SALTLEN_RECOVER_E;
static const int CHACHA_POLY_OVERFLOW;
Expand Down Expand Up @@ -860,7 +891,7 @@ def build_ffi(local_wolfssl, features):
if features["SHA"]:
cdef += """
typedef struct { ...; } wc_Sha;
int wc_InitSha(wc_Sha*);
int wc_InitSha_ex(wc_Sha*, void*, int);
int wc_ShaUpdate(wc_Sha*, const byte*, word32);
int wc_ShaFinal(wc_Sha*, byte*);
void wc_ShaFree(wc_Sha*);
Expand All @@ -870,7 +901,7 @@ def build_ffi(local_wolfssl, features):
if features["SHA256"]:
cdef += """
typedef struct { ...; } wc_Sha256;
int wc_InitSha256(wc_Sha256*);
int wc_InitSha256_ex(wc_Sha256*, void*, int);
int wc_Sha256Update(wc_Sha256*, const byte*, word32);
int wc_Sha256Final(wc_Sha256*, byte*);
void wc_Sha256Free(wc_Sha256*);
Expand All @@ -880,7 +911,7 @@ def build_ffi(local_wolfssl, features):
if features["SHA384"]:
cdef += """
typedef struct { ...; } wc_Sha384;
int wc_InitSha384(wc_Sha384*);
int wc_InitSha384_ex(wc_Sha384*, void*, int);
int wc_Sha384Update(wc_Sha384*, const byte*, word32);
int wc_Sha384Final(wc_Sha384*, byte*);
void wc_Sha384Free(wc_Sha384*);
Expand All @@ -891,7 +922,7 @@ def build_ffi(local_wolfssl, features):
cdef += """
typedef struct { ...; } wc_Sha512;

int wc_InitSha512(wc_Sha512*);
int wc_InitSha512_ex(wc_Sha512*, void*, int);
int wc_Sha512Update(wc_Sha512*, const byte*, word32);
int wc_Sha512Final(wc_Sha512*, byte*);
void wc_Sha512Free(wc_Sha512*);
Expand Down Expand Up @@ -1018,6 +1049,10 @@ def build_ffi(local_wolfssl, features):
int wc_HmacFinal(Hmac*, byte*);
void wc_HmacFree(Hmac*);
"""
if features["HMAC_COPY"]:
cdef += """
int wc_HmacCopy(Hmac* src, Hmac* dst);
"""

if features["RSA"]:
cdef += """
Expand Down Expand Up @@ -1304,11 +1339,6 @@ def build_ffi(local_wolfssl, features):
int wolfCrypt_GetPrivateKeyReadEnable_fips(enum wc_KeyType);
"""

if features["ML_KEM"] or features["ML_DSA"]:
cdef += """
static const int INVALID_DEVID;
"""

if features["ML_KEM"]:
cdef += """
static const int WC_ML_KEM_512;
Expand Down Expand Up @@ -1363,6 +1393,155 @@ def build_ffi(local_wolfssl, features):
int wc_dilithium_verify_msg(const byte* sig, word32 sigLen, const byte* msg, word32 msgLen, int* res, dilithium_key* key);
"""

if features["CRYPTO_CB"]:
cdef += """
static const int WC_ALGO_TYPE_NONE;
static const int WC_ALGO_TYPE_HASH;
static const int WC_ALGO_TYPE_CIPHER;
static const int WC_ALGO_TYPE_PK;
static const int WC_ALGO_TYPE_RNG;
static const int WC_ALGO_TYPE_SEED;
static const int WC_ALGO_TYPE_HMAC;
static const int WC_ALGO_TYPE_CMAC;
static const int WC_ALGO_TYPE_CERT;
static const int WC_ALGO_TYPE_KDF;
static const int WC_ALGO_TYPE_COPY;
static const int WC_ALGO_TYPE_FREE;
static const int WC_ALGO_TYPE_MAX;

static const int WC_HASH_TYPE_SHA; /* SHA-1 (not old SHA-0) */
static const int WC_HASH_TYPE_SHA256;
static const int WC_HASH_TYPE_SHA384;
static const int WC_HASH_TYPE_SHA512;
static const int WC_HASH_TYPE_SHA3_256;
static const int WC_HASH_TYPE_SHA3_384;
static const int WC_HASH_TYPE_SHA3_512;
"""


cdef += """
typedef struct {
int algo_type; /* enum wc_AlgoType */
union {
"""

# The following block is commented out as there are issues with cffi code generation for the
# wc_CryptoInfo structure with two layers of anonymous unions.
# Uncommenting more parts of the cipher struct causes errors regarding conflicting struct sizes of
# other parts of the wc_CryptoInfo struct.
# Cffi cdef and the compiler seem to disagree.
#
# cdef += """
# struct {
# int type; /* enum wc_CipherType */
# int enc;
# union {
# //wc_CryptoCb_AesAuthEnc aesgcm_enc;
# //wc_CryptoCb_AesAuthDec aesgcm_dec;
# //wc_CryptoCb_AesAuthEnc aesccm_enc;
# //wc_CryptoCb_AesAuthDec aesccm_dec;
# struct {
# Aes* aes;
# byte* out;
# const byte* in;
# word32 sz;
# } aescbc;
# //struct {
# // Aes* aes;
# // byte* out;
# // const byte* in;
# // word32 sz;
# //} aesctr;
# //struct {
# // Aes* aes;
# // byte* out;
# // const byte* in;
# // word32 sz;
# //} aesecb;
# //struct {
# // Des3* des;
# // byte* out;
# // const byte* in;
# // word32 sz;
# //} des3;
# //void* ctx;
# };
# } cipher;
# """

# wolfSSL names the input fields in/inSz; renamed here because "in" is a
# Python keyword. The layout must still match wc_CryptoInfo in cryptocb.h.
cdef += """
Comment thread
dgarske marked this conversation as resolved.
struct {
int type; /* enum wc_HashType */
const byte* data;
word32 data_size;
Comment thread
dgarske marked this conversation as resolved.
byte* digest;
union {
"""
if features["SHA"]:
cdef += """
wc_Sha* sha1;
"""
if features["SHA256"]:
cdef += """
wc_Sha256* sha256;
"""
if features["SHA384"]:
cdef += """
wc_Sha384* sha384;
"""
if features["SHA512"]:
cdef += """
wc_Sha512* sha512;
"""
if features["SHA3"]:
cdef += """
wc_Sha3* sha3;
"""
cdef += """
void* ctx;
} u;
} hash;
"""
cdef += """
struct {
WC_RNG* rng;
byte* out;
word32 sz;
} rng;
"""
if features["CRYPTO_CB_COPY"]:
cdef += """
struct {
int algo; /* enum wc_AlgoType */
int type; /* enum wc_HashType for WC_ALGO_TYPE_HASH */
void* src;
void* dst;
} copy;
"""
if features["CRYPTO_CB_FREE"]:
cdef += """
struct {
int algo; /* enum wc_AlgoType */
int type; /* enum wc_HashType for WC_ALGO_TYPE_HASH */
int subType;
void* obj;
} free;
"""
cdef += """
};
...;
} wc_CryptoInfo;

typedef int (*CryptoDevCallbackFunc)(int devId, wc_CryptoInfo* info, void* ctx);
extern "Python" int py_wc_crypto_callback(int devId, wc_CryptoInfo* info, void* ctx);
int wc_CryptoCb_RegisterDevice(int devId, CryptoDevCallbackFunc cb, void* ctx);
void wc_CryptoCb_UnRegisterDevice(int devId);
int wc_CryptoCb_DefaultDevID();
// void wc_CryptoCb_InfoString(wc_CryptoInfo* info);
"""

ffibuilder.cdef(cdef)

def main(ffibuilder):
Expand Down Expand Up @@ -1400,6 +1579,10 @@ def main(ffibuilder):
"ML_DSA_NO_CTX": 0,
"HKDF": 1,
"HASHDRBG": 1,
"CRYPTO_CB": 1,
"CRYPTO_CB_COPY": 1,
"CRYPTO_CB_FREE": 1,
"HMAC_COPY": 1,
}

# Ed448 requires SHAKE256, which isn't part of the Windows build, yet.
Expand Down
Loading
Loading