Swarmauri Signing HMAC

An HMAC-based signer implementing the ISigning interface for detached signatures over raw bytes and canonicalized envelopes.

Features

• JSON canonicalization (always available)
• Optional CBOR canonicalization via cbor2
• Detached signatures using standard library hmac
• Supports raw, hex, environment, and HKDF-derived KeyRef secrets.

Security Notes

• Supports HMAC-SHA-256/384/512 only.
• Keys must be at least 32 bytes (256 bits).
• Tags default to the hash digest size and may be truncated via opts["tag_size"] but not below 16 bytes (128 bits).
• Secrets shorter than 32 bytes are rejected even when using a longer digest.

Installation

Install the package with your preferred Python packaging tool:

pip install swarmauri_signing_hmac

poetry add swarmauri_signing_hmac

uv pip install swarmauri_signing_hmac

Install cbor2 to enable CBOR canonicalization:

pip install cbor2

Usage

import asyncio
from swarmauri_signing_hmac import HmacEnvelopeSigner
from swarmauri_core.crypto.types import JWAAlg


async def main() -> None:
    signer = HmacEnvelopeSigner()

    # KeyRef with a raw 32-byte secret; see swarmauri_core for more options
    key = {"kind": "raw", "key": "a" * 32}

    # Sign and verify raw bytes
    payload = b"hello"
    sigs = await signer.sign_bytes(key, payload, alg=JWAAlg.HS256, opts={"tag_size": 16})
    assert await signer.verify_bytes(payload, sigs, opts={"keys": [key]})

    # Sign and verify a JSON envelope
    env = {"msg": "hello"}
    sigs_env = await signer.sign_envelope(
        key, env, alg=JWAAlg.HS256, canon="json", opts={"tag_size": 16}
    )
    assert await signer.verify_envelope(env, sigs_env, canon="json", opts={"keys": [key]})


asyncio.run(main())

Verification requires providing one or more keys via opts["keys"].

Key references

HmacEnvelopeSigner accepts multiple KeyRef forms:

• {"kind": "raw", "key": <bytes-or-str>} ? direct secret material.
• {"kind": "hex", "key": <hex str>} ? hex encoded secret.
• {"kind": "env", "name": <ENV_NAME>} ? loads the secret from an environment variable.
• {"kind": "derived", "key": <bytes-or-str>, "hkdf": {"salt": ..., "info": ...}} ? derives the signing secret with HKDF.

Provide an optional "kid" to control the key identifier or specify "alg" when verifying to override the default HS256 digest for a key entry.

Entry Point

The signer registers under the swarmauri.signings entry point as HmacEnvelopeSigner.

Want to help?

If you want to contribute to swarmauri-sdk, read up on our guidelines for contributing that will help you get started.