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.

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
 
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
 
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
 
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
 
npm install node-jose
node convert-key.js

The output will contain a JWK like:

Code
 
{
  "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
 
{
  "@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

Verification

After deployment, verify your setup by:

1. Accessibility Check: Visit https://yourdomain.com/.well-known/did.json in your browser
2. JSON Validation: Ensure the response is valid JSON
3. CORS Headers: Verify that appropriate CORS headers are set if needed
4. HTTPS: Confirm the file is served over HTTPS

Testing Your DID Document

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

The response should be your DID document with proper JSON formatting.

Deployment Options

Security Considerations

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