openbadgeslib 2.0.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 both OpenBadges 2.0 (JWS compact serialisation) and OpenBadges 3.0 (W3C Verifiable Credentials / JWT-VC).

Features

• Sign badge images (SVG and PNG) with a JWS assertion (OB 2.0)
• 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
• 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 2.0 (default)
openbadges-signer -c ./config/config.ini -b 1 -r [e-mail] -o /tmp/ -E

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

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

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

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

Using the library — OpenBadges 2.0

from openbadgeslib.ob2 import Badge, BadgeImgType, BadgeType, Signer
from openbadgeslib.keys import KeyType

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

badge = Badge(
    ini_name='my_badge',
    name='My Badge',
    description='Awarded for excellence',
    image_type=BadgeImgType.SVG,
    image=image,
    image_url='https://example.com/badge.svg',
    criteria_url='https://example.com/criteria.html',
    json_url='https://example.com/badge.json',
    verify_key_url='https://example.com/verify.pem',
    key_type=KeyType.RSA,
    privkey_pem=priv_pem,
    pubkey_pem=pub_pem,
)

signer = Signer(identity='[e-mail]', badge_type=BadgeType.SIGNED)
signed = signer.sign_badge(badge)
signed.save_to_file('/tmp/signed_badge.svg')

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]