Authentication

Metadata 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. Liccium supports two approaches for signing: X.509 Certificate-based signing and Keypair-based signing with embedded credentials.

Overview

Metadata signatures in Liccium serve multiple purposes:

• Authentication: Proves the identity of the declarer
• Integrity: Ensures the metadata hasn't been tampered with
• Non-repudiation: Provides proof that the declaration was made by the certificate holder

Two Signing Approaches

Prerequisites

Before creating signatures, ensure you have:

---

Approach 1: X.509 Certificate-Based Signing

This approach uses X.509 certificates to establish identity. The certificate chain is embedded in the JWT header using the x5c field.

Step 1: Prepare Your Public Metadata

Structure your public metadata according to Liccium requirements:

Code
 
const publicMetadata = {
  "$schema": "https://w3id.org/liccium/schema/0.1.0.json",
  "@context": "https://w3id.org/liccium/context/0.1.0.json",
  iscc: "ISCC:KACYPXW445FNGZZ2",
  name: "Example Content Title",
  description: "Detailed description of the content",
  mediatype: "image/jpeg",
  timestamp: Date.now(),
  declarerId: "did:web:yourdomain.com",
  credentials: [
    {
      "@context": ["https://www.w3.org/ns/credentials/v2"],
      type: ["VerifiableCredential", "VerifiableAttestation"],
      proof: { type: "JwtProof2020", jwt: "eyJhbGciOiJSUzI1NiJ9..." }
    }
  ]
};

Step 2: Load Your Certificate

Load your X.509 certificate and private key:

Code
 
const fs = require('fs');
const jwt = require('jsonwebtoken');
const certificatePem = fs.readFileSync('path/to/your/cert.pem', 'utf8');
const privateKeyPem = fs.readFileSync('path/to/your/private-key.pem', 'utf8');
const certBase64 = certificatePem
  .replace(/-----BEGIN CERTIFICATE-----/g, '')
  .replace(/-----END CERTIFICATE-----/g, '')
  .replace(/\n/g, '')
  .trim();

Step 3: Create the JWT Signature

Generate a JWT signature using your certificate and private key:

Code
 
const signature = jwt.sign(publicMetadata, privateKeyPem, {
  algorithm: 'ES256',
  header: {
    typ: 'JWT',
    alg: 'ES256',
    x5c: [certBase64],
  }
});

Step 4: Complete Certificate-Based Example

Full example with validation:

Code
 
const fs = require('fs');
const jwt = require('jsonwebtoken');

class CertificateSignatureCreator {
  constructor(certPath, privateKeyPath) {
    const certPem = fs.readFileSync(certPath, 'utf8');
    this.privateKey = fs.readFileSync(privateKeyPath, 'utf8');
    this.certBase64 = certPem
      .replace(/-----BEGIN CERTIFICATE-----/g, '')
      .replace(/-----END CERTIFICATE-----/g, '')
      .replace(/\n/g, '')
      .trim();
  }
  signMetadata(publicMetadata) {
    this.validateMetadata(publicMetadata);
    return jwt.sign(publicMetadata, this.privateKey, {
      algorithm: 'ES256',
      header: { typ: 'JWT', alg: 'ES256', x5c: [this.certBase64] }
    });
  }
  validateMetadata(metadata) {
    const requiredFields = ['$schema', '@context', 'iscc', 'name', 'timestamp', 'declarerId', 'credentials'];
    for (const field of requiredFields) {
      if (!metadata[field]) throw new Error(`Missing required field: ${field}`);
    }
    if (!Array.isArray(metadata.credentials) || metadata.credentials.length === 0) {
      throw new Error('credentials must be a non-empty array');
    }
  }
}
const signer = new CertificateSignatureCreator('path/to/cert.pem', 'path/to/private-key.pem');
const signature = signer.signMetadata(publicMetadata);

---

Approach 2: Keypair-Based Signing with Embedded JWK

This approach uses a self-generated EC keypair. The public key is embedded in the JWT header as a JSON Web Key (JWK), and verifiable credentials are included in the publicMetadata.

Step 1: Generate an EC Keypair

Code
 
openssl ecparam -name prime256v1 -genkey -noout -out private_key.pem
openssl ec -in private_key.pem -pubout -out public_key.pem

Step 2: Convert Public Key to JWK

Code
 
const fs = require('fs');
const crypto = require('crypto');
const publicKeyPem = fs.readFileSync('public_key.pem', 'utf8');
const keyObject = crypto.createPublicKey(publicKeyPem);
const jwk = keyObject.export({ format: 'jwk' });

Step 3: Create JWT Signature with JWK in Header

Code
 
const signature = jwt.sign(publicMetadata, privateKeyPem, {
  algorithm: 'ES256',
  header: {
    typ: 'JWT',
    alg: 'ES256',
    jwk: jwk,
  }
});

Step 5: Complete Keypair-Based Example

Code
 
const fs = require('fs');
const jwt = require('jsonwebtoken');
const crypto = require('crypto');

class KeypairSignatureCreator {
  constructor(privateKeyPath, publicKeyPath) {
    this.privateKey = fs.readFileSync(privateKeyPath, 'utf8');
    const publicKeyPem = fs.readFileSync(publicKeyPath, 'utf8');
    const keyObject = crypto.createPublicKey(publicKeyPem);
    this.jwk = keyObject.export({ format: 'jwk' });
  }
  signMetadata(publicMetadata) {
    this.validateMetadata(publicMetadata);
    return jwt.sign(publicMetadata, this.privateKey, {
      algorithm: 'ES256',
      header: { typ: 'JWT', alg: 'ES256', jwk: this.jwk }
    });
  }
  validateMetadata(metadata) {
    const requiredFields = ['$schema', '@context', 'iscc', 'name', 'timestamp', 'declarerId', 'credentials'];
    for (const field of requiredFields) {
      if (!metadata[field]) throw new Error(`Missing required field: ${field}`);
    }
    if (!Array.isArray(metadata.credentials) || metadata.credentials.length === 0) {
      throw new Error('credentials must be a non-empty array');
    }
  }
}
const signer = new KeypairSignatureCreator('private_key.pem', 'public_key.pem');
const signature = signer.signMetadata(publicMetadata);

---

Signature Verification

Decode the JWT (without verification) to inspect structure:

Code
 
const decoded = jwt.decode(signature, { complete: true });
console.log('JWT Header:', JSON.stringify(decoded.header, null, 2));

Certificate-based (x5c): header contains x5c with base64-encoded certificate.
Keypair-based (jwk): header contains jwk with EC P-256 public key.

---

Security Best Practices

Key Management

---

Common Issues and Solutions

Issue	Cause	Solution
Invalid signature format	Incorrect algorithm or header	Use ES256 and proper x5c or jwk header
Certificate/JWK not found	Missing x5c or jwk in JWT header	Include base64 certificate or JWK in header
Validation fails	Metadata missing required fields	Validate structure before signing ($schema, @context, iscc, name, timestamp, declarerId, credentials)
Key mismatch	Private key doesn't match certificate/public key	Verify key pair correspondence
Credentials validation fails	Missing or invalid credentials array	Ensure credentials is a non-empty array with valid VC structure

---

Integration with Liccium

Include your signature in the declaration payload:

Code
 
const declarationPayload = {
  signature: signature,
  tsaSignature: {
    tsr: "base64-encoded-timestamp-response",
    tsq: "base64-encoded-timestamp-request"
  },
  declarationMetadata: {
    publicMetadata: publicMetadata
  }
};

For complete declaration examples, see the Declaration API.

---

Next Steps

1. TSA Signature Creation – Add timestamp signatures for temporal verification
2. Test your signatures with the Declaration API
3. Implement error handling for production use
4. Monitor certificate/key expiration and plan for renewal