Blockchain-based certifications

3.5.1. Creating Credentials 

 

In brief, creating credentials using our methodology involves populating a PDF template with data from a CSV file to generate the individual certificates, hashing these certificates, and creating a Merkle tree. The Merkle root is then published to the Bitcoin blockchain.  

 

The steps are summarized as follows: 

1. Populate a PDF template with graduate data from a CSV file to create individual certificates.
2. Add metadata to each PDF
3. Hash each PDF certificate using SHA-256 to ensure integrity.
4. 4. Construct a Merkle tree from these hashes and publish the Merkle root to the Bitcoin blockchain.
5. 5. Ensure each PDF contains metadata with issuer information and a chainpoint
6. 6. Once the Merkle root is published, the certificates are ready for distribution. 

 

 

 

 

 

Add metadata to each PDF 

 

Derive the Merkle root 

 

 

The process is managed through scripts that handle certificate creation, validation, and revocation, with configuration defined in a `config.ini` file. 

 

Configuration Options (config.ini) 

Option	Explanation and example
Global
working_direcory	The working directory for issuing the certificates. All paths/files are always relative to this directory. Example: /home/kostas/spring_2016_graduates
PDF certificates related
pdf_cert_template	The name of the PDF template file relative to working_directory. Example: certificate_template.pdf
csv_file	The name of the comma separated value file that contains individual information for each awardee. It is relative to working_directory. Example: graduates.csv
certificates_directory	The directory were all the new certificates will be stored. It is recommended that this directory is always empty before running the script. If it doesn’t exist it will be created. It is relative to working_directory. Example: certificates
certificates_global_fields	An object that contains data for the pdf_cert_template to fill in fields that are common to all graduates. Given that there is a field called date for the date that the certificate was awarded an example would be: { “fields”: [ { “date”: { “label”: “Date”, “order”: 2, “hide”: false, “value”: “5 Dec 2016” } } ] }
issuer	The name of the issuer/institution. Example: UNIVERSITY OF NEVERLAND
expiry_date	The date of expiry (if any) expressed in Unix Epoch / UTC. Example: 1553929397
CSV file related
cert_names_csv_column	Specifies the header of the column to use to name the certificates filenames. It has to be unique for each row or else the latter certificates will overrite the former! A good approach is to use a graduate identifier or their name. Given that csv_file contains a column with header name with all the (unique) names of the graduates an example value would be: name
cert_metadata_columns	Specifies the header of the columns and the respective data to be added in the metadata field for each individual certificate. Global fields, as specified by certificates_global_fields can also be specified here to be included in the metadata. Example: { “columns”: [ { “student_name”: { “label”: “Student Name”, “order”: 1, “hide”:false } } ] }
Validation related
f	Specify the PDF certificates to be validated.
blockchain_services	For each supported blockchain one can specify the validation services to use and how many successes required. Example (and default): { “bitcoin”: { “services”: [ {“blockcypher”:{} } ], “required_successes”: 1} }. Currently, blockchains supported are ‘bitcoin’, ‘litecoin’, ‘bitcoin_testnet’ and ‘litecoin_testnet’. Bitcoin suports ‘blockcypher’, ‘btcd’ and ‘custom_api’: … {“btcd”: { “full_url”: “http://user:[email protected]:18334” }}. Litecoin currently supports ‘ltcd’ and ‘custom_api’.
verify_issuer	Specify the methods that an issuer identity (Bitcoin address) can be validated. Example (and default): { “methods”: [] }. Possible values are … { “domain”: { “url”: “http://kkarasavvas.com” } } and { “github”: { “user”: “karask”, “gist_id”: “db951671b1af6b1edd56df06f1b9109a” } }
Revocation related	Mutually exclusive options
p	Specify the PDF certificates that we need to revoke.
batch	Specify the transaction id of the issuance which we want to revoke/invalidate.
address	Specify the address which will be revoked/invalidated. Not implemented yet.
Blockchain related	Note: currently only Bitcoin’s blockchain is supported.
blockchain	The blockchain network to anchor the hash data. Currently ‘bitcoin’ and ‘litecoin’ are supported.
issuing_address	The blockchain (testnet or mainnet) address to use for creating the OP_RETURN transaction that will issue the documents merkle root hash in the blockchain. It should be either a legacy address or a native segiwit address and needs to have sufficient funds to cover just the fees of the transaction. If more funds are present we send them back as change to the same address. Make sure that you have the private key for this address safe since that might be the only formal way of proving who issued the certificates. Example for testnet: mgs9DLttzvWFkZ46YLSNKSZbgSNiMNUsdJ
full_node_url	The URL of the full node together with the port. Example for testnet: 127.0.0.1:18332
full_node_rpc_user	The name of the RPC user as configured in bitcoin.conf of the full node. Note that the RPC password is going to be asked during execution of the create-certificates script. Example: kostasnode
full_node_rpc_password	The password of the RPC user as configured in bitcoin.conf of the full node. Note that the RPC password is going to be asked during execution of the create-certificates script. Example: kostastoolongtoguess
testnet	Specifies whether it will use testnet of mainnet to issue the hash. Example: true
tx_fee_per_byte	Specifies the mining fee to use per byte of the transaction’s size. Consult https://bitcoinfees.21.co or another site for possible values. Example value on Jan 2017 is: 100
issuer_identifier	It is possible to specify a value (max 8 bytes/chars) that is added in the OP_RETURN transaction to differentiate the issuer. It is optional. Example value: “UNicDC “.

 

 

For a detailed process and scripts, please refer to the original documentation.

 

3.5.2. Issuing Credentials 

 

Issuing certificates on the blockchain involves the following steps: 

 

1. Adding Metadata to Credentials: Add programmatically retrievable metadata, including issuer and Bitcoin address, are added to each PDF credential. 

 

2. Calculating the Merkle Root: A Merkle tree is formed from the hashes of all credentials, resulting in a Merkle root.

 

3. Blockchain Issuance: A Bitcoin transaction with an OP_RETURN operator, containing the institution’s identifier and the Merkle root, is sent to a Bitcoin node. The transaction ID confirms the successful blockchain storage.

 

4. Adding Blockchain Proof Metadata: Post-issuance, additional metadata proving their blockchain issuance are attached to the PDF of each credential. This includes the Merkle proof, Merkle root, and transaction ID. As we note in subsequent sessions the additional proof information is removed, reverting the credential to its post-step 1 state, to enable the validation process.

 

 

Fig. Add blockchain proof metadata each credential 

 

 

3.5.3. Validating Credentials 

 

The validation process involves a series of steps that ensure the authenticity and integrity of the certificates: 

 

1. Extraction of Blockchain Proof Metadata: The first step involves extracting the blockchain proof metadata from the PDF credential. The metadata set includes essential details like the Merkle proof, Merkle root, and transaction identifier (TxID). 

 

Fig. Extract blockchain proof metadata 

 

1. Certificate Hash Calculation: The hash of the PDF credential is recalculated. For this step the credential’s metadata are extracted and removed from the PDF. Removing the proof metadata, reverts the PDF to its original state; as it was when initially generated during the credential creation process. This is crucial because any modification to the certificate (including the set of metadata) would alter its hash, indicating tampering.  

 

 

Fig. Calculate the hash of the remaining certificate 

 

1. Retrieving Merkle Root from Blockchain: Using the TxID from the extracted metadata, the transaction containing the OP_RETURN with the Merkle root is retrieved from the blockchain. 

 

Fig. Get the merkle root stored in the blockchain 

 

1. Calculate Merkle root from proof and compare: The final step is to validate that the recalculated hash of the credential matches the hash stored in the blockchain. By reconstructing the Merkle root using the Merkle proof and comparing it to the Merkle root retrieved from the blockchain, it can be confirmed that the credential is unmodified and was indeed issued by the institution. 

 

Fig. Calculate Merkle root from proof and compare 

 

 

3.5.4. Revoking Credentials 

 

The Blockchain Document Issuing Protocol (BDIP) leverages the 80-byte OP_RETURN operator in Bitcoin transactions to define (encode) a meta-protocol that enables operations like: issuing, revoking batches or specific credentials, and revoking issuing addresses. The protocol defines the structure of the messages that can be encoded and the semantics of each. For each operation a separate transaction is issued which consists of an input; the Bitcoin address controlled by the issuing institution, an OP_RETURN output, and optionally a change output  

 

This decentralized approach is simple, intuitive, and independent, relying solely on the blockchain. The main limitation is the 80-byte constraint, allowing only two revocations per transaction (a separate transaction per two revocations). However, given the infrequency of revocations, this is a minor inconvenience, given the protocol’s efficiency and scalability. The revocation of an entire batch of credentials is also possible by revoking the Merkle root.  

 

1. Message Operations and Structure:  

 

 

 

Each message is transmitted via a separate transaction and is composed of a header and payload. The header includes a protocol identifier (‘BDIP’ in ASCII, converted to hex), ensuring protocol-specific processing information. The header is 8 Bytes and is comprised of three parts: 

 

1. Protocol identifier: An identifier for the protocol; the ASCII of ’BDIP’, which is 4 bytes and corresponds to ’42444950’ in hex 

1. Protocol version: 2 bytes for a total of 65536 versions, starting with ’0001’ in hex 

1. Protocol operation: 2 bytes for a total of 65536 operations 

 

Every operation starts with the above header being differentiated only by the last 2 bytes. The current BDIP-v1, defines the following five operations: 

 

OP_1 – Issue Operation (operation code: 0004): Issue a batch of credentials. 

 

 

Fig.   Issue credentials — structure / bytemap 

 

The issuer identifier is used to allows the issuer to apply a unique identifier to the issuer process which is visible in the OP_RETURN message on the blockchain. Although this identifier aids in distinguishing the issuer, it is not utilized in the validation process of the credentials. 

 

OP_2 – Issue Operation (operation code: 0006): Issue credentials with expiration. 

 

 

Fig. Issue credentials with expiry data — structure / bytemap 

 

This operation indicates the issuance of a batch of credentials with a predefined expiration. This operation expands upon the standard issuance by incorporating an expiration date, which can be specified as either Unix time or as a specific future block height on the blockchain. When validating these time-sensitive credentials, the expiry date is checked first, using Median Time-Past (MTP) conventions to resolve the exact timing. This ensures the credentials are valid only within the designated timeframe. 

 

OP_3 – Revoke a batch of redentials operation (operation code: 0008): Revoke batch operation. 

 

 

Fig.   Revoke a batch of credentials — structure / bytemap 

 

This operation enables the revocation of an entire batch of credentials. This operation requires the transaction ID(s) of the batch issuance to be revoked. For validation purposes, the revocation must originate from the same address as the initial issuance. During the validation process, any such revocation operations are considered to determine the current validity of credentials. 

 

OP_4 – Revoke credentials operation (operation code: 000c): Revokes specific credentials (max two credentials). 

 

 

Fig. Revoke specific credentials — structure / bytemap 

 

The operation allows for revocation of one or two specific credentials by specifying a transaction ID from a prior issuing operation and including the hashes of the credentials to be revoked. These hashes are processed with RIPEMD-160 to fit within the message constraints (20 bytes each). During validation, the credential’s RIPEMD-160 hash is checked against the revocation list. If there’s a match, the credential is considered revoked. This operation ensures that individual credentials can be selectively invalidated. 

 

 

 

OP_5 – Revoke address operation (operation code: ff00): Revokes issuance address 

 

 

Fig.   Revoke address — structure / bytemap 

 

This operation is used to invalidate an issuing address, ensuring that it can no longer be used to issue credentials. This is particularly useful in scenarios where the private key associated with an address has been compromised. The operation targets the public key hash format of the address; both compressed and uncompressed versions of the public key can be specified. Once this operation is executed, all future activities from the address are deemed invalid, although past operations remain unaffected.  

 

 

Validation Rules 

 

To validate a credential the following validation rules should be considered: 

 

1. Verify the credential as detailed in Section 3.5.1 and confirm the issuing operation has at least one blockchain confirmation.
2. Check for expiration:
3. For block height-based expiry, validate against the current block height.
4. For Unix time-based expiry, calculate the MTP and validate accordingly.
5. Retrieve and examine all transactions for the issuing address prior to the credential’s issuance; if a revoke address operation is present, validation fails.
6. Retrieve and examine all transactions post-issuance for revoke operations; fail validation if a revoke batch operation or a revoke credentials operation targets the credential’s hash.

 

This process, though complex, can be efficiently executed using optimized blockchain queries.