One very important design consideration is that data stored on Storj DCS is encrypted. That means only you have the encryption keys for your data. The service doesn't ever have access to or store your encryption keys. If you lose your keys (or lose the Access Grant containing your encryption passphrase), you will be unable to recover your data.
Where an Authorization Token within an Access Grant 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 or encrypt.
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 serialized Authorization Token. Both are hierarchically deterministic, but where the hierarchy of an Authorization Token is based on the hierarchy of access restrictions, the hierarchy of encryption keys is based on the hierarchy of paths and objects.
The primary difference is that while a Satellite could generate restricted Access Grants that would be essentially the same artifact as a restricted Access Grant generated by an Uplink Client, a Satellite never has access to Encryption Keys.
Out-of-the-box, the Uplink Client supports two encryption standards:
AES 256 GCM
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.
The first part of this documentation explains how Access Grants 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 Access Grant has an Encryption Passphrase that is configured when the Access Grant is initially created. This Encryption Passphrase is used to encrypt all objects and metadata stored on Storj DCS. When a child Restricted Access Grant is created, two things happen:
A restricted Authorization Token is created inside of the new child Restricted Access Grant with a caveat that includes the restrictions in the tail of the Authorization Token
A child encryption key is derived from the encryption key in the parent Access Grant.
If the child Restricted Access Grant includes a path based restriction, not only will the Authorization Token be restricted to just objects with that path prefix, but the hierarchically deterministic derived encryption key contained in that child Restricted Access Grant can only be used to decrypt or encrypt objects with that same path prefix. Just as the child Authorization Token cannot access objects beyond the restrictions contained in it's caveat, that child Encryption Key cannot be used to decrypt objects above the path restriction to which it is limited.
When an Uplink Client (libuplink, Uplink CLI, or Self-hosted Uplink S3 GatewayST) 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 Access Grant 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.
While the Access Grant 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 Authorization Token and the EncryptionAccess, that is passed peer-to-peer. The application behavior is then for the receiving peer Client Uplink to separate the Authorization Token and the EncryptionAccess, pass the Authorization Token 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. This behavior is automatic and all of that complexity is abstracted behind the