sdjwt

README

sdjwt

Go implementation of SD-JWT (RFC 9901) verification.

• One dependency — golang-jwt/jwt/v5, a mature and widely-used JWT library
• Thoroughly tested — coverage enforced above 95% in CI

Scope

This module implements verifier functionality only. It does not support issuing or holding SD-JWTs.

Supported

• Verification of SD-JWT and SD-JWT+KB compact serialization
• Key Binding verification (SD-JWT+KB)
• Selective disclosure processing (object properties and array elements)
• Recursive disclosures
• sha-256 digest algorithm
• Signature algorithms: ES256/384/512, RS256/384/512, PS256/384/512, EdDSA
• Validation of exp, nbf, iss, and aud claims

Not supported

• Issuance (creating SD-JWTs)
• Holder operations (selecting disclosures, creating presentations)
• Key Binding confirmation methods other than cnf.jwk (e.g., jku, kid, x5c)
• Digest algorithms other than sha-256
• JWS JSON serialization

Usage

import "github.com/joesiltberg/sdjwt"

Basic verification (SD-JWT)

claims, err := sdjwt.Verify(token, issuerPublicKey,
    sdjwt.WithTime(time.Now()),
    sdjwt.WithIssuer("https://issuer.example.com"),
)
// claims.Payload contains the reconstructed JSON payload

Verification with Key Binding (SD-JWT+KB)

claims, err := sdjwt.Verify(token, issuerPublicKey,
    sdjwt.WithTime(time.Now()),
    sdjwt.WithKeyBinding("expected-nonce", "https://verifier.example.org"),
)
// claims.Payload contains the reconstructed JSON payload
// claims.KeyBindingPayload contains the KB-JWT claims (iat, nonce, aud)

Documentation

Index

• type Claims
  • func Verify(token string, key crypto.PublicKey, opts ...Option) (*Claims, error)
• type Option
  • func WithAudience(audience string) Option
  • func WithIssuer(issuer string) Option
  • func WithKeyBinding(nonce, audience string) Option
  • func WithTime(t time.Time) Option

Examples

• Verify
• Verify (KeyBinding)

Types

type Claims

type Claims struct {
	Payload           map[string]any
	KeyBindingPayload map[string]any
}

Claims holds the verified and processed payload of an SD-JWT. When Key Binding is used, KeyBindingPayload contains the KB-JWT claims.

func Verify

func Verify(token string, key crypto.PublicKey, opts ...Option) (*Claims, error)

Verify verifies an SD-JWT compact serialization, validates the issuer's signature, processes disclosures, and returns the reconstructed claims.

Example

ExampleVerify demonstrates verifying an SD-JWT with selective disclosure. The token and key are from RFC 9901 Section 5. Only four of the ten disclosures are included: given_name, family_name, address, and one nationality (US).

key := rfc9901IssuerKey(nil)
token := buildSDJWT(rfc9901JWT,
	discFamilyName, discAddress,
	discGivenName, discNationalityUS,
)

claims, err := Verify(token, key, WithTime(rfc9901VerifyTime))
if err != nil {
	fmt.Println("error:", err)
	return
}

fmt.Println("iss:", claims.Payload["iss"])
fmt.Println("given_name:", claims.Payload["given_name"])
fmt.Println("family_name:", claims.Payload["family_name"])

nats := claims.Payload["nationalities"].([]any)
fmt.Println("nationalities:", nats)

Output:
iss: https://issuer.example.com
given_name: John
family_name: Doe
nationalities: [US]

Example (KeyBinding)

ExampleVerify_keyBinding demonstrates verifying an SD-JWT+KB with Key Binding. The verifier requires a specific nonce and audience, which are checked against the KB-JWT claims.

key := rfc9901IssuerKey(nil)
token := buildSDJWTKB(rfc9901JWT, rfc9901KBJWT,
	discFamilyName, discAddress,
	discGivenName, discNationalityUS,
)

claims, err := Verify(token, key,
	WithTime(rfc9901KBVerifyTime),
	WithKeyBinding("1234567890", "https://verifier.example.org"),
)
if err != nil {
	fmt.Println("error:", err)
	return
}

fmt.Println("given_name:", claims.Payload["given_name"])
fmt.Println("family_name:", claims.Payload["family_name"])
fmt.Println("kb nonce:", claims.KeyBindingPayload["nonce"])
fmt.Println("kb aud:", claims.KeyBindingPayload["aud"])

Output:
given_name: John
family_name: Doe
kb nonce: 1234567890
kb aud: https://verifier.example.org

type Option

type Option func(*verifyConfig)

Option configures the behavior of Verify.

func WithAudience

func WithAudience(audience string) Option

WithAudience requires the aud claim to contain the expected audience.

func WithIssuer

func WithIssuer(issuer string) Option

WithIssuer requires the iss claim to match the expected issuer.

func WithKeyBinding

func WithKeyBinding(nonce, audience string) Option

WithKeyBinding requires the Holder to provide a Key Binding JWT (SD-JWT+KB). The nonce and audience must be non-empty and are verified against the KB-JWT claims.

func WithTime

func WithTime(t time.Time) Option

WithTime sets a fixed time for exp/nbf validation instead of the system clock.