1 // Copyright 2015 Google Inc. All rights reserved. 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 // RAPPOR encoder. 16 // 17 // See README.md and encoder_demo.cc for an example. 18 19 #ifndef RAPPOR_H_ 20 #define RAPPOR_H_ 21 22 #include <string> 23 24 #include "rappor_deps.h" // for dependency injection 25 26 namespace rappor { 27 28 // For debug logging 29 void log(const char* fmt, ...); 30 31 // RAPPOR encoding parameters. 32 class Params { 33 public: Params(int num_bits,int num_hashes,int num_cohorts,float prob_f,float prob_p,float prob_q)34 Params(int num_bits, int num_hashes, int num_cohorts, 35 float prob_f, float prob_p, float prob_q) 36 : num_bits_(num_bits), 37 num_hashes_(num_hashes), 38 num_cohorts_(num_cohorts), 39 prob_f_(prob_f), 40 prob_p_(prob_p), 41 prob_q_(prob_q) { 42 } 43 44 // Accessors num_bits()45 int num_bits() { return num_bits_; } num_hashes()46 int num_hashes() { return num_hashes_; } num_cohorts()47 int num_cohorts() { return num_cohorts_; } prob_f()48 float prob_f() { return prob_f_; } prob_p()49 float prob_p() { return prob_p_; } prob_q()50 float prob_q() { return prob_q_; } 51 52 private: 53 friend class Encoder; 54 55 // k: size of bloom filter, PRR, and IRR. 0 < k <= 32. 56 int num_bits_; 57 58 // number of bits set in the Bloom filter ("h") 59 int num_hashes_; 60 61 // Total number of cohorts ("m"). Note that the cohort assignment is what 62 // is used in the client, not m. We include it here for documentation (it 63 // can be unset, unlike the other params.) 64 int num_cohorts_; 65 66 float prob_f_; // noise probability for PRR, quantized to 1/128 67 68 float prob_p_; // noise probability for IRR, quantized to 1/128 69 float prob_q_; // noise probability for IRR, quantized to 1/128 70 }; 71 72 // Encoder: take client values and transform them with the RAPPOR privacy 73 // algorithm. 74 class Encoder { 75 public: 76 // Note that invalid parameters cause runtime assertions in the constructor. 77 // Encoders are intended to be created at application startup with constant 78 // arguments, so errors should be caught early. 79 80 // encoder_id: A unique ID for this encoder -- typically the name of the 81 // metric being encoded, so that different metrics have different PRR 82 // mappings. 83 // params: RAPPOR encoding parameters, which affect privacy and decoding. 84 // (held by reference; it must outlive the Encoder) 85 // deps: application-supplied dependencies. 86 // (held by reference; it must outlive the Encoder) 87 Encoder(const std::string& encoder_id, const Params& params, 88 const Deps& deps); 89 90 // Encode raw bits (represented as an integer), setting output parameter 91 // irr_out. Only valid when the return value is 'true' (success). 92 bool EncodeBits(const Bits bits, Bits* irr_out) const; 93 94 // Encode a string, setting output parameter irr_out. Only valid when the 95 // return value is 'true' (success). 96 bool EncodeString(const std::string& value, Bits* irr_out) const; 97 // For use with HmacDrbg hash function and any num_bits divisible by 8. 98 bool EncodeString(const std::string& value, 99 std::vector<uint8_t>* irr_out) const; 100 101 // For testing/simulation use only. 102 bool _EncodeBitsInternal(const Bits bits, Bits* prr_out, Bits* irr_out) 103 const; 104 bool _EncodeStringInternal(const std::string& value, Bits* bloom_out, 105 Bits* prr_out, Bits* irr_out) const; 106 107 // Accessor for the assigned cohort. cohort()108 uint32_t cohort() { return cohort_; } 109 // Set a cohort manually, if previously generated. 110 void set_cohort(uint32_t cohort); 111 112 private: 113 bool MakeBloomFilter(const std::string& value, Bits* bloom_out) const; 114 bool MakeBloomFilter(const std::string& value, 115 std::vector<uint8_t>* bloom_out) const; 116 bool GetPrrMasks(const Bits bits, Bits* uniform, Bits* f_mask) const; 117 118 // static helper function for initialization 119 static uint32_t AssignCohort(const Deps& deps, int num_cohorts); 120 121 const std::string encoder_id_; 122 const Params& params_; 123 const Deps& deps_; 124 uint32_t cohort_; 125 std::string cohort_str_; 126 }; 127 128 } // namespace rappor 129 130 #endif // RAPPOR_H_ 131