/** \file * \brief Wrappers for the Magnetometer Sensor * * \see https://www.w3.org/TR/magnetometer/ * * \author Copyright (C) 2021 Radek Hranicky * * \license SPDX-License-Identifier: GPL-3.0-or-later */ // // This program is free software: you can redistribute it and/or modify // it under the terms of the GNU General Public License as published by // the Free Software Foundation, either version 3 of the License, or // (at your option) any later version. // // This program is distributed in the hope that it will be useful, // but WITHOUT ANY WARRANTY; without even the implied warranty of // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the // GNU General Public License for more details. // // You should have received a copy of the GNU General Public License // along with this program. If not, see . // /** \file * \ingroup wrappers * * MOTIVATION * * Magnetometer is a platform sensor available under the Generic Sensor API. * Magnetometer measures strength and direction of the magnetic field at device's * location. The interface offers sensor readings using three properties: x, y, and z. * Each returns a number that describes the magnetic field aroud the particular axis. * The numbers have a double precision and can be positive or negative, depending * on the orientation of the field. The total strength of the magnetic field (M) * can be calculated as M = sqrt(x^2 + z^2 + y^2). The unit is in microtesla (µT). * * The Earth's magnetic field ranges between approximately 25 and 65 µT. Concrete * values depend on location, altitude, weather, interference made by other electric. * devices, etc. While we consider it is unlikely that someone determines the precise * location of the device from the Mangetometer values, its data can be used for * fingerprinting. For instance, it can be determined wheter the device is moving or not. * In case of a stationary device, we can make a fingerprint from the device's orientation. * Another fingerprintable value is the average total strength of the field, which * should remain stable if the device is at the same position and in the same environment. * * * WRAPPING * * To protect the device, we are wrapping the x, y, z getters of the * `Magnetometer.prototype` object. Instead of using the original data, we use * artificially generated values that look like actual sensor readings. * * At every moment, our wrapper stores information about the previous reading. Each * rewrapped getter first checks the `timestamp` value of the sensor object. If there * is no difference from the previous reading's timestamp, the wrapper returns the * last measured value. Otherwise, it provides a new fake reading. * * We designed our fake field generator to fulfill the following properties: * * - The randomness of the generator should be high enough to prevent attackers from * deducing the sensor values. * - Multiple scripts from the same website that access readings with the same * timestamp must get the same results. And thus: * - The readings are deterministic - e.g., for a given website and time, we must * be able to say what values to return. * * For every "random" draw, we use the Mulberry32 sen_prng that is seeded with a value * generated from the `domainHash` which ensures deterministic behavior for the given * website. First, we choose the desired total strength `M` of the magnetic field at * our simulated location. This is a pseudo-random number from 25 to 60 uT, like on * the Earth. * * We support two variants of settings the initial axes orientaton: * - A pseudorandom draw (RANDOM_AXES_ORIENTATION = true) - the original implementation * - Calculation from the faked device rotation (shared by other wrappers) - improved version * * For both methods, the orientation is defined by a number from -1 to 1 for each axis: * `baseX`, `baseY`, and `baseZ`. By modifying the above-shown formula, we calculate * the `multiplier` that needs to be applied to the base values to get the desired field. * The calculation is done as follows: * - mult = (M * sqrt(baseX^2 + baseY^2 + baseZ^2) / (baseX^2 + baseY^2 + baseZ^2)) * Now, we know that for axis `x`, the value should fluctuate around `baseX * mult`, etc. * * How much the field changes over time is specified by the fluctuation factor (0;1] * that can also be configured. For instance, 0.2 means that the magnetic field on * the axis may change from the base value by 20% in both positive and negative way. * * The fluctuation is simulated by using a series of **sine** functions for each axis. * Each sine has a unique amplitude, phase shift, and period. The number of sines per * axis is chosen pseudorandomly based on the wrapper settings. For initial experiments, * we used around 20 to 30 sines for each axis. The optimal configuration is in question. * More sines give less predictable results, but also increase the computing complexity * that could have a negative impact on the browser's performance. * * For the given timestamp `t`, we make the sum of all sine values at the point `x=t`. * The result is then shifted over the y-axis by adding `base[X|Y|Z] * multiplier` to * the sum. The initial configuration of the fake field generator was chosen intuitively * to resemble the results of the real measurements. Currently, the generator uses at * least one sine with the period around 100 us (with 10% tolerance), which seems to be * the minimum sampling rate obtainable using the API on mobile devices. Then, at least * one sine around 1 s, around 10 s, 1 minute, and 1 hour. When more than 5 sines are * used, the cycle repeats using `modulo 5` and creates a new sine with the period around * 100 us, but this time the tolerance is 20%. The same follows for seconds, tens of * seconds, minutes, hours. The tolerance grows every 5 sines. For 11+ sines, the tolerance * is 30% up to the maximum (currently 50%). The amplitude of each sine is chosen pseudo- * randomly based on the **fluctuation factor** described above. The phase shift of each * sine is also pseudo-random number from [0;2PI). * * Based on the results, this heuristic returns belivable values that look like actual * sensor readings. Nevertheless, the generator uses a series of constants, whose optimal * values should be a subject of future research and improvements. Perphaps, a correlation * analysis with real mesurements could help in the future. * * * POSSIBLE IMPROVEMENTS * Non-stationary devices can be supported if the baseX,Y,Z is updated with each movement. * Do more experiments in real environments and possibly update the reference magnetic field * vector, or the sine generator, e.g. by simulating temporary pseudorandom electromagnetic * interferences, etc. */ /* * Create private namespace */ (function() { /* * \brief Initialization of data for storing sensor readings */ var init_data = ` var currentReading = currentReading || {orig_x: null, orig_y: null, orig_z: null, timestamp: null, fake_x: null, fake_y: null, fake_z: null}; var previousReading = previousReading || {orig_x: null, orig_y: null, orig_z: null, timestamp: null, fake_x: null, fake_y: null, fake_z: null}; var emulateStationaryDevice = (typeof args === 'undefined') ? true : args[0]; var debugMode = false; const TWOPI = 2 * Math.PI; `; /* * \brief Property getters of the original sensor object */ var orig_getters = ` var origGetX = Object.getOwnPropertyDescriptor(Magnetometer.prototype, "x").get; var origGetY = Object.getOwnPropertyDescriptor(Magnetometer.prototype, "y").get; var origGetZ = Object.getOwnPropertyDescriptor(Magnetometer.prototype, "z").get; var origGetTimestamp = Object.getOwnPropertyDescriptor(Sensor.prototype, "timestamp").get; `; /* * \brief Constructor of the sine configuration object */ function SineCfg() { this.center = 0; this.amplitude = 1; this.shift = 0; this.period = 1; } /* * \brief Creates sine configurations based on the given settings * * \param Minimum number of sines * \param Maximum number of sines * \param Center 'y' value that the sine should spin around * \param Minimal fluctuation factor of a sine * \param Maximal fluctuation factor of a sine * \param Minimal period of a sine * \param Maximal period of a sine */ function configureSines(cntMin, cntMax, center, flucMin, fluctMax, periodMin, periodMax) { // This is helping function for the field generator // Configures an array of sines for the given settings // How many sines we have? var cnt = Math.floor(sen_prng() * (cntMax - cntMin + 1) + cntMin); // max difference from base period const TOLERANCE_MAX = 0.5; // What is the typical amplitude for these sines? var sineAmplitude = center / cnt; var fluctMinMax = flucMin - fluctMax; let sines = []; let iteration = 0; let tolerance = 0.1; for (let i = 0; i < cnt; i++) { let s = new SineCfg(); let fluctuationFactor = sen_prng() * (fluctMinMax) + fluctMax; s.center = center; s.amplitude = sineAmplitude * fluctuationFactor; s.shift = sen_prng() * TWOPI; let series = i % 5; switch(series) { case 0: iteration += 1; // increase tolerance for new iterations if (iteration > 1 && tolerance < TOLERANCE_MAX) { tolerance += 0.1; } // Minimal sampling rate (default: 100 miliseconds) s.period = sen_generateAround(periodMin, tolerance); break; case 1: // Seconds s.period = sen_generateAround(1000, tolerance); break; case 2: // Tens of seconds s.period = sen_generateAround(10000, tolerance); break; case 3: // Minutes s.period = sen_generateAround(60000, tolerance); break; case 4: // Hours s.period = sen_generateAround(3600000, tolerance); break; } sines.push(s); } return sines; } /* * \brief Fake magnetic field generator class * (Modify the constants below to change the generator's behavior.) */ class FieldGenerator { constructor() { // Specifies, how much the values may (pseudorandomly) oscillate, // i.e., how much the may relatively differ from the chosen center value // in both positiva and negative way this.FLUCTUATION_MIN = 0.20; this.FLUCTUATION_MAX = 0.45; this.AXES_OSCILLATE_DIFFERENTLY = true; this.NUMBER_OF_SINES_MIN = 25; this.NUMBER_OF_SINES_MAX = 30; // Shifts the phase of each axis randomly [0, 2*PI) this.RANDOM_PHASE_SHIFT = true; // Minimum sampling rate of the device(s) // Motivation: It does not have sense to waste computing resources // by oscillating in periods smaller than this value this.MIN_SAMPLING_RATE = 100; // [ms] // Period configuration this.PERIOD_MIN = this.MIN_SAMPLING_RATE; this.PERIOD_MAX = 60000 // 1 minute // Defines whether the axes orientation is generated pseudorandomly // true = A PRNG is used to draw the orientation of x/y/z axes // false = orientation is calculated from the Earth's reference // coordinate system and the (faked) orientation of the // phone defined by the global rotation matrix (orient.rotMat) this.RANDOM_AXES_ORIENTATION = false; let m = generateBaseField(); // Base of each axis var baseX = 0; var baseY = 0; var baseZ = 0; // Calculate the axes base if (this.RANDOM_AXES_ORIENTATION) { /* * Pseudorandom axes orientation * * The generateRandomAxisBase() is used to draw a number between * -1 and 1 for each axis base. */ baseX = generateRandomAxisBase(); baseY = generateRandomAxisBase(); baseZ = generateRandomAxisBase(); } else { /* * Calculation of axes orientation from the device's rotation * * The magnetic field vector is oriented towards the Earth's magnetic * north and towards the center of the earth. */ let referenceMagVec = [0, 0.4, -0.6]; /* * Actual field's strengths in all directions, based on the orientation: * (Tested on Samsung Galaxy S21 Ultra [And12] and Xiaomi Redmi 9 [And11]) * * Legend: * -- ... highly negative * - ... negative * 0 ... zero * + ... positive * ++ ... highly positive * * +-------+-------+------+---+---+---+ * | yaw | pitch | roll | x | y | z | * +-------+-------+------+---+---+---+ * | 0 0 0 0 + -- | * | PI 0 0 0 - -- | * | PI/2 0 0 - 0 -- | * | -PI/2 0 0 + 0 -- | * +----------------------------------+ */ // The vector is rotated using the device's fake rotation matrix var deviceMagVec = multVectRot(referenceMagVec, orient.rotMat); if (debugMode) { } // The orientation is taken from the elements of the vector baseX = deviceMagVec[0]; baseY = deviceMagVec[1]; baseZ = deviceMagVec[2]; } var baseX2 = Math.pow(baseX,2) var baseY2 = Math.pow(baseY,2) var baseZ2 = Math.pow(baseZ,2) // The total magnetic field strength is calculated as: // m = sqrt(x^2, y^2, z^2) // where x,y,z are strengs in individual directions (axes). // // For x,y,z, the algorithm generates a sine-based fluctuation around // a center value for each axis. For axis x, it is calculated as: // x = baseX * multiplier // // At this moment, we have calculate the basis (-1,1) for each axis. // Now, we calculate the multiplier: // // m + sqrt(baseX^2 + baseY^2 + baseZ^2) // multiplier = +/- ------------------------------------- // baseX^2 + baseY^2 + baseZ^2 // // Values at axis X will oscillate around: baseX * multiplier, etc. let mult = (m * Math.sqrt(baseX2 + baseY2 + baseZ2)) / (baseX2 + baseY2 + baseZ2); this.baseField = m, this.multiplier = mult, this.x = { base: baseX, center: baseX * mult, sines: [], value: null }; this.y = { base: baseY, center: baseY * mult, sines: [], value: null }; this.z = { base: baseZ, center: baseZ * mult, sines: [], value: null }; this.x.sines = configureSines(this.NUMBER_OF_SINES_MIN, this.NUMBER_OF_SINES_MAX, this.x.center, this.FLUCTUATION_MIN, this.FLUCTUATION_MAX, this.PERIOD_MIN, this.PERIOD_MAX); this.y.sines = configureSines(this.NUMBER_OF_SINES_MIN, this.NUMBER_OF_SINES_MAX, this.y.center, this.FLUCTUATION_MIN, this.FLUCTUATION_MAX, this.PERIOD_MIN, this.PERIOD_MAX); this.z.sines = configureSines(this.NUMBER_OF_SINES_MIN, this.NUMBER_OF_SINES_MAX, this.z.center, this.FLUCTUATION_MIN, this.FLUCTUATION_MAX, this.PERIOD_MIN, this.PERIOD_MAX); } // Updates the x/y/z values based on timestamp update(t) { // Simulate the magnetic field fluctuation based on settings // Center is added only once - we want to y-shift the result, not individial sines this.x.value = this.x.center + this.x.sines.reduce(function (val, s) { return val + (Math.sin(t * (TWOPI/s.period) + s.shift) * s.amplitude); }, 0); this.y.value = this.y.center + this.y.sines.reduce(function (val, s) { return val + (Math.sin(t * (TWOPI/s.period) + s.shift) * s.amplitude); }, 0); this.z.value = this.z.center + this.z.sines.reduce(function (val, s) { return val + (Math.sin(t * (TWOPI/s.period) + s.shift) * s.amplitude); }, 0); } } /* * \brief Pseudorandomly draws the desired total magnetic field around the device */ function generateBaseField() { const FIELD_MIN = 25; const FIELD_MAX = 60; return sen_prng() * (FIELD_MIN - FIELD_MAX) + FIELD_MAX; } /* * \brief Pseudorandomly draws the orientation of X, Y, Z axes */ function generateRandomAxisBase() { // Returns a number in (-1,1) var v = sen_prng(); // Random in [0,1) v *= Math.round(sen_prng()) ? 1 : -1; // 50% change for positive / negative return v; } /* * \brief Updates the stored (both real and fake) sensor readings * according to the data from the sensor object. * * \param The sensor object */ function updateReadings(sensorObject) { // We need the original reading's timestamp to see if it differs // from the previous sample. If so, we need to update the faked x,y,z let previousTimestamp = previousReading.timestamp; let currentTimestamp = origGetTimestamp.call(sensorObject); if (debugMode) { // [!] Debug mode: overriding timestamp // This allows test suites to set a custom timestamp externally // by modifying the property of the Magnetometer object directly. currentTimestamp = sensorObject.timestamp; } if (currentTimestamp === previousTimestamp) { // No new reading, nothing to update return; } // Rotate the readings: previous <- current previousReading = JSON.parse(JSON.stringify(currentReading)); // Update current reading // NOTE: Original values are also stored for possible future use // in improvements of the magnetic field generator currentReading.orig_x = origGetX.call(sensorObject); currentReading.orig_y = origGetY.call(sensorObject); currentReading.orig_z = origGetZ.call(sensorObject); currentReading.timestamp = currentTimestamp; fieldGenerator.update(currentTimestamp); currentReading.fake_x = fieldGenerator.x.value; currentReading.fake_y = fieldGenerator.y.value; currentReading.fake_z = fieldGenerator.z.value; if (debugMode) { } } /* * \brief Initializes the related generators */ var generators = ` // Initialize the field generator, if not initialized before var fieldGenerator = fieldGenerator || new FieldGenerator(); `; var helping_functions = sensorapi_prng_functions + device_orientation_functions + SineCfg + configureSines + FieldGenerator + generateBaseField + generateRandomAxisBase + updateReadings; var hc = init_data + orig_getters + helping_functions + generators; var wrappers = [ { parent_object: "Magnetometer.prototype", parent_object_property: "x", wrapped_objects: [], helping_code: hc, post_wrapping_code: [ { code_type: "object_properties", parent_object: "Magnetometer.prototype", parent_object_property: "x", wrapped_objects: [], /** \brief replaces Sensor.prototype.x getter to return a faked value */ wrapped_properties: [ { property_name: "get", property_value: ` function() { updateReadings(this); return currentReading.fake_x; }`, }, ], } ], }, { parent_object: "Magnetometer.prototype", parent_object_property: "y", wrapped_objects: [], helping_code: hc, post_wrapping_code: [ { code_type: "object_properties", parent_object: "Magnetometer.prototype", parent_object_property: "y", wrapped_objects: [], /** \brief replaces Sensor.prototype.y getter to return a faked value */ wrapped_properties: [ { property_name: "get", property_value: ` function() { updateReadings(this); return currentReading.fake_y; }`, }, ], } ], }, { parent_object: "Magnetometer.prototype", parent_object_property: "z", wrapped_objects: [], helping_code: hc, post_wrapping_code: [ { code_type: "object_properties", parent_object: "Magnetometer.prototype", parent_object_property: "z", wrapped_objects: [], /** \brief replaces Sensor.prototype.z getter to return a faked value */ wrapped_properties: [ { property_name: "get", property_value: ` function() { updateReadings(this); return currentReading.fake_z; }`, }, ], } ], }, ] add_wrappers(wrappers); })()