Encryption Keys

How encryption and encryption keys works on Tardigrade

Encryption & API Keys

Where an API Key controls what resources and operations a Satellite will allow a user to access and perform, an HD Encryption Key controls what buckets, path prefixes, and objects a user has the ability to decrypt.

This is done via the EncryptionAccess of the Uplink Client. An EncryptionAccess is a serializable collection of hierarchically-determined encryption keys, where by default the key starts at the root.

At each level of the hierarchy of buckets, path prefixes, and objects, a child HD Encryption Key is derived in essentially the same manner as the API Keys.

The primary difference is that while a Satellite could generate restricted API Keys that would be essentially the same artifact as a restricted API Key generated by an Uplink Client, a Satellite never has access to Encryption Keys.

Supported Protocols

Out-of-the-box, the Uplink Client supports two encryption standards:

  1. AES 256 GCM

  2. SecretBox

In addition, the Uplink Client is designed to be pluggable so that developers can remove the default encryption standards and replace them with a custom or preferred encryption scheme.

It doesn’t matter what encryption solution you use with your application, but it does matter that you encrypt your data. Remember that your data is erasure coded and distributed across statistically uncorrelated storage nodes that are assumed to be untrusted as they are operated by complete strangers distributed all over the globe.

In addition to not wanting to expose your data to the risk of compromise by byzantine storage nodes, unencrypted data creates a potential insider threat from rogue satellite operators.

During ordinary Satellite file repair operation, file segments are downloaded by Satellites, re-encoded, and redistributed across storage nodes. As long as all data is encrypted client-side, the repair function does not expose the privacy or security of the data.

Allowing Decryption for Shared Access to Objects

The first part of this documentation explains how API Keys work when access to objects stored on the Tardigrade Platform is to be shared between applications. Encryption keys work in a very similar way.

Each Uplink Client has an Encryption Passphrase that is configured when the Uplink Client is initially set up. This Encryption Passphrase is used to encrypt all objects and metadata stored on the Tardigrade Network.

When an Uplink Client (libuplink, Uplink CLI, or Uplink S3 Gateway) is configured to use an Encryption Passphrase, the Uplink Client automatically creates an HMAC signature that is encoded in the metadata of the object at the time of encryption. At each level of the hierarchy of buckets, path prefixes, and objects, a child HD Encryption Key is derived, and the hierarchy is encoded in the object and object metadata. Based on where an object falls in the hierarchy, if the parent API Key is known, an Encryption Key can be derived for any level of the hierarchy that is valid from that point in the hierarchy and below to any child objects below it in the hierarchy.

Similar to the hierarchically derived structure of API Keys, developers or applications don’t need to worry about the complexity of maintaining a set of keys. Since the hierarchy is encoded into the encryption mechanism, a shareable key can be derived on demand. The shareable HD Encryption Key is described as an EncryptionAccess in the Uplink Client.

Important Design Point

While the API Key is intended to be passed from an Uplink Client to a Satellite, the EncryptionAccess is designed to be passed peer to peer, but never to the Satellite. For efficiency and ease of use, the file sharing functions of the Uplink Client constructs a ‘security envelope’ that contains both the API Key and the EncryptionAccess, that is passed peer-to-peer. The expected application behavior is then for the receiving peer Client Uplink to separate the API Key and the EncryptionAccess, pass the API Key to the Satellite to obtain access to the object, and then, as the Object is downloaded, it is decrypted client-side using the HD Key.