services/network/public/mojom/oblivious_http_request.mojom

// Copyright 2022 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

module network.mojom;

import "mojo/public/mojom/base/byte_string.mojom";
import "mojo/public/mojom/base/time.mojom";
import "services/network/public/mojom/isolation_info.mojom";
import
 "services/network/public/mojom/mutable_network_traffic_annotation_tag.mojom";
import "services/network/public/mojom/network_param.mojom";
import "services/network/public/mojom/trust_tokens.mojom";
import "url/mojom/url.mojom";

// The body and content-type of the request. The size of the content is used as
// the content length when constructing headers.
struct ObliviousHttpRequestBody {
  mojo_base.mojom.ByteString content;
  string content_type;
};

//  The inner response wrapped in binary HTTP from the OHTTP gateway.
struct ObliviousHttpResponse {
  // The response code of the inner gateway HTTP response.
  int32 response_code;
  // The headers of the inner gateway HTTP response. It should only be used to
  // get header values. To get the response code, use `response_code` instead.
  HttpResponseHeaders headers;
  // The response code of the inner gateway HTTP response. It is empty if
  // `response_code` is non-200.
  mojo_base.mojom.ByteString response_body;
};

// The structure used to deliver result to Oblivious HTTP clients.
union ObliviousHttpCompletionResult {
  // A general net::Error code in case of failure. If the result is net::OK, one
  // of the other fields in the union will be populated.
  int32 net_error;
  // The response code of the outer relay HTTP response, used to wrap the binary
  // HTTP (bHTTP) response. This is set iff the result fails because the outer
  // HTTP response status code is not HTTP_OK (200). The value will never be
  // 200.
  int32 outer_response_error_code;
  // The inner gateway HTTP response. Parsed out from the binary HTTP (bHTTP)
  // structure.
  ObliviousHttpResponse inner_response;
};

struct ObliviousHttpPaddingParameters {
  // Whether to add a random number of bytes following an exponential
  // probability distribution with mean `exponential_mean` extra bytes.
  bool add_exponential_pad;
  uint16 exponential_mean;

  // Whether to pad the request to the next power of 2 in length. If the request
  // is already a power of 2 in length, no padding is added.
  // If both `add_exponential_pad` and `pad_to_next_power_of_two` are enabled,
  // the result from `add_exponential_pad` is padded to the next higher power of
  // 2.
  bool pad_to_next_power_of_two;
};

struct ObliviousHttpRequest {
  url.mojom.Url relay_url;
  MutableNetworkTrafficAnnotationTag traffic_annotation;

  // How long the URL loader should wait before timing out the request. The
  // handler will use a default timeout if not set.
  mojo_base.mojom.TimeDelta? timeout_duration;

  // The key config contains the public key of the `resource_url` server, which
  // is the only reassurance we have that we are talking to the `resource_url`
  // server, so care should be taken when getting the key config.
  string key_config;

  url.mojom.Url resource_url;

  // The request method: GET, POST, etc.
  string method;

  // An optional HTTP request body.
  ObliviousHttpRequestBody? request_body;

  // Contains trust token params for inner request.
  network.mojom.TrustTokenParams? trust_token_params;

  // Padding parameters to apply to the inner request before encryption.
  ObliviousHttpPaddingParameters? padding_params;
};

// Callback interface for Oblivious HTTP Requests.
interface ObliviousHttpClient {
  // Called when the OHTTP request completes.
  OnCompleted(ObliviousHttpCompletionResult response);
};