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
To install sd-jwt, use go get:
go get github.com/TBD54566975/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/TBD54566975/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 official 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
- type FlatBlindOption
- type HashFunc
- type HolderBindingOption
- type IssuanceVerificationOptions
- type RecursiveBlindOption
- type SDJWTSigner
- type SaltGenerator
- type Signer
- type SubClaimBlindOption
- type VerificationOptions
Constants ¶
This section is empty.
Variables ¶
This section is empty.
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 ¶
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/TBD54566975/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 ¶
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 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 ¶
SaltGenerator generates a cryptographically random string.
func NewSaltGenerator ¶
func NewSaltGenerator(numBytes int) SaltGenerator
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
}
Source Files
Directories