Encrypt your users' data with a key that you do not possess!

Disclaimer: Encryption is hard to do well. The main risks are doing it poorly and an attacker being able to decrypt it and the other danger
is having encrypted data that cannot be decrypted because you have lost the decryption key or corrupted the data in some way. PixelPin will not be liable for your encryption implementation, testing
or procedures, even if it was modified to use the encryption key returning from PixelPin. Any advice you might receive from us on the developer web site or in person is advisory only and does
not form part of a legally binding contract.

Please contact us via pixelpin.io if you require more information on this disclaimer or the potential usage of these keys in your application.

Introduction

Most of the recent high-profile hacks have demonstrated that once a site's data has been accessed, it is either stored in plain text, for an attacker to read easily, or has used encryption that is
trivially reversed since the encryption keys are discovered in the same database, in code or on the file system of the compromised hardware.

By using a key stored by a third-party, you can encrypt the same data with a key that cannot be stolen from your premises, because it is not stored there!

Does this give me "zero-knowledge"?

Not in the strictest sense. Zero knowledge would mean you couldn't decrypt the data even if you wanted to. In this use case, you could decrypt the data either by waiting for the user to
login or by storing the decryption key - something that is not recommended!

Since most web applications pass authentication through the server, true zero knowledge is very difficult on the web. Current options are browser-based where the server cannot see e.g. the key
derivation step but these solutions present their own problems due to the insecurity of JavaScript and the lack of mature security and encryption tools in browsers.

It is also not zero knowledge because PixelPin has the knowledge of how the keys are generated

Should I encrypt any or all of my data using this key?

It depends. For a start, the end-user must be able to authenticate using PixelPin in order for the key to be released to your system. If you have, e.g. a call centre using the telephone, the user
is not going to be able to release the key which means the data can't be decrypted.

You should not try and mitigate this by storing the key. If you are going to store keys, there are more secure ways to do this internally to your organisation including Hardware Security Modules, which
provide soft and hard protections to the keys themselves or otherwise a system that generates keys in a similar way to PixelPin but taking into account all the ways in which your system needs to encrypt
or decrypt data. Keys should never be stored in the same database as the data you are encrypting and should use as many security controls as possible to protect them from being stolen or hacked

What details do I need to know about PixelPin keys?

They are 32 bytes long (256 bits) and can be used directly to encrypt using AES256. Shorter keys can be obtained by truncating the key at the required length.

They are generated using 1000 rounds of HMAC_SHA1 using PBKDF2 - a password stretching function

They combine the site id and user id as well as a long fixed salt that was randomly generated

Because they use the site and user ids, if you change the PixelPin developer account that your site is using or your end-user deletes and recreates their PixelPin account - even with the same email address, their key will no longer work! You
should consider how these scenarios might affect your product before implementing any encryption whether with the PixelPin key or not.

How do I get this key?

login.pixelpin.io does not currently return the key to the caller. This will be resolved in the future but for now, you will need to continue to use the older (ws3.pixelpin.co.uk) endpoints.

The older versions of the PixelPin OAuth2 API function /userdata will include the key by default in a property called keyid. In later versions of /userdata (oauth2v11/userdata and later),
you must pass key_id=true into the call to /token and /userdata otherwise an empty string will be returned. This change was made for performance reasons since key generation is slow for customers
who do not need it.

Note: You must pass key_id=true into /token as well as /userdata since /token will retrieve and generate the data for userdata and cache it. If you do not,
you might receive an empty string back from /userdata