| // 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 { |
| uint32 customer_id = 1; |
| uint32 project_id = 2; |
| uint32 id = 3; |
| 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; |
| } |