openbadgeslib 3.1.0

A library to sign and verify OpenBadges

OpenBadgesLib

A Python library and CLI for signing and verifying Open Badges embedded in SVG and PNG image files. It supports strict OpenBadges 2.0 (JWS / hosted assertions) and OpenBadges 3.0 (W3C Verifiable Credentials / JWT-VC), plus a frozen OpenBadges 1.0 legacy format — selected with -V {1,2,3} (default 3).

Features

• Sign badge images (SVG and PNG) as strict OB 2.0 JWS / hosted assertions (with a frozen OB 1.0 legacy format)
• Issue and verify OpenBadges 3.0 JWT-VC credentials
• Bake OB 3.0 JWT tokens into SVG and PNG badge images
• RSA 2048-bit (RS256), ECC NIST P-256 (ES256), and Ed25519 (EdDSA) key support
• SHA-256 hashed recipient identity with salt (OB 2.0)
• Expiration and revocation checking
• Issuer-side OB 3.0 revocation and suspension: W3C Bitstring Status List publication and --revoke / --suspend / --unsuspend management
• did:web issuer identity: did.json generation and DID resolution
• Five command-line tools included

Requirements

• Python >= 3.10 (tested on 3.10–3.13)
• pycryptodome >= 3.20
• ecdsa >= 0.19
• pypng >= 0.20220715.0
• PyJWT[crypto] >= 2.8
• cryptography >= 42
• defusedxml >= 0.7

Installation

pip install openbadgeslib

All dependencies are installed automatically. For a development checkout with the test suite and linters:

pip install -e ".[dev]"

Quick Start

# 1. Initialize a configuration directory
openbadges-init ./config/

# 2. Generate a key pair for a badge
openbadges-keygenerator -c ./config/config.ini -g 1

# 3a. Sign a badge — OpenBadges 3.0 (default)
openbadges-signer -c ./config/config.ini -b 1 -r [e-mail] -o /tmp/ -E

# 3b. Sign a badge — strict OpenBadges 2.0
openbadges-signer -c ./config/config.ini -b 1 -r [e-mail] -o /tmp/ -E -V 2

# 4a. Verify — OpenBadges 3.0
openbadges-verifier -i /tmp/[e-mail] \
    -r [e-mail] -V 3 -k ./config/keys/verify_rsa_key_1.pem

# 4b. Verify — strict OpenBadges 2.0 (pin a trusted key with -l/--local or -k/--pubkey)
openbadges-verifier -i /tmp/[e-mail] \
    -r [e-mail] -V 2 -l 1

# 5. OpenBadges 3.0 revocation (opt-in: set 'status_lists = revocation, suspension'
#    in the badge section before signing). Publish the issuer's did.json and the
#    signed Bitstring Status Lists, then revoke and re-publish.
openbadges-publish -c ./config/config.ini -o ./public -V 3
openbadges-publish -c ./config/config.ini -o ./public -V 3 \
    --revoke [e-mail] --reason "issued in error"

See the Quick Start and CLI Reference wiki pages for the full walkthrough and every flag.

Using the library — OpenBadges 2.0 (strict)

from datetime import datetime, timezone
from openbadgeslib.ob2 import OB2Signer, Assertion, IdentityObject, Verification

with open('sign.pem', 'rb') as f:
    priv_pem = f.read()
with open('badge.svg', 'rb') as f:
    image = f.read()

assertion = Assertion(
    recipient=IdentityObject.create('[e-mail]', salt='s4lt3d'),
    badge='https://example.com/badge_1/badge.json',
    verification=Verification(type='SignedBadge',
                              creator='https://example.com/badge_1/key.json'),
    issued_on=datetime(2026, 1, 1, tzinfo=timezone.utc),
)

signer = OB2Signer(privkey_pem=priv_pem, algorithm='RS256')
baked_svg = signer.sign_into_svg(assertion, image)
with open('/tmp/signed_badge.svg', 'wb') as f:
    f.write(baked_svg)

For the frozen OpenBadges 1.0 legacy API (Badge / Signer / Verifier), import from openbadgeslib.ob1 instead.

Using the library — OpenBadges 3.0 (JWT-VC)

from openbadgeslib.ob3 import (
    Issuer, Achievement, OpenBadgeCredential, OB3Signer, OB3Verifier,
)

issuer = Issuer(id='https://example.com/issuer', name='Example Org')
achievement = Achievement(
    id='https://example.com/achievements/python',
    name='Python Developer',
    description='Awarded for Python proficiency',
    criteria_narrative='Must pass the Python assessment',
)
credential = OpenBadgeCredential(
    issuer=issuer,
    recipient_id='mailto:[e-mail]',
    achievement=achievement,
)

with open('sign.pem', 'rb') as f:
    priv_pem = f.read()
signer = OB3Signer(privkey_pem=priv_pem, algorithm='RS256')

# Bake the signed JWT-VC into a badge image
with open('badge.svg', 'rb') as f:
    baked_svg = signer.sign_into_svg(credential, f.read())

# Verify
with open('verify.pem', 'rb') as f:
    verifier = OB3Verifier(pubkey_pem=f.read())
token = OB3Verifier.extract_token_from_svg(baked_svg)
restored = verifier.verify(token, expected_recipient='[e-mail]')
print('Recipient:', restored.recipient_id)

Documentation

• User & developer guide — the project Wiki: installation, configuration, concepts, the security model, CLI reference and how-to guides.
• API reference — generated from the docstrings and published at luisgf.github.io/openbadgeslib.

Running the test suite

pytest
pytest --cov=openbadgeslib      # with coverage report
flake8 openbadgeslib tests      # lint
mypy                            # type check (config in pyproject.toml)

Changelog

See Changelog.txt for the full history, and the GitHub Releases page for release notes.

License

The library (openbadgeslib/ package) is licensed under the GNU Lesser General Public License v3 (LGPLv3). The command-line wrapper tools are licensed under the BSD 2-Clause license.

Authors

• Luis González Fernández [e-mail]
• Jesús Cea Avión [e-mail]