The Vanadium security model defines mechanisms for identification, authentication, and authorization. The model supports fully decentralized, fine-grained, and auditable delegation of authority.

For example, Alice could choose to delegate access to Bob only under the following conditions:

Such delegations do not have to go through the cloud or any centralized service, can be accomplished by a single interaction between Alice and Bob, and encode an audit trail of the principals involved in the delegation.

All network communication is always mutually authenticated and encrypted. The model is heavily influenced by the work on Simple Distributed Security Infrastructure by Ronald Rivest and Butler Lampson.

Principals & blessings

The security model is centered around the concepts of principals and blessings. A principal in the Vanadium framework is a public and private key pair. All Vanadium processes act on behalf of a principal. The notation (PAlice, SAlice) is used to refer to the public and private key respectively of a principal Alice.

Principals have a set of human-readable names bound to them, via blessings. For instance, a television principal, represented by the key pair (Ptv, Stv), may have a blessing from the manufacturer with the human-readable name of popularcorp:products:tv. Principals can have multiple blessings bound to them and thus have multiple names, each reflecting the principal that granted the blessing. For example, the particular PopularCorp tv owned by Alice might also have the name alice:devices:hometv.

Principals are authenticated and authorized based on the blessing names bound to them. For example, a service may grant access to alice:devices:hometv, which means that all principals with a blessing name matching alice:devices:hometv will have access. Service administrators always use blessing names, not public keys, when making authorization decisions or inspecting audit trails.

Concretely, blessings are represented by public-key certificate chains bound to the principal's public key. For example, the name popularcorp:products:tv could be bound to the public key Ptv using a chain of three certificates:

  1. Certificate with public key Ppopularcorp and name popularcorp, chained to
  2. Certificate with public key Pproducts and name products, chained to
  3. Certificate with public key Ptv and name tv

Chaining means that the certificate is signed by the private counterpart of the public key in the previous certificate. The first certificate in the chain is self-signed, i.e. signed by private counterpart of the public key mentioned in the certificate (Ppopularcorp in this case).

The first certificate is also called the root certificate and the first certificate's public key is called the blessing root.

The term blessing is used to refer to a certificate chain and the term blessing name is used to refer to the human-readable name specified in the certificate chain. If it is clear from the context, then blessing may be used in lieu of blessing name for brevity.

The private key of the principal will generally be hosted by a TPM (Trusted Platform Module) or an agent process and will not be held in memory of the application process to protect against leakage. Private keys are never sent on the network and are used only for digital signing operations.

Mutual authentication

Clients and servers in a Vanadium remote procedure call (RPC) always act on behalf of a principal, and mutually authenticate each other via blessings bound to the other end's principal. The Vanadium authentication protocol allows clients and servers to exchange blessings bound to them, and verify that the other end possesses the private counterpart of the public key to which their blessings are bound. At the end of the protocol, an encrypted channel is established between the client and server for performing the RPC. Forward-secrecy safe protocols (like TLS with ECDHE key exchanges or a NaCl box with ephemerel keys) are used for setting up the encrypted channel.


The authorizations associated with a principal are determined solely by the blessings bound to the principal. Delegation of authority across principals is achieved via the Bless operation. Bless allows a principal to extend one of its blessings and create a blessing bound to another principal's public key, thereby delegating any authorizations associated with the blessing.

For example, a principal (Palice, Salice) may bless another principal (Ptv, Stv) by extending one of her blessings, say alice, with a certificate with the name devices:hometv and the tv's public key Ptv. This certificate is signed with the secret key of the blesser (Salice). The blessing can therefore be viewed as making the statement

Palice using name alice says that Ptv can use the name alice:devices:hometv

Blessing names are thus hierarchical, with colons used to distinguish the blesser (alice) from the blessee (devices:hometv).


In practice, delegation of authority is never unconditional and this is supported by the security model. Blessings can carry caveats that restrict the conditions under which the blessing can be used. For example, a principal (Palice, Salice) can bless another principal (Pbob, Sbob) as alice:houseguest:bob but with the caveat that the blessing can only be used to talk to her TV (and not to remote services that Alice uses). This caveat is specified in the certificate written by alice (for Bob's public key Pbob). Thus the blessing makes a signed statement of the form:

Palice using name alice says that Pbob can use the name alice:houseguest:bob as long as

When Bob presents this blessing to a server, the server will recognize the principal as alice:houseguest:bob only if the server's own blessing name matches alice:devices:hometv.

Caveats can be placed on any information available at the time of the request. This includes, among other things, the time the request is being made, whether the blessing wielder is a client or a server, the communication protocol being used and the method being invoked.

Third-party caveats

Validation of some caveats may involve expensive computation or I/O or information not accessible to the authorizing service. In such cases, the blesser can push the burden of validation to a third party (i.e., neither the party that wields the blessings nor the party that is authorizing them). For example, Alice can allow Bob to use the blessing alice:houseguest:bob only if bob is within 100 feet of Alice's home. When bob wants to authenticate as alice:houseguest:bob, he must obtain a discharge (proof) from the third-party service home_proximity_discharger (mentioned in the caveat) before he can use the name alice:houseguest:bob. Thus the blessing makes the signed statement:

Palice using name alice says that Pbob can use the name alice:houseguest:bob as long as

By using such third-party caveats, the burden of making the network calls to obtain a discharge and the burden of any computation or I/O to validate the restrictions are moved to the wielder of the blessing and to the third-party respectively, away from the end at which the authorization decision is being made.

Validating blessings

A blessing is considered valid in the context of an RPC if and only if

A blessing is recognized by a Vanadium application if and only if the application considers the blessing root as authoritative for the blessing name. (Recall that blessing root is the public key of the first certificate in the blessing's certificate chain.)

For example, an application may consider the root Ppopularcorp as authoritative on all blessing names that begin with popularcorp. Such an application would then recognize the blessing popularcorp:products:tv if it is rooted in Ppopularcorp.

All Vanadium applications are configured to consider certain blessing roots as authoritative for certain names, and this configuration may vary across applications.


In a remote procedure call, two authorization decisions need to be made:

Both these decision are made using the following principle:

Authorization is based on validated blessing names

For example, a client may wish to invoke the Display method on a service only if the server presents a blessing matching the pattern alice:devices:hometv. Similarly, the service may allow a client to invoke the Display method only if the client presents a blessing matching the pattern alice:houseguest.

The public keys of the client and server principals do not matter as long as they present a blessing with a valid name matching the other end's authorization policy. Each end ascertains the valid blessing name of the other end by validating all caveats associated with the blessing and verifying that the blessing is recognized.

A pattern is a blessing name that may optionally end in a :$. If the pattern ends in a `:$``, it is only matched by the exact blessing name. Otherwise, it is matched by the blessing name and all its extensions.

For example, the pattern alice:houseguest will be matched by the name alice:houseguest and its extensions (e.g., alice:houseguest:bob) but not by the name bob or alice:colleague or prefixes of the pattern (i.e. alice). On the other hand, the pattern alice:houseguest:$ would be matched exactly by the name alice:houseguest.

Selecting a blessing

A principal may have collected multiple blessings and may need to choose which subset of them to present when authenticating with a peer. It could present all, at the cost of leaking sensitive information (e.g., bob is a houseguest of alice) when not necessary. Instead Vanadium provides a means to selectively share blessings with appropriate peers.

All blessings for a principal are stored in a blessing store, akin to a cookie jar in web browsers. The store marks the blessings to be presented when acting as a server (and a server always reveals its blessings first as per the Vanadium authentication protocol). Clients select a subset of their blessings from the store to share with a server based on the blessing names of the server.

For example, Bob's blessing store can add the blessing alice:houseguest:bob to the store only to be shared with servers matching the pattern alice. Thus, all servers run by alice (such as alice:hometv and alice:homedoor) will see the alice:houseguest:bob blessing when Bob makes requests to them, but any other servers that Bob communicates with will not know that he has this blessing from Alice.