cannam@49: # Copyright (c) 2014 Sandstorm Development Group, Inc. and contributors
cannam@49: # Licensed under the MIT License:
cannam@49: #
cannam@49: # Permission is hereby granted, free of charge, to any person obtaining a copy
cannam@49: # of this software and associated documentation files (the "Software"), to deal
cannam@49: # in the Software without restriction, including without limitation the rights
cannam@49: # to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
cannam@49: # copies of the Software, and to permit persons to whom the Software is
cannam@49: # furnished to do so, subject to the following conditions:
cannam@49: #
cannam@49: # The above copyright notice and this permission notice shall be included in
cannam@49: # all copies or substantial portions of the Software.
cannam@49: #
cannam@49: # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
cannam@49: # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
cannam@49: # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
cannam@49: # AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
cannam@49: # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
cannam@49: # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
cannam@49: # THE SOFTWARE.
cannam@49: 
cannam@49: @0xb8630836983feed7;
cannam@49: 
cannam@49: $import "/capnp/c++.capnp".namespace("capnp");
cannam@49: 
cannam@49: interface Persistent@0xc8cb212fcd9f5691(SturdyRef, Owner) {
cannam@49:   # Interface implemented by capabilities that outlive a single connection. A client may save()
cannam@49:   # the capability, producing a SturdyRef. The SturdyRef can be stored to disk, then later used to
cannam@49:   # obtain a new reference to the capability on a future connection.
cannam@49:   #
cannam@49:   # The exact format of SturdyRef depends on the "realm" in which the SturdyRef appears. A "realm"
cannam@49:   # is an abstract space in which all SturdyRefs have the same format and refer to the same set of
cannam@49:   # resources. Every vat is in exactly one realm. All capability clients within that vat must
cannam@49:   # produce SturdyRefs of the format appropriate for the realm.
cannam@49:   #
cannam@49:   # Similarly, every VatNetwork also resides in a particular realm. Usually, a vat's "realm"
cannam@49:   # corresponds to the realm of its main VatNetwork. However, a Vat can in fact communicate over
cannam@49:   # a VatNetwork in a different realm -- in this case, all SturdyRefs need to be transformed when
cannam@49:   # coming or going through said VatNetwork. The RPC system has hooks for registering
cannam@49:   # transformation callbacks for this purpose.
cannam@49:   #
cannam@49:   # Since the format of SturdyRef is realm-dependent, it is not defined here. An application should
cannam@49:   # choose an appropriate realm for itself as part of its design. Note that under Sandstorm, every
cannam@49:   # application exists in its own realm and is therefore free to define its own SturdyRef format;
cannam@49:   # the Sandstorm platform handles translating between realms.
cannam@49:   #
cannam@49:   # Note that whether a capability is persistent is often orthogonal to its type. In these cases,
cannam@49:   # the capability's interface should NOT inherit `Persistent`; instead, just perform a cast at
cannam@49:   # runtime. It's not type-safe, but trying to be type-safe in these cases will likely lead to
cannam@49:   # tears. In cases where a particular interface only makes sense on persistent capabilities, it
cannam@49:   # still should not explicitly inherit Persistent because the `SturdyRef` and `Owner` types will
cannam@49:   # vary between realms (they may even be different at the call site than they are on the
cannam@49:   # implementation). Instead, mark persistent interfaces with the $persistent annotation (defined
cannam@49:   # below).
cannam@49:   #
cannam@49:   # Sealing
cannam@49:   # -------
cannam@49:   #
cannam@49:   # As an added security measure, SturdyRefs may be "sealed" to a particular owner, such that
cannam@49:   # if the SturdyRef itself leaks to a third party, that party cannot actually restore it because
cannam@49:   # they are not the owner. To restore a sealed capability, you must first prove to its host that
cannam@49:   # you are the rightful owner. The precise mechanism for this authentication is defined by the
cannam@49:   # realm.
cannam@49:   #
cannam@49:   # Sealing is a defense-in-depth mechanism meant to mitigate damage in the case of catastrophic
cannam@49:   # attacks. For example, say an attacker temporarily gains read access to a database full of
cannam@49:   # SturdyRefs: it would be unfortunate if it were then necessary to revoke every single reference
cannam@49:   # in the database to prevent the attacker from using them.
cannam@49:   #
cannam@49:   # In general, an "owner" is a course-grained identity. Because capability-based security is still
cannam@49:   # the primary mechanism of security, it is not necessary nor desirable to have a separate "owner"
cannam@49:   # identity for every single process or object; that is exactly what capabilities are supposed to
cannam@49:   # avoid! Instead, it makes sense for an "owner" to literally identify the owner of the machines
cannam@49:   # where the capability is stored. If untrusted third parties are able to run arbitrary code on
cannam@49:   # said machines, then the sandbox for that code should be designed using Distributed Confinement
cannam@49:   # such that the third-party code never sees the bits of the SturdyRefs and cannot directly
cannam@49:   # exercise the owner's power to restore refs. See:
cannam@49:   #
cannam@49:   #     http://www.erights.org/elib/capability/dist-confine.html
cannam@49:   #
cannam@49:   # Resist the urge to represent an Owner as a simple public key. The whole point of sealing is to
cannam@49:   # defend against leaked-storage attacks. Such attacks can easily result in the owner's private
cannam@49:   # key being stolen as well. A better solution is for `Owner` to contain a simple globally unique
cannam@49:   # identifier for the owner, and for everyone to separately maintain a mapping of owner IDs to
cannam@49:   # public keys. If an owner's private key is compromised, then humans will need to communicate
cannam@49:   # and agree on a replacement public key, then update the mapping.
cannam@49:   #
cannam@49:   # As a concrete example, an `Owner` could simply contain a domain name, and restoring a SturdyRef
cannam@49:   # would require signing a request using the domain's private key. Authenticating this key could
cannam@49:   # be accomplished through certificate authorities or web-of-trust techniques.
cannam@49: 
cannam@49:   save @0 SaveParams -> SaveResults;
cannam@49:   # Save a capability persistently so that it can be restored by a future connection.  Not all
cannam@49:   # capabilities can be saved -- application interfaces should define which capabilities support
cannam@49:   # this and which do not.
cannam@49: 
cannam@49:   struct SaveParams {
cannam@49:     sealFor @0 :Owner;
cannam@49:     # Seal the SturdyRef so that it can only be restored by the specified Owner. This is meant
cannam@49:     # to mitigate damage when a SturdyRef is leaked. See comments above.
cannam@49:     #
cannam@49:     # Leaving this value null may or may not be allowed; it is up to the realm to decide. If a
cannam@49:     # realm does allow a null owner, this should indicate that anyone is allowed to restore the
cannam@49:     # ref.
cannam@49:   }
cannam@49:   struct SaveResults {
cannam@49:     sturdyRef @0 :SturdyRef;
cannam@49:   }
cannam@49: }
cannam@49: 
cannam@49: interface RealmGateway(InternalRef, ExternalRef, InternalOwner, ExternalOwner) {
cannam@49:   # Interface invoked when a SturdyRef is about to cross realms. The RPC system supports providing
cannam@49:   # a RealmGateway as a callback hook when setting up RPC over some VatNetwork.
cannam@49: 
cannam@49:   import @0 (cap :Persistent(ExternalRef, ExternalOwner),
cannam@49:              params :Persistent(InternalRef, InternalOwner).SaveParams)
cannam@49:          -> Persistent(InternalRef, InternalOwner).SaveResults;
cannam@49:   # Given an external capability, save it and return an internal reference. Used when someone
cannam@49:   # inside the realm tries to save a capability from outside the realm.
cannam@49: 
cannam@49:   export @1 (cap :Persistent(InternalRef, InternalOwner),
cannam@49:              params :Persistent(ExternalRef, ExternalOwner).SaveParams)
cannam@49:          -> Persistent(ExternalRef, ExternalOwner).SaveResults;
cannam@49:   # Given an internal capability, save it and return an external reference. Used when someone
cannam@49:   # outside the realm tries to save a capability from inside the realm.
cannam@49: }
cannam@49: 
cannam@49: annotation persistent(interface, field) :Void;
cannam@49: # Apply this annotation to interfaces for objects that will always be persistent, instead of
cannam@49: # extending the Persistent capability, since the correct type parameters to Persistent depend on
cannam@49: # the realm, which is orthogonal to the interface type and therefore should not be defined
cannam@49: # along-side it.
cannam@49: #
cannam@49: # You may also apply this annotation to a capability-typed field which will always contain a
cannam@49: # persistent capability, but where the capability's interface itself is not already marked
cannam@49: # persistent.
cannam@49: #
cannam@49: # Note that absence of the $persistent annotation doesn't mean a capability of that type isn't
cannam@49: # persistent; it just means not *all* such capabilities are persistent.