1# Nanopb: Security model
2
3Importance of security in a Protocol Buffers library
4----------------------------------------------------
5
6In the context of protocol buffers, security comes into play when
7decoding untrusted data. Naturally, if the attacker can modify the
8contents of a protocol buffers message, he can feed the application any
9values possible. Therefore the application itself must be prepared to
10receive untrusted values.
11
12Where nanopb plays a part is preventing the attacker from running
13arbitrary code on the target system. Mostly this means that there must
14not be any possibility to cause buffer overruns, memory corruption or
15invalid pointers by the means of crafting a malicious message.
16
17Division of trusted and untrusted data
18--------------------------------------
19
20The following data is regarded as **trusted**. It must be under the
21control of the application writer. Malicious data in these structures
22could cause security issues, such as execution of arbitrary code:
23
241.  Callback, pointer and extension fields in message structures given
25    to pb_encode() and pb_decode(). These fields are memory pointers,
26    and are generated depending on the message definition in the .proto
27    file.
282.  The automatically generated field definitions, i.e.
29    `pb_msgdesc_t`.
303.  Contents of the `pb_istream_t` and `pb_ostream_t` structures
31    (this does not mean the contents of the stream itself, just the
32    stream definition).
33
34The following data is regarded as **untrusted**. Invalid/malicious data
35in these will cause "garbage in, garbage out" behaviour. It will not
36cause buffer overflows, information disclosure or other security
37problems:
38
391.  All data read from `pb_istream_t`.
402.  All fields in message structures, except:
41    -   callbacks (`pb_callback_t` structures)
42    -   pointer fields and `_count` fields for pointers
43    -   extensions (`pb_extension_t` structures)
44
45Invariants
46----------
47
48The following invariants are maintained during operation, even if the
49untrusted data has been maliciously crafted:
50
511.  Nanopb will never read more than `bytes_left` bytes from
52    `pb_istream_t`.
532.  Nanopb will never write more than `max_size` bytes to
54    `pb_ostream_t`.
553.  Nanopb will never access memory out of bounds of the message
56    structure.
574.  After `pb_decode()` returns successfully, the message structure will
58    be internally consistent:
59    -   The `count` fields of arrays will not exceed the array size.
60    -   The `size` field of bytes will not exceed the allocated size.
61    -   All string fields will have null terminator.
62    -   bool fields will have valid true/false values (since
63        nanopb-0.3.9.4)
64    -   pointer fields will be either `NULL` or point to valid data
655.  After `pb_encode()` returns successfully, the resulting message is a
66    valid protocol buffers message. (Except if user-defined callbacks
67    write incorrect data.)
686.  All memory allocated by `pb_decode()` will be released by a subsequent
69    call to `pb_release()` on the same message.
70
71Further considerations
72----------------------
73
74Even if the nanopb library is free of any security issues, there are
75still several possible attack vectors that the application author must
76consider. The following list is not comprehensive:
77
781.  Stack usage may depend on the contents of the message. The message
79    definition places an upper bound on how much stack will be used.
80    Tests should be run with all fields present, to record the maximum
81    possible stack usage.
822.  Callbacks can do anything. The code for the callbacks must be
83    carefully checked if they are used with untrusted data.
843.  If using stream input, a maximum size should be set in
85    `pb_istream_t` to stop a denial of service attack from using an
86    infinite message.
874.  If using network sockets as streams, a timeout should be set to stop
88    denial of service attacks.
895.  If using `malloc()` support, some method of limiting memory use
90    should be employed. This can be done by defining custom
91    `pb_realloc()` function. Nanopb will properly detect and handle
92    failed memory allocations.
93