faq.md (11993B)
1 --- 2 layout: page 3 title: FAQ 4 --- 5 6 # FAQ 7 8 ## Design 9 10 ### Isn't I/O bandwidth more important than CPU usage? Is Cap'n Proto barking up the wrong tree? 11 12 It depends. What is your use case? 13 14 Are you communicating between two processes on the same machine? If so, you have unlimited 15 bandwidth, and you should be entirely concerned with CPU. 16 17 Are you communicating between two machines within the same datacenter? If so, it's unlikely that 18 you will saturate your network connection before your CPU. Possible, but unlikely. 19 20 Are you communicating across the general internet? In that case, bandwidth is probably your main 21 concern. Luckily, Cap'n Proto lets you choose to enable "packing" in this case, achieving similar 22 encoding size to Protocol Buffers while still being faster. And you can always add extra 23 compression on top of that. 24 25 ### Have you considered building the RPC system on ZeroMQ? 26 27 ZeroMQ (and its successor, Nanomsg) is a powerful technology for distributed computing. Its 28 design focuses on scenarios involving lots of stateless, fault-tolerant worker processes 29 communicating via various patterns, such as request/response, produce/consume, and 30 publish/subscribe. For big data processing where armies of stateless nodes make sense, pairing 31 Cap'n Proto with ZeroMQ would be an excellent choice -- and this is easy to do today, as ZeroMQ 32 is entirely serialization-agnostic. 33 34 That said, Cap'n Proto RPC takes a very different approach. Cap'n Proto's model focuses on 35 stateful servers interacting in complex, object-oriented ways. The model is better suited to 36 tasks involving applications with many heterogeneous components and interactions between 37 mutually-distrusting parties. Requests and responses can go in any direction. Objects have 38 state and so two calls to the same object had best go to the same machine. Load balancing and 39 fault tolerance is pushed up the stack, because without a large pool of homogeneous work there's 40 just no way to make them transparent at a low level. 41 42 Put concretely, you might build a search engine indexing pipeline on ZeroMQ, but an online 43 interactive spreadsheet editor would be better built on Cap'n Proto RPC. 44 45 (Actually, a distributed programming framework providing similar features to ZeroMQ could itself be 46 built on top of Cap'n Proto RPC.) 47 48 ### Aren't messages that contain pointers a huge security problem? 49 50 Not at all. Cap'n Proto bounds-checks each pointer when it is read and throws an exception or 51 returns a safe dummy value (your choice) if the pointer is out-of-bounds. 52 53 ### So it's not that you've eliminated parsing, you've just moved it to happen lazily? 54 55 No. Compared to Protobuf decoding, the time spent validating pointers while traversing a Cap'n 56 Proto message is negligible. 57 58 ### I think I heard somewhere that capability-based security doesn't work? 59 60 This was a popular myth in security circles way back in the 80's and 90's, based on an incomplete 61 understanding of what capabilities are and how to use them effectively. Read 62 [Capability Myths Demolished](http://zesty.ca/capmyths/usenix.pdf). (No really, read it; 63 it's awesome.) 64 65 ## Usage 66 67 ### How do I make a field "required", like in Protocol Buffers? 68 69 You don't. You may find this surprising, but the "required" keyword in Protocol Buffers turned 70 out to be a horrible mistake. 71 72 For background, in protocol buffers, a field could be marked "required" to indicate that parsing 73 should fail if the sender forgot to set the field before sending the message. Required fields were 74 encoded exactly the same as optional ones; the only difference was the extra validation. 75 76 The problem with this is, validation is sometimes more subtle than that. Sometimes, different 77 applications -- or different parts of the same application, or different versions of the same 78 application -- place different requirements on the same protocol. An application may want to 79 pass around partially-complete messages internally. A particular field that used to be required 80 might become optional. A new use case might call for almost exactly the same message type, minus 81 one field, at which point it may make more sense to reuse the type than to define a new one. 82 83 A field declared required, unfortunately, is required everywhere. The validation is baked into 84 the parser, and there's nothing you can do about it. Nothing, that is, except change the field 85 from "required" to "optional". But that's where the _real_ problems start. 86 87 Imagine a production environment in which two servers, Alice and Bob, exchange messages through a 88 message bus infrastructure running on a big corporate network. The message bus parses each message 89 just to examine the envelope and decide how to route it, without paying attention to any other 90 content. Often, messages from various applications are batched together and then split up again 91 downstream. 92 93 Now, at some point, Alice's developers decide that one of the fields in a deeply-nested message 94 commonly sent to Bob has become obsolete. To clean things up, they decide to remove it, so they 95 change the field from "required" to "optional". The developers aren't idiots, so they realize that 96 Bob needs to be updated as well. They make the changes to Bob, and just to be thorough they 97 run an integration test with Alice and Bob running in a test environment. The test environment 98 is always running the latest build of the message bus, but that's irrelevant anyway because the 99 message bus doesn't actually care about message contents; it only does routing. Protocols are 100 modified all the time without updating the message bus. 101 102 Satisfied with their testing, the devs push a new version of Alice to prod. Immediately, 103 everything breaks. And by "everything" I don't just mean Alice and Bob. Completely unrelated 104 servers are getting strange errors or failing to receive messages. The whole data center has 105 ground to a halt and the sysadmins are running around with their hair on fire. 106 107 What happened? Well, the message bus running in prod was still an older build from before the 108 protocol change. And even though the message bus doesn't care about message content, it _does_ 109 need to parse every message just to read the envelope. And the protobuf parser checks the _entire_ 110 message for missing required fields. So when Alice stopped sending that newly-optional field, the 111 whole message failed to parse, envelope and all. And to make matters worse, any other messages 112 that happened to be in the same batch _also_ failed to parse, causing errors in seemingly-unrelated 113 systems that share the bus. 114 115 Things like this have actually happened. At Google. Many times. 116 117 The right answer is for applications to do validation as-needed in application-level code. If you 118 want to detect when a client fails to set a particular field, give the field an invalid default 119 value and then check for that value on the server. Low-level infrastructure that doesn't care 120 about message content should not validate it at all. 121 122 Oh, and also, Cap'n Proto doesn't have any parsing step during which to check for required 123 fields. :) 124 125 ### How do I make a field optional? 126 127 Cap'n Proto has no notion of "optional" fields. 128 129 A primitive field always takes space on the wire whether you set it or not (although default-valued 130 fields will be compressed away if you enable packing). Such a field can be made semantically 131 optional by placing it in a union with a `Void` field: 132 133 {% highlight capnp %} 134 union { 135 age @0 :Int32; 136 ageUnknown @1 :Void; 137 } 138 {% endhighlight %} 139 140 However, this field still takes space on the wire, and in fact takes an extra 16 bits of space 141 for the union tag. A better approach may be to give the field a bogus default value and interpret 142 that value to mean "not present". 143 144 Pointer fields are a bit different. They start out "null", and you can check for nullness using 145 the `hasFoo()` accessor. You could use a null pointer to mean "not present". Note, though, that 146 calling `getFoo()` on a null pointer returns the default value, which is indistinguishable from a 147 legitimate value, so checking `hasFoo()` is in fact the _only_ way to detect nullness. 148 149 ### How do I resize a list? 150 151 Unfortunately, you can't. You have to know the size of your list upfront, before you initialize 152 any of the elements. This is an annoying side effect of arena allocation, which is a fundamental 153 part of Cap'n Proto's design: in order to avoid making a copy later, all of the pieces of the 154 message must be allocated in a tightly-packed segment of memory, with each new piece being added 155 to the end. If a previously-allocated piece is discarded, it leaves a hole, which wastes space. 156 Since Cap'n Proto lists are flat arrays, the only way to resize a list would be to discard the 157 existing list and allocate a new one, which would thus necessarily waste space. 158 159 In theory, a more complicated memory allocation algorithm could attempt to reuse the "holes" left 160 behind by discarded message pieces. However, it would be hard to make sure any new data inserted 161 into the space is exactly the right size. Fragmentation would result. And the allocator would 162 have to do a lot of extra bookkeeping that could be expensive. This would be sad, as arena 163 allocation is supposed to be cheap! 164 165 The only solution is to temporarily place your data into some other data structure (an 166 `std::vector`, perhaps) until you know how many elements you have, then allocate the list and copy. 167 On the bright side, you probably aren't losing much performance this way -- using vectors already 168 involves making copies every time the backing array grows. It's just annoying to code. 169 170 Keep in mind that you can use [orphans](cxx.html#orphans) to allocate sub-objects before you have 171 a place to put them. But, also note that you cannot allocate elements of a struct list as orphans 172 and then put them together as a list later, because struct lists are encoded as a flat array of 173 struct values, not an array of pointers to struct values. You can, however, allocate any inner 174 objects embedded within those structs as orphans. 175 176 ## Security 177 178 ### Is Cap'n Proto secure? 179 180 What is your threat model? 181 182 ### Sorry. Can Cap'n Proto be used to deserialize malicious messages? 183 184 Cap'n Proto's serialization layer is designed to be safe against malicious input. The Cap'n Proto implementation should never segfault, corrupt memory, leak secrets, execute attacker-specified code, consume excessive resources, etc. as a result of any sequence of input bytes. Moreover, the API is carefully designed to avoid putting app developers into situations where it is easy to write insecure code -- we consider it a bug in Cap'n Proto if apps commonly misuse it in a way that is a security problem. 185 186 With all that said, Cap'n Proto's C++ reference implementation has not yet undergone a formal security review. It may have bugs. 187 188 ### Is it safe to use Cap'n Proto RPC with a malicious peer? 189 190 Cap'n Proto's RPC layer is explicitly designed to be useful for interactions between mutually-distrusting parties. Its capability-based security model makes it easy to express complex interactions securely. 191 192 At this time, the RPC layer is not robust against resource exhaustion attacks, possibly allowing denials of service. 193 194 ### Is Cap'n Proto encrypted? 195 196 Cap'n Proto may be layered on top of an existing encrypted transport, such as TLS, but at this time it is the application's responsibility to add this layer. We plan to integrate this into the Cap'n Proto library proper in the future. 197 198 ### How do I report security bugs? 199 200 Please email [security@sandstorm.io](mailto:security@sandstorm.io). 201 202 ## Sandstorm 203 204 ### How does Cap'n Proto relate to Sandstorm.io? 205 206 [Sandstorm.io](https://sandstorm.io) is an Open Source project and startup founded by Kenton, the author of Cap'n Proto. Cap'n Proto is owned and developed by Sandstorm the company and heavily used in Sandstorm the project. 207 208 ### How does Sandstorm use Cap'n Proto? 209 210 See [this Sandstorm blog post](https://blog.sandstorm.io/news/2014-12-15-capnproto-0.5.html). 211