Skip to content
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
160 lines (112 sloc) 11.1 KB

Blockcerts and Open Badges signature alignment

by Kim Hamilton Duffy (with input from Philipp Schmidt and Nate Otto)

Note on terminology

(alternatives welcome)

This uses the term "document" to refer to a credential being issued to a recipient. This is to avoid confusion with terms that already have precise meanings in the Verifiable Claims data model. Note that the existing Open Badges/Blockcerts formats roughly correspond to a set of Claims and Identity Profiles in the VC definitions.


Blockcerts is a certification infrastructure that puts recipients in control of their achievements and accomplishments. It consists of open standards and open source libraries enabling blockchain issuing and verification of documents. Blockcerts is Open Badges compliant, and is working with the Open Badges Initiative (OBI) to contribute blockchain extensions back to the Open Badges standard, enabling blockchain verification for the broader OBI community.

Why we have not used CA-based PKI approaches, and why RWoT

There are 2 aspects to why we have avoided CA-based PKI approaches:

Scalably enabling trustless verification

Blockcerts uses blockchain, as opposed to traditional PKI techniques, to scalably enable trustless verification. The verification process requires a reliable timestamp at which the transaction occurred. This, combined with public key(s) (with or without expired dates) claimed by the issuer, are used to ensure the transaction happened at a time when the issuer claimed ownership of the key. This is essential for alowing issuer rotation of keys without invalidating previously issued, but valid documents.

With blockchain approaches, the timestamp (and contents) are tamper proof by construction. We considered PKI type approaches, but there are a range of technical and philosophical issues, ranging from needing to rely on a timestamp authority server, trust in the certificate authority, and potential barriers to entry this would impose.

Integration of decentralized identification approaches in the Blockcerts ecosystem

The Blockcerts project intentionally does not address identity -- participation requires only cryptographic keys. Yet, identity is a critical aspect of a deployed Blockcerts system. And while it will never be part of the Blockcerts core, we are researching best practice approaches for our deployments and as recommendations for the community.

RWoT's efforts on decentralized identity are well aligned to our goals of enabling open participation and recipient control. We are also interested in other efforts promoted by this group:

  • Verifiable Claims (and general alignment of OBI with VS data model)
  • JSON-LD signatures
  • Proof of publication

Rebooting Web of Trust Spring 2017 Topics (summary)

Our near-term goal is to align the Blockcerts/OBI signature formats and standards with those of Verifiable Claim, JSON-LD signatures, etc, specifically:

  • Aligning signature schema and techniques for blockchain-issued documents, including proof of publication-style Merkle proofs
  • Best practices to enable recipients to make a strong claim of ownership over the claim

This is a small, but feasible set of topics for Spring 2017 RWoT. Subsequently, we will pursue the following topics (which currently require elaboration).

  • Integrating a decentralized identity approach with Blockcerts
  • Longevity of credentials
  • Broader alignment of Open Badges into claims via OBI Endorsement type

Topic 1: Aligning signature schema and techniques for blockchain-issued documents

Blockcerts signatures

Blockcerts uses Merkle proofs and JSON-LD signatures for issuing and verification. JSON-LD normalization (canonicalization) is a critical element, used to predictably format a json-formatted input document.

The Blockcerts signature schema is heavily inspired by specifications generated by RWOT and Verifiable Claims groups, including:

Blockcerts currently uses Chainpoint V2 merkle receipt format, with plans to enable other formats, e.g. Peter Todd's Open Timestamps.

"signature": {
    "type": ["EcdsaKoblitzSignature2016", "LinkedDataEcdsaKoblitzSignature", "Extension"],
    "merkleProof": {
      "type": "ChainpointSHA256v2",
      "merkleRoot": "68f3ede17fdb67ffd4a5164b5687a71f9fbb68da803b803935720f2aa38f7728",
      "targetHash": "c9ead76a54426b4ce4899bb921e48f5b55ea7592e5cee4460c86ebf4698ac3a6",
      "proof": [{
        "right": "7fef060cb17614fdfddd8c558e102fbb96433f5281e96c80f805459773e51163"
      "anchors": [{
        "sourceId": "8623beadbc7877a9e20fb7f83eda6c1a1fc350171f0714ff6c6c4054018eb54d",
        "type": "BTCOpReturn"
    "created" = "2017-03-24T21:48:24Z",
    "creator" = "ecdsa-koblitz-pubkey:1LGpGhGK8whX23ZNdxrgtjKrek9rP4xWER",
    "signatureValue": "OGQzNGVkMzVm4NTIyZTkZDY...NmExMgoYzI43Q3ODIyOWM32NjI="

Problems with JSON-LD signatures for blockchain-issued documents

Some aspects of JSON-LD signatures are not an ideal fit for blockchain verification, which has resulted in some duplication and ambiguity in our schema. Per VC discussions and this thread, there is interest in aligning JSON-LD signatures with JOSE/JWS, but we also have some concerns with this. (Note that, per Manu's email, details are emerging soon, and my concerns may be out of date).

Clarification and generalization of the JSON-LD signature standard (and/or its evolution with JOSE/JWS) would help express blockchain signatures. Some concerns include:

  • The 'signatureValue' field is not necessary if the issuing key is the same used to sign the document (which is true in the Blockcerts case).
    • Could signatureValue be removed as a required field in favor of the merkle proof for blockchain-issued documents?
    • Per this thread, there are additional concerns with relying on Ecdsa Koblitz signatures.
  • 'created' is less important than the blockchain timestamp.
    • Including this field in a blockchain certificate introduces confusion as to the interpretation of this field.
    • One option is to clarify the role of the transaction timestamp in verifiction.
  • 'creator' field, if assumed to be the issuer of the blockchain transaction, is present in the transaction
    • Note that OBI/Blockcerts allows specification of Issuer Key URI ('creator' field) in the issuer profile. The type is Key. In Blockcerts, it is enforced to be the same.
  • JOSE/JWS: we are very interested in alignment of json-ld signatures with JWS, but have concerns about the resulting format and usability.

Other questions

  • Any interest in revisiting Proof of Publication?
  • Standardization of a JSON-LD signature approach to dropped fields during JSON-LD normalization
    • Blockcerts addresses this through use of the '@vocab' keyword to detect fields not present in any JSON-LD context
    • Ideally verifiers could adopt a standard convention to flag such attempts to alter a claim

Topic 2: Recipient Strong Claim of Ownership

In the absence of an existing recipient DID, are there best practices for future proofing a credential via an embedded recipient public key, enabling subsequent mapping of the public key to a DID?

Because we cannot yet assume existence of DID for recipients, Blockcerts embeds the recipient's cryptographic key in the document issued on the blockchain. This allows the recipient to make a strong claim of ownership (by signing a message). For that reason, we plan to include (as an OBI extension) a public key that the recipient owns in the document. The current Blockcerts schema has added publicKey field to a recipient object, and reserved id on this object for future expression as a DID.

Are there any better approaches?

Note that in the Blockcerts model, the credential recipient provides their own public key (in advance of issuing) to the issuer. As mentioned above, the notion of identity is external to the Blockcerts project. It is assumed (and enforced in various ways in implementations) that the issuer and recipient have a separate means of establishing identity and transferring keys.


This is a technical summary of the Blockcerts approach, for reference:

Blockcerts Issuing

  • Input is a batch of json-formatted documents (currently content of each is an OBI-compliant badge)
  • For each document:
    • perform JSON-LD normalization
    • take SHA256 hash of normalized result
    • add hash to Merkle tree
  • Issue Merkle root on blockchain. The transaction is signed with issuer's cryptographic key (e.g. bitcoin blockchain uses a bitcoin public address)
  • Additionally, for each document, sign the JSON-LD normalized payload consistent with JSON-LD signatures

The resulting Blockcert contains the original document and the signature/merkle proof. JSON-LD normalization, along with merkle proof allows predictable verification of the issued document

Note that the last JSON-LD signature step is unnecessary. Because each document is sha256 hashed and placed into a merkle tree, issued on the blockchain, and the issuer signing key is the one performing the blockchain transaction, the separate signatureValue is actually unnecessary.

Blockcerts Verification


  • Document with proof (1 json file -- schema)
  • Fetch blockchain transaction info given in the proof. This reveals:
    • issuing address
    • op_return field (or similar anchor)
    • time
  • Issuer profile/Issuer key


  • Check integrity; has not been tampered with
    • Ensure local hash matches value in proof
    • Ensure value in blockchain transaction matches value in proof
    • Check merkle proof: essentially verification of the intermediate steps in the merkle path
  • Signature/authenticity
    • Establish 2-way link between issuer's profile and issuing key. I.e. is this issuing key actually claimed by the issuer?
    • Establish that the transaction was issued WHEN issuer key was valid
    • JSON-LD signature (EcdsaKoblitzSignature2016) -- technically unnecessary
  • Not revoked
    • The Open Badge format expects a revocationList URI, currently expected to be hosted URL in a certain format. See long term notes
  • Not expired
    • Open badges standard supplies an expiration date field, which is currently used by verification. See long term notes.
You can’t perform that action at this time.