Authentication

Setup of .well-known/did.json

If you are using an X.509 certificate for authentication of your declarations, you must set up a .well-known/did.json file on your domain to enable verification of your digital signatures.

Overview

This file associates your domain with a Decentralized Identifier (DID) and provides the necessary cryptographic keys for signature validation. To make digital signatures verifiable, the domain used for your DID and certificate issuance must host a .well-known/did.json file.

Prerequisites

Before starting, 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

Convert the .p12 file to a .pem format using OpenSSL to extract the certificate (which contains the public key):

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

Step 2: Extract the Public Key

Extract the public key from your certificate:

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

This command creates a pubkey.pem file containing just the public key in PEM format.

Step 3: Convert the Public Key to JSON Format

The extracted key must be structured in JSON Web Key (JWK) format to be compatible with did.json. The required format is:

Code(json)
 
{
  "kty": "EC",
  "crv": "P-256",
  "x": "<your cert x component>",
  "y": "<your cert y component>"
}

Using Node.js Script

Create a Node.js script to convert the PEM key to JWK format:

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

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

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

Installation and Execution:

Code(bash)
 
# Install the required package
npm install node-jose

# Run the script
node convert-key.js

Alternative: Using Python

If you prefer Python, you can use the following script:

Code(python)
 
import json
from cryptography import x509
from cryptography.hazmat.primitives import serialization
from cryptography.hazmat.primitives.asymmetric import ec
import base64

# Load the certificate
with open('cert.pem', 'rb') as f:
    cert_data = f.read()

cert = x509.load_pem_x509_certificate(cert_data)
public_key = cert.public_key()

# Extract the public key coordinates
public_numbers = public_key.public_numbers()

# Convert to JWK format
jwk = {
    "kty": "EC",
    "crv": "P-256",
    "x": base64.urlsafe_b64encode(public_numbers.x.to_bytes(32, 'big')).decode().rstrip('='),
    "y": base64.urlsafe_b64encode(public_numbers.y.to_bytes(32, 'big')).decode().rstrip('=')
}

print(json.dumps(jwk, indent=2))

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

Using the extracted values, construct your .well-known/did.json file:

Code(json)
 
{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/suites/jws-2020/v1"
  ],
  "id": "did:web:yourdomain.com",
  "verificationMethod": [
    {
      "id": "did:web:yourdomain.com#0",
      "type": "JsonWebKey2020",
      "controller": "did:web:yourdomain.com",
      "publicKeyJwk": {
        "kty": "EC",
        "crv": "P-256",
        "x": "your_cert_x_component",
        "y": "your_cert_y_component"
      }
    }
  ],
  "authentication": [
    "did:web:yourdomain.com#0"
  ],
  "assertionMethod": [
    "did:web:yourdomain.com#0"
  ]
}

Step 5: Deploy the .well-known/did.json File

To enable cryptographic verification of your metadata signatures, upload the .well-known/did.json file to the root of your domain at:

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

Deployment Options

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

You can test your DID document using curl:

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

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

Security Considerations

Next Steps

Once your .well-known/did.json file is properly deployed and accessible:

Certificate Signature Creation - Learn how to sign metadata

This ensures that external verifiers can retrieve and validate your DID document, allowing trusted verification of digital signatures associated with your declarations.