cannam@149: // Copyright (c) 2015 Sandstorm Development Group, Inc. and contributors cannam@149: // Licensed under the MIT License: cannam@149: // cannam@149: // Permission is hereby granted, free of charge, to any person obtaining a copy cannam@149: // of this software and associated documentation files (the "Software"), to deal cannam@149: // in the Software without restriction, including without limitation the rights cannam@149: // to use, copy, modify, merge, publish, distribute, sublicense, and/or sell cannam@149: // copies of the Software, and to permit persons to whom the Software is cannam@149: // furnished to do so, subject to the following conditions: cannam@149: // cannam@149: // The above copyright notice and this permission notice shall be included in cannam@149: // all copies or substantial portions of the Software. cannam@149: // cannam@149: // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR cannam@149: // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, cannam@149: // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE cannam@149: // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER cannam@149: // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, cannam@149: // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN cannam@149: // THE SOFTWARE. cannam@149: cannam@149: #ifndef CAPNP_MEMBRANE_H_ cannam@149: #define CAPNP_MEMBRANE_H_ cannam@149: // In capability theory, a "membrane" is a wrapper around a capability which (usually) forwards cannam@149: // calls but recursively wraps capabilities in those calls in the same membrane. The purpose of a cannam@149: // membrane is to enforce a barrier between two capabilities that cannot be bypassed by merely cannam@149: // introducing new objects. cannam@149: // cannam@149: // The most common use case for a membrane is revocation: Say Alice wants to give Bob a capability cannam@149: // to access Carol, but wants to be able to revoke this capability later. Alice can accomplish this cannam@149: // by wrapping Carol in a revokable wrapper which passes through calls until such a time as Alice cannam@149: // indicates it should be revoked, after which all calls through the wrapper will throw exceptions. cannam@149: // However, a naive wrapper approach has a problem: if Bob makes a call to Carol and sends a new cannam@149: // capability in that call, or if Carol returns a capability to Bob in the response to a call, then cannam@149: // the two are now able to communicate using this new capability, which Alice cannot revoke. In cannam@149: // order to avoid this problem, Alice must use not just a wrapper but a "membrane", which cannam@149: // recursively wraps all objects that pass through it in either direction. Thus, all connections cannam@149: // formed between Bob and Carol (originating from Alice's original introduction) can be revoked cannam@149: // together by revoking the membrane. cannam@149: // cannam@149: // Note that when a capability is passed into a membrane and then passed back out, the result is cannam@149: // the original capability, not a double-membraned capability. This means that in our revocation cannam@149: // example, if Bob uses his capability to Carol to obtain another capability from her, then send cannam@149: // it back to her, the capability Carol receives back will NOT be revoked when Bob's access to cannam@149: // Carol is revoked. Thus Bob can create long-term irrevocable connections. In most practical use cannam@149: // cases, this is what you want. APIs commonly rely on the fact that a capability obtained and then cannam@149: // passed back can be recognized as the original capability. cannam@149: // cannam@149: // Mark Miller on membranes: http://www.eros-os.org/pipermail/e-lang/2003-January/008434.html cannam@149: cannam@149: #include "capability.h" cannam@149: cannam@149: namespace capnp { cannam@149: cannam@149: class MembranePolicy { cannam@149: // Applications may implement this interface to define a membrane policy, which allows some cannam@149: // calls crossing the membrane to be blocked or redirected. cannam@149: cannam@149: public: cannam@149: virtual kj::Maybe inboundCall( cannam@149: uint64_t interfaceId, uint16_t methodId, Capability::Client target) = 0; cannam@149: // Given an inbound call (a call originating "outside" the membrane destined for an object cannam@149: // "inside" the membrane), decides what to do with it. The policy may: cannam@149: // cannam@149: // - Return null to indicate that the call should proceed to the destination. All capabilities cannam@149: // in the parameters or result will be properly wrapped in the same membrane. cannam@149: // - Return a capability to have the call redirected to that capability. Note that the redirect cannam@149: // capability will be treated as outside the membrane, so the params and results will not be cannam@149: // auto-wrapped; however, the callee can easily wrap the returned capability in the membrane cannam@149: // itself before returning to achieve this effect. cannam@149: // - Throw an exception to cause the call to fail with that exception. cannam@149: // cannam@149: // `target` is the underlying capability (*inside* the membrane) for which the call is destined. cannam@149: // Generally, the only way you should use `target` is to wrap it in some capability which you cannam@149: // return as a redirect. The redirect capability may modify the call in some way and send it to cannam@149: // `target`. Be careful to use `copyIntoMembrane()` and `copyOutOfMembrane()` as appropriate when cannam@149: // copying parameters or results across the membrane. cannam@149: // cannam@149: // Note that since `target` is inside the capability, if you were to directly return it (rather cannam@149: // than return null), the effect would be that the membrane would be broken: the call would cannam@149: // proceed directly and any new capabilities introduced through it would not be membraned. You cannam@149: // generally should not do that. cannam@149: cannam@149: virtual kj::Maybe outboundCall( cannam@149: uint64_t interfaceId, uint16_t methodId, Capability::Client target) = 0; cannam@149: // Like `inboundCall()`, but applies to calls originating *inside* the membrane and terminating cannam@149: // outside. cannam@149: // cannam@149: // Note: It is strongly recommended that `outboundCall()` returns null in exactly the same cases cannam@149: // that `inboundCall()` return null. Conversely, for any case where `inboundCall()` would cannam@149: // redirect or throw, `outboundCall()` should also redirect or throw. Otherwise, you can run cannam@149: // into inconsistent behavion when a promise is returned across a membrane, and that promise cannam@149: // later resolves to a capability on the other side of the membrane: calls on the promise cannam@149: // will enter and then exit the membrane, but calls on the eventual resolution will not cross cannam@149: // the membrane at all, so it is important that these two cases behave the same. cannam@149: cannam@149: virtual kj::Own addRef() = 0; cannam@149: // Return a new owned pointer to the same policy. cannam@149: // cannam@149: // Typically an implementation of MembranePolicy should also inherit kj::Refcounted and implement cannam@149: // `addRef()` as `return kj::addRef(*this);`. cannam@149: // cannam@149: // Note that the membraning system considers two membranes created with the same MembranePolicy cannam@149: // object actually to be the *same* membrane. This is relevant when an object passes into the cannam@149: // membrane and then back out (or out and then back in): instead of double-wrapping the object, cannam@149: // the wrapping will be removed. cannam@149: }; cannam@149: cannam@149: Capability::Client membrane(Capability::Client inner, kj::Own policy); cannam@149: // Wrap `inner` in a membrane specified by `policy`. `inner` is considered "inside" the membrane, cannam@149: // while the returned capability should only be called from outside the membrane. cannam@149: cannam@149: Capability::Client reverseMembrane(Capability::Client outer, kj::Own policy); cannam@149: // Like `membrane` but treat the input capability as "outside" the membrane, and return a cannam@149: // capability appropriate for use inside. cannam@149: // cannam@149: // Applications typically won't use this directly; the membraning code automatically sets up cannam@149: // reverse membranes where needed. cannam@149: cannam@149: template cannam@149: ClientType membrane(ClientType inner, kj::Own policy); cannam@149: template cannam@149: ClientType reverseMembrane(ClientType inner, kj::Own policy); cannam@149: // Convenience templates which return the same interface type as the input. cannam@149: cannam@149: template cannam@149: typename ServerType::Serves::Client membrane( cannam@149: kj::Own inner, kj::Own policy); cannam@149: template cannam@149: typename ServerType::Serves::Client reverseMembrane( cannam@149: kj::Own inner, kj::Own policy); cannam@149: // Convenience templates which input a capability server type and return the appropriate client cannam@149: // type. cannam@149: cannam@149: template cannam@149: Orphan::Reads> copyIntoMembrane( cannam@149: Reader&& from, Orphanage to, kj::Own policy); cannam@149: // Copy a Cap'n Proto object (e.g. struct or list), adding the given membrane to any capabilities cannam@149: // found within it. `from` is interpreted as "outside" the membrane while `to` is "inside". cannam@149: cannam@149: template cannam@149: Orphan::Reads> copyOutOfMembrane( cannam@149: Reader&& from, Orphanage to, kj::Own policy); cannam@149: // Like copyIntoMembrane() except that `from` is "inside" the membrane and `to` is "outside". cannam@149: cannam@149: // ======================================================================================= cannam@149: // inline implementation details cannam@149: cannam@149: template cannam@149: ClientType membrane(ClientType inner, kj::Own policy) { cannam@149: return membrane(Capability::Client(kj::mv(inner)), kj::mv(policy)) cannam@149: .castAs(); cannam@149: } cannam@149: template cannam@149: ClientType reverseMembrane(ClientType inner, kj::Own policy) { cannam@149: return reverseMembrane(Capability::Client(kj::mv(inner)), kj::mv(policy)) cannam@149: .castAs(); cannam@149: } cannam@149: cannam@149: template cannam@149: typename ServerType::Serves::Client membrane( cannam@149: kj::Own inner, kj::Own policy) { cannam@149: return membrane(Capability::Client(kj::mv(inner)), kj::mv(policy)) cannam@149: .castAs(); cannam@149: } cannam@149: template cannam@149: typename ServerType::Serves::Client reverseMembrane( cannam@149: kj::Own inner, kj::Own policy) { cannam@149: return reverseMembrane(Capability::Client(kj::mv(inner)), kj::mv(policy)) cannam@149: .castAs(); cannam@149: } cannam@149: cannam@149: namespace _ { // private cannam@149: cannam@149: OrphanBuilder copyOutOfMembrane(PointerReader from, Orphanage to, cannam@149: kj::Own policy, bool reverse); cannam@149: OrphanBuilder copyOutOfMembrane(StructReader from, Orphanage to, cannam@149: kj::Own policy, bool reverse); cannam@149: OrphanBuilder copyOutOfMembrane(ListReader from, Orphanage to, cannam@149: kj::Own policy, bool reverse); cannam@149: cannam@149: } // namespace _ (private) cannam@149: cannam@149: template cannam@149: Orphan::Reads> copyIntoMembrane( cannam@149: Reader&& from, Orphanage to, kj::Own policy) { cannam@149: return _::copyOutOfMembrane( cannam@149: _::PointerHelpers::Reads>::getInternalReader(from), cannam@149: to, kj::mv(policy), true); cannam@149: } cannam@149: cannam@149: template cannam@149: Orphan::Reads> copyOutOfMembrane( cannam@149: Reader&& from, Orphanage to, kj::Own policy) { cannam@149: return _::copyOutOfMembrane( cannam@149: _::PointerHelpers::Reads>::getInternalReader(from), cannam@149: to, kj::mv(policy), false); cannam@149: } cannam@149: cannam@149: } // namespace capnp cannam@149: cannam@149: #endif // CAPNP_MEMBRANE_H_