Certificates

Overview of how certificates function within HUDI's ecosystem.

Understand the structure and purpose of HUDI-issued certificates, which function similarly to JSON Web Signatures (JWS). These certificates provide a secure, verifiable way to manage personal identity information across the decentralized web, ensuring that all data transactions are trustworthy and tamper-proof.

A certificate issued by HUDI resembles a JsonWebSignature object. It carries a payload containing personal information (similar to KYC) that serves as proof of your human identity.

How is it structured?

Certificates, functioning similarly to JSON Web Signatures (JWS), consist of two Base64-encoded stringified JSONs and one Base64-encoded final signature string concatenated with dots, like this: "aaaa.bbbb.cccc." These strings represent the header, payload, and signature, respectively.

interface JwsTokenModel {
  header: JwsTokenHeaderModel;
  payload: JwsTokenPayloadModel;
  signature: string;
}

The header string contains information about the signature algorithm, and the public key corresponding to the private key used for certificate signing.

interface JwsTokenHeaderModel {
  alg: string;
  publicKey: string;
}

The payload includes essential certificate details: a unique serial number, the start and end dates of validity (typically notAfter = notBefore + 1 year), issuer information (such as HUDI name, registered office, and certificate type from the organization unit parameter), and subject information (the certificate owner's address and another unique identifier).

interface JwsTokenPayloadModel {
  serialNumber: string;
  notBefore: Date;
  notAfter: Date;
  issuer: CertificateIssuerModel;
  subject: CertificateSubjectModel;
}

interface CertificateIssuerModel {
  commonName: string;
  country: string;
  state: string;
  locality: string;
  organizationName: string;
  organizationUnit: string;
}

interface CertificateSubjectModel {
  address: string;
  uid: string;
  provider: string;
}

The header and payload are first stringified and then concatenated with a dot. The resulting string is hashed using the Keccak algorithm and signed using the secp256k1 algorithm with the secret HUDI private key.

The resulting signature string is appended to the message that was signed, resulting in a format like "aaaa.bbbb.cccc." This string is then encoded in base64 and securely exported and stored exclusively within the owner's IPDW.

How to verify a HUDI certificate?

In a JavaScript/Typescript environment, you can verify it using the Web3 npm library with a code snippet like the following:

import * as Web3 from "web3";

/**
 * Verify a certificate using its publicKey to validate the signature
 * @param certificate
 */
verify(certificate: string) {
  // reproduce the message creation
  const jws = this.decodeJWS(cert);
  const messageSigned = JSON.stringify(jws.header) + '.' + JSON.stringify(jws.payload);

  // verify the signature
  const signingAddress = Web3.eth.accounts.recover(messageSigned, jws.signature);
  return signingAddress === jws.header.publicKey;
} 

/**
 * Decoded the certificate given in input
 * @param certificate
 */
decodeJWS(token: string): JwsTokenModel {
  const segments: string[] = token.split('.');
  if (segments.length < 3) {
     throw Error('Not conformed JSON Web Signature, impossible to decode');
  }
  return {
    header: JSON.parse(Buffer.from(segments[0], 'base64').toString()),
    payload: JSON.parse(Buffer.from(segments[1], 'base64').toString()),
    signature: Buffer.from(segments[2], 'base64').toString()
  }
}