config/encodings.proto

// Copyright 2016 The Fuchsia Authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//    http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
syntax = "proto3";

package cobalt;

option go_package = "config";

// A Cobalt Epoch is a contiguous sequence of days used to aggregate
// observations. Each Report analyzes a set of observations from one epoch.
// Some encodings, such as Forculus, use the current epoch as a parameter.
//
// Each Cobalt |Observation| includes a |day_index| which determines in
// which epoch the Observation falls.
enum EpochType {
  // Each day is a different epoch.
  DAY = 0;
  // A week epoch is a seven day period from Sunday to Saturday
  WEEK = 1;
  // A month epoch is the set of days in a single month of the Gregorian
  // calendar
  MONTH = 2;
}

///////////////////////////////////////////////////////////////
// Messages that describe the configuration of an encoding.
// These are registered in the Cobalt Config Database and consumed
// by both the Encoder and the Analyzer. Each ObservationPart (see
// observation.proto) contains the ID of an EncodingConfig describing how the
// data was encoded.
///////////////////////////////////////////////////////////////

message ForculusConfig {
  // Must satisfy 2 <= threshold <= 1,000,000
  uint32 threshold = 1;

  // Forculus threshold encryption is based on the current epoch. For example
  // if epoch_type = WEEK and threshold = 20 then the criteria for being able
  // to decrypt a given ciphertext is that at least 20 different clients
  // all submit observations of that ciphertext tagged with a day_index in
  // the same week, from Sunday to Saturday.
  EpochType epoch_type = 2;
}

message RapporConfig {
  // k = the number of Bloom filter bits. This must be a power of 2 and
  // it must satisfy:
  // 1 <= h < k <= 1024, where h = num_hashes.
  uint32 num_bloom_bits = 1;

  // h = the number of hashes. This must satisfy
  // 1 <= h <=  8
  uint32 num_hashes = 2;

  // m = the number of cohorts. This must satisfy
  // 1 <= m <= 1024
  uint32 num_cohorts = 3;

  // All probabilities below must be in the range [0.0, 1.0]

  // prob_0_becomes_1 MAY NOT BE EQUAL to prob_1_stays_1.

  // p = p(a zero bit is changed to a one bit in the IRR)
  float prob_0_becomes_1 = 4;

  // q = p(a one bit remains a one bit in the IRR)
  float prob_1_stays_1 = 5;

  // f = p(a bit is randomly assigned a value in the PRR)
  // Note: Not Implemented in version 0.1 of Cobalt.
  // This value must not be set to a non-zero value.
  float prob_rr = 6;
}

// A list of categories to be used in Basic RAPPOR for a metric part of
// type STRING. They must be distinct, non-empty strings and the number
// of categories, k, must satisfy 1 < k < 1024. The zero-based index of a
// category in the list is its bit position in the encoding.
message StringCategories {
  repeated string category = 1;
}

// A range of integer categories to be used in Basic RAPPOR for a metric part of
// type INT. The categories are those integers in the range [first, last].
// The number of categories, k = last - first + 1, must satisfy
// 1 < k < 1024. If i is an integer in the range [first, last] then the bit
// position of category i in the encoding is i - first.
message IntRangeCategories {
  int64 first = 1;
  int64 last = 2;
}

// A specification of the number of categories to be used in Basic RAPPOR for a
// metric part of type INDEX. k = |num_categories| must satisfy
// 1 < k < 1024.
message IndexedCategories {
  uint32 num_categories = 1;
}

message BasicRapporConfig {
  // All probabilities below must be in the range [0.0, 1.0].

  // prob_0_becomes_1 MAY NOT BE EQUAL to prob_1_stays_1.

  // p = p(a zero bit is changed to a one bit in the IRR)
  float prob_0_becomes_1 = 1;

  // q = p(a one bit remains a one bit in the IRR)
  float prob_1_stays_1 = 2;

  // f = p(a bit is randomly assigned a value in the PRR)
  // NOTE: PRR is not implemented in Version 0.1 of Cobalt.
  // This value must not be set to a non-zero value.
  float prob_rr = 3;

  // For basic RAPPOR the Encoder needs to know something about the list of
  // categories. For encoding metric parts of type STRING |string_categories|
  // should be used, for encoding metric parts of type INT
  // |int_range_categories| should be used and for encoding metric parts of
  // type INDEX, |indexed_categories| should be used.
  oneof categories {
    StringCategories string_categories = 7;
    IntRangeCategories int_range_categories = 8;
    IndexedCategories indexed_categories = 9;
  }
}

// The NoOpEncoding specifies that no encoding will be performed. Unencoded
// raw input-values will be used as observations.
message NoOpEncodingConfig {
  // There is no configuration to specify.
}

message EncodingConfig {
  // Next ID: 101
  uint32 customer_id = 1;
  uint32 project_id = 2;
  uint32 id = 3;
  string name = 100;
  oneof config {
    ForculusConfig forculus = 4;
    RapporConfig rappor = 5;
    BasicRapporConfig basic_rappor = 6;
    NoOpEncodingConfig no_op_encoding = 99;
  }
}

// Constains the list of all EncodingConfigs that are registered in the
// Cobalt system. An instance of RegisteredEncodings is deserialized
// from a text file.
message RegisteredEncodings {
  repeated EncodingConfig element = 1;
}