docs/security.rst

   1 ======================
   2 Nanopb: Security model
   3 ======================
   4
   5 .. include :: menu.rst
   6
   7 .. contents ::
   8
   9
  10
  11 Importance of security in a Protocol Buffers library
  12 ====================================================
  13 In the context of protocol buffers, security comes into play when decoding
  14 untrusted data. Naturally, if the attacker can modify the contents of a
  15 protocol buffers message, he can feed the application any values possible.
  16 Therefore the application itself must be prepared to receive untrusted values.
  17
  18 Where nanopb plays a part is preventing the attacker from running arbitrary
  19 code on the target system. Mostly this means that there must not be any
  20 possibility to cause buffer overruns, memory corruption or invalid pointers
  21 by the means of crafting a malicious message.
  22
  23 Division of trusted and untrusted data
  24 ======================================
  25 The following data is regarded as **trusted**. It must be under the control of
  26 the application writer. Malicious data in these structures could cause
  27 security issues, such as execution of arbitrary code:
  28
  29 1. Callback, pointer and extension fields in message structures given to
  30    pb_encode() and pb_decode(). These fields are memory pointers, and are
  31    generated depending on the message definition in the .proto file.
  32 2. The automatically generated field definitions, i.e. *pb_field_t* lists.
  33 3. 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
  36 The following data is regarded as **untrusted**. Invalid/malicious data in
  37 these will cause "garbage in, garbage out" behaviour. It will not cause
  38 buffer overflows, information disclosure or other security problems:
  39
  40 1. All data read from *pb_istream_t*.
  41 2. All fields in message structures, except callbacks, pointers and extensions.
  42    (Beginning with nanopb-0.2.4, in earlier versions the field sizes are partially unchecked.)
  43
  44 Invariants
  45 ==========
  46 The following invariants are maintained during operation, even if the
  47 untrusted data has been maliciously crafted:
  48
  49 1. Nanopb will never read more than *bytes_left* bytes from *pb_istream_t*.
  50 2. Nanopb will never write more than *max_size* bytes to *pb_ostream_t*.
  51 3. Nanopb will never access memory out of bounds of the message structure.
  52 4. 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
  59 5. 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
  63 Further considerations
  64 ======================
  65 Even if the nanopb library is free of any security issues, there are still
  66 several possible attack vectors that the application author must consider.
  67 The following list is not comprehensive:
  68
  69 1. 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.
  73 2. Callbacks can do anything. The code for the callbacks must be carefully
  74    checked if they are used with untrusted data.
  75 3. 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.
  77 4. If using network sockets as streams, a timeout should be set to stop
  78    denial of service attacks.
  79 5. If using *malloc()* support, some method of limiting memory use should be
  80    employed. This can be done by defining custom *pb_realloc()* function.
  81    Nanopb will properly detect and handle failed memory allocations.