1====================== 2Nanopb: Security model 3====================== 4 5.. include :: menu.rst 6 7.. contents :: 8 9 10 11Importance of security in a Protocol Buffers library 12==================================================== 13In the context of protocol buffers, security comes into play when decoding 14untrusted data. Naturally, if the attacker can modify the contents of a 15protocol buffers message, he can feed the application any values possible. 16Therefore the application itself must be prepared to receive untrusted values. 17 18Where nanopb plays a part is preventing the attacker from running arbitrary 19code on the target system. Mostly this means that there must not be any 20possibility to cause buffer overruns, memory corruption or invalid pointers 21by the means of crafting a malicious message. 22 23Division of trusted and untrusted data 24====================================== 25The following data is regarded as **trusted**. It must be under the control of 26the application writer. Malicious data in these structures could cause 27security issues, such as execution of arbitrary code: 28 291. Callback and extension fields in message structures given to pb_encode() 30 and pb_decode(). These fields are memory pointers, and are generated 31 depending on the .proto file. 322. The automatically generated field definitions, i.e. *pb_field_t* lists. 333. Contents of the *pb_istream_t* and *pb_ostream_t* structures (this does not 34 mean the contents of the stream itself, just the stream definition). 35 36The following data is regarded as **untrusted**. Invalid/malicious data in 37these will cause "garbage in, garbage out" behaviour. It will not cause 38buffer overflows, information disclosure or other security problems: 39 401. All data read from *pb_istream_t*. 412. All fields in message structures, except callbacks and extensions. 42 (Beginning with nanopb-0.2.4, in earlier versions the field sizes are partially unchecked.) 43 44Invariants 45========== 46The following invariants are maintained during operation, even if the 47untrusted data has been maliciously crafted: 48 491. Nanopb will never read more than *bytes_left* bytes from *pb_istream_t*. 502. Nanopb will never write more than *max_size* bytes to *pb_ostream_t*. 513. Nanopb will never access memory out of bounds of the message structure. 524. After pb_decode() returns successfully, the message structure will be 53 internally consistent: 54 55 - The *count* fields of arrays will not exceed the array size. 56 - The *size* field of bytes will not exceed the allocated size. 57 - All string fields will have null terminator. 58 595. After pb_encode() returns successfully, the resulting message is a valid 60 protocol buffers message. (Except if user-defined callbacks write incorrect 61 data.) 62 63Further considerations 64====================== 65Even if the nanopb library is free of any security issues, there are still 66several possible attack vectors that the application author must consider. 67The following list is not comprehensive: 68 691. Stack usage may depend on the contents of the message. The message 70 definition places an upper bound on how much stack will be used. Tests 71 should be run with all fields present, to record the maximum possible 72 stack usage. 732. Callbacks can do anything. The code for the callbacks must be carefully 74 checked if they are used with untrusted data. 753. If using stream input, a maximum size should be set in *pb_istream_t* to 76 stop a denial of service attack from using an infinite message. 774. If using network sockets as streams, a timeout should be set to stop 78 denial of service attacks. 79 80