Payload encryption

In addition to the transport encryption via TLS, the OwnTracks apps support payload encryption using libsodium, in particular secret-key authenticated encryption. We have also implemented support for payload encryption (i.e. decryption) in the OwnTracks Recorder.

You configure a secret (which you keep secret) in the app's settings. From this moment onwards, the apps encrypt the JSON with this secret and transport the payload in a new JSON object which looks like this:

  "_type": "encrypted",
  "data": "1Vu7Owp ... W4lMnh28FB+el22GsCrlnggvEcp4H8GR9iKJdi1qfwkejYpzrQ+491Mwunjg="

If you want to share location with a friend, both you and your friend need to share the same secret. A secret should be kept secret; it is an up to 32 octet long passphrase (which the apps pad with binary zeroes) which is required both for encryption as well as for decryption of the payloads. It is not possible to share locations with a friend's device using different secret keys.


You can set up multiple decryption keys on the Recorder (but not in the apps). This is to enable, say, different people to use different secrets on the same Recorder.

Add a key by determining the username and the device name of the client app. Lowercase these, and create a string with the two values separated with a dash. Suppose the username is jjolie and the device name is Phone, the result will be jjolie-phone.

Load the key into the (running) Recorder:

echo "jjolie-phone mysecreTpass01" | ocat --load=keys

From this moment onwards, the Recorder will use this secret key for this username/device combination when it receives JSON payloads of _type: encrypted. The Recorder will decrypt the payload and will store the result in plain text in its storage.

You can check which decryption keys you have stored by running:

ocat --dump=keys

You can also delete entries for specific devices by replacing the encryption key with DELETE:

echo "jjolie-phone DELETE" | ocat --load=keys

Be aware that this is a very powerful command that can corrupt your database if you write it incorrectly!