sdjwt

README

SD-JWT support in golang

sd-jwt is a library that implements the IETF draft for Selective Disclosure for JWTs. This library facilitates creating combined formats for issuance and presentation with arbitrary payloads, and performing verification from the holder or from the verifiers perspective.

Table of Contents

• Installation
• Quick Start
• Usage
• API Reference
• Configuration
• Contributing
• Building

Installation

To install sd-jwt, use go get:

go get github.com/extrimian/ssi-sdk/sd-jwt

Quick Start

See this example.

You can run it by cloning this repo, changing directory into this directory, and running a go application. See the terminal command below.

git clone github.com/extrimian/ssi-sdk.git
cd ssi-sdk/sd-jwt
go run example.main.go

Usage

The best usage examples can be found in the sd_jwt_test.go file.

API Reference

See our oficial godocs.

Configuration

Configuration is done via dependency injection on the SDJWTSigner struct.

If you want to inject your own implementation of JWT signatures, you can pass it by implementing a struct that satisfies the Signer interface.

If you want to inject your own random number generator, you can pass it by implementation the SaltGenerator interface. We provide a default one which relies on crypto/rand, which you can instantiate by calling NewSaltGenerator.

Building

See the SDK Building section.

Contributing

See the general CONTRIBUTING guide.

Issues

See current issues here.

Documentation

Index

• func CreatePresentation(jwtAndDisclosures []byte, disclosuresToPresent []int, holderBindingJWT []byte) []byte
• func SelectDisclosures(jwtAndDisclosures []byte, claimNames map[string]struct{}) ([]int, error)
• func VerifyIssuance(issuance []byte, verificationOptions IssuanceVerificationOptions) error
• func VerifySDPresentation(presentation []byte, verificationOptions VerificationOptions) (map[string]any, error)
• type BlindOption
• type Disclosure
  • func (d Disclosure) Digest(hashAlg HashFunc) string
  • func (d Disclosure) EncodedDisclosure() (string, error)
• type FlatBlindOption
• type HashFunc
  • func GetHashAlg(t jwt.Token) (HashFunc, error)
• type HolderBindingOption
• type IssuanceVerificationOptions
• type RecursiveBlindOption
• type SDJWTSigner
  • func NewSDJWTSigner(signer Signer, saltGenerator SaltGenerator) *SDJWTSigner
  • func (s SDJWTSigner) BlindAndSign(claimsData []byte, claimsToBlind map[string]BlindOption) ([]byte, error)
• type SaltGenerator
  • func NewSaltGenerator(numBytes int) SaltGenerator
• type Signer
• type SubClaimBlindOption
• type VerificationOptions

Functions

func CreatePresentation

func CreatePresentation(jwtAndDisclosures []byte, disclosuresToPresent []int, holderBindingJWT []byte) []byte

CreatePresentation creates the Combined Format for Presentation as specified in https://www.ietf.org/archive/id/draft-ietf-oauth-selective-disclosure-jwt-04.html#name-combined-format-for-present jwtAndDisclosures is a Combined Format for Issuance as specified in https://www.ietf.org/archive/id/draft-ietf-oauth-selective-disclosure-jwt-04.html#name-combined-format-for-issuanc. disclosuresToPresent is a set of which the indices of the disclosures that the presentation should contain. holderBindingJWT may be empty. It's a JWT with the claims `nonce` and `aud` in them. It's proof shows that this presentation is intended for the Verifier, while also preventing replay attacks.

func SelectDisclosures

func SelectDisclosures(jwtAndDisclosures []byte, claimNames map[string]struct{}) ([]int, error)

SelectDisclosures returns a slice of indices for disclosures contained within the Combined Issuance Format. The indices are selected such that the disclosure's claim name is contained inside the claimNames map.

func VerifyIssuance

func VerifyIssuance(issuance []byte, verificationOptions IssuanceVerificationOptions) error

VerifyIssuance returns an error whenever any of the following happens for the given combined format for issuance: 1. The SD-JWT cannot be verified with the given key and algorithm. 2. There is a disclosure with a digest that is not included in any of the digests of the JWT, nor of the disclosures. This function is intented to aid with https://www.ietf.org/archive/id/draft-ietf-oauth-selective-disclosure-jwt-04.html#name-processing-by-the-holder

func VerifySDPresentation

func VerifySDPresentation(presentation []byte, verificationOptions VerificationOptions) (map[string]any, error)

VerifySDPresentation takes in a combined presentation format as defined in https://www.ietf.org/archive/id/draft-ietf-oauth-selective-disclosure-jwt-04.html#name-combined-format-for-present and Verifies it according to https://www.ietf.org/archive/id/draft-ietf-oauth-selective-disclosure-jwt-04.html#name-verification-by-the-verifie Succesful verifications return a processed SD-JWT payload. TODO(https://github.com/extrimian/ssi-sdk/issues/378): only accept certain algos for validating the JWT, and the holder binding JWT

Types

type BlindOption

type BlindOption interface{}

BlindOption is an interface to encapsulate the different blinding options for nested data in SD-JWTs as described in https://www.ietf.org/archive/id/draft-ietf-oauth-selective-disclosure-jwt-04.html#name-nested-data-in-sd-jwts

type Disclosure

type Disclosure struct {
	Salt       string
	ClaimName  string
	ClaimValue any
}

func (Disclosure) Digest

func (d Disclosure) Digest(hashAlg HashFunc) string

Digest returns the digest according to https://www.ietf.org/archive/id/draft-ietf-oauth-selective-disclosure-jwt-04.html#name-hashing-disclosures

func (Disclosure) EncodedDisclosure

func (d Disclosure) EncodedDisclosure() (string, error)

EncodedDisclosure returns the base64 url safe encoding of this disclosure.

type FlatBlindOption

type FlatBlindOption struct {
	BlindOption
}

FlatBlindOption implements https://www.ietf.org/archive/id/draft-ietf-oauth-selective-disclosure-jwt-04.html#name-option-1-flat-sd-jwt

type HashFunc

type HashFunc func([]byte) []byte

func GetHashAlg

func GetHashAlg(t jwt.Token) (HashFunc, error)

GetHashAlg returns the hashFunc specified in the token.

type HolderBindingOption

type HolderBindingOption bool

const (
	VerifyHolderBinding     HolderBindingOption = true
	SkipVerifyHolderBinding                     = false
)

type IssuanceVerificationOptions

type IssuanceVerificationOptions struct {
	// contains filtered or unexported fields
}

type RecursiveBlindOption

type RecursiveBlindOption struct {
	BlindOption
}

RecursiveBlindOption implements https://www.ietf.org/archive/id/draft-ietf-oauth-selective-disclosure-jwt-04.html#name-option-3-sd-jwt-with-recurs

type SDJWTSigner

type SDJWTSigner struct {
	// contains filtered or unexported fields
}

SDJWTSigner is a struct that facilitates creating the combined format for issuance of SD-JWTs.

func NewSDJWTSigner

func NewSDJWTSigner(signer Signer, saltGenerator SaltGenerator) *SDJWTSigner

NewSDJWTSigner creates an SDJWTSigner with a default configuration. It uses the passed in signer to sign payloads.

func (SDJWTSigner) BlindAndSign

func (s SDJWTSigner) BlindAndSign(claimsData []byte, claimsToBlind map[string]BlindOption) ([]byte, error)

BlindAndSign returns an SD-JWT and Disclosures from an arbitrary JSON-encoded payload. The claims to selectively disclose are determined using the claimsToBlind map. The format of the result is the Combined Format for Issuance as specified in https://www.ietf.org/archive/id/draft-ietf-oauth-selective-disclosure-jwt-04.html#name-combined-format-for-issuanc

type SaltGenerator

type SaltGenerator interface {
	Generate() (string, error)
}

SaltGenerator generates a cryptographically random string.

func NewSaltGenerator

func NewSaltGenerator(numBytes int) SaltGenerator

type Signer

type Signer interface {
	Sign(blindedClaimsData []byte) ([]byte, error)
}

type SubClaimBlindOption

type SubClaimBlindOption struct {
	BlindOption
	// contains filtered or unexported fields
}

SubClaimBlindOption implements https://www.ietf.org/archive/id/draft-ietf-oauth-selective-disclosure-jwt-04.html#name-option-2-structured-sd-jwt

type VerificationOptions

type VerificationOptions struct {
	HolderBindingOption HolderBindingOption
	Alg                 string
	IssuerKey           any

	// The nonce and audience to check for when doing holder binding verification.
	// Needed only when HolderBindingOption == VerifyHolderBinding.
	DesiredNonce, DesiredAudience string

	// Function that goes from a token, to the public key of the holder bound to the confirmation claim. The key will
	// be used for integrity checking.
	// Needed only when HolderBindingOption == VerifyHolderBinding.
	ResolveHolderKey func(jwt.Token) gocrypto.PublicKey
}