persistent.capnp (7288B)
1 # Copyright (c) 2014 Sandstorm Development Group, Inc. and contributors 2 # Licensed under the MIT License: 3 # 4 # Permission is hereby granted, free of charge, to any person obtaining a copy 5 # of this software and associated documentation files (the "Software"), to deal 6 # in the Software without restriction, including without limitation the rights 7 # to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 8 # copies of the Software, and to permit persons to whom the Software is 9 # furnished to do so, subject to the following conditions: 10 # 11 # The above copyright notice and this permission notice shall be included in 12 # all copies or substantial portions of the Software. 13 # 14 # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 15 # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 16 # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 17 # AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 18 # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 19 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 20 # THE SOFTWARE. 21 22 @0xb8630836983feed7; 23 24 $import "/capnp/c++.capnp".namespace("capnp"); 25 26 interface Persistent@0xc8cb212fcd9f5691(SturdyRef, Owner) { 27 # Interface implemented by capabilities that outlive a single connection. A client may save() 28 # the capability, producing a SturdyRef. The SturdyRef can be stored to disk, then later used to 29 # obtain a new reference to the capability on a future connection. 30 # 31 # The exact format of SturdyRef depends on the "realm" in which the SturdyRef appears. A "realm" 32 # is an abstract space in which all SturdyRefs have the same format and refer to the same set of 33 # resources. Every vat is in exactly one realm. All capability clients within that vat must 34 # produce SturdyRefs of the format appropriate for the realm. 35 # 36 # Similarly, every VatNetwork also resides in a particular realm. Usually, a vat's "realm" 37 # corresponds to the realm of its main VatNetwork. However, a Vat can in fact communicate over 38 # a VatNetwork in a different realm -- in this case, all SturdyRefs need to be transformed when 39 # coming or going through said VatNetwork. The RPC system has hooks for registering 40 # transformation callbacks for this purpose. 41 # 42 # Since the format of SturdyRef is realm-dependent, it is not defined here. An application should 43 # choose an appropriate realm for itself as part of its design. Note that under Sandstorm, every 44 # application exists in its own realm and is therefore free to define its own SturdyRef format; 45 # the Sandstorm platform handles translating between realms. 46 # 47 # Note that whether a capability is persistent is often orthogonal to its type. In these cases, 48 # the capability's interface should NOT inherit `Persistent`; instead, just perform a cast at 49 # runtime. It's not type-safe, but trying to be type-safe in these cases will likely lead to 50 # tears. In cases where a particular interface only makes sense on persistent capabilities, it 51 # still should not explicitly inherit Persistent because the `SturdyRef` and `Owner` types will 52 # vary between realms (they may even be different at the call site than they are on the 53 # implementation). Instead, mark persistent interfaces with the $persistent annotation (defined 54 # below). 55 # 56 # Sealing 57 # ------- 58 # 59 # As an added security measure, SturdyRefs may be "sealed" to a particular owner, such that 60 # if the SturdyRef itself leaks to a third party, that party cannot actually restore it because 61 # they are not the owner. To restore a sealed capability, you must first prove to its host that 62 # you are the rightful owner. The precise mechanism for this authentication is defined by the 63 # realm. 64 # 65 # Sealing is a defense-in-depth mechanism meant to mitigate damage in the case of catastrophic 66 # attacks. For example, say an attacker temporarily gains read access to a database full of 67 # SturdyRefs: it would be unfortunate if it were then necessary to revoke every single reference 68 # in the database to prevent the attacker from using them. 69 # 70 # In general, an "owner" is a course-grained identity. Because capability-based security is still 71 # the primary mechanism of security, it is not necessary nor desirable to have a separate "owner" 72 # identity for every single process or object; that is exactly what capabilities are supposed to 73 # avoid! Instead, it makes sense for an "owner" to literally identify the owner of the machines 74 # where the capability is stored. If untrusted third parties are able to run arbitrary code on 75 # said machines, then the sandbox for that code should be designed using Distributed Confinement 76 # such that the third-party code never sees the bits of the SturdyRefs and cannot directly 77 # exercise the owner's power to restore refs. See: 78 # 79 # http://www.erights.org/elib/capability/dist-confine.html 80 # 81 # Resist the urge to represent an Owner as a simple public key. The whole point of sealing is to 82 # defend against leaked-storage attacks. Such attacks can easily result in the owner's private 83 # key being stolen as well. A better solution is for `Owner` to contain a simple globally unique 84 # identifier for the owner, and for everyone to separately maintain a mapping of owner IDs to 85 # public keys. If an owner's private key is compromised, then humans will need to communicate 86 # and agree on a replacement public key, then update the mapping. 87 # 88 # As a concrete example, an `Owner` could simply contain a domain name, and restoring a SturdyRef 89 # would require signing a request using the domain's private key. Authenticating this key could 90 # be accomplished through certificate authorities or web-of-trust techniques. 91 92 save @0 SaveParams -> SaveResults; 93 # Save a capability persistently so that it can be restored by a future connection. Not all 94 # capabilities can be saved -- application interfaces should define which capabilities support 95 # this and which do not. 96 97 struct SaveParams { 98 sealFor @0 :Owner; 99 # Seal the SturdyRef so that it can only be restored by the specified Owner. This is meant 100 # to mitigate damage when a SturdyRef is leaked. See comments above. 101 # 102 # Leaving this value null may or may not be allowed; it is up to the realm to decide. If a 103 # realm does allow a null owner, this should indicate that anyone is allowed to restore the 104 # ref. 105 } 106 struct SaveResults { 107 sturdyRef @0 :SturdyRef; 108 } 109 } 110 111 annotation persistent(interface, field) :Void; 112 # Apply this annotation to interfaces for objects that will always be persistent, instead of 113 # extending the Persistent capability, since the correct type parameters to Persistent depend on 114 # the realm, which is orthogonal to the interface type and therefore should not be defined 115 # along-side it. 116 # 117 # You may also apply this annotation to a capability-typed field which will always contain a 118 # persistent capability, but where the capability's interface itself is not already marked 119 # persistent. 120 # 121 # Note that absence of the $persistent annotation doesn't mean a capability of that type isn't 122 # persistent; it just means not *all* such capabilities are persistent.