SdJwt.Net 1.0.0

SdJwt.Net Core - RFC 9901 Implementation

A production-ready .NET library for Selective Disclosure JSON Web Tokens (SD-JWTs) compliant with RFC 9901. This is the core library that provides fundamental SD-JWT functionality with enhanced security, performance optimization, and comprehensive multi-platform support.

Features

• RFC 9901 Compliant: Complete implementation of Selective Disclosure for JSON Web Tokens
• JWS JSON Serialization: Full support for Flattened and General JSON formats (RFC 9901 Section 8)
• Enhanced Security: Blocks weak algorithms (MD5, SHA-1), enforces approved SHA-2 family
• Multi-Platform: .NET 8, 9, and .NET Standard 2.1 with platform-specific optimizations
• Production Ready: Battle-tested with comprehensive tests and security hardening

Installation

dotnet add package SdJwt.Net

Quick Start

SD-JWT Structure

graph LR
    subgraph SdJwtCompactFormat[SD-JWT Compact Format]
        Header[Base64url Header: alg, typ]
        Payload[Base64url Payload: iss, iat, exp, _sd hashes, _sd_alg sha-256]
        Sig[Base64url Signature]
        Disc1[~Disclosure 1: salt + claim_name + value]
        Disc2[~Disclosure 2: salt + claim_name + value]
        KB[~KB-JWT: nonce + aud + iat]
    end

    Header -.->|.|  Payload
    Payload -.->|.| Sig
    Sig -.->|~| Disc1
    Disc1 -.->|~| Disc2
    Disc2 -.->|~| KB

    style Header fill:#1b4332,color:#fff
    style Payload fill:#2d6a4f,color:#fff
    style Sig fill:#40916c,color:#fff
    style KB fill:#d62828,color:#fff

Basic SD-JWT Creation

using SdJwt.Net.Issuer;
using Microsoft.IdentityModel.Tokens;
using System.Security.Cryptography;

// Create signing key
using var key = ECDsa.Create();
var signingKey = new ECDsaSecurityKey(key) { KeyId = "issuer-key-1" };
var holderJwk = JsonWebKeyConverter.ConvertFromSecurityKey(
    new ECDsaSecurityKey(ECDsa.Create()) { KeyId = "holder-key-1" });

// Create SD-JWT issuer
var issuer = new SdIssuer(signingKey, SecurityAlgorithms.EcdsaSha256);

// Define claims with selective disclosure
var claims = new JwtPayload
{
    ["iss"] = "https://issuer.example.com",
    ["given_name"] = "John",
    ["family_name"] = "Doe",
    ["email"] = "john.doe@example.com",
    ["address"] = new {
        street = "123 Main St",
        city = "Anytown",
        state = "CA"
    }
};

// Configure selective disclosure
var options = new SdIssuanceOptions
{
    DisclosureStructure = new
    {
        given_name = true,
        family_name = true,
        email = true,
        address = new { city = true, state = true }
    }
};

// Issue SD-JWT
var result = issuer.Issue(claims, options, holderJwk);

Holder Creates Presentation

using SdJwt.Net.Holder;
using Microsoft.IdentityModel.Tokens;
using System.IdentityModel.Tokens.Jwt;
using System.Security.Cryptography;

// Create holder from issuance
var holder = new SdJwtHolder(result.Issuance);
using var holderPrivateEcdsa = ECDsa.Create();
var holderPrivateKey = new ECDsaSecurityKey(holderPrivateEcdsa) { KeyId = "holder-key-1" };
var kbPayload = new JwtPayload
{
    ["aud"] = "https://verifier.example.com",
    ["nonce"] = "job-application-2024-12345",
    ["iat"] = DateTimeOffset.UtcNow.ToUnixTimeSeconds()
};

// Create selective presentation (only disclose email and city)
var presentation = holder.CreatePresentation(
    disclosure => disclosure.ClaimName == "email" || disclosure.ClaimName == "city",
    kbPayload, holderPrivateKey, SecurityAlgorithms.EcdsaSha256);

// For SD-JWT (without KB-JWT), compact output follows RFC 9901 and ends with "~".
// For SD-JWT+KB, the final component is the KB-JWT (no trailing empty component).

Verification

sequenceDiagram
    participant Holder as Holder (Wallet)
    participant Verifier as Verifier

    Holder->>Verifier: VP Token (SD-JWT~email~KB-JWT)

    Note over Verifier: Step 1 - Parse & split
    Verifier->>Verifier: Split on ~ separator
    Verifier->>Verifier: Decode header / payload / sig

    Note over Verifier: Step 2 - Verify issuer signature
    Verifier->>Verifier: Resolve issuer JWKS
    Verifier->>Verifier: Validate JWT signature

    Note over Verifier: Step 3 - Reconstruct disclosures
    Verifier->>Verifier: For each disclosure: SHA-256(salt+name+value)
    Verifier->>Verifier: Verify hash appears in _sd array

    Note over Verifier: Step 4 - Verify Key Binding
    Verifier->>Verifier: Verify KB-JWT signature with holder key
    Verifier->>Verifier: Check nonce matches expected value
    Verifier->>Verifier: Check aud matches verifier URL

    Verifier-->>Holder: Verification Result + Revealed Claims

using SdJwt.Net.Verifier;

// Create verifier with key resolver
var verifier = new SdVerifier(async issuer =>
{
    // Resolve issuer's public key from trusted source
    return await ResolveIssuerKeyAsync(issuer);
});

// Verify presentation
var validationParams = new TokenValidationParameters
{
    ValidateIssuer = true,
    ValidIssuer = "https://issuer.example.com",
    ValidateAudience = false,
    ValidateLifetime = true
};
var kbParams = new TokenValidationParameters
{
    ValidateAudience = true,
    ValidAudience = "https://verifier.example.com",
    ValidateLifetime = true
};

// Verify presentation with expected nonce for replay protection
var expectedNonce = "job-application-2024-12345";
var result = await verifier.VerifyAsync(presentation, validationParams, kbParams, expectedNonce);

if (result.KeyBindingVerified)
{
    Console.WriteLine($"Key Binding Verified. Nonce: {result.KeyBindingJwtPayload?["nonce"]}");
}

// Optional strict policy controls (strict mode is enabled by default)
var verifierOptions = new SdVerifierOptions
{
    StrictMode = true,
    KeyBinding = new KeyBindingValidationPolicy
    {
        RequireKeyBinding = true,
        ExpectedAudience = "https://verifier.example.com",
        MaxKeyBindingJwtAge = TimeSpan.FromMinutes(5)
    }
};

Security Features

• Algorithm Enforcement: Blocks MD5, SHA-1; enforces SHA-2 family
• Constant-time Operations: Protection against timing attacks
• Input Validation: Comprehensive validation throughout APIs
• Cross-platform Security: Consistent guarantees across platforms

Documentation

For comprehensive examples and advanced usage, see the main repository.

License

Licensed under the Apache License 2.0.