Counterpart of https://vanadium-review.googlesource.com/17703
Details in vanadium/issues#739
MultiPart: 4/6
Change-Id: I75062e52f2166b5e67423c6fb27318c9113975f2
diff --git a/concepts/security.md b/concepts/security.md
index 300ca0d..47bc680 100644
--- a/concepts/security.md
+++ b/concepts/security.md
@@ -30,21 +30,21 @@
Principals have a set of human-readable names bound to them, via _blessings_.
For instance, a television principal, represented by the key pair
(<code>P<sub>tv</sub>, S<sub>tv</sub></code>), may have a blessing from the
-manufacturer with the human-readable name of `popularcorp/products/tv`.
+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`.
+`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.
+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
+`popularcorp:products:tv` could be bound to the public key
<code>P<sub>tv</sub></code> using a chain of three certificates:
1. Certificate with public key <code>P<sub>popularcorp</sub></code> and name
@@ -92,18 +92,18 @@
For example, a principal (<code>P<sub>alice</sub>, S<sub>alice</sub></code>) may bless another principal
(<code>P<sub>tv</sub>, S<sub>tv</sub></code>) by extending one of
-her blessings, say `alice`, with a certificate with the name `devices/hometv` and the tv's public key
+her blessings, say `alice`, with a certificate with the name `devices:hometv` and the tv's public key
<code>P<sub>tv</sub></code>. This certificate is signed with the secret key of the blesser
(<code>S<sub>alice</sub></code>). The blessing can therefore be viewed as making
the statement
> <code>P<sub>alice</sub></code> using name <code>alice</code> says that
> <code>P<sub>tv</sub></code> can use the name
-> <code>alice/devices/hometv</code>
+> <code>alice:devices:hometv</code>
Blessing names are thus hierarchical, with
slashes used to distinguish the blesser (`alice`) from the blessee
-(`devices/hometv`).
+(`devices:hometv`).
## Caveats
@@ -112,7 +112,7 @@
conditions under which the blessing can be used. For example, a principal
(<code>P<sub>alice</sub>, S<sub>alice</sub></code>) can bless
another principal (<code>P<sub>bob</sub>, S<sub>bob</sub></code>)
-as `alice/houseguest/bob` but with the caveat that the blessing can only be used
+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
<code>P<sub>bob</sub></code>). Thus the blessing makes a signed statement of
@@ -120,12 +120,12 @@
> <code>P<sub>alice</sub></code> using name <code>alice</code> says that
> <code>P<sub>bob</sub></code> can use the name
-> <code>alice/houseguest/bob</code> _as long as_<br>
- * <code>server</code> matches `alice/devices/hometv`
+> <code>alice:houseguest:bob</code> _as long as_<br>
+ * <code>server</code> matches `alice:devices:hometv`
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`.
+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
@@ -138,16 +138,16 @@
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
+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
+`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
+use the name `alice:houseguest:bob`. Thus the blessing makes the signed
statement:
> <code>P<sub>alice</sub></code> using name <code>alice</code> says that
> <code>P<sub>bob</sub></code> can use the name
-> <code>alice/houseguest/bob</code> _as long as_<br>
+> <code>alice:houseguest:bob</code> _as long as_<br>
* <code>home_proximity_discharger</code> issues a discharge after validating that
<code>P<sub>bob</sub></code> is <code>"within 100 ft"</code> of it.
@@ -171,7 +171,7 @@
For example, an application may consider the root
<code>P<sub>popularcorp</sub></code> 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
+blessing `popularcorp:products:tv` if it is rooted in
<code>P<sub>popularcorp</sub></code>.
All Vanadium applications are configured to consider certain blessing roots as
@@ -193,9 +193,9 @@
<center><h4>Authorization is based on validated blessing names</h4></center>
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`.
+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`.
+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
@@ -203,15 +203,15 @@
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
+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`.
+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
@@ -228,10 +228,10 @@
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`
+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,
+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.
@@ -253,38 +253,38 @@
The main motivations for using patterns (as opposed to fixed strings) for
authorization are to encourage delegation, enable auditing, and discourage
insecure workarounds. For example, if Alice's tv authorizes based on the
- pattern `alice/houseguest`, then an authorized principal Bob with the
- blessing `alice/houseguest/bob` can delegate Carol to use the tv by blessing
- her with the name `alice/houseguest/bob/friend` (with appropriate caveats).
- This name would match the blessing pattern `alice/houseguest`. By making
+ pattern `alice:houseguest`, then an authorized principal Bob with the
+ blessing `alice:houseguest:bob` can delegate Carol to use the tv by blessing
+ her with the name `alice:houseguest:bob:friend` (with appropriate caveats).
+ This name would match the blessing pattern `alice:houseguest`. By making
safely constrained delegation easy, Vanadium aims to discourage insecure
workarounds. If delegates were not authorized and Bob really wanted to share
access to Alice's tv with Carol, he may be tempted to work around the
restriction by running a proxy service for Carol. Alternatively, he could
- create a new private key, get that blessed as `alice/houseguest/bob` and
+ create a new private key, get that blessed as `alice:houseguest:bob` and
share the key with Carol. By making blessings and patterns easy to use
instead, Bob is discouraged from trying out these hacks.
Having said that, patterns can also terminate with a `$` which forbid
- delegation. So the pattern `alice/$` will only be matched by the blessing
- name `alice` and not by `alice/houseguest` etc. While this facility does
+ delegation. So the pattern `alice:$` will only be matched by the blessing
+ name `alice` and not by `alice:houseguest` etc. While this facility does
exist, application developers and administrators are encouraged to think hard
about why they want to disallow delegation and whether doing so will
encourage hacky, insecure workarounds.
-- **Why does the pattern `alice/houseguest` not match prefixes like `alice`?**
+- **Why does the pattern `alice:houseguest` not match prefixes like `alice`?**
- The pattern `alice/houseguest` matches the blessing name `alice/houseguest`
- and any delegates like `alice/houseguest/bob` or `alice/houseguest/carol`,
+ The pattern `alice:houseguest` matches the blessing name `alice:houseguest`
+ and any delegates like `alice:houseguest:bob` or `alice:houseguest:carol`,
but not `alice` itself. Doing so does not really prevent `alice` from
accessing the resource, as `alice` can generate the blessing name
- `alice/houseguest/foo` for herself at any time. However, this does protect
+ `alice:houseguest:foo` for herself at any time. However, this does protect
against accidental use of authority.
Think of how `sudo` works in UNIX-based systems. Users with `sudo` access can
act as the superuser, but they must explicitly do so by invoking the `sudo`
command. Similar to that, `alice` can generate the blessings required to
- access resources protected by the pattern `alice/houseguest`, but she must
+ access resources protected by the pattern `alice:houseguest`, but she must
explicitly choose to do so by blessing herself.
- **The authorization story described above demonstrates that there are two
@@ -299,7 +299,7 @@
- _Do you have the ability to change the access list?_
It is likely that only `alice` can change the access list on the tv
- (since she owns it). Thus, if `alice/houseguest/bob` wants to provide
+ (since she owns it). Thus, if `alice:houseguest:bob` wants to provide
`carol` with access to the tv, his options are to either bless `carol` or
find `alice` and trouble her to change the access list or try workarounds
like proxying the RPC.
@@ -311,7 +311,7 @@
- _Are there conditions on the access?_
Blessings allow for caveats on their use. For example,
- `alice/houseguest/bob` can only be used within 100ft of the house. For
+ `alice:houseguest:bob` can only be used within 100ft of the house. For
simplicity, Vanadium currently intends to support such caveats only on
blessings and keep access lists as simple lists of patterns (instead of
being able to specify arbitrary caveats in the access list).
@@ -343,10 +343,10 @@
A server pattern is a blessing pattern indicating that the specific blessing it accompanies can
only be revealed to servers that have a blessing name matching the pattern.
- For example, if a client has a blessing `alice/houseguest` tagged with the pattern
- `alice/devices` in its blessing store then the blessing will only be revealed to servers that have
- blessings matching the pattern `alice/devices` (e.g.,`alice/devices/tv`).
- Other services (e.g., `carol/homedoor`) that the client communicates with will never see
+ For example, if a client has a blessing `alice:houseguest` tagged with the pattern
+ `alice:devices` in its blessing store then the blessing will only be revealed to servers that have
+ blessings matching the pattern `alice:devices` (e.g.,`alice:devices:tv`).
+ Other services (e.g., `carol:homedoor`) that the client communicates with will never see
this blessing and thus never learn that the client is Alice's _houseguest_.
[TLS]: http://en.wikipedia.org/wiki/Transport_Layer_Security
diff --git a/designdocs/identity-service.md b/designdocs/identity-service.md
index 2c01582..0576106 100644
--- a/designdocs/identity-service.md
+++ b/designdocs/identity-service.md
@@ -4,7 +4,7 @@
It uses an [OAuth2] identity provider to get the email address of a user and
then issues a blessing with that email address. For example, after determining
that the user is `alice@university.edu` (using OAuth2), this service will issue
-the blessing `dev.v.io/u/alice@university.edu` (where `dev.v.io` is
+the blessing `dev.v.io:u:alice@university.edu` (where `dev.v.io` is
the namespace for which the public key of the identity service is considered
authoriative). The blessing may also contain specific caveats per the user's
request.
@@ -164,7 +164,7 @@
impersonation attacks wherein an attacker steals the macaroon handed out in
step 5 and then tries to obtain a blessing for the email address encapsulated
in the macaroon.
- - Generates a [blessing] with the name `dev.v.io/u/<email>` and the
+ - Generates a [blessing] with the name `dev.v.io:u:<email>` and the
caveats extracted from the macaroon. This blessing is bound to the public
key of the principal making the RPC request (i.e., `toolPublicKey`).
- Records the creation of this blessing in a database which can be queried via
diff --git a/glossary.md b/glossary.md
index 1da6517..0ceb1fd 100644
--- a/glossary.md
+++ b/glossary.md
@@ -9,10 +9,10 @@
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.
+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](#blessing-pattern) for the semantics of pattern
matching, [Security Concepts].
@@ -58,11 +58,11 @@
2. The `allie` 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"
+`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 <code>S<sub>bob</sub></code> to his `allie/friend`
+_Bob_ can then bless _Carol_ with the name `allie:friend:colleague` by chaining
+a new certificate, signed by <code>S<sub>bob</sub></code> to his `allie:friend`
blessing.
See also: [Security Concepts].
@@ -95,14 +95,14 @@
[blessing name](#blessing-name) or the blessing name and all its
[extensions](#blessing).
-The pattern `<b>/$` is matched by the blessing name `<b>`, while the pattern `<b>`
+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`.
+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].
@@ -117,7 +117,7 @@
For example, one application may recognize the root
<code>P<sub>alice</sub></code> as an authority on blessings matching the
-pattern `allie`, such as `allie` and `allie/friend`. Other applications may
+pattern `allie`, such as `allie` and `allie:friend`. Other applications may
not do so. Thus, when a blessing with the root <code>P<sub>alice</sub></code>
is presented to them, they will discard this blessing when extracting [blessing
names](#blessing-name).
@@ -219,10 +219,10 @@
For example, _Popular Corp_ could be an identity provider with public key
<code>P<sub>popularcorp</sub></code> and name `popularcorp`. It could bless
-other principals with the name `popularcorp/<username>`. However, this identity
+other principals with the name `popularcorp:<username>`. However, this identity
provider will only be useful to other applications that recognize
<code>P<sub>popularcorp</sub></code> as an authoritative key on blessing names
-beginning with `popularcorp/`.
+beginning with `popularcorp:`.
Root certificates (and thus identity providers) are recognized only for
blessings matching a specific [pattern](#blessing-pattern). For example, an
