New wolfSSL Crypto Callback Utilities: Set Key and Export Key

    • wolfSSL’s crypto callback framework lets you offload cryptographic operations to hardware. PR #9851 extends this framework with two new callback utilities, Set Key and Export Key, which provide a standardized way to move key material between wolfSSL and your hardware across AES, HMAC, RSA, and ECC.

    How It Works

    When a key is bound to a hardware device via devId, these callbacks allow you to intercept the key import and export paths. This ensures your hardware receives key material in the exact format it requires, and exports are routed properly through your hardware’s extraction interface.

    The approach differs slightly depending on whether you are working with symmetric or asymmetric keys.

    Symmetric Keys (AES, HMAC)

    For Set Key, the raw key bytes and metadata (IV, direction, key length) are passed directly to your callback. Your callback receives the hardware-bound key object alongside the raw material, allowing it to deliver the data to the hardware in whatever format is needed.

    Supported APIs for Symmetric Keys:

    • AES (Set Key): wc_AesSetKey
    • HMAC (Set Key): wc_HmacSetKey

    Asymmetric Keys (RSA, ECC)

    For both Set Key and Export Key, a temporary wolfSSL key struct is constructed. This allows your callback to use the standard wolfSSL API to extract key components in whatever form your hardware requires, regardless of the key’s original arrival format (DER, raw components, X9.63, etc.).

    • On Import (Set Key): The incoming key material is parsed into the temporary key via the standard software path. Your callback then receives both the hardware destination key and the fully parsed temporary key.
    • On Export (Export Key): An empty temporary key is passed to your callback so it can be populated from the hardware using standard wolfSSL import functions. The original export operation then runs on this newly populated temporary key.

    Supported APIs for Asymmetric Keys:

    • RSA
      • Set Key: wc_RsaPrivateKeyDecode, wc_RsaPublicKeyDecodeRaw, wc_RsaKeyDecodeRawIndex
      • Export Key: wc_RsaFlattenPublicKey, wc_RsaExportKey
    • ECC
      • Set Key: wc_ecc_import_x963_ex2, wc_ecc_import_private_key_ex, wc_ecc_import_raw_private
      • Export Key: wc_ecc_export_x963, wc_ecc_export_ex

    Questions?

    If you have questions about using callbacks in wolfSSL, please contact us at facts@wolfssl.com or +1 425 245 8247.

    Download wolfSSL Now