Authentication

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.

Overview

Certificate signatures in CommonsDB 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

Prerequisites

Before creating certificate signatures, ensure you have:

The Signing Process

Step 1: Prepare Your Public Metadata

First, structure your public metadata according to CommonsDB requirements:

Code(javascript)
 
const publicMetadata = {
  // Required fields
  title: "Example Content Title",
  creator: "John Doe",
  description: "Detailed description of the content",
  
  // Content identifiers
  contentType: "text/plain",
  language: "en",
  
  // Rights and licensing
  license: "CC-BY-4.0",
  rights: "Copyright 2024 Example Corp",
  
  // Optional metadata
  tags: ["example", "content", "metadata"],
  category: "documentation",
  
  // Timestamps
  created: "2024-01-01T00:00:00Z",
  modified: "2024-01-01T00:00:00Z"
};

Step 2: Load Your Certificate

Load your X.509 certificate and extract the necessary components:

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

// Load the certificate from .p12 file
// Note: You'll need to convert this to the appropriate format for your environment
const certificate509Buffer = fs.readFileSync('path/to/your/cert.pem');
const certificatePrivateKeyBuffer = fs.readFileSync('path/to/your/private-key.pem');

// Convert certificate to base64 for JWT header
const certB64 = certificate509Buffer.toString('base64');

Step 3: Create the JWT Signature

Generate a JWT (JSON Web Token) signature using your private key:

Code(javascript)
 
const signature = jwt.sign(publicMetadata, certificatePrivateKeyBuffer, {
  algorithm: 'ES256', // Use ES256 for P-256 elliptic curve
  header: {
    typ: 'JWT',
    alg: 'ES256',
    x5c: [certB64], // Include the certificate chain
  },
  // Optional: Add issuer and audience claims
  issuer: 'did:web:yourdomain.com',
  audience: 'commonsdb-api'
});

Step 4: Complete Example Implementation

Here's a complete example that demonstrates the entire signing process:

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

class CertificateSignatureCreator {
  constructor(certPath, privateKeyPath) {
    this.certificate = fs.readFileSync(certPath);
    this.privateKey = fs.readFileSync(privateKeyPath);
    this.certB64 = this.certificate.toString('base64');
  }

  signMetadata(publicMetadata) {
    // Validate required fields
    this.validateMetadata(publicMetadata);
    
    // Create JWT signature
    const signature = jwt.sign(publicMetadata, this.privateKey, {
      algorithm: 'ES256',
      header: {
        typ: 'JWT',
        alg: 'ES256',
        x5c: [this.certB64],
      },
      issuer: 'did:web:yourdomain.com', // Replace with your domain
      audience: 'commonsdb-api',
      expiresIn: '1h' // Optional: Add expiration
    });
    
    return signature;
  }
  
  validateMetadata(metadata) {
    const requiredFields = ['title', 'creator', 'description'];
    
    for (const field of requiredFields) {
      if (!metadata[field]) {
        throw new Error(`Missing required field: ${field}`);
      }
    }
  }
}

// Usage example
const signer = new CertificateSignatureCreator(
  'path/to/cert.pem',
  'path/to/private-key.pem'
);

const signature = signer.signMetadata(publicMetadata);
console.log('Generated signature:', signature);

Signature Verification

To verify that your signature is correctly formatted, you can decode the JWT header:

Code(javascript)
 
// Decode JWT header to verify structure
const [header, payload, signature] = jwtSignature.split('.');

const decodedHeader = JSON.parse(
  Buffer.from(header, 'base64').toString('utf8')
);

const decodedPayload = JSON.parse(
  Buffer.from(payload, 'base64').toString('utf8')
);

console.log('JWT Header:', decodedHeader);
console.log('JWT Payload:', decodedPayload);

Expected header structure:

Code(json)
 
{
  "typ": "JWT",
  "alg": "ES256",
  "x5c": ["base64-encoded-certificate"]
}

Security Best Practices

Key Management

Common Issues and Solutions

Issue	Cause	Solution
Invalid signature format	Incorrect algorithm or header	Ensure ES256 algorithm and proper x5c header
Certificate not found	Missing x5c in JWT header	Include base64-encoded certificate in header
Validation fails	Metadata missing required fields	Validate metadata structure before signing
Key mismatch	Private key doesn't match certificate	Verify key pair correspondence

Integration with CommonsDB

Once you have your certificate signature, include it in your CommonsDB declaration:

Code(javascript)
 
const declarationPayload = {
  declarerId: "did:web:yourdomain.com",
  iscc: "ISCC:KACYPXW445FNGZZ2",
  cid: "QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG",
  signature: signature, // Your generated JWT signature
  tsaSignature: "...", // TSA signature (next step)
  declarationMetadata: {
    publicMetadata: publicMetadata
  }
};

Next Steps

After creating your certificate signature:

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 expiration and plan for renewal

Your certificate signature is now ready for use with CommonsDB declarations, providing cryptographic proof of authenticity and integrity for your metadata.