github.com/nuts-foundation/go-did

A library to parse and generate W3C DID Documents and W3C Verifiable Credentials.

Example usage

Note on parsing: in earlier versions, DID documents, credentials and presentations were parsed using UnmarshalJSON. Now, ParseDocument(), ParseVerifiableCredential() and ParseVerifiablePresentation() should be used instead: they better support VCs and VPs in JWT format.

Parsing a DID document

didDoc, err := did.ParseDocument(didDocJson)
if err != nil {
    panic(err)
}
// do something with didDoc

Creating a DID document

Creation of a simple DID Document which is its own controller and contains an AssertionMethod.

didID, err := did.ParseDID("did:example:123")

// Empty did document:
doc := &did.Document{
    Context:            []did.URI{did.DIDContextV1URI()},
    ID:                 *didID,
}

// Add an assertionMethod
keyID, _ := did.ParseDIDURL("did:example:123#key-1")

keyPair, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
verificationMethod, err := did.NewVerificationMethod(*keyID, did.JsonWebKey2020, did.DID{}, keyPair.Public())

// This adds the method to the VerificationMethod list and stores a reference to the assertion list
doc.AddAssertionMethod(verificationMethod)

didJson, _ := json.MarshalIndent(doc, "", "  ")
fmt.Println(string(didJson))

Outputs:

{
  "assertionMethod": [
    "did:example:123#key-1"
  ],
  "@context": "https://www.w3.org/ns/did/v1",
  "controller": "did:example:123",
  "id": "did:example:123",
  "verificationMethod": [
    {
      "controller": "did:example:123",
      "id": "did:example:123#key-1",
      "publicKeyJwk": {
        "crv": "P-256",
        "kty": "EC",
        "x": "UANQ8pgvJT33JbrnwMiu1L1JCGQFOEm1ThaNAJcFrWA=",
        "y": "UWm6q5n1iXyeCJLMGDInN40bkkKr8KkoTWDqJBZQXRo="
      },
      "type": "JsonWebKey2020"
    }
  ]
}

Parsing Verifiable Credentials and Verifiable Presentations

The library supports parsing of Verifiable Credentials and Verifiable Presentations in JSON-LD, and JWT proof format. Use ParseVerifiableCredential(raw string) and ParseVerifiablePresentation(raw string).

Creating Verifiable Credentials and Verifiable Presentations

The library supports creating Verifiable Credentials and Verifiable Presentations in JWT proof format.

Use CreateJWTVerifiableCredential() and CreateJWTVerifiablePresentation().

See vc/vp_test.go and vc/vc_test.go for examples.

Supported key types

• JsonWebKey2020
• Ed25519VerificationKey2018
• EcdsaSecp256k1VerificationKey2019 (pass build tag to enable: -tags=jwx_es256k)

Note: as of the jwx v3 upgrade, RSA keys used as JsonWebKey2020 are validated on creation and on parsing an existing publicKeyJwk, and are rejected if the modulus is smaller than 2048 bits. Earlier versions of this library did not perform this check, so a DID document containing a pre-existing RSA key below 2048 bits that resolved before will now fail to parse. This is a process-wide setting of the underlying jwx library; it can be lowered (not recommended) by calling jwk.Configure(jwk.WithMinRSAModulusBits(n)) (from github.com/lestrrat-go/jwx/v3/jwk) once during application startup, before any keys are parsed.

Installation

go get github.com/nuts-foundation/go-did

Testing

go test ./... -tags=jwx_es256k

State of the library

We keep the API stable, breaking changes will only be introduced in new major versions.