MoLE HTTP Transport

6.1.1. Anchor -> Client

struct {
  uint16 endorsement_type;
  opaque anchor_context<V>;
} EndorsementChallenge;

• endorse contains a base64url EndorsementChallenge value, encoded per [BASE64].¶

WWW-Authenticate: Mole endorse="<endorsement-challenge>",
                       realm="anchor"

6.1.2. Client <-> Anchor

After receiving a challenge, the Client runs the grant exchanges with the Anchor as defined by the endorsement protocol in [PROTOCOLS], for example HTTP POST requests such as the ones defined there. The anchor_context from the challenge is carried into the first request as specified by the endorsement type.¶

6.2.1. Moderator -> Client

struct {
  uint16 endorsement_type; // always present, see PROTOCOLS
  opaque challenge<V>;
} ModeratorChallenge;

• redeem contains a base64url ModeratorChallenge value, encoded per [BASE64].¶

The challenge field carries exactly the TLS encoding of the common RedemptionChallenge defined in [PROTOCOLS]. Anchor material and issuance contexts come from authenticated configuration; this challenge is never sent to an Anchor.¶

WWW-Authenticate: Mole redeem="<moderator-challenge>",
                       realm="moderator"

6.2.2. Client -> Moderator

The Client answers with a CredentialRequest ([PROTOCOLS]) in the Authorization header of a POST request to the Moderator's Redeem & Issue endpoint (Section 5), whichever resource sent the redeem challenge. It carries the endorsement redemption, bound to this challenge, together with the issuance request.¶

Authorization: Mole credential-request="<credential-request>"

6.2.3. Moderator -> Client

The Moderator returns the CredentialResponse ([PROTOCOLS]) in the Mole-Credential response header.¶

Mole-Credential: response="<credential-response>"

6.3.1. Moderator -> Client - Challenge

struct {
  uint16 credential_type; // always present, see PROTOCOLS
  opaque challenge<V>;
} CredentialChallenge;

• challenge which contains a base64url CredentialChallenge value, encoded per [BASE64]¶

The challenge field carries exactly the type-specific challenge defined for the named credential type in [PROTOCOLS]. The Moderator endpoint for Redeem & Issue comes from configuration (Section 5).¶

A field that binds a presentation to a request, such as the ACT request_context of [PROTOCOLS], is constructed by the Moderator and opaque to the Client, which uses the received challenge octets as the credential type specifies. This document defines no canonicalization of HTTP requests.¶

WWW-Authenticate: Mole challenge="<credential-challenge>",
                       realm="moderator"

6.3.2. Client -> Moderator - Presentation

struct {
  uint16 credential_type; // always present, see PROTOCOLS
  opaque presentation_and_update<V>;
} CredentialPresentation;

The presentation_and_update field carries the PresentationAndUpdate structure of the named credential type, defined in [PROTOCOLS].¶

Authorization: Mole presentation="<credential-presentation>"

A complete instantiation example is given in the appendix of [PROTOCOLS].¶

6.3.3. Moderator -> Client - Update

TODO(thibault) 1. Headers do not have a fixed protocol limit, but large values are hard to deploy. Other instantiations may define another method, such as returning a URL that the client can fetch. TBD¶

struct {
  uint16 credential_type;
  opaque update_response<V>;
} CredentialUpdate;

struct {
  optional<CredentialUpdate> update;
} OptionalCredentialUpdate;

The update_response field carries the Update structure of the named credential type, defined in [PROTOCOLS].¶

Updates use the same Mole-Credential header as issuance: both return credential material from the Moderator. The parameter distinguishes them, response for issuance and update after a presentation.¶

The Moderator MUST send Mole-Credential with the update parameter after accepting a presentation. For ACCEPTED_WITH_UPDATE, the optional update is present and carries the credential type's Update. For ACCEPTED_NO_UPDATE, the optional update is absent. The Client MUST process this header even when the protected operation returns an error status.¶

An absent optional update records the Moderator's decision to consume the Credential without a replacement. A missing header supplies no such decision; Clients MUST apply the credential type's recovery rules and single-use requirements.¶

• update which contains a base64url OptionalCredentialUpdate value, encoded per [BASE64]¶

Mole-Credential: update="<optional-credential-update>"

Each credential type MUST define the challenge fields that partition cached Credentials, or state that Credentials of that type are not cacheable.¶

6.3.4. Client -> Moderator - Recovery

A Client missing the response to a presentation MAY send a handle instead of resending it.¶

struct {
  uint16 credential_type;
  opaque recovery_handle<V>;
} CredentialRecovery;

The handle is defined by the credential type ([PROTOCOLS]). It is sent in a POST request with empty content to the Redeem & Issue endpoint (Section 5):¶

Authorization: Mole recovery="<credential-recovery>"

The Moderator treats it as a byte-identical resend of the presentation, using no other Client identifier. It MUST NOT perform the protected operation or verify a proof. It answers 409 with the recorded update while the result is retained, and 401 otherwise, whether or not a record exists.¶

6.3.5. ACT Responses

For credential type 0x0001, the Moderator MUST use the following response rules. The issuance rows apply to Redeem & Issue, and the presentation rows apply to Presentation and Update and to recovery requests (Section 6.3.4), as specified in [PROTOCOLS].¶

A 401 response MUST include a WWW-Authenticate: Mole challenge for the required exchange. Invalid authentication includes an unknown or retired key, an unaccepted credential context, a failed proof, or a repeated nullifier for which recovery is unavailable. A recoverable byte-identical presentation or recovery request (Section 6.3.4) is handled by the recovery row.¶

Acceptance of an ACT presentation is the recording of its result in the nullifier store. A response sent after that recording MUST carry the recorded update, including when the protected operation fails with a 4xx or 5xx status. The update is present for a refund and absent for a recorded NoUpdate decision. Rejecting a presentation MUST NOT create a nullifier record or carry a credential update.¶

A recovery response uses 409 (Conflict, Section 15.5.10 of [HTTP]) because the presentation has already been accepted. It carries only the recorded credential result and MUST NOT authorize another attempt of the protected operation. Application-specific recovery determines the outcome of the earlier operation. The Client finalizes a recovered refund under the same rules as a refund received with the original response.¶