fp_detect_background.js File Reference

Fingerprint Detector (FPD) main logic, fingerprinting evaluation and other essentials. More...

Functions
	if (typeof browser.browserAction.setBadgeTextColor==="function")
function	initFpd ()
function	balanceUnsupportedWrappers ()
function	correctGroupCriteria (rootGroup, effectedGroups, level)
function	evaluateGroups (tabId)
function	evaluateGroupsCriteria (rootGroup, level, tabId)
function	evaluateResourcesCriteria (resource, groupName, level, tabId)
function	fpdCommonMessageListener (record, sender)
function	fpdRequestCancel (requestDetails)
function	fpdLoadConfiguration ()
function	processGroupsRecursive (input, groupsLevel)
function	isFpdWhitelisted (hostname)
function	isFpdOn (tabId)
function	notifyFingerprintBlocking (tabId)
function	generateFpdReport (tabId)
function	refreshDb (tabId)
function	periodicEvaluation (tabId, delay)
function	evaluateFingerprinting (tabId)
function	clearStorageFacilities (url)
function	split_resource (text)

Variables
var	fpDetectionOn
var	fpdWhitelist = {}
var	fpdSettings = {}
var	fpDb = new Observable()
var	latestEvals = {}
var	fpGroups = {}
var	unsupportedWrappers = {}
var	exceptionWrappers = ["CSSStyleDeclaration.prototype.fontFamily"]
var	availableTabs = {}
var	fpd_track_callers_tab = undefined
const	FPD_DEF_SETTINGS

Detailed Description

Fingerprint Detector (FPD) main logic, fingerprinting evaluation and other essentials.

This file is part of Fingerprint Detector (FPD) and contains API groups evaluation logic. File also contains event listeners used for API logging, requests blocking and tabs management.

Author

Copyright (C) 2021-2022 Marek Salon

License:

SPDX-License-Identifier: GPL-3.0-or-later

Function Documentation

balanceUnsupportedWrappers()

function balanceUnsupportedWrappers

(

)

This function provides ability to balance/optimalize evaluation heuristics for cross-browser behaviour uniformity. It checks which resources are unsupported for given browser and adjust criteria of loaded FPD configuration accordingly.

Here is the call graph for this function:

Here is the caller graph for this function:

clearStorageFacilities()

function clearStorageFacilities

(

url

)

The function that clears all supported browser storage mechanisms for a given origin.

Parameters

url	URL address of the origin.

Here is the call graph for this function:

Here is the caller graph for this function:

correctGroupCriteria()

function correctGroupCriteria	(		rootGroup,
			effectedGroups,
			level
	)

The function that corrects groups criteria according to unsupported wrappers. Groups should be deleted when more than half of weights (resources) cannot be obtained in the same group (whole group is invalidated). Groups criteria of "value" type are also recomputed to take into account unsupported resources and deleted groups/subgroups.

Parameters

rootGroup	Group object of certain level from FPD configuration (in "fp_levels.wrappers" format).
effectedGroups	Object containing groups effected by criteria adjustment and corresponding deleted subgroups.
level	FPD configuration level identifier.

Returns

true if group should be deleted because of unsupported wrappers

false if group don't need to be deleted

Here is the call graph for this function:

Here is the caller graph for this function:

evaluateFingerprinting()

function evaluateFingerprinting

(

tabId

)

The function that starts evaluation process and if fingerprinting is detected, it reacts accordingly.

Parameters

tabId

Integer number representing ID of evaluated browser tab.

Returns

Object containing key "cancel" with value true if request is blocked, otherwise with value false

Here is the call graph for this function:

Here is the caller graph for this function:

evaluateGroups()

function evaluateGroups

(

tabId

)

The function initializing evaluation of logged API calls (fpDb) according to groups criteria (fpGroups).

Parameters

tabId

Integer number representing ID of browser tab that is going to be evaluated.

Returns

object where "weight" property represents evaluated weight of root group and "severity" property contain severity array

Here is the call graph for this function:

Here is the caller graph for this function:

evaluateGroupsCriteria()

function evaluateGroupsCriteria	(		rootGroup,
			level,
			tabId
	)

The function that evaluates group criteria according to evaluation of its child items (groups/resources).

Parameters

rootGroup	Group name that needs to be evaluated.
level	Level ID of groups and wrappers used for evaluation.
tabId	Integer number representing ID of evaluated browser tab.

Returns

Array that contains "Result" objects

Result object contains following properties: actualWeight (Obtained weight value of group after evaluation) maxWeight (Maximum obtainable weight value of group) type (Type of group item - group/call/get/set) accesses (Number of accesses to specified resource - groups always 0)

Here is the call graph for this function:

Here is the caller graph for this function:

evaluateResourcesCriteria()

function evaluateResourcesCriteria	(		resource,
			groupName,
			level,
			tabId
	)

The function that evaluates resource (wrapper) criteria according to API calls logs.

Parameters

resource	Full name of resource/wrapper.
groupName	Name of direct parent group.
level	Level ID of groups and wrappers used for evaluation.
tabId	Integer number representing ID of evaluated browser tab.

Returns

Array that contains "Result" objects

Result object contains following properties (all of them in context of parent group): actualWeight (Obtained weight value of resource after evaluation) maxWeight (Maximum obtainable weight value of resource) type (Type of resource - call/get/set) accesses (Number of accesses to specified resource)

Here is the caller graph for this function:

fpdCommonMessageListener()

function fpdCommonMessageListener	(		record,
			sender
	)

Callback function that parses and handles messages recieved by FPD module. Messages may contain wrappers logging data that are stored into fpDb object. Also listen for popup messages to update FPD state and whitelist.

Parameters

message	Receives full message.
sender	Sender of the message.

Here is the call graph for this function:

Here is the caller graph for this function:

fpdLoadConfiguration()

function fpdLoadConfiguration

(

)

The function that loads module configuration from sync storage.

Here is the caller graph for this function:

fpdRequestCancel()

function fpdRequestCancel

(

requestDetails

)

The function that makes decisions about requests blocking. If blocking enabled, also clear browsing data.

Parameters

requestDetails

Details about the request.

Returns

Object containing key "cancel" with value true if request is blocked, otherwise with value false

Here is the call graph for this function:

generateFpdReport()

function generateFpdReport

(

tabId

)

The function that generates a report about fingerprinting evaluation in a separate window.

Parameters

tabId

Integer number representing ID of evaluated browser tab.

Here is the caller graph for this function:

if()

if

(

typeof browser.browserAction.

setBadgeTextColor = == "function"

)

initFpd()

function initFpd

(

)

This function initializes FPD module, loads configuration from storage, and registers listeners needed for fingerprinting detection.

Here is the call graph for this function:

isFpdOn()

function isFpdOn

(

tabId

)

The function that returns FPD setting for given url.

Parameters

tabId

Tab identifier for which FPD setting is needed.

Returns

Boolean value TRUE if FPD is on, otherwise FALSE.

Here is the call graph for this function:

Here is the caller graph for this function:

isFpdWhitelisted()

function isFpdWhitelisted

(

hostname

)

Check if the hostname or any of it's domains is whitelisted.

Parameters

hostname

Any hostname (subdomains allowed).

Returns

TRUE when domain (or subdomain) is whitelisted, FALSE otherwise.

Here is the call graph for this function:

Here is the caller graph for this function:

notifyFingerprintBlocking()

function notifyFingerprintBlocking

(

tabId

)

The function that creates notification and informs user about fingerprinting activity.

Parameters

tabId

Integer number representing ID of suspicious browser tab.

Here is the caller graph for this function:

periodicEvaluation()

function periodicEvaluation	(		tabId,
			delay
	)

The function that periodically starts fingerprinting evaluation without the need for a request. Delay is increased exponentially and doubles in every call.

Parameters

tabId	Integer number representing ID of browser tab.
delay	Initial value of a delay in milliseconds.

Here is the call graph for this function:

Here is the caller graph for this function:

processGroupsRecursive()

function processGroupsRecursive	(		input,
			groupsLevel
	)

The function transforming recursive groups definition into indexed fpGroups object.

Parameters

input	Group object from loaded JSON format.
groupsLevel	Level ID of groups to process.

Here is the call graph for this function:

Here is the caller graph for this function:

refreshDb()

function refreshDb

(

tabId

)

Clear all stored logs for a tab.

Parameters

tabId

Integer number representing ID of browser tab.

Here is the caller graph for this function:

split_resource()

function split_resource

(

text

)

The function splitting resource string into path and name. For example: "window.navigator.userAgent" => path: "window.navigator", name: "userAgent"

Parameters

wrappers

text String representing full name of resource.

Returns

Object consisting of two properties (path, name) for given resource.

Here is the caller graph for this function:

Variable Documentation

availableTabs

var availableTabs = {}

Contains information about tabs current state.

exceptionWrappers

var exceptionWrappers = ["CSSStyleDeclaration.prototype.fontFamily"]

Array containing names of unsupported wrappers that should be treated like supported ones during groups evaluation.

FPD_DEF_SETTINGS

const FPD_DEF_SETTINGS

Definition of settings supported by this module.

fpd_track_callers_tab

var fpd_track_callers_tab = undefined

A global variable shared with level_cache that controls the collection of calling scripts for FPD report.

fpDb

var fpDb = new Observable()

API logs database of following structure: "tabId" : { "resource" : { "type" : { arguments { arg : "access count" }, total : "total access count" } } }

*values in quotations are substituted by concrete names

fpDetectionOn

var fpDetectionOn

FPD enable flag. Evaluate only when active.

fpdSettings

var fpdSettings = {}

Associtive array of settings supported by this module.

fpdWhitelist

var fpdWhitelist = {}

Associtive array of hosts, that are currently among trusted ones.

fpGroups

var fpGroups = {}

Parsed groups object containing necessary group information needed for evaluation. Groups are indexed by level and name for easier and faster access.

latestEvals

var latestEvals = {}

Stores latest evaluation statistics for every examined tab. This statistics contains data about accessed groups and resources and their weights after evaluation. It can be used for debugging or as an informative statement in GUI. It also contains flag for every tab to limit number of notifications.

unsupportedWrappers

var unsupportedWrappers = {}

Object containing information about unsupported wrappers for given browser.