= yaml = title: Glossary toc: true = yaml =
An access list describes which blessing names should be granted access to a particular object or method.
An access list has an In list of blessing patterns that grants access to all blessing names that are matched by one of the patterns, and an optional NotIn list that specifies exclusions from the In list.
For example, an access list with the In list {alice:family} and NotIn list {alice:family:uncle} is matched by principals with blessing names alice:family, alice:family:friend, but NOT alice, alice:friend, alice:family:uncle, alice:family:uncle:spouse, and so on.
See also: Blessing patterns for the semantics of pattern matching, Security Concepts.
Agent is a utility for serving credentials to applications analogous to an ssh-agent. The agent is used to protect private keys from vulnerabilities in the application. The private key is kept encrypted on disk and unencrypted in the memory of the agent process.
Application processes that are descendants of the agent process can use the credentials (e.g., sign a message using the private key) by making requests to the agent process over inter-process communication channels.
See also: Security Concepts.
A blessing is a binding of a human-readable name to a principal, valid under some caveats, given by another principal.
Principals are authorized for operations based on these names.
The binding between the name, the principal and the caveats is cryptographically secured via a chain of certificates. A blessing bound to one principal cannot be used by another. Thus, the theft of blessings does not present a security risk.
For example, a principal Alice (with the key pair (Palice, Salice)) can bind the name allie (or any other name of her choosing) to herself with a self-signed certificate that binds the name allie to Palice, with the caveat that this name can only be used for “read” operations. Since the blessing is based on a self-signed certificate, it is referred to as a self-blessing.
When one principal blesses another, they do so by chaining a new certificate to one of their existing blessings. For example, consider the following two certificates:
friend to the public key Pbob with the caveat “use only between 9am and 5pm” chained toallie certificate mentioned above.Both certificates chained together represent a blessing that binds the name allie:friend to Bob, but only for “read operations, between 9am and 5pm” (all the caveats in all the certificates in the chain).
Bob can then bless Carol with the name allie:friend:colleague by chaining a new certificate, signed by Sbob to his allie:friend blessing.
See also: Security Concepts.
A blessing name is the human readable name extracted from a blessing. Principals are typically authorized based on the blessing names bound to them.
For example, say a principal Carol wishes to invoke the Read method on a service run by a principal Alice. The authorization decision is made after a sequence of steps:
Two principals can have the same blessing name bound to them, allowing them to share authorization without sharing each other's secret private key.
See also: Security Concepts.
A blessing pattern is a “pattern” that is matched by either a specific blessing name or the blessing name and all its extensions.
The pattern <b>:$ is matched by the blessing name <b>, while the pattern <b> is matched by <b> and all its extensions.
For example, the pattern alice:houseguest will be matched by the blessing name alice:houseguest, alice:houseguest:bob, alice:houseguest:bob:friend but not alice:colleague, alice:houseguest2 or prefixes of the pattern like alice (for example alicea or aliceb). The pattern alice:houseguest:$ would be matched only by the exact blessing name alice:houseguest.
See also: Security Concepts.
The root of a blessing is the public key of the first certificate in the certificate chain of the blessing.
A blessing is recognized by an application if and only if the application considers the root of the blessing as being authoritative on the corresponding blessing name.
For example, one application may recognize the root Palice as an authority on blessings matching the pattern allie, such as allie and allie:friend. Other applications may not do so. Thus, when a blessing with the root Palice is presented to them, they will discard this blessing when extracting blessing names.
See also: Security Concepts.
Caveats are conditions placed on a blessing to restrict the validity of a blessing name. For example, caveats may restrict the time duration for which the blessing name can be used, or the set of peers that can be communicated with or the type of operations that can be performed.
When two principals communicate via an RPC, they validate all the caveats in the blessings presented by the peer. In a client-server setting, the client validates caveats on the blessings presented by the server and vice-versa.
Caveats are of two kinds -- first-party and third-party. First-party caveats are validated entirely by the party making an authorization decision on the blessings presented by the remote end.
Third-party caveats are validated by the specific third party mentioned in the caveat. The party making the authorization decision expects a proof of validity (i.e., a Discharge) for the caveat from the third party.
See also: Security Concepts.
A certificate is an object consisting of a human-readable string name, a public key, a list of caveats, and a digital signature over its contents.
Certificates can be chained to form a blessing. The first certificate in the chain is self-signed, i.e., it is signed using the private counterpart of the public key mentioned in the certificate and is referred to as the root certificate.
All other certificates in the chain are signed by the private counterpart of the public key mentioned in the previous certificate in the chain.
See also: Security Concepts.
A client is the caller-side of an RPC. Clients invoke methods on servers.
Credentials encompass a principal (i.e., a public-private key pair), the set of blessings bound to that principal, and the set of recognized blessing roots.
An application process retrieves its credentials from a directory containing this data, or from an agent that holds this data (including the private key of the principal) safely.
A discharge is a proof of validity of a third-party caveat issued by the third party mentioned in the caveat. It is cryptographically tied to the particular caveat.
A discharge may have caveats of its own that limit the validity of the discharge.
A discharge can be cached and reused, so it's not necessarily true that every attempt to use a blessing will incur the cost of obtaining a discharge.
Discharges may expire, but the expiration time is typically broad enough to allow for clock skew.
A server that must be consulted to mint a discharge for a caveat. A blessing is valid only if all of its third-party caveats are discharged.
See also: Security Concepts.
An Endpoint is an encoding of all the information required to securely contact a server. Among other things, this includes the network address of the server, e.g.,<IP address>:<port> (tcp), or <MAC address> (bluetooth).
An identity provider is a principal that signs root certificates of blessings with a fixed name.
For an identity provider to be useful, an application must use credentials that recognize its public key as an authority on blessings extended from its name.
For example, Popular Corp could be an identity provider with public key Ppopularcorp and name popularcorp. It could bless other principals with the name popularcorp:<username>. However, this identity provider will only be useful to other applications that recognize Ppopularcorp as an authoritative key on blessing names beginning with popularcorp:.
Root certificates (and thus identity providers) are recognized only for blessings matching a specific pattern. For example, an application might recognize the root Ppopularcorp for blessings that match the pattern popularcorp and not for blessings that match othercorp. This prevents certificate forging where one recognized identity provider can issue certificates for an entity that is normally managed by another identity provider.
Companies, schools, or other public agencies could become identity providers and application credentials will be configured to recognize some subset of these. For example, services run for general consumption might trust a Google-run blessing service, while services run within a corporate setting would only recognize blessings whose root was a key owned by the corporation.
See also: Security Concepts.
A mount table is a server that associates object names with (endpoint, suffix) pairs. The endpoint identifies the server that hosts the named object, and the suffix is used to locate the object within the server.
The process of associating a name (aka “mount point”) with the (endpoint, suffix) pair of an object is called “mounting”.
Since the mount point is itself an object (on which the Mount RPC can be invoked), it can be mounted on other mount points. This allows for the creation of a hierarchy of names, a namespace of objects.
See also: Naming Concepts.
A directed graph made up of mount tables that create a hierarchy of object names.
A namespace may contain loops (it is not a DAG).
An object name is a human-readable name of an object that exports methods on which RPCs can be made.
Object names are resolved to a set of (endpoint, suffix) pairs via mount tables. Invoking an RPC on an object implies sending the RPC to one of the pairs obtained by resolving the object name.
For example, the object name alice/calendar/today might resolve to the endpoint of Alice‘s calendar server and the suffix today. The object might export methods AddAppointment and RemoveAppointment, which are invoked to manage Alice’s calendar.
See also: Naming Concepts.
Permissions are maps from string tags (like “Read” or “Admin”) to Access Lists specifying the blessings required to invoke methods with that tag.
See also: Security Concepts.
A principal is a public and private key pair.
Every RPC is executed on behalf of a principal. To encourage security, different processes and certainly processes on different devices run as different principals - each with their own private key. The private key should ideally be in secure storage such that it cannot be stolen from the device on which the application is being run.
Applications should never share their private key or transmit it on the wire. Only public keys and blessings should be transmitted. Multiple blessings can be bound to a single principal.
See also: Security Concepts.
Remote procedure calls enable communications between processes by presenting an API based on function calls. The caller of an RPC is known as the client and the receiver that implements the RPC is known as the server. Clients invoke methods implemented on the server, which is identified by its object name.
See also: RPC concepts.
A blessing who's certificate chain has only one certificate, necessarily self-signed, since if it had been signed by another principal it would not be a single entry chain.
A self-blessing is the starting point to issuing blessings to other principals.
A server is the receiver-side of an RPC. Servers implement methods that are invoked by clients.
The term server is also used to refer to the process that hosts objects and dispatches RPC requests to the methods implemented by those objects.
A suffix is the trailing portion of an object name used to identify the object within a server.
For example, the object name alice/calendar/today may be hosted by a server that hosts all objects with the prefix alice/calendar. In that case, the RPC alice/calendar/today.AddAppointment() will be directed to this server and the suffix today will be used by the server to identify the object.
Third-party caveats are caveats wherein the burden of validation is pushed to a specific third party that is different from the request recipient.
A blessing with a third-party caveat is considered valid only when accompanied by a discharge (proof of validity) issued by the specific third party mentioned in the caveat. The third party validates the caveat before granting or denying a discharge.
Examples of third-party caveats include revocation caveats that are discharged by a specific revocation service if and only if the blessing has not been revoked, proximity caveats that are discharged by a proximity service if and only if the requester satisfies the proximity constraints mentioned in the caveat, and audit caveats that are discharged by an auditing service only after updating the audit log.
It is the responsibility of the wielder of a blessing to fetch discharges for all third-party caveats present on the blessing. The wielder may cache discharges for as long as they are valid.
See also: Security Concepts.
The atomic number of Vanadium is 23, which is the inspiration behind the v23 shorthand for Vanadium.
The vrpc command line tool sends and receives RPCs. It is used as a generic client to interact with any server.
VDL describes the API for interfaces provided by objects. This includes the set of methods that can be invoked via an RPC, their arguments and return types. These interfaces are described in .vdl files. The vdl command-line tool generates language-specific interfaces for these APIs.
See also: VDL specification.
VOM is the data serialization format used in Vanadium. It enables the encoding and decoding of typed values across different programming languages, e.g. Go, Java, and JavaScript.
See also: VOM specification.
A server (usually called WSPR, pronounced whisper) allows JavaScript running in a web browser or Node.js to communicate with a Vanadium system. WSPR proxies the Vanadium world behind a WebSocket interface.
A JavaScript app uses a Node.js module that implements a WebSocket front-end to WSPR. WSPR accepts requests from the app over the WebSocket, sends them on as conventional Vanadium RPCs, and returns the responses to the JavaScript app via WebSocket.
WSPR as a concept will move from a freestanding server into a browser extension, and ultimately become native to browsers.