Getting Started

Overview

The Liccium API facilitates the declaration of metadata using cryptographic methods. This section provides an overview of key processes required for making API calls, generating unique content identifiers (CID), and ensuring secure and verifiable declarations.

Metadata collection

To make a proper API call, a structured metadata object must be included in the HTTP request body.

The metadata object contains essential information required for a declaration, including internal identifiers such as declarerId, isccCode, declarationId, and cid. It also includes cryptographic signatures for validation, namely signature and tsaSignature. The declarationMetadata section stores publicMetadata.

This structure ensures that each declaration is complete, verifiable, and secure.

Example Request Body Structure

Code
 
const requestBody = {
  metaInternal: {
    declarerId: didKey,
    isccCode: ISCC, // iscc code in format `ISCC:{iscc}`
    cid,
  },
  signature,
  tsaSignature,
  declarationMetadata: {
    publicMetadata,
  },
};

Core Properties for Declaration

To perform a valid declaration, several key parameters must be generated and included in the request. This includes computing the CID, which is a hash of the metadata, creating a cryptographic signature using a private key, and constructing a unique declaration ID. These elements ensure that each declaration is uniquely identifiable, verifiable, and compliant with the API's security requirements.

Code
 
const publicMetadata = {
  // all required and optional metadata described on API page
};

const certB64 = certificate509Buffer.toString('base64');
const signature = jwt.sign(entryIngestMetadata, certificatePrivateKeyBuffer, {
  header: {
    x5c: [certB64],
  },
});

const CID = this.generateCid(publicMetadata); // CID generation is described in separate block

const hashCID = crypto.createHash('sha256');
hashCID.update(CID, 'utf-8');
const cidHash = hashCID.digest();

const concatenatedId = Buffer.concat([
  Buffer.from(publicMetadata.declarationIdVersion, 'hex'),
  Buffer.from(publicMetadata.regId, 'hex'),
  cidHash,
]);

const declarationId = base58.encode(concatenatedId).slice(0, 20).toLowerCase();

CID Calculation

A unique Content Identifier (CID) is generated using cryptographic hashing of the metadata object. The CID serves as a unique, deterministic, verifiable fingerprint of the declaration metadata, ensuring its data integrity. It is created by serializing the metadata, computing a SHA-256 hash, and encoding it using a multihash format. This process requires the installation of multihashes and crypto modules.

Code
 
import * as multihashes from 'multihashes';
import * as crypto from 'crypto';

generateCid(jsonObj) {
  const jsonString = JSON.stringify(jsonObj, Object.keys(jsonObj).sort());
  const serializedJson = Buffer.from(jsonString, 'utf-8');

  const hash = crypto.createHash('sha256');
  hash.update(serializedJson);
  const hashBytes = hash.digest();

  const multihash = multihashes.encode(hashBytes, 'sha2-256');
  const cidv1Prefix = Buffer.from([0x12, 0x20]); // Qm based cid
  const cidBuffer = Buffer.concat([cidv1Prefix, multihash]);
  return multihashes.toB58String(cidBuffer);
}

Setup of .well-known/did.json

If you are using an X.509 certificate for authentication of your declarations, you must set up a .well-known/did.json file on your domain to enable verification of your digital signatures. This file associates your domain with a Decentralized Identifier (DID) and provides the necessary cryptographic keys for signature validation.

To make digital signatures verifiable, the domain used for your did and certificate issuance must host a .well-known/did.json file. See Setup .well-known/did.json for step-by-step instructions.

Certificate Signature Creation

To ensure the declaration is verifiable, all metadata must be signed using a private key, which generates a cryptographic signature proving its authenticity. The x.509 certificate provides attribution, linking the signature to a verified identity and enabling trust in the declaration.

Code
 
const publicMetadata = {
  // all required and optional metadata described on API page
};

const certB64 = certificate509Buffer.toString('base64');
const signature = jwt.sign(publicMetadata, certificatePrivateKeyBuffer, {
  header: {
    x5c: [certB64],
  },
});

TSA Signature Creation

To ensure the integrity and authenticity of the metadata at a specific point in time, a trusted timestamp must be applied to the metadata signature. This process, known as Timestamp Authority (TSA) confirmation, provides cryptographic proof that the data existed before a given time. A TSA service, such as FreeTSA, can be used to generate a timestamp, which is then included in the declaration for verification purposes.

Code
 
echo -n '{"data": "your json here"}' > data.json
openssl dgst -sha256 -binary data.json | openssl ts -query -sha256 -no_nonce -out request.tsq
curl -H "Content-Type: application/timestamp-query" --data-binary @request.tsq http://freetsa.org/tsr > response.tsr

The resulting response.tsr file contains a cryptographic timestamp proving the metadata's existence at a specific time. This file serves as the tsaSignature, which must be included in the declaration object to ensure its integrity and enable verifiable time-based validation. See TSA Signature for full details.

Next Steps

• Setup .well-known/did.json for DID-based verification
• Certificate Signature for signing metadata
• TSA Signature for timestamping
• Declaration API for making your first declaration