Authentication Protocol

When a network connection is established between two Vanadium processes, they authenticate each other, i.e., exchange blessings so that both ends can identify the specific principal at the other end. The remote blessing names are then used to authorize RPCs. This document describes:

Principals & blessings

A principal is defined by a unique (public, private) key pair (P, S) and a set of blessings in the form of certificate chains that bind a name to P. For more details, read security concepts.

Within the Go codebase, the set of blessings is encapsulated within the type. The principal and all private key operations are encapsulated in the type.


Communication between two processes takes place after they establish a confidential, authenticated connection. Encryption with keys derived from an Elliptic curve Diffie-Hellman (ECDH) exchange is used to provide message confidentiality and integrity . The goal of the authentication protocol is to exchange the blessings in a way that provides the following properties:

  1. Session binding: The private counterpart S of the public key P to which the blessings are bound must be possessed by the same process with which the session encryption keys have been established.
  2. Client Privacy: An active or passive network attacker listening in on all communication between the two processes cannot determine the set of blessings presented by the initiator of the connection (the "Client").

Additionally the protocol also offers an optional mode where Server Privacy is upheld, i.e., an active or passive network attacker cannot determine the set of blessings presented by the responder of the connection (the "Server"). This mode makes use of Identity-Based Encryption and has an additional performance overhead.

Current implementation

As of March 2016, the reference implementation of the Vanadium networking stack in [] provides confidential, authenticated communication streams (referred to as virtual circuits or VCs). Blessings bound to the public key used to establish the communication stream are provided with each RPC request.

In this implementation, NaCl/box is used to establish an authenticated-encryption channel based on an ECDH key exchange.

Authentication flow diagram


Server Privacy

In the protocol described above, the server presents its blessings first and thus reveals it to active network attackers that initiate a connection to it. (Note that while such active network attackers may learn the server's blessings they would not be able to complete the protocol unless they can present valid blessings that satisfy the server's authorization policy.) In light of this privacy threat, the protocol offers a server privacy mode wherein the server's blessings only get revealed to clients that satisfy its authorization policy.

The key primitive in the design of our protocols is a mechanism to encrypt a message under an authorization policy so that it can only be decrypted by principals possessing blessings satisfying the policy. Once we have such a primitive we can modify the above protocol by having the server send its blessings encrypted under its authorization policy. This would ensure that the server's blessings get revealed only to authorized clients and thus protect the server's privacy.

Authorization policies in Vanadium are based on blessing patterns, which are a special form of name prefixes. Encrypting a message under a blessing pattern is possible using a prefix-encryption scheme which can be built using Identity-Based Encryption (IBE).

An IBE scheme requires a trusted root authority for extracting and handing out identity secret keys corresponding to the blessing names possessed by principals. Such trusted root authorities may coincide with blessing roots in the Vanadium setting. For example, the principal Alice could be an IBE root as well as a blesing roots that issues a blessing and an identity secret key for the name Alice:Device:TV to its television set.

Correctness Proof

The protocol along with the guarantees that it makes has been formalized in ProVerif to provide a proof of correctness. This formalization is available here

Code pointers

Pointers to code in the reference implementation of the Vanadium APIs: