by András Arányi

The Access Control Trie (ACT) is an essential feature designed to manage access control in Swarm’s decentralized storage infrastructure. It enables publishers to grant or revoke access to specific content at the chunk level using encrypted session keys. This guide will walk you through the key concepts and practical aspects of using ACT to protect your data in Swarm.

If you’re a content publisher and looking for a way to share data but maintain full control and privacy, you might find that the below concept of a fully fledged access control mechanism covers all your needs.

Content Publishers

⚠️ TLDR: Publishers can control access to their data by encrypting access keys for each viewer and adding/removing them from the ACT lookup table. ⚠️

As a publisher, you have full control over who can view your content. Using ACT, you can upload your data and grant access to specific grantees (viewers) by referring to their Swarm node wallets’ public keys. Additionally, you can revoke access at any time, ensuring that only authorized viewers have the ability to access your data.

What makes ACT unique is that, as opposed to other solutions which only encrypt data, ACT ensures that only the intended viewers will have access to the data. Everyone else is blocked, even from discovering an encrypted version of it. This significantly increases the privacy and security of your content, preventing unauthorized users from knowing the data even exists.

How to manage access:

1. Upload your content to Swarm as you normally would, but with ACT request headers included.
2. Assign access rights by adding the grantee’s public key to the ACT.
3. If needed, revoke access by removing the grantee from the ACT.

Keep in mind: Publishers can control the latest version of content that grantees are able to access. If you update your content, viewers might still have access to an older version if they were granted access to that earlier version before.

You can learn more about how to manage access using tools like swarm-cli by following the tutorial in the Swarm documentation. These features are also fully supported by the Bee API (starting from version 7.0+), enabling any application to interact with them directly.

Grantees (Content Viewers)

⚠️ TLDR: Grantees can access the specific version of content that the publisher has granted access to, but may lose access to future versions if revoked. ⚠️

As a grantee, your ability to view the content is based on the public key of your Swarm node’s wallet and depends on the permission granted by the publisher. The process for gaining access is simple and secure, thanks to ACT’s encryption mechanisms.

How it works:

• Your Swarm node wallet’s public key is used as a session key, which is then used to create two additional keys:
  • A lookup key to find your entry in the ACT lookup table.
  • An access key decryption key, allowing you to decrypt the content access key specifically encrypted for you.

This ensures that only you can decrypt the content, and you can retrieve the version of the content you have (or have had) permission for.

How ACT Manages Grantee Access

ACT employs a sophisticated mechanism to manage grantee access using public-key cryptography and secure key derivation. At the heart of this system is the ACT lookup table, a key-value store that securely links each grantee’s Swarm node wallet’s public key to an encrypted access key. Here’s a breakdown of how it works:

1. Session Key:
   Each grantee’s Swarm node’s public and private key pair serves as their unique session key. This session key is crucial because it forms the basis for all further encryption steps related to the grantee’s access.
2. Key Derivation via Diffie-Hellman:
   Using Diffie-Hellman key derivation, the session key is used to derive two important keys:
   • Lookup Key: This key is used to identify the specific entry for a grantee in the ACT lookup table.
   • Access Key Decryption Key: This key is used to decrypt the access key, which in turn allows the grantee to unlock the protected content.
3. Encrypted Access Keys:
   The content access key is encrypted specifically for each grantee using their derived decryption key. This ensures that only the intended grantee can decrypt the access key and thus view the content. This per-grantee encryption adds a layer of security, preventing unauthorized access even if someone else obtains the encrypted data.
4. ACT Lookup Table:
   The lookup table itself is implemented as a key-value store within a Swarm manifest. Each grantee’s public key maps to an encrypted access key, ensuring that only authorized users with the correct session and decryption keys can retrieve the access key and, subsequently, the content. This table allows publishers to manage access dynamically, adding or removing grantees as needed without compromising the security of the stored content.
5. Adding and Removing Grantees:
   Publishers have the flexibility to dynamically add or remove grantees from the lookup table. When a grantee is added, their public key and the corresponding encrypted access key are stored in the lookup table.

Version Control and Historical Access:
The ACT maintains a version history, which includes timestamps for each version of the access control list. If a grantee’s access is revoked for new versions of the content, they can still access older versions to which they had been granted permission, based on the relevant timestamps.

Encryption and Security in ACT

⚠️ TLDR: Every element in the ACT process is encrypted, ensuring complete security of content and access control. ⚠️

As demonstrated earlier, encryption is central to how ACT is implemented. Every component, from the grantee list to the content access keys, is encrypted using strong cryptographic methods. This ensures that only authorized users can access your data, and any tampering or unauthorized access is effectively prevented.

Here’s how encryption is applied:

• Grantee List Encryption:
  The list of grantees is encrypted using the publisher’s lookup key, ensuring that unauthorized users cannot even detect the existence of the grantee list. This adds another layer of privacy, as only the publisher and authorized grantees are aware of who has access.
• Access Key Encryption:
  Each grantee’s access key is individually encrypted using their specific decryption key derived through the Diffie-Hellman process. This ensures that only the intended grantee can decrypt the access key and gain access to the protected content.
• Historical Version Encryption:
  All versions of the ACT, including older ones, are protected by encryption. This means that even if a grantee’s access is revoked, the historical data they had access to remains encrypted and secure.

Content Encryption:
Finally, the actual content itself is encrypted at the chunk level. Only those who possess the correct access key (which is encrypted for each grantee) can decrypt and retrieve the content.

Key Takeaways

• Publishers: Maintain control over your data and manage grantee access with fine-grained control using ACT. You can easily add or remove access rights and ensure your data is always protected by encryption.
• Grantees: Access specific versions of content securely, knowing that only you have the ability to decrypt the content you’ve been granted access to.

For anyone operating in the Swarm ecosystem, the Access Control Trie (ACT) represents a critical advancement in decentralized content management, offering robust security while maintaining flexibility in access control.

If you’re interested in learning more about how ACT works or how to implement it in your Swarm nodes, have a look at the Swarm documentation.