Multi-Perspective Issuance Corroboration (MPIC) Service

API Structure The MPIC API implements a system for domain validation and CAA record checking using multiple perspectives across different regions. An MPIC service can accept JSON requests over an arbitrary communication channel with an MPIC client. The MPIC service then produces MPIC responses which are sent back to the MPIC client over the communication channel. The communication channel may be synchronous (i.e., stall open on each MPIC request until an MPIC response is generated) or asynchronous (i.e., send a message to the MPIC service, close, and then receive a future message from the MPIC service containing a corresponding MPIC response). The MPIC service protocol does not provide any form of matching between MPIC requests and MPIC responses. A communication channel is responsible for ensuring that a client can match requests with corresponding responses. The communication channel MUST provide confidentiality and integrity as well as support for authentication of the MPIC service. This document describes communication with an MPIC service using HTTPS POST as the communication channel. Alternate communication channels include gRPC, Apache Kafka, RabbitMQ, etc... A MPIC service running over the HTTPS POST communication channel is identified by a HTTPS url. As a running example, say https://mpc.example.com/staging. A client requests a MPIC validation from the service by sending a POST request to the resource /mpic/draft-00 below the service URL. In the running example https://mpc.example.com/staging/mpic/draft-00. [[ The final version of the API will use /mpic/v1. Incompatible versions of the draft will bump the -00. ]] The body of the HTTP POST is a JSON object that describs the MPIC request. The service will respond with a JSON object containing MPIC results. There are three different MPIC validation methods, described below. The request object has a method field that allows to distinguish between each.

caa validation method A caa requests asks the MPIC service to retrieve the relevant CAA DNS records for a given domain from multiple perspectives. This method has the following specific fields.

domain (required, string): The domain to check the CAA records for.

An example request is given below. If successful (described in TODO REF below), the response object contains a success field set to true, and an caa field, which itself is an object with two fields:

domain The domain on which the CAA records were found. This could be a parent domain of the requested domain.
records A list of base64 encoded CAA records.

An example of a response for a succesful validation. On failure, the response object will have the success field set to false, and an error field describing the error. [[ TODO do we to define the possible errors, or at least assign some codes? ]] An example of a response for an unsuccesful validation. [[ TODO How much information to return on error to help debug, and how structured should it be? I'd say it's good to be helpful, but it's bad to be structured as it's less readable. ]]

http-acme method http-acme requests the MPIC server to perform ACME http-01 challenge validation for the domain's HTTP server from each distributed perspectives. Performs a GET from multiple perspectives, and checks whether the body matches expectation. Optionally, it allows performing an additional CAA record lookup for the domain. The request JSON object has the following specific fields.

domain_or_ip (required, string): The domain name or IP address being verified.
token (required, string): The token value defined in Section 8.3.
key_authorization (required, string): The Key Authorization defined in Section 8.1.
caa_check (optional, boolean): Performs CAA validation at the same time for the domain as described above. Defaults to true unless domain_or_ip is an IP address.

The MPIC server constructs a URL by populating the URL template , http://{domain_or_ip}/.well-known/acme-challenge/{token}, and verifies that the resulting URL is well-formed, before making a HTTP GET request to the URL from each vantage point. Each perspective SHOULD follow redirects when dereferencing the URL. The MPIC server verifies that the key_authorization value provided by the client matches with the body of the response received from each perspective. If the above verifications succeeds, then the validation is successful. If the request fails, or the body does not pass these checks, then it has failed. Along side, the MPIC server queries for the CAA records for the domain_or_ip if the caa_check request parameter is set to "true". If either HTTP or CAA validation (when requested) fail, the response objects contains a top-level success field set to false, and contains an error field that describes the error. If both succeed, the response object contains a top-level success field set to true. The response also contains an object (located under the key perspectives) with keys that uniquiely identify the perspectives used in the reqest. Each perspective is associated with an object that contains success key pointing to a boolean value of true or false to indicate whether validation was successful at that perspective or not. If a CAA check was requested, the response object will contain a top level caa field as described in . An example of a response for a succesful validation with caa-check set to false. An example of a response for a succesful validation with caa-check set to true. An example of a response where the validation failed with caa_check set to true, and the caa method being successful. Similarly example of a response where caa_check set to true, and both methods fail. { "success": false, "perspectives": { "jfk": {"success": false}, "fra": {"success": true}, "lis": {"success": false} } "caa": { "domain": "example.com", "records": ["AAVpc3N1ZWxldHNlbmNyeXB0Lm9yZw=="] } "error": "HTTP found unexpected value at LIS perspective. CAA check failed at the JFK perspective.", }

dns method Required request fields

domain
record-type
prefix
expected

Optional

caa Defaults to true.

Response is same as with http.