Access Control

Learn how Authorization and Encryption work

Tardigrade contains tools for Access Management, which enables developers to granularly control sharing within their applications, on top of a decentralized, distributed system.

Access management on the Tardigrade platform requires coordination of two parallel constructs:

  • Authorization - An API Key must be provided in order to access an object on the platform. API keys are based on macaroons.

  • Encryption - An HD Encryption Key must also be provided so that the object can be decrypted when it is accessed. Objects are encrypted with a randomized encryption key that is salted with a predetermined salt. Paths and randomized encryption keys are encrypted with a passphrase using AES 256 CTR or Secretbox.

Both of these constructs work together to provide an access management framework that is secure and private, as well as extremely flexible for application developers.

To make the implementation of these constructs as easy as possible for developers to use, the Tardigrade developer tools abstracts the complexity of encoding objects for access management and encryption/decryption.

Understanding how Authorization and Encryption work together is critical to designing an appropriate access management flow for an application

API Keys can be restricted both from the server side (at the Satellite) and from the client side using a serialized, hierarchically derived structure and caveats. The Tardigrade satellites never come in contact with encryption keys – they are managed client-side using a serialized, hierarchically derived structure.

Diagram of hierarchical deterministic encryption

The Tardigrade Platform is not designed to handle identity management for end users of applications that store data on the platform. User authentication is expected to be handled by applications. Application developers may then make further design decisions related to use the authorization management functions of the platform.


The API Keys issued by the satellite are based on Macaroons. A Macaroon is essentially a cookie with an internal structure. A Macaroon embeds the logic for the access it allows and can be restricted, simply by embedding the path restrictions and any additional restrictions within the string that represents the Macaroon. Unlike a typical cookie, a Macaroon is not a random string of bytes, but rather is an envelope with access logic encoded in it.

About Macaroons

For a more complete review of Macaroons, please check out the Google paper. This document will provide enough information to effectively use the access management and object sharing functionality of the Tardigrade platform, but is not intended to be an exhaustive explanation on the full functionality of Macaroons.

Although this document uses the terms “Macaroon” and “API Key” interchangeably, only the term “API Key” is referenced on the platform, through the libraries, and in the documentation. Hereafter, only the term API Key will be used.

Access Management Starts at the Project Level

Each Project has a Root API Key Secret that is issued by the Satellite. This Root API Key Secret is used to create API Keys. Since all API Keys are derived from the same Root Macaroon Secret, they all have the same level of access. By default, all API Keys have complete, unrestricted access to perform all functions against all objects within a project.

When an Uplink Client (LibUplink, Uplink CLI, or Uplink S3 Gateway) is configured to use an API Key, the Uplink Client automatically creates an HMAC signature that is encoded in the metadata of the object stored. As objects (buckets, files, folders, n-tier subfolders) are created, the hierarchy is encoded in the object metadata. Based on where an object falls in the hierarchy, If the parent API Key is known, an access credential 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.

Sharing Access to Objects

Access is shared client-to-client

When the access credential is created by the Uplink Client, that access credential can be passed to a peer (another Uplink Client). That Uplink Client peer can then pass the access credential to the appropriate Satellite to request access to the object. The Satellite can determine the validity of the API Key passed to it (along with any Caveats as described below) without needing access to the actual metadata. Since the metadata is also encrypted client-side, this is extremely important.

Effectively, the Satellite does not need to know which user or application is attempting an object or what the object is; The Uplink Client provides only the minimum information that allows the Satellite to determine the validity of the request without knowing anything about the requestor or the object being requested.

It is also possible to restrict an API Key to provide a limited level of access to an object. Access restrictions are accomplished through the use of Caveats. Caveats are conditional access restrictions that are encoded into the body of an API Key.

An API Key has three parts, a head, a list of caveats, and a tail. These are concatenated and serialized together. An unrestricted API Key has no caveats, so it’s just a head and a tail. The head is a random nonce, and the tail of the unrestricted API Key is the HMAC of the root secret and the head.

The next section will detail the specific restrictions on the bucket and object constructs.