Encryption Keys
How encryption and encryption keys work on Storj.
Managing Encryption Keys
One very important design consideration is that data stored on Storj 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 (and lose the Access Grant containing your encryption passphrase), you will be unable to recover your data.
Encryption & Access Grants
Where an API Key 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 API Key. Both are hierarchically deterministic, but where the hierarchy of an API Key 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.
Supported Protocols
Out-of-the-box, the Uplink Client supports the AES-256-GCM encryption standard.
Being open source, 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 diverse 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 Access Grants work when access to objects stored on the Storj Platform is to be shared between applications. Encryption keys work in a very similar way.
Encryption Management Encoded into the Access Grant
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. When a child Restricted Access Grant is created, two things happen:
A restricted API Key is created inside of the new child Restricted Access Grant with a caveat that includes the restrictions in the API Key
A child encryption key (or set of appropriate descendant encryption keys) is derived from the appropriate encryption keys in the parent Access Grant.
If the child Restricted Access Grant includes an object key path component prefix based restriction, not only will the API Key be restricted to just objects with that path prefix, but the hierarchically deterministic derived encryption key store 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 API Key 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.
By creating a restricted Access Grant, whether through the Satellite Admin Console or using an Uplink client, creating the Access Grant automatically creates an API Key and Encryption Key with the appropriate scope of restriction.
At each level of the hierarchy of buckets, object key 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 encryption 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 Access Grants, 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 set is described as an EncryptionAccess in the Uplink Client.
Important Design Point
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 API Key and the EncryptionAccess, that is passed peer-to-peer. The 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. This behavior is automatic and all of that complexity is abstracted behind the cp and share commands.