Module hdk::capability

source ·
Expand description

Capability claims and grants.

Every exposed function in Holochain uses capability grants/claims to secure access.Capability grants are system entries committed to the source chain that define access. Capability claims are system entries that reference a grant on a source chain.


  1. When Alice wants Bob to be able to call a function on her running conductor she commits a grant for Bob.
  2. Bob commits the grant as a claim on his source chain.
  3. When Bob wants to call Alice’s function he sends the claim back to Alice along with the function call information.
  4. Alice cross references Bob’s claim against her grant, e.g. to check it is still valid, before granting access.

There are four types of capability grant:

  • Author: The author of the local source chain provides their agent key as a claim and has full access to all functions.
  • Unrestricted: Anyone can call this function without providing a claim.
  • Unassigned: Anyone with the randomly generated secret associated with the grant can call this function.
  • Assigned: The specific named agents can call this function if they provide the associated secret.

Capability grants and claims reference each other by a shared, unique, unpredictable secret. The security properties of a capability secret are roughly the same as an API key for a server.

  • If an attacker knows or guesses the secret they can call Unassigned functions
  • An attacker cannot call Assigned functions even if they know or guess the secret
  • If a secret is compromised the grant can be deleted and new claims can be distributed
  • The secret only grants access to live function calls against a running conductor reachable on the network
  • Holochain compares capability secrets using constant time equality checks to mitigate timing attacks
  • Grant secrets are stored in WASM memory so are NOT as secure as a dedicated keystore

Grant secrets are less sensitive than cryptographic keys but are not intended to be public data. Don’t store them to the DHT in plaintext, or commit them to Github repositories, etc!

For best security, assign grants to specific agents if you can as the assignment check does cryptographically validate the caller.