| // Copyright 2015 The Vanadium Authors. All rights reserved. |
| // Use of this source code is governed by a BSD-style |
| // license that can be found in the LICENSE file. |
| |
| /** |
| * Package security defines types and utilities associated with security. |
| * <p><ul> |
| * <li>Concept: <a href="https://github.com/vanadium/docs/blob/master/concepts/security.md">https://github.com/vanadium/docs/blob/master/concepts/security.md</a></li> |
| * <li>Tutorial: (forthcoming)</li> |
| * </ul><p> |
| * 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. |
| * <p> |
| * <strong>Overview</strong> |
| * <p> |
| * The Vanadium security model is centered around the concepts of principals |
| * and blessings. |
| * <p> |
| * A principal in the Vanadium framework is a public and private key pair. |
| * Every RPC is executed on behalf of a principal. |
| * <p> |
| * 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., {@code popularcorp/products/tv}) as well as |
| * from the owner (e.g., {@code alice/devices/hometv}). Principals are authorized for |
| * operations based on the blessings bound to them. |
| * <p> |
| * 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 |
| * {@code "johndoe"} can delegate to his phone by blessing the phone as |
| * {@code "johndoe/phone"}, which in-turn can delegate to the headset by blessing it as |
| * {@code "johndoe/phone/headset"}. |
| * <p> |
| * 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. |
| * <p> |
| * <strong>Navigating the interfaces</strong> |
| * <p> |
| * We recommend the following order in order to introduce yourself to the API: |
| * <p><ul> |
| * <li>{@link io.v.v23.security.VPrincipal}</li> |
| * <li>{@link io.v.v23.security.Blessings}</li> |
| * <li>{@link io.v.v23.security.BlessingStore}</li> |
| * <li>{@link io.v.v23.security.BlessingRoots}</li> |
| * <li>{@link io.v.v23.security.VSecurity}</li> |
| * </ul> |
| * <p> |
| * <strong>Examples</strong> |
| * <p> |
| * A principal can decide to name itself anything it wants: |
| * <p><blockquote><pre> |
| * // (in process A) |
| * VPrincipal p1 = VSecurity.newPrincipal(); |
| * Blessings alice := p1.blessSelf("alice"); |
| * </pre></blockquote><p> |
| * This {@code alice} blessing can be presented to to another principal (typically a |
| * remote process), but that other principal will not recognize this "self-proclaimed" authority: |
| * <p><blockquote><pre> |
| * // (in process B) |
| * // context = current context |
| * // call = current security state |
| * VPrincipal p2 = VSecurity.newPrincipal(); |
| * String[] names = VSecurity.getRemoteBlessingNames(ctx, call); |
| * System.out.println(Arrays.toString(names)); // Will print {@code ""} |
| * </pre></blockquote><p> |
| * However, {@code p2} can decide to trust the roots of the {@code "alice"} blessing and then it |
| * will be able to recognize her delegates as well: |
| * <p><blockquote><pre> |
| * // (in process B) |
| * VSecurity.addToRoots(p2, call.remoteBlessings()); |
| * String[] names = VSecurity.getRemoteBlessingNames(ctx, call); |
| * System.out.println(Arrays.toString(names)); // Will print {@code "alice"} |
| * </pre></blockquote><p> |
| * Furthermore, {@code p2} can seek a blessing from {@code "alice"}: |
| * <p><blockquote><pre> |
| * // (in process A) |
| * // call = call under which p2 is seeking a blessing from alice, call.localPrincipal() = p1 |
| * ECPublicKey key2 = call.remoteBlessings().publicKey(); |
| * Caveat onlyFor10Minutes = VSecurity.newExpiryCaveat(DateTime.now().plus(10000)); |
| * Blessings aliceFriend = p1.bless(key2, alice, "friend", onlyFor10Minutes); |
| * sendBlessingToProcessB(aliceFriend); |
| * </pre></blockquote><p> |
| * {@code p2} can then add this blessing to its store such that this blessing will be |
| * presented to {@code p1} anytime {@code p2} communicates with it in the future: |
| * <p><blockquote><pre> |
| * // (in process B) |
| * p2.blessingStore().set(aliceFriend, new BlessingPattern("alice")); |
| * </pre></blockquote><p> |
| * {@code p2} can also choose to present multiple blessings to some servers: |
| * <p><blockquote><pre> |
| * // (in process B) |
| * Blessings charlieFriend = receiveBlessingFromSomewhere(); |
| * Blessings union = VSecurity.unionOfBlessings(aliceFriend, charlieFriend); |
| * p2.blessingStore().set(union, new BlessingPattern("alice/mom")); |
| * </pre></blockquote><p> |
| * Thus, when communicating with a server that presents the blessing {@code "alice/mom"}, |
| * {@code p2} will declare that he is both "alice's friend" and "charlie's friend" and |
| * the server may authorize actions based on this fact. |
| * <p> |
| * {@code 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): |
| * <p><blockquote><pre> |
| * // (in process B) |
| * Blessings default = VSecurity.unionOfBlessings(aliceFriend, charlieFriend); |
| * p2.blessingStore().SetDefault(default); |
| * </pre></blockquote><p> |
| */ |
| package io.v.v23.security; |
