Crate ssi_dids

Expand description

DID Methods.

This library provides Decentralized Identifiers (DIDs), a type of identifier defined by the W3C that enables verifiable, self-sovereign digital identities. Unlike traditional identifiers, such as email addresses or usernames, DIDs are not tied to a central authority. Instead, they are generated and managed on decentralized networks like blockchains, providing greater privacy, security, and control to the individual or entity that owns them.

Each DID is an URI using the did scheme. This library uses the DID and DIDBuf (similar to str and String) to parse and store DIDs.

use ssi_dids::{DID, DIDBuf};

// Create a `&DID` from a `&str`.
let did = DID::new("did:web:w3c-ccg.github.io:user:alice").unwrap();

// Create a `DIDBuf` from a `String`.
let owned_did = DIDBuf::from_string("did:web:w3c-ccg.github.io:user:alice".to_owned()).unwrap();

Just like regular URLs, it is possible to provide the DID with a fragment part. The result is a DID URL, which can be parsed and stored using DIDURL and DIDURLBuf.

use ssi_dids::{DIDURL, DIDURLBuf};

// Create a `&DIDURL` from a `&str`.
let did_url = DIDURL::new("did:web:w3c-ccg.github.io:user:alice#key").unwrap();

// Create a `DIDBuf` from a `String`.
let owned_did_url = DIDURLBuf::from_string("did:web:w3c-ccg.github.io:user:bob#key".to_owned()).unwrap();

Note that a DID URL, with a fragment, is not a valid DID.

§DID document resolution

DID resolution is the process of retrieving the DID document associated with a specific DID. A DID document is a JSON-LD formatted file that contains crucial information needed to interact with the DID, such as verification methods containing the user’s public keys, and service endpoints. Here is an example DID document:

{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/suites/jws-2020/v1"
  ],
  "id": "did:jwk:eyJjcnYiOiJQLTI1NiIsImt0eSI6IkVDIiwieCI6ImFjYklRaXVNczNpOF91c3pFakoydHBUdFJNNEVVM3l6OTFQSDZDZEgyVjAiLCJ5IjoiX0tjeUxqOXZXTXB0bm1LdG00NkdxRHo4d2Y3NEk1TEtncmwyR3pIM25TRSJ9",
  "verificationMethod": [
    {
      "id": "did:jwk:eyJjcnYiOiJQLTI1NiIsImt0eSI6IkVDIiwieCI6ImFjYklRaXVNczNpOF91c3pFakoydHBUdFJNNEVVM3l6OTFQSDZDZEgyVjAiLCJ5IjoiX0tjeUxqOXZXTXB0bm1LdG00NkdxRHo4d2Y3NEk1TEtncmwyR3pIM25TRSJ9#0",
      "type": "JsonWebKey2020",
      "controller": "did:jwk:eyJjcnYiOiJQLTI1NiIsImt0eSI6IkVDIiwieCI6ImFjYklRaXVNczNpOF91c3pFakoydHBUdFJNNEVVM3l6OTFQSDZDZEgyVjAiLCJ5IjoiX0tjeUxqOXZXTXB0bm1LdG00NkdxRHo4d2Y3NEk1TEtncmwyR3pIM25TRSJ9",
      "publicKeyJwk": {
        "crv": "P-256",
        "kty": "EC",
        "x": "acbIQiuMs3i8_uszEjJ2tpTtRM4EU3yz91PH6CdH2V0",
        "y": "_KcyLj9vWMptnmKtm46GqDz8wf74I5LKgrl2GzH3nSE"
      }
    }
  ],
  "assertionMethod": ["did:jwk:eyJjcnYiOiJQLTI1NiIsImt0eSI6IkVDIiwieCI6ImFjYklRaXVNczNpOF91c3pFakoydHBUdFJNNEVVM3l6OTFQSDZDZEgyVjAiLCJ5IjoiX0tjeUxqOXZXTXB0bm1LdG00NkdxRHo4d2Y3NEk1TEtncmwyR3pIM25TRSJ9#0"],
  "authentication": ["did:jwk:eyJjcnYiOiJQLTI1NiIsImt0eSI6IkVDIiwieCI6ImFjYklRaXVNczNpOF91c3pFakoydHBUdFJNNEVVM3l6OTFQSDZDZEgyVjAiLCJ5IjoiX0tjeUxqOXZXTXB0bm1LdG00NkdxRHo4d2Y3NEk1TEtncmwyR3pIM25TRSJ9#0"],
  "capabilityInvocation": ["did:jwk:eyJjcnYiOiJQLTI1NiIsImt0eSI6IkVDIiwieCI6ImFjYklRaXVNczNpOF91c3pFakoydHBUdFJNNEVVM3l6OTFQSDZDZEgyVjAiLCJ5IjoiX0tjeUxqOXZXTXB0bm1LdG00NkdxRHo4d2Y3NEk1TEtncmwyR3pIM25TRSJ9#0"],
  "capabilityDelegation": ["did:jwk:eyJjcnYiOiJQLTI1NiIsImt0eSI6IkVDIiwieCI6ImFjYklRaXVNczNpOF91c3pFakoydHBUdFJNNEVVM3l6OTFQSDZDZEgyVjAiLCJ5IjoiX0tjeUxqOXZXTXB0bm1LdG00NkdxRHo4d2Y3NEk1TEtncmwyR3pIM25TRSJ9#0"],
  "keyAgreement": ["did:jwk:eyJjcnYiOiJQLTI1NiIsImt0eSI6IkVDIiwieCI6ImFjYklRaXVNczNpOF91c3pFakoydHBUdFJNNEVVM3l6OTFQSDZDZEgyVjAiLCJ5IjoiX0tjeUxqOXZXTXB0bm1LdG00NkdxRHo4d2Y3NEk1TEtncmwyR3pIM25TRSJ9#0"]
}

DID documents are represented using the Document type and can be resolved from a DID using any implementation of the DIDResolver trait. The AnyDidMethod type is provided as a default implementation for DIDResolver that supports various DID methods (see below).

use ssi_dids::{DID, AnyDidMethod, DIDResolver};

// Create a DID.
let did = DID::new("did:jwk:eyJjcnYiOiJQLTI1NiIsImt0eSI6IkVDIiwieCI6ImFjYklRaXVNczNpOF91c3pFakoydHBUdFJNNEVVM3l6OTFQSDZDZEgyVjAiLCJ5IjoiX0tjeUxqOXZXTXB0bm1LdG00NkdxRHo4d2Y3NEk1TEtncmwyR3pIM25TRSJ9").unwrap();

// Setup the DID resolver.
let resolver = AnyDidMethod::default();

// Resolve the DID document (equal to the example document above).
let document = resolver.resolve(did).await.unwrap().document;

// Extract the first verification method.
let vm = document.verification_method.first().unwrap();

Instead of resolving a DID document and extracting verification methods manually, you can use the dereference method to resolve a DID URL:

use ssi_dids::{DIDURL, AnyDidMethod, DIDResolver};

// Create a DID URL with the fragment `#0` referencing a verification method.
let did_url = DIDURL::new("did:jwk:eyJjcnYiOiJQLTI1NiIsImt0eSI6IkVDIiwieCI6ImFjYklRaXVNczNpOF91c3pFakoydHBUdFJNNEVVM3l6OTFQSDZDZEgyVjAiLCJ5IjoiX0tjeUxqOXZXTXB0bm1LdG00NkdxRHo4d2Y3NEk1TEtncmwyR3pIM25TRSJ9#0").unwrap();

// Setup the DID resolver.
let resolver = AnyDidMethod::default();

// Dereference the verification method.
let vm = resolver
  .dereference(did_url)
  .await
  .unwrap()
  .content
  .into_verification_method()
  .unwrap();

§DID methods

A key component of the DID system is the concept of DID methods. A DID method defines how a specific type of DID is created, resolved, updated, and deactivated on a particular decentralized network or ledger. Each DID method corresponds to a unique identifier format and a set of operations that can be performed on the associated DIDs. The general syntax of DIDs depends on the method used:

did:method:method-specific-id

There exists various DID methods, each defined by their own specification. In this library, methods are defining by implementing the DIDMethod trait. Implementations are provided for the following methods:

did:key: for static cryptographic keys, implemented by DIDKey.
did:jwk: for Json Web Keys (JWK) implemented by DIDJWK.
did:web: for web-hosted DID documents, implemented by DIDWeb.
did:pkh: implemented by DIDPKH.
did:ethr: implemented by DIDEthr.
did:ion: implemented by DIDION.
did:tz: implemented by DIDTz.

The AnyDidMethod regroups all those methods into one DIDResolver implementation.

DID method types can also be used to generate fresh DID URLs:

use ssi_jwk::JWK;
use ssi_dids::DIDJWK;

/// Generate a new JWK.
let jwk = JWK::generate_p256();

/// Generate a DID URL out of our JWK URL.
let did_url = DIDJWK::generate_url(&jwk);

Re-exports§

pub use did_ethr as ethr;
pub use did_ion as ion;
pub use did_jwk as jwk;
pub use did_method_key as key;
pub use did_pkh as pkh;
pub use did_tz as tz;
pub use did_web as web;

Modules§

document
http
method_resolver
registration: DID Registration & Recovery.
resolution
ssi_json_ld: Linked-Data types.

Macros§

did

Structs§

AnyDidMethod: DID resolver for any known DID method.
DID: DID.
DIDBuf: Owned DID.
DIDEthr: did:ethr DID Method
DIDJWK: JSON Web Token (jwt) DID method.
DIDKey: The did:key Method v0.7.
DIDPKH: did:pkh DID Method
DIDTz: did:tz DID Method
DIDURL: DID URL.
DIDURLBuf
DIDWeb: did:web Method
Document: A DID document
Fragment
FragmentBuf
InvalidDID: Error raised when a conversion to a DID fails.
InvalidDIDURL: Error raised when a conversion to a DID URL fails.
InvalidRelativeDIDURL: Error raised when a conversion to a relative DID URL fails.
Path: DID URL path.
PrimaryDIDURL: DID URL without fragment.
PrimaryDIDURLBuf: DID URL without fragment.
Query: DID URL query.
RelativeDIDURL: Relative DID URL.
RelativeDIDURLBuf
RelativePath: DID URL path.
StaticDIDResolver: A simple static DID resolver to perform tests.
Unexpected
VerificationMethodDIDResolver

Enums§

DIDURLReference
DIDURLReferenceBuf
GenerateError: DID generation error.

Constants§

JSON_LD_CONTEXT_IRI: URI required as the first value of the @context property for a DID Document in JSON-LD representation.

Traits§

DIDMethod: DID Method type.
DIDMethodResolver
DIDResolver: DID resolver.

Type Aliases§

DIDION: did:ion Method

Crate ssi_didsCopy item path