security

Overview ¶

Package security defines types and utilities associated with security.

Concept: https://vanadium.github.io/concepts/security.html
Tutorial: (forthcoming)

The primitives and APIs defined in this package enable bi-directional, end-to-end authentication between communicating parties; authorization based on that authentication; and secrecy and integrity of all communication.

Overview ¶

The Vanadium security model is centered around the concepts of principals and blessings.

A principal in the Vanadium framework is a public and private key pair. Every RPC is executed on behalf of a principal.

A blessing is a binding of a human-readable name to a principal, valid under some caveats, given by another principal. A principal can have multiple blessings bound to it. For instance, a television principal may have a blessing from the manufacturer (e.g., popularcorp:products:tv) as well as from the owner (e.g., alice:devices:hometv). Principals are authorized for operations based on the blessings bound to them.

A principal can "bless" another principal by binding an extension of one of its own blessings to the other principal. This enables delegation of authority. For example, a principal with the blessing "johndoe" can delegate to his phone by blessing the phone as "johndoe:phone", which in-turn can delegate to the headset by blessing it as "johndoe:phone:headset".

Caveats can be added to a blessing in order to restrict the contexts in which it can be used. Amongst other things, caveats can restrict the duration of use and the set of peers that can be communicated with using a blessing.

Navigating the interfaces ¶

Godoc renders all interfaces in this package in alphabetical order. However, we recommend the following order in order to introduce yourself to the API:

• Principal
• Blessings
• BlessingStore
• BlessingRoots
• NewCaveat
• ThirdPartyCaveat
• NewPublicKeyCaveat

Examples ¶

A principal can decide to name itself anything it wants:

// (in process A)
var p1 Principal
alice, _ := p1.BlessSelf("alice")

This "alice" blessing can be presented to to another principal (typically a remote process), but that other principal will not recognize this "self-proclaimed" authority:

// (in process B)
var p2 Principal
ctx, call := GetContextAndCall() // current context and security state
names, rejected := RemoteBlessingNames(ctx, call)
fmt.Printf("%v %v", names, rejected) // Will print [] ["alice": "..."]

However, p2 can decide to trust the roots of the "alice" blessing and then it will be able to recognize her delegates as well:

// (in process B)
AddToRoots(p2, call.RemoteBlessings())
names, rejected := RemoteBlessingNames(ctx, call)
fmt.Printf("%v %v", names, rejected) // Will print ["alice"] []

Furthermore, p2 can seek a blessing from "alice":

// (in process A)
call := GetCall() // Call under which p2 is seeking a blessing from alice, call.LocalPrincipal = p1
key2 := call.RemoteBlessings().PublicKey()
onlyFor10Minutes := NewExpiryCaveat(time.Now().Add(10*time.Minute))
aliceFriend, _ := p1.Bless(key2, alice, "friend", onlyFor10Minutes)
SendBlessingToProcessB(aliceFriend)

p2 can then add this blessing to its store such that this blessing will be presented to "alice" (and her delegates) anytime p2 communicates with it in the future:

// (in process B)
p2.BlessingStore().Set(aliceFriend, "alice")

p2 can also choose to present multiple blessings to some servers:

// (in process B)
charlieFriend := ReceiveBlessingFromSomeWhere()
union, _ := UnionOfBlessings(aliceFriend, charlieFriend)
p2.BlessingStore().Set(union, "alice:mom")

Thus, when communicating with a "server" that presents the blessing "alice:mom", p2 will declare that he is both "alice's friend" and "charlie's friend" and the server may authorize actions based on this fact.

p2 may also choose that it wants to present these two blessings when acting as a "server", (i.e., when it does not know who the peer is):

// (in process B)
default, _ := UnionOfBlessings(aliceFriend, charlieFriend)
p2.BlessingStore().SetDefault(default)