DataVaccinator for developers

Developing with industrial grade pseudonymisation

Sourcecode on GitHub

The source code of DataVaccinator and its documentation is Open Source and can be accessed from GitHub.

How does it work?

DataVaccinator is an input/output system. You put content in and in return you get a unique ID to identify the data in future. This ID is called the VID (Vaccination Identifier). Then, you request your data by submitting the VID and get back your content.

For the DataVaccinator service, data is simply a string with up to 512KB. As data is usually encrypted and then encoded, it allows about 256KB of real-life data (if hex encoded, maybe more if base64 encoded). The DataVaccinator JavaScript Client submits encrypted JSON data in hex encoding.

Additional functionality is available which lets you update data based on a VID or delete data inside the system.

In addition, there is a plugin to allow searching inside of data by using a technique similar to Searchable Symmetric Encryption (SSE). This allows you to search with keywords for corresponding VIDs - while the DataVaccinator service is not able to identify the keywords themselves. For example, allowing a search for Lastname and City.

Search plugin documentation

Use Case

Use in local application

This figure shows a layout where DataVaccinator is used to secure a local database:

Privacy by design is applied to personal information in a car rental application using DataVaccinator. The data is encrypted and put into DataVaccinator (Step 1). On the right, please see the DataVaccinator database. The information in red is stored encrypted and assigned to a VID. The VID is returned to the application (Step 2). The application only stores the VID together with the information assigned to a specific car rental. In Step 3 you can see a portion of the application database, using VID instead of personal information.

Advanced use to secure a cloud service

If DataVaccinator is used to secure some cloud service, the idea is to not even get in touch with any personal identifiable data. The cloud service should not get any personal information at all. Thus, DataVaccinator can get used like in this example:

Here, the cloud service provider runs a web application with a JavaScript powered car rental client application. Due to the Same Origin Policy of web browsers, the DataVaccinator client can not directly connect to the DataVaccinator service. Thus, the cloud provider has to act as a sort of proxy to forward, enrich and sanitize the requests.

The personal information is also encrypted by the DataVaccinator client. Then it is sent to the cloud service domain. There it gets enriched by the access credentials and forwarded to DataVaccinator (Step 1). The VID is returned and can get stored and assigned by the cloud provider (Step 2). Alternatively, the client application submits the VID and process information to the service provider (Step 3).

Typical workflow

The illustration below shows you a typical flow with DataVaccinator in combination with the search plugin:

By following this principle, the same rich end user functionality can be made available as in a traditional application.

Code example

The code sample below shows you how to use the DataVaccinator Client in a JavaScript project.


const appid = "Rc-De_6nyCbb";

const providerUrl = "https://cloud-service.company.com/service.php";

const vData = '{"firstname":"Spongebob", "lastname":"Square Pants", '+
              '"Gender":"male", "address_street":"Bikinistreet", '+
              '"address_number":"42", "address_city":"Bikini Bottom"}';

example(); // call testing function (must be a function because of async)

async function example() {
	try {
		var v = new vaccinator();
		await v.init(providerUrl, "user", appid, "passwd", true);

		// Enable search function using some vData fields
		v.enableSearchFunction( [ "firstname", "lastname", "address_city" ] );

		// Put some data into DataVaccinator
		var vid = await v.new(vData);  
		console.log("The created data VID is " + vid);
		
		// Search and retrieve VIDs from search words
		results = await v.search("square bikini");
		console.log("Found using 'square bikini': " + JSON.stringify(results));
		
		// Remove the created entry
		results = await v.delete(vid);
		console.log("Successfully removed the entry for " + JSON.stringify(results));

	} catch (e) {
		// Catch any vaccinator class errors from here
		console.error(e);
	}
}

The JavaScript class object vaccinator takes care of encryption (AES256), generation of secure SearchHashes, server communication including authentication and local caching (using IndexedDB database). It allows full asynchronous operation and is compatible with all modern web browsers and also node.js.