Expand description
DID resolution and production: the DidResolver and DidProducer traits a DID method
implements, the Resolver registry that routes a DID to the resolver of its method, an
optional TTL DocumentCache, and DID URL dereferencing. Beside DIDs, finding the key a
token was signed with: KeyReference and KeyResolver.
The module ships no DID method. Each method is a type implementing DidResolver and/or
DidProducer, registered with ResolverBuilder::with; adding one needs no change here.
§Resolution
Resolver::resolve implements the DID Resolution algorithm around the method’s resolver:
it reports ResolutionErrorKind::MethodNotSupported for a method nobody registered, turns a
result whose metadata reports an error into Err, refuses a document whose id is not the
DID being resolved (nor its canonicalId), and serves repeated resolutions from the cache
when one is configured. Resolver::resolve_document is the shortcut to the document.
§Dereferencing
Resolver::dereference resolves the DID of a DID URL and then selects the resource the URL
names: the document itself, or the verification method or service whose id is the URL
(Dereferenced). The versionId and versionTime DID parameters are passed to the
method’s resolver as resolution options; a path, any other query parameter and the
service/relativeRef parameters are method-specific and reported as
DereferenceError::MethodSpecific. Resolver::resolve_public_key goes one step further
and returns the Jwk of a verification method, optionally checked to be
usable for a verification relationship, decoding publicKeyMultibase material as a Multikey,
which is what a JWS verifier needs.
§Key references
A JWT names the key that signed it in one of several ways (ADR 0006), and
KeyReference::from_jws reads which, in this order: a kid that is a DID URL
(did:…#fragment, without a path or DID parameters); a kid that is a #fragment, joined
with a DID iss; an x5c certificate chain; another kid with an HTTPS iss, naming a key
of the issuer’s key set; the key itself in a jwk header; a jku key set URL. A token can
carry more than one of these, and which applies is the verifier’s policy, not the token’s:
KeyReference::candidates lists them all in that order, and a validator takes the first
its KeyResolver handles, so the resolvers an application configures are that policy
(ADR 0008). A KeyResolver turns the reference into a key for a KeyRole, the
issuer’s (assertionMethod in a DID document) or the subject’s (authentication), at the
validation time (KeyResolver::resolve_key_at):
| Reference | Resolved by |
|---|---|
KeyReference::DidUrl | Resolver, dereferencing the verification method |
KeyReference::Jwk | JwkResolver, the key itself |
KeyReference::Jwks | JwksResolver (feature jwks), the JWT VC issuer metadata of the issuer |
KeyReference::X509Chain | X509Resolver (feature x509), the chain validated against the application’s trust anchors |
KeyReference::Jku | nothing in the crate yet; an application’s own KeyResolver |
CompositeKeyResolver tries several in order. Resolving says nothing about trust: after
the signature verifies, KeyReference::binds_to checks that the key belongs to the party
the token claims, which the validators of the upper layer do.
§X.509
With the x509 feature, X509Resolver validates the certificate chain of an x5c header
against trust anchors the application supplies (RFC 5280 §6, by rustls-webpki) and
returns the key of its first certificate: the Inline X.509 Certificates mechanism of
SD-JWT VC §3.5, which the OpenID4VC High Assurance Interoperability Profile 1.0 mandates.
It adds what that profile requires of every x5c, that the signing certificate is not
self-signed. The issuer of such a token is the subject of the first certificate, which
X509Certificate reads; an iss claim binds only as an https URL whose host is a DNS
name of that certificate. An issuer signs with
CertifiedSigner, which puts its chain in the header.
§Plain JWTs
JwtValidator validates a JWT that is neither a credential nor a presentation, an OAuth
2.0 access token say, as RFC 7519 §7.2 and RFC 8725 describe: an allowed alg, the
expected typ, the signature under the key a KeyResolver finds, that key bound to
iss (IssuerBinding), the expected iss and aud, exp, nbf and iat within a
leeway, and the claims the JwtValidationOptions require.
§Examples
A method is a type implementing DidResolver; here one that serves documents from memory.
use std::collections::HashMap;
use identity_kit::did::{
Did, DidDocument, DidUrl, ResolutionError, ResolutionErrorKind, ResolutionOptions,
ResolutionResult,
};
use identity_kit::resolver::{Dereferenced, DidResolver, Resolver};
struct Static(HashMap<Did, DidDocument>);
#[async_trait::async_trait]
impl DidResolver for Static {
fn method(&self) -> &'static str {
"example"
}
async fn resolve(
&self,
did: &Did,
_: &ResolutionOptions,
) -> Result<ResolutionResult, ResolutionError> {
self.0.get(did).cloned().map(ResolutionResult::new).ok_or_else(|| {
ResolutionError::new(ResolutionErrorKind::NotFound)
.with_detail(format!("no document is stored for `{did}`"))
})
}
}
let document: DidDocument = serde_json::from_str(r##"{
"id": "did:example:123",
"verificationMethod": [{
"id": "did:example:123#key-1",
"type": "JsonWebKey2020",
"controller": "did:example:123",
"publicKeyJwk": {
"kty": "OKP", "crv": "Ed25519", "x": "11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHURo"
}
}],
"authentication": ["#key-1"]
}"##)?;
let did = document.id.clone();
let resolver = Resolver::builder()
.with(Static(HashMap::from([(did.clone(), document)])))
.cache(std::time::Duration::from_secs(60))
.build();
assert_eq!(resolver.resolve_document(&did).await?.id, did);
let key = DidUrl::parse("did:example:123#key-1")?;
let jwk = resolver.resolve_public_key(&key, None).await?;
assert_eq!(jwk.crv(), Some("Ed25519"));
assert!(matches!(resolver.dereference(&key).await?, Dereferenced::VerificationMethod(_)));
let unknown = Did::parse("did:other:123")?;
let error = resolver.resolve(&unknown).await.unwrap_err();
assert_eq!(error, ResolutionErrorKind::MethodNotSupported);
assert_eq!(error.detail(), Some("no resolver is registered for `did:other`"));Structs§
- Composite
KeyResolver - Resolvers tried in order: the first answer other than
Unsupportedis the answer, an error included. - Document
Cache - A bounded cache of resolution results, keyed by DID, where every entry expires after the same time to live.
- Document
KeyResolver - Resolves a
KeyReference::DidUrlagainst DID documents supplied by the caller, without resolving the DID again: a document resolved to read its services, or one the caller fetched or publishes itself. - JwkResolver
- Resolves a
KeyReference::Jwkto its public part; every other reference isUnsupported. - Jwks
Resolver jwks - Resolves a
KeyReference::Jwksthrough the JWT VC issuer metadata of the issuer (SD-JWT VC §3.5); every other reference isUnsupported. - JwtValidation
Options - Options of
JwtValidator: what the token must be, and when. - JwtValidator
- Validates a compact JWT that is neither a credential nor a presentation: an OAuth 2.0 access token (RFC 9068), an ID token, a request object.
- Method
Capabilities - What a DID method can do, declared by its
DidProducerso an application can pick a method without knowing it. - Resolver
- Routes each DID to the
DidResolverregistered for its method, with an optionalDocumentCachein front. - Resolver
Builder - Builds a
Resolver. - Validated
Jwt - A JWT that passed
JwtValidator::validate: its header, its claims and the key that signed it. - X509
Certificate x509 - What an X.509 certificate says: its subject and issuer, the names of its Subject Alternative Name extension, its validity period, its key identifiers and its public key.
- X509
Resolver x509 - Resolves a
KeyReference::X509Chain, thex5cheader of a token (RFC 7515 §4.1.6), to the public key of its first certificate once the chain validates against a trust anchor; every other reference isUnsupported.
Enums§
- Dereference
Error - Why a DID URL could not be dereferenced.
- Dereferenced
- The resource a DID URL names, as
Resolver::dereferencereturns it. - Hosting
- Where the documents of a DID method live, which decides what creating one involves.
- Issuer
Binding - Whether the key that signed a token must belong to its issuer.
- Jwks
Error jwks - Why a
JwksResolverfound no key. - JwtValidation
Error - Why a JWT did not pass
JwtValidator::validate. - KeyReference
- Where a token says the key that signed it is (ADR 0006).
- KeyReference
Error - Why a token names no key this crate can look for.
- KeyResolution
Error - Why a
KeyResolverfound no key. - KeyRole
- The role a key plays in a token, which decides what a DID document must say about it.
- Produce
Error - Why a
DidProducercould not produce a document. - X509
Error x509 - Why an
x5cchain yields no key.
Traits§
- DidProducer
- Produces the DID document of one method from public keys.
- DidResolver
- Resolves the DIDs of one method (DID Resolution “DID Resolution Algorithm”).
- KeyResolver
- Finds the public key a
KeyReferencenames.