How to use naked domain name DID

The usage of did:wba:{domain} is similar to did:web:{domain}. The main rules are as follows:

1. The resolution method is consistent with the naked domain name entry of did:web: did:wba:example.com corresponds to https://example.com/.well-known/did.json
2. Naked domain name DID is mainly used to express "the entire domain name subject" or "domain-level service identity", rather than a specific user or sub-identity;
3. For domain-level service-to-service HTTP identity authentication, a service can use the naked domain name DID as its service identity, unless its application protocol defines a different binding;
4. The naked domain name DID does not carry the e1_ path binding fingerprint, so the path binding verification rules of this specification for the e1_ path type DID do not apply;
5. Its HTTP Message Signatures verification method is consistent with the similar usage of did:web: the verifier parses the DID, checks whether the verification method pointed to by keyid exists and is authorized by the authentication relationship, and then uses the corresponding public key to verify the request signature.

See the native did:web compatibility section for details on how native did:web identifiers can participate in the same authentication model.

Create (Register)

The did:wba method specification does not specify specific HTTP API operations, but leaves programmatic registration and management to each implementation to define according to the requirements of its Web environment.

Creating a DID requires the following steps:

1. Apply to the domain name registrar to use the domain name;
2. Store the location and IP address of the hosting service in the DNS query service;
3. If you create a path-type DID, first generate the Ed25519 binding key and calculate the e1_ fingerprint segment according to Section 2.2.2;
4. Create a DID document JSON-LD file, containing the appropriate key pair, and store the did.json file under the .well-known URL to represent the entire domain name, or under the specified path if multiple DIDs need to be resolved under the domain name.

For example, for the domain name example.com, did.json will be available under the following URL:

Example: Creating a DID
did:wba:example.com
 -> https://example.com/.well-known/did.json

The creation and hosting method of the naked domain name DID is consistent with the naked domain name entry of did:web: the domain name owner only needs to provide the corresponding DID document in /.well-known/did.json, and the DID can be used as the domain name subject identity or domain-level service identity.

If an optional path is specified instead of a naked domain name, and the default path scheme is used, did.json will be available under the path with the e1_ fingerprint segment:

Example: Creating a path-based DID with the default path scheme
did:wba:example.com:user:alice:e1_<fingerprint>
 -> https://example.com/user/alice/e1_<fingerprint>/did.json

If an optional port is specified on the domain name, the colon between the host and the port must be percent-encoded to prevent conflicts with the path.

Example: Creating a DID with an optional path and port
did:wba:example.com%3A3000:user:alice:e1_<fingerprint>
 -> https://example.com:3000/user/alice/e1_<fingerprint>/did.json

Reading and Parsing

The following steps must be performed to parse a DID Document from a did:wba DID:

• Replace : with / in method-specific identifiers to obtain the fully qualified domain name and optional path.
• Percent decode the colon if the domain name contains a port.
• Generate HTTPS URLs by prepending https:// to the expected DID document location.
• If no path is specified in the URL, /.well-known is appended.
• Append /did.json to complete the URL.
• Perform HTTP GET requests to the URL using a proxy capable of successfully negotiating a secure HTTPS connection that enforces the security requirements described in Section 2.6 Security and Privacy Considerations.
• Verify that the id of the parsed DID Document matches the did:wba DID being parsed.
• For the e1_ path type DID defined by the main specification, it must be verified according to the following strict binding relationship:
  • DID Document top-level proof must exist;
  • proof must pass DataIntegrityProof + eddsa-jcs-2022 verification;
  • The verification method pointed to by proof.verificationMethod MUST be Ed25519 Multikey (or a semantically equivalent Ed25519 verification method representation);
  • Calculate the RFC 7638 thumbprint with the Ed25519 public key corresponding to proof.verificationMethod, and the result must be completely consistent with the last e1_ fingerprint segment of the DID path.
• When performing DNS resolution during an HTTP GET request, clients should use RFC8484 to prevent tracking of the identity being resolved.
• For e1_ DID, the above proof verification is not affected by the local policy switch, but is a necessary condition for successful parsing.
• For other profiles, if the local policy enables DID Document proof verification and the document contains proof, it should be verified according to the corresponding profile rules.

For naked domain name DIDs, the parsing and verification process follows the same basic pattern as did:web naked domain name DIDs: parse /.well-known/did.json, check id consistency, and verify the verification method in the authentication relationship according to DID Core / HTTP Message Signatures rules; e1_ path binding verification does not apply.

Update

To update the DID document, you need to update the did.json file corresponding to the DID.

For path type did:wba with the default path scheme, as long as the last bound key fingerprint of the DID path does not change, the DID itself will remain unchanged, but other contents of the DID document can change, for example, adding new verification keys, revoking old keys, or updating service endpoints.

If the binding key changes, the path DID MUST be changed to the new DID. At this time, a new DID document should be created, and an upper-layer Agent Name Service, similar to DNS, can be responsible for stable references and migration.

Note:

1. Use a version control system such as git and a continuous integration system such as GitHub Actions to manage updates to DID documents, which can provide support for authentication and audit history.
2. The HTTP API update process does not specify a specific HTTP API, but leaves programmatic registration and management to each implementer to define according to their needs.

Deactivation

To delete a DID document, the did.json file must be removed or otherwise no longer publicly available.

For path type did:wba using the default path scheme, if the binding key is permanently discarded, the rotation can also be completed by deactivating the old DID and creating a new DID; the stable reference relationship is maintained by an upper-layer Agent Name Service.

DID Document Proof

Whether the top-level proof field appears in a did:wba DID Document depends on the profile in use. For the default e1_ profile, proof is a required field; for other profiles, the DID Document MAY contain a top-level proof field to provide proof of document integrity. This field is used to prove that the DID Document has not been tampered with after the proof was generated and indicates that the signer controlled the corresponding private key when the proof was created. Proof itself does not replace DID method parsing, nor does it replace the id consistency check on its own.

For the default e1_ profile, the proof profile defined by the master specification MUST conform to:

• Verifiable Credential Data Integrity 1.0
• Data Integrity EdDSA Cryptosuites v1.0

The proof object contains the following fields:

• type: required field. Fixed to DataIntegrityProof
• cryptosuite: required field. Fixed to eddsa-jcs-2022
• created: required field. Proof creation time, in XML Schema datetime format
• verificationMethod: required field. Full DID URL pointing to Ed25519 Multikey in the DID Document used to generate the proof
• proofPurpose: required field. Fixed to assertionMethod
• proofValue: required field. Use base58-btc multibase (z...) encoding
• domain: optional field
• challenge: optional field

Additional constraints:

1. proof.verificationMethod MUST use e1_ to bind the key to unify DID path binding, public key binding and document integrity certification;
2. The parser MUST recalculate the RFC 7638 thumbprint with the Ed25519 public key corresponding to proof.verificationMethod and verify that it is completely consistent with the last e1_ fingerprint segment of the DID path;
3. The generation and verification of proof MUST follow the standard algorithm process of eddsa-jcs-2022, and the algorithm details will no longer be rewritten by this specification.

When parsing an e1_ did:wba DID Document, proof verification is not an optional enhanced check, but part of the path-binding semantics. If proof is missing, proof verification fails, or proof.verificationMethod is inconsistent with the e1_ binding fingerprint, parsing MUST fail.

For e1_ DIDs, there is no relaxed mode of "DID Document does not contain proof and can still be parsed".

For non-e1_ profiles, implementations MAY choose one of the following two modes according to the corresponding profile rules or local policy:

1. Relaxed mode: If the DID Document does not contain proof, parsing can still continue;
2. Strict mode: If the local policy requires proof, the lack of proof in the DID Document MUST be regarded as a verification failure.

Normative Note:

For DIDs using the e1_ profile, this specification requires that the top-level proof of the DID Document use the W3C standard Data Integrity proof mechanism. Its proof data model, proof configuration, document transformation, hashing, proof serialization and verification rules follow Verifiable Credential Data Integrity 1.0 and Data Integrity EdDSA Cryptosuites v1.0 respectively. This specification only restricts the use location, field requirements and verification relationship of proof in the did:wba scenario, and does not repeatedly define the underlying cryptographic algorithm; if a conflict occurs, the upstream W3C specification shall prevail.

Request header format

Clients MUST send authentication information using the Signature-Input and Signature header fields defined in RFC 9421. When a request includes a message body, the client MUST also send the Content-Digest header field defined in RFC 9530.

The minimum signature coverage set is as follows:

• @method
• @target-uri
• content-digest (when the request contains a message body)

Recommended additional components for coverage are as follows:

• @authority
• content-type
• content-length

The key parameter requirements in Signature-Input are as follows:

• keyid: MUST be a complete DID URL, pointing to a verification method in the DID document, for example: did:wba:example.com:user:alice:e1_<fingerprint>#key-1
• created: MUST, indicating the signature creation time
• expires: SHOULD, indicating the signature expiration time
• nonce: MAY be carried; if nonce is given in the server challenge, the client MUST use that nonce
• alg: Non-required field. This specification does not mandate the use of the alg parameter, the verifier can determine the algorithm based on the DID verification method type pointed to by keyid

By default, the client SHOULD sign using the binding key corresponding to the last e1_ fingerprint segment of the DID path. If the server allows other authentication verification methods, it belongs to the local authorization policy and does not change the binding semantics of DID.

Client request example:

POST /orders HTTP/1.1
Host: api.example.com
Content-Type: application/json
Content-Digest: sha-256=:BASE64_SHA256_DIGEST:
Signature-Input: sig1=("@method" "@target-uri" "@authority" "content-digest");created=1733402096;expires=1733402156;nonce="abc123";keyid="did:wba:example.com:user:alice:e1_<fingerprint>#key-1"
Signature: sig1=:BASE64_SIGNATURE:

Signature generation process

1. If the HTTP request contains a message body, the client first calculates the Content-Digest value of the message body according to RFC 9530.
2. Select the verification method to use for the signature. By default, binding keys for path-type DIDs should be used in preference.
   • If the DID uses the Ed25519 binding key represented by Multikey (corresponding to the e1_ profile), it should be signed using the Ed25519 algorithm;
   • Other algorithms are defined by corresponding verification method types.
3. Construct Signature-Input, covering at least @method and @target-uri; if a message body exists, content-digest must also be covered.
4. Generate a signature base string (signature base) according to the rules defined in RFC 9421.
5. Use the client private key to sign the signature base, obtain the signature byte string, and write it into the Signature header field.
6. Send Signature-Input, Signature, and (if applicable) Content-Digest to the server.

Verification request header

After receiving the client request, the server performs the following verification:

1. Verify request format: Check whether Signature-Input and Signature exist; when the request contains a message body, check whether Content-Digest exists.
2. Verify message body integrity: When the request contains a message body, verify whether Content-Digest is consistent with the actual message body according to RFC 9530.
3. Extract keyid and parse DID: Extract keyid from Signature-Input to obtain the corresponding DID and verification method.
4. Read DID document: Parse the DID document based on DID.
5. Verify DID binding relationship:
   • Verify that the verification method pointed to by keyid exists;
   • Verify that the verification method is authorized by the authentication relationship of the DID document;
   • For e1_ DID, the DID binding relationship must be verified based on the Ed25519 public key corresponding to proof.verificationMethod instead of randomly selecting an Ed25519 key in authentication:
     • proof must exist and pass eddsa-jcs-2022 verification;
     • Recalculate the RFC 7638 thumbprint using this public key, and the result MUST be exactly the same as the last e1_ fingerprint segment of the DID path.
6. Verify signature coverage: Rebuild the signature base based on Signature-Input, and verify that the HTTP components covered by the signature are consistent with the actual request.
7. Verification time window: Check whether created / expires is within a reasonable time range. The recommended time window is 1 minute to 5 minutes, which is configurable by the implementer.
8. Verification Replay Protection:
   • For direct connection proof profile, the server should establish a short-term replay cache for (keyid, nonce) or equivalent keys;
   • For challenge profile, if nonce comes from a server challenge, then nonce MUST be used one at a time.
9. Verify DID permission: After successful authentication, independently verify whether the DID in the request has the permission to access server resources. If there is no permission, 403 Forbidden is returned.
10. Verification result: If the signature verification is successful, the request passes the authentication; otherwise, 401 Unauthorized is returned with challenge information attached.

Signature verification process

1. Parse the signature tag, coverage component, created, expires, nonce, keyid and other parameters from Signature-Input, and extract the corresponding signature value from Signature.
2. According to RFC 9421 rules, the signature base is reconstructed based on the actual HTTP request.
3. Obtain the corresponding verification method and public key from the DID document according to keyid.
4. Select the verification algorithm based on the verification method type:
   • For the Ed25519 verification method represented by Multikey, verify according to the 64-byte signature format of Ed25519;
   • Other algorithms are defined according to the corresponding verification method type.
5. Use the obtained public key to verify the signature to ensure that the signature is generated by the corresponding private key.
6. If the request contains a message body, the Content-Digest verification results should also be included in the overall certification conclusion.

Successful authentication returns access_token

After the server-side verification is successful, the access token can be returned in the response. The access token is recommended to use JWT (JSON Web Token) format. The client's subsequent requests carry the access token. The server does not need to verify the client's DID identity every time, but only needs to verify the access token. The following generation process is not required by the specification and is for reference only. Implementers can define and implement it as needed.

JWT generation method reference RFC7519.

1. Generate Access Token

Assuming that the server uses JWT (JSON Web Token) as the Access Token format, JWT usually contains the following fields:

• header: Specify signature algorithm
• payload: stores user related information
• signature: Sign header and payload to ensure their integrity

The payload can contain the following fields (other fields are added as needed):

{
  "sub": "did:wba:example.com:user:alice:e1_<fingerprint>",
  "iat": "2024-12-05T12:34:56Z",
  "exp": "2024-12-06T12:34:56Z",
  "scope": "orders.read orders.write"
}

2. Return Access Token

The server MUST return the access token via the Authentication-Info response header, not the Authorization response header.

Example:

Authentication-Info: access_token="eyJhbGciOi...", token_type="Bearer", expires_in=3600, scope="orders.read orders.write"

3. Suggestions on sender-constrained token

In order to reduce the risk of the token being directly reused after being leaked, it is recommended to use sender-constrained access token to bind the token to the key held by the client.

This version of the specification retains this extension capability, but does not yet fully define the specific profile of sender-constrained token. Implementers can reserve the following capabilities for future expansion:

• Add a statement bound to the client's public key in the token (such as cnf or equivalent field);
• Require the client to continue to provide proof bound to the token in subsequent requests;
• Differentiate different token profiles through the token_type field.

Before the sender-constrained profile is unified, for the sake of compatibility, you can use Bearer as the default token_type.

4. Client sends Access Token

The client usually sends the Access Token via the Authorization header field in subsequent requests:

Authorization: Bearer <access_token>

If the token_type returned by the server is not Bearer, the client MUST send the token according to the corresponding extension specification.

5. Server-side verification Access Token

After receiving the client's request, the server extracts the Access Token from the Authorization header and performs verification, including verifying the signature, verifying the expiration time, verifying the fields in the payload, etc. The verification method refers to RFC7519.

Error handling

3.2.4.1 401 response

When the server fails to verify the signature, Content-Digest fails to verify, the signature expires, there is a risk of replay, or the server requires the client to re-sign according to the challenge information, it can return a 401 Unauthorized response.

If the server requires that the client must use the nonce issued by the server for signature, it can return 401 when the client makes the first request and append the challenge information to the response. This adds an interaction that implementers can choose to use or not if needed.

Error information is returned through the WWW-Authenticate header field, and the server can also indicate the components it expects to cover in the next request through Accept-Signature. Examples are as follows:

WWW-Authenticate: DIDWba realm="api.example.com", error="invalid_signature", error_description="Signature verification failed.", nonce="xyz987"
Accept-Signature: sig1=("@method" "@target-uri" "@authority" "content-digest");created;expires;nonce;keyid
Cache-Control: no-store

Contains the following fields:

• realm: optional field, indicating the domain to which the protected resource belongs
• error: required field, error type, containing the following string values:
  • invalid_request: The request is malformed, missing required fields, or contains unsupported parameters
  • invalid_nonce: Nonce is used, is invalid, or does not match the server challenge
  • invalid_timestamp: timestamp out of range
  • invalid_did: The DID format is wrong, or the corresponding DID document cannot be found based on the DID.
  • invalid_signature: Signature verification failed
  • invalid_verification_method: Unable to find the corresponding public key based on keyid
  • invalid_content_digest: Content-Digest does not match the message body
  • invalid_access_token: access token verification failed
  • forbidden_did: DID does not have permission to access server resources
• error_description: optional field, error description
• nonce: Optional field, a random string generated by the server. If carried, the client needs to use the nonce to regenerate the signature and reinitiate the request

After the client receives the 401 response, if the response carries nonce, it needs to use the server's nonce to regenerate the signature and reinitiate the request. If the response does not carry nonce, the client can regenerate the local nonce and try again.

It should be noted that the client and server need to limit the number of retries in their respective implementations to prevent an infinite loop.

3.2.4.2 403 response

When server-side authentication is successful, but the DID does not have the permission to access server-side resources, a 403 Forbidden response can be returned.