openbadgeslib 1.1.1__py3-none-any.whl

openbadgeslib/__init__.py

@@ -0,0 +1,40 @@
+#!/usr/bin/env python3
+"""
+        OpenBadges Library
+
+        Copyright (c) 2014-2026, Luis González Fernández, luisgf@luisgf.es
+        Copyright (c) 2014-2026, Jesús Cea Avión, jcea@jcea.es
+
+        All rights reserved.
+
+        This library is free software; you can redistribute it and/or
+        modify it under the terms of the GNU Lesser General Public
+        License as published by the Free Software Foundation; either
+        version 3.0 of the License, or (at your option) any later version.
+
+        This library is distributed in the hope that it will be useful,
+        but WITHOUT ANY WARRANTY; without even the implied warranty of
+        MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+        Lesser General Public License for more details.
+
+        You should have received a copy of the GNU Lesser General Public
+        License along with this library.
+"""
+
+# ── OpenBadges 2.0 ─────────────────────────────────────────────────────────────
+from .ob2 import (  # noqa: F401
+    Signer, Verifier, VerifyInfo,
+    Badge, BadgeSigned, Assertion,
+    BadgeStatus, BadgeImgType, BadgeType,
+    extract_svg_assertion, extract_png_assertion,
+)
+
+# ── OpenBadges 3.0 ─────────────────────────────────────────────────────────────
+from .ob3 import (  # noqa: F401
+    OB3Signer, OB3Verifier, OB3VerificationError,
+    OpenBadgeCredential, Achievement, Issuer,
+)
+
+# ── Shared utilities ────────────────────────────────────────────────────────────
+from .keys import KeyFactory, KeyRSA, KeyECC  # noqa: F401
+from .util import __version__  # noqa: F401

openbadgeslib/_jws/__init__.py

@@ -0,0 +1,102 @@
+"""JWS sign/verify backed by PyJWT algorithm implementations (RS256/384/512, ES256/384/512)."""
+
+from . import utils
+from .exceptions import SignatureError, MissingKey, MissingSigner, MissingVerifier, RouteMissingError
+
+from jwt.algorithms import RSAAlgorithm, ECAlgorithm
+from jwt.exceptions import InvalidKeyError
+
+from ..keys import KeyType, detect_key_type, key_to_pem
+from ..errors import UnknownKeyType
+
+_ALGORITHMS = {
+    'RS256': (RSAAlgorithm, RSAAlgorithm.SHA256),
+    'RS384': (RSAAlgorithm, RSAAlgorithm.SHA384),
+    'RS512': (RSAAlgorithm, RSAAlgorithm.SHA512),
+    'ES256': (ECAlgorithm,  ECAlgorithm.SHA256),
+    'ES384': (ECAlgorithm,  ECAlgorithm.SHA384),
+    'ES512': (ECAlgorithm,  ECAlgorithm.SHA512),
+}
+
+
+def _algo_for(alg_name):
+    entry = _ALGORITHMS.get(alg_name)
+    if entry is None:
+        raise RouteMissingError(f"Algorithm {alg_name!r} is not supported")
+    cls, hash_id = entry
+    return cls(hash_id)
+
+
+def _allowed_algs_for_key(key):
+    """Signature algorithms permitted for a verification key, bound to its type.
+
+    Binding the accepted algorithm to the key type stops a forged JWS header
+    from dictating the algorithm (cross-type confusion, and—were a symmetric
+    entry ever added to _ALGORITHMS—the classic RS256->HS256 downgrade).
+    """
+    try:
+        key_type = detect_key_type(key_to_pem(key))
+    except UnknownKeyType:
+        return set()
+    if key_type is KeyType.RSA:
+        return {'RS256', 'RS384', 'RS512'}
+    if key_type is KeyType.ECC:
+        return {'ES256', 'ES384', 'ES512'}
+    return set()
+
+
+def sign(header_dict, payload_dict, key):
+    """Sign header+payload dicts and return raw signature bytes."""
+    if key is None:
+        raise MissingKey("No signing key provided")
+    alg_name = header_dict.get('alg')
+    if not alg_name:
+        raise MissingSigner("Header is missing 'alg'")
+
+    signing_input = utils.encode(header_dict) + b'.' + utils.encode(payload_dict)
+    algo = _algo_for(alg_name)
+    try:
+        prepared = algo.prepare_key(key_to_pem(key))
+        return algo.sign(signing_input, prepared)
+    except (InvalidKeyError, ValueError) as exc:
+        raise SignatureError(str(exc)) from exc
+
+
+def verify_block(msg, key=None):
+    """Verify a JWS compact serialization (bytes or str). Returns True or raises SignatureError."""
+    if isinstance(msg, str):
+        msg = msg.encode('utf-8')
+
+    try:
+        head_b64, payload_b64, sig_b64 = msg.split(b'.')
+    except ValueError:
+        raise SignatureError("Malformed JWS: expected header.payload.signature")
+
+    if key is None:
+        raise MissingKey("No verification key provided")
+
+    header = utils.decode(head_b64)
+    alg_name = header.get('alg')
+    if not alg_name:
+        raise MissingVerifier("JWS header is missing 'alg'")
+
+    allowed = _allowed_algs_for_key(key)
+    if allowed and alg_name not in allowed:
+        raise SignatureError(
+            "Algorithm %r in JWS header is not allowed for this key type"
+            % alg_name)
+
+    signing_input = head_b64 + b'.' + payload_b64
+    raw_sig = utils.from_base64(sig_b64)
+
+    algo = _algo_for(alg_name)
+    try:
+        prepared = algo.prepare_key(key_to_pem(key))
+        valid = algo.verify(signing_input, prepared, raw_sig)
+    except (InvalidKeyError, ValueError) as exc:
+        raise SignatureError(str(exc)) from exc
+
+    if not valid:
+        raise SignatureError("Signature verification failed")
+
+    return True

openbadgeslib/_jws/exceptions.py

@@ -0,0 +1,18 @@
+class MissingKey(Exception):
+    pass
+
+
+class MissingSigner(Exception):
+    pass
+
+
+class MissingVerifier(Exception):
+    pass
+
+
+class SignatureError(Exception):
+    pass
+
+
+class RouteMissingError(Exception):
+    pass

openbadgeslib/_jws/utils.py

@@ -0,0 +1,30 @@
+import base64
+import json
+
+
+def base64url_decode(data):
+    # JWS/JWT base64url strips the '=' padding; restore it before decoding.
+    # The required pad count is (-len) % 4, which is 0 when the length is
+    # already a multiple of 4 (the old `4 - len % 4` wrongly added 4 there).
+    data += b'=' * (-len(data) % 4)
+    return base64.urlsafe_b64decode(data)
+
+
+def base64url_encode(input):
+    return base64.urlsafe_b64encode(input).replace(b'=', b'')
+
+
+def to_json(a):
+    return json.dumps(a).encode('utf-8')
+
+
+def from_json(a):
+    if isinstance(a, (bytes, bytearray)):
+        a = a.decode('utf-8')
+    return json.loads(a)
+
+
+def to_base64(a): return base64url_encode(a)
+def from_base64(a): return base64url_decode(a)
+def encode(a): return to_base64(to_json(a))
+def decode(a): return from_json(from_base64(a))

openbadgeslib/badge.py

@@ -0,0 +1,12 @@
+"""OpenBadges 2.0 badge objects — compatibility shim, re-exports from openbadgeslib.ob2."""
+from .ob2.badge import (
+    BadgeStatus, BadgeImgType, BadgeType,
+    Assertion, Badge, BadgeSigned,
+    extract_svg_assertion, extract_png_assertion,
+)
+
+__all__ = [
+    'BadgeStatus', 'BadgeImgType', 'BadgeType',
+    'Assertion', 'Badge', 'BadgeSigned',
+    'extract_svg_assertion', 'extract_png_assertion',
+]

openbadgeslib/baking.py

@@ -0,0 +1,166 @@
+"""
+        OpenBadges Library
+
+        Copyright (c) 2014-2026, Luis González Fernández, luisgf@luisgf.es
+        Copyright (c) 2014-2026, Jesús Cea Avión, jcea@jcea.es
+
+        All rights reserved.
+
+        This library is free software; you can redistribute it and/or
+        modify it under the terms of the GNU Lesser General Public
+        License as published by the Free Software Foundation; either
+        version 3.0 of the License, or (at your option) any later version.
+
+        This library is distributed in the hope that it will be useful,
+        but WITHOUT ANY WARRANTY; without even the implied warranty of
+        MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+        Lesser General Public License for more details.
+
+        You should have received a copy of the GNU Lesser General Public
+        License along with this library.
+"""
+
+# Version-agnostic carrier format for embedding an OpenBadges token (an OB 2.0
+# JWS or an OB 3.0 JWT-VC) into an SVG or PNG badge image, and extracting it
+# back out. OB2 and OB3 share the exact on-disk format; keeping a single
+# implementation here stops the two paths from drifting (e.g. two PNG readers,
+# one fixed-offset and one structured).
+
+from struct import pack
+from zlib import crc32
+
+from defusedxml.minidom import parseString
+from png import Reader, signature as _png_signature
+
+ITXT_KEYWORD = b'openbadges'
+SVG_ELEMENT = 'openbadges:assertion'
+
+# Maximum bytes a compressed iTXt token is allowed to inflate to. A JWS/JWT-VC
+# is a few KB; this cap stops a crafted zlib bomb from exhausting memory during
+# extraction (which runs on untrusted input, before any signature check).
+MAX_ITXT_DECOMPRESSED = 256 * 1024
+
+
+class DecompressionLimitExceeded(Exception):
+    """Raised when a compressed iTXt token inflates beyond the allowed size."""
+
+
+def _bounded_inflate(data, limit=MAX_ITXT_DECOMPRESSED):
+    import zlib
+    inflator = zlib.decompressobj()
+    out = inflator.decompress(data, limit)
+    if inflator.unconsumed_tail:
+        raise DecompressionLimitExceeded(
+            "Compressed token exceeds the %d-byte limit" % limit)
+    return out
+
+
+# ── SVG ─────────────────────────────────────────────────────────────────────
+
+def bake_svg(image_bytes, token, comment=None):
+    """Return *image_bytes* with an ``<openbadges:assertion verify=token>``
+    element (and an optional XML comment) appended to the root ``<svg>``."""
+    svg_doc = parseString(image_bytes)
+    try:
+        svg_tag = svg_doc.getElementsByTagName('svg').item(0)
+        node = svg_doc.createElement(SVG_ELEMENT)
+        node.attributes['xmlns:openbadges'] = 'http://openbadges.org'
+        node.attributes['verify'] = token
+        svg_tag.appendChild(node)
+        if comment:
+            svg_tag.appendChild(svg_doc.createComment(comment))
+        return svg_doc.toxml().encode('utf-8')
+    finally:
+        svg_doc.unlink()
+
+
+def has_svg(image_bytes):
+    """Return True if *image_bytes* already carries an OpenBadges assertion."""
+    svg_doc = parseString(image_bytes)
+    try:
+        return bool(svg_doc.getElementsByTagName(SVG_ELEMENT))
+    finally:
+        svg_doc.unlink()
+
+
+def extract_svg(image_bytes):
+    """Return the embedded token string, or None if there is no assertion node.
+
+    Raises on malformed XML (left to the caller to map to its own error type).
+    """
+    svg_doc = None
+    try:
+        svg_doc = parseString(image_bytes)
+        nodes = svg_doc.getElementsByTagName(SVG_ELEMENT)
+        if not nodes:
+            return None
+        return nodes[0].attributes['verify'].nodeValue
+    finally:
+        if svg_doc is not None:
+            svg_doc.unlink()
+
+
+# ── PNG ─────────────────────────────────────────────────────────────────────
+
+def _serialize_png(chunks):
+    out = _png_signature
+    for tag, data in chunks:
+        out += pack("!I", len(data))
+        if isinstance(tag, str):
+            tag = tag.encode('iso8859-1')
+        out += tag + data
+        checksum = crc32(tag)
+        checksum = crc32(data, checksum) & 0xFFFFFFFF
+        out += pack("!I", checksum)
+    return out
+
+
+def bake_png(image_bytes, token, text_comment=None):
+    """Return *image_bytes* with the token stored in an ``openbadges`` iTXt
+    chunk (and an optional ``tEXt`` comment chunk) inserted before IEND."""
+    chunks = list(Reader(bytes=image_bytes).chunks())
+    itxt_data = ITXT_KEYWORD + pack('BBBBB', 0, 0, 0, 0, 0) + token.encode('utf-8')
+    chunks.insert(len(chunks) - 1, ('iTXt', itxt_data))
+    if text_comment:
+        chunks.insert(len(chunks) - 1, ('tEXt', text_comment.encode('utf-8')))
+    return _serialize_png(chunks)
+
+
+def has_png(image_bytes):
+    """Return True if *image_bytes* already carries an OpenBadges iTXt chunk."""
+    for tag, data in Reader(bytes=image_bytes).chunks():
+        tag_str = tag.decode('ascii') if isinstance(tag, bytes) else tag
+        if tag_str == 'iTXt' and data.startswith(ITXT_KEYWORD):
+            return True
+    return False
+
+
+def extract_png(image_bytes, max_decompressed=MAX_ITXT_DECOMPRESSED):
+    """Return the embedded token string, or None if there is no openbadges
+    iTXt chunk.
+
+    Parses the iTXt structure (keyword, compression flag/method, language tag,
+    translated keyword, then text) rather than a fixed byte offset, so tokens
+    baked by any conformant tool — including compressed ones — are recovered.
+    Raises :class:`DecompressionLimitExceeded` if a compressed token inflates
+    beyond *max_decompressed*.
+    """
+    for tag, data in Reader(bytes=image_bytes).chunks():
+        tag_str = tag.decode('ascii') if isinstance(tag, bytes) else tag
+        if tag_str != 'iTXt':
+            continue
+
+        # iTXt layout: keyword \0 comp_flag comp_method lang \0 trans \0 text
+        keyword, sep, rest = data.partition(b'\x00')
+        if sep != b'\x00' or keyword != ITXT_KEYWORD or len(rest) < 2:
+            continue
+        compression_flag = rest[0]
+        _, sep_lang, rest = rest[2:].partition(b'\x00')   # drop language tag
+        _, sep_trans, text = rest.partition(b'\x00')      # drop translated keyword
+        if sep_lang != b'\x00' or sep_trans != b'\x00':
+            continue
+        if compression_flag:
+            text = _bounded_inflate(text, max_decompressed)
+        return text.decode('utf-8')
+
+    return None

openbadgeslib/config.ini.example

@@ -0,0 +1,67 @@
+;
+; OpenBadges Lib configuration example for RSA keys.
+;
+
+; Paths to the keys and log
+[paths]
+base         = .
+base_key     = ${base}/keys
+base_log     = ${base}/log
+base_image   = ${base}/images
+
+; Log configuration. Stored in ${base_log}
+[logs]
+general = general.log
+signer  = signer.log
+
+; SMTP Configuration
+[smtp]
+smtp_server = localhost
+smtp_port = 25
+use_ssl = False
+mail_from = no-reply@issuer.badge
+; Uncomment this if your SMTP server needs authentication
+;username =
+;password =
+
+; Configuration of the OpenBadges issuer.
+[issuer]
+name           = OpenBadge issuer
+url            = https://www.issuer.badge
+image          = issuer_logo.png
+email          = issuer_mail@issuer.badge
+publish_url    = https://openbadges.issuer.badge/issuer/
+revocationList = revoked.json
+
+;Badge configuration sections.
+[badge_1]
+name        = Badge 1
+description = Given to any user that install this library
+local_image = image_badge1.svg
+image       = https://www.issuer.badge/issuer/badge_1/badge1.svg
+criteria    = https://www.issuer.badge/issuer/badge_1/criteria.html
+verify_key  = https://www.issuer.badge/issuer/badge_1/verify_rsa_key.pem
+badge       = https://www.issuer.badge/issuer/badge_1/badge.json
+private_key = ${paths:base_key}/sign_rsa_key_1.pem
+public_key  = ${paths:base_key}/verify_rsa_key_1.pem
+; key_type selects the algorithm for openbadges-keygenerator: RSA (default) or ECC
+key_type    = RSA
+;alignement  =
+;tags        =
+;mail        = ${paths:base}/badge_1_mail.txt
+
+[badge_2]
+name        = Badge 2
+description = Given to any user that promote the library
+local_image = image_badge2.svg
+image       = https://www.issuer.badge/issuer/badge_2/badge2.svg
+criteria    = https://www.issuer.badge/issuer/badge_2/criteria.html
+verify_key  = https://www.issuer.badge/issuer/badge_2/verify_rsa_key.pem
+badge       = https://www.issuer.badge/issuer/badge_2/badge.json
+private_key = ${paths:base_key}/sign_rsa_key_2.pem
+public_key  = ${paths:base_key}/verify_rsa_key_2.pem
+key_type    = RSA
+;alignement =
+;tags       =
+;mail       = ${paths:base}/badge_2_mail.txt
+

openbadgeslib/confparser.py

@@ -0,0 +1,73 @@
+#!/usr/bin/env python3
+"""
+        OpenBadges Library
+
+        Copyright (c) 2014-2026, Luis González Fernández, luisgf@luisgf.es
+        Copyright (c) 2014-2026, Jesús Cea Avión, jcea@jcea.es
+
+        All rights reserved.
+
+        This library is free software; you can redistribute it and/or
+        modify it under the terms of the GNU Lesser General Public
+        License as published by the Free Software Foundation; either
+        version 3.0 of the License, or (at your option) any later version.
+
+        This library is distributed in the hope that it will be useful,
+        but WITHOUT ANY WARRANTY; without even the implied warranty of
+        MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+        Lesser General Public License for more details.
+
+        You should have received a copy of the GNU Lesser General Public
+        License along with this library.
+"""
+
+from configparser import ConfigParser, ExtendedInterpolation
+import os
+import sys
+import logging
+logger = logging.getLogger(__name__)
+
+
+def read_config_or_exit(config_file):
+    """Read a config file for a CLI tool, exiting with a clear message if it is
+    missing or empty. Shared by all the console-script entrypoints."""
+    conf = ConfParser(config_file).read_conf()
+    if not conf:
+        print('[!] The config file %s does not exist or is empty' % config_file)
+        sys.exit(-1)
+    return conf
+
+
+def resolve_badge_section(conf, name):
+    """Return the ``badge_<name>`` section name, exiting if it is not defined."""
+    section = 'badge_' + name
+    if section not in conf:
+        sys.exit('There is no "%s" badge in the configuration' % name)
+    return section
+
+
+class ConfParser():
+    def __init__(self, config_file='config.ini'):
+        self.config_file = config_file
+
+    def read_conf(self):
+        if not os.path.isfile(self.config_file):
+            return None
+
+        self.parser = ConfigParser(interpolation=ExtendedInterpolation())
+
+        try:
+            self.parser.read(self.config_file)
+        except UnicodeDecodeError:
+            # We should raise an UnicodeDecodeError, but the error message is too cryptic.#
+            raise ValueError("The encoding of the configuration file and the default encoding of "
+                             "the operating system mismatch") from None
+        if self.parser['paths']['base'][0] == '.':
+            abs_path = os.path.dirname(self.config_file)
+            full_path = os.path.abspath(abs_path)
+            self.parser['paths']['base'] = full_path
+        return self.parser
+
+
+if __name__ == '__main__':
+    pass

openbadgeslib/errors.py

@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+"""
+        OpenBadges Library
+
+        Copyright (c) 2014-2026, Luis González Fernández, luisgf@luisgf.es
+        Copyright (c) 2014-2026, Jesús Cea Avión, jcea@jcea.es
+
+        All rights reserved.
+
+        This library is free software; you can redistribute it and/or
+        modify it under the terms of the GNU Lesser General Public
+        License as published by the Free Software Foundation; either
+        version 3.0 of the License, or (at your option) any later version.
+
+        This library is distributed in the hope that it will be useful,
+        but WITHOUT ANY WARRANTY; without even the implied warranty of
+        MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+        Lesser General Public License for more details.
+
+        You should have received a copy of the GNU Lesser General Public
+        License along with this library.
+"""
+
+
+class LibOpenBadgesException(Exception):
+    pass
+
+
+""" Exception base classes """
+
+
+class KeyGenExceptions(LibOpenBadgesException):
+    pass
+
+
+class SignerExceptions(LibOpenBadgesException):
+    pass
+
+
+class VerifierExceptions(LibOpenBadgesException):
+    pass
+
+
+""" User-defined Exceptions """
+
+
+class GenPrivateKeyError(KeyGenExceptions):
+    pass
+
+
+class GenPublicKeyError(KeyGenExceptions):
+    pass
+
+
+class PrivateKeySaveError(KeyGenExceptions):
+    pass
+
+
+class PublicKeySaveError(KeyGenExceptions):
+    pass
+
+
+class PrivateKeyReadError(KeyGenExceptions):
+    pass
+
+
+class PublicKeyReadError(KeyGenExceptions):
+    pass
+
+
+class UnknownKeyType(KeyGenExceptions):
+    pass
+
+
+""" Signer Exceptions """
+
+
+class ErrorSigningFile(SignerExceptions):
+    pass
+
+
+""" Verifier Exceptions """
+
+
+class AssertionFormatIncorrect(VerifierExceptions):
+    pass
+
+
+class NotIdentityInAssertion(VerifierExceptions):
+    pass
+
+
+class ErrorParsingFile(VerifierExceptions):
+    pass
+
+
+""" Badge Object Exceptions """
+
+
+class BadgeImgFormatUnsupported(LibOpenBadgesException):
+    pass