Authentication

Setup of .well-known/did.json

If you are choosing to use the did method to publish your Decentralized Identifier (DID), you must set up a .well-known/did.json file on your domain. This enables third parties to retrieve your public key and verify your digital signatures.

Overview

The .well-known/did.json file connects your domain with a Decentralized Identifier (DID) and exposes the public key used to sign declarations. This enables verifiers to confirm that the same entity controls both the cryptographic key and the domain used in your Liccium declarations.

What is a DID Document?

A DID document is a JSON-LD file containing one or more cryptographic public keys and metadata linked to a Decentralized Identifier. With did, it provides a trust anchor by allowing anyone to look up the key at a well-known location on your domain.

Prerequisites

To complete the setup, ensure you have:

• Your X.509 certificate in .p12 format
• openssl installed on your system
• Node.js and npm (for the key conversion script)
• Access to your domain's web server

Step-by-Step Setup

Step 1: Convert .p12 to .pem Certificate

Extract your certificate (with public key) from the .p12 container:

Code(bash)
 
openssl pkcs12 -in your_cert.p12 -out cert.pem -clcerts -nokeys

Replace your_cert.p12 with your actual file. This creates a cert.pem file.

Step 2: Extract the RSA Public Key

Code(bash)
 
openssl x509 -pubkey -noout -in cert.pem > pubkey.pem

This creates a pubkey.pem file containing your RSA public key.

Step 3: Convert the Public Key to JWK Format (RSA)

Use node-jose to convert the PEM to JWK format:

JavaScript Script (Node.js)

Code(javascript)
 
const fs = require('fs');
const jose = require('node-jose');

const pem = fs.readFileSync('pubkey.pem', 'utf8');

jose.JWK.asKey(pem, 'pem').then((key) => {
  console.log(JSON.stringify(key.toJSON(true), null, 2));
});

Install and Run:

Code(bash)
 
npm install node-jose
node convert-key.js

The output will contain a JWK like:

Code(json)
 
{
  "kty": "RSA",
  "e": "AQAB",
  "n": "sXchYzQFKeYj6rNb1CzCBB4piOnD8VwDFlbs2qQoG5RYW8GKvH6XzZmgEyJBSbL7aVo3zY0Q8rMCYMg8Sfd1i6xhViOwLZCRkKrQqPIYTWfppW95OfgMRi1rsyWB64TxLfvhCbiD3l4r9rfZKZx7ehFs50B2iXkC8UMKiS6w-CF8",
  "x5t#S256": "WjZhI8mwlIPbyrwffu6Zhv79yy2_lh9Pbz08qa3l25c"
}

Step 4: Generate the .well-known/did.json File

Create a JSON file at /.well-known/did.json using the extracted values:

Code(json)
 
{
  "@context": "https://www.w3.org/ns/did/v1",
  "id": "did:web:yourdomain.com",
  "verificationMethod": [
    {
      "id": "did:web:yourdomain.com#0",
      "type": "JsonWebKey2020",
      "controller": "did:web:yourdomain.com",
      "publicKeyJwk": {
        "kty": "RSA",
        "n": "sXchYzQFKeYj6rNb1CzCBB4piOnD8VwDFlbs2qQoG5RYW8GKvH6XzZmgEyJBSbL7aVo3zY0Q8rMCYMg8Sfd1i6xhViOwLZCRkKrQqPIYTWfppW95OfgMRi1rsyWB64TxLfvhCbiD3l4r9rfZKZx7ehFs50B2iXkC8UMKiS6w-CF8",
        "e": "AQAB",
        "x5t#S256": "WjZhI8mwlIPbyrwffu6Zhv79yy2_lh9Pbz08qa3l25c"
      }
    }
  ],
  "authentication": [
    "did:web:yourdomain.com#0"
  ],
  "assertionMethod": [
    "did:web:yourdomain.com#0"
  ]
}

Important:

• Replace yourdomain.com with your actual domain name
• Use the real n, e, and x5t#S256 values from your conversion

Step 5: Deploy the DID Document

Place the did.json file at:

Code
 
https://yourdomain.com/.well-known/did.json

Your web server must:

• Serve the file over HTTPS
• Return application/json content type
• Respond to CORS requests if needed

Testing Your Setup

To check your configuration:

Code(bash)
 
curl -H "Accept: application/json" https://yourdomain.com/.well-known/did.json

Ensure:

• The document loads successfully
• The JSON is valid and contains the public key
• HTTPS and domain control are in place

Security Considerations

• Never publish private keys – only the public key belongs in the DID document
• Ensure your domain uses HTTPS
• Keep the certificate and private key securely stored

Next Steps

Once your .well-known/did.json is deployed and verified:

1. Use the corresponding private key to sign Liccium declarations
2. Submit your declarations via the Liccium Declaration API
3. Enable cryptographic verification of your declarations by third parties using your domain-bound DID