aboutsummaryrefslogtreecommitdiffstats
path: root/erts/doc/src
diff options
context:
space:
mode:
authorJayson Vantuyl <[email protected]>2010-01-05 17:37:18 -0800
committerBjörn Gustavsson <[email protected]>2010-01-08 14:37:12 +0100
commit77ce185291b73438b7987587c0871041e5a66d83 (patch)
tree7022044d901cde9f9dce1e4d056566df226a559e /erts/doc/src
parentfbdeb03d3919b096e039302801e2e865267a6943 (diff)
downloadotp-77ce185291b73438b7987587c0871041e5a66d83.tar.gz
otp-77ce185291b73438b7987587c0871041e5a66d83.tar.bz2
otp-77ce185291b73438b7987587c0871041e5a66d83.zip
add options to binary_to_term
term_to_binary and binary_to_term are powerful tools that can be used easily in lieu of a custom binary network protocol. Unfortunately, carefully crafted data can be used to exhaust the memory in an Erlang node by merely attempting to decode binaries. This makes it unsafe to receive data from untrusted sources. This is possible because binary_to_term/1 will allocate new atoms and new external function references. These data structures are not garbage collected. This patch implements the new form of binary_to_term that takes a list of options, and a simple option called 'safe'. If specified, this option will cause decoding to fail with a badarg error if an atom or external function reference would be allocated. In the general case, it will happily decode any Erlang term other than those containing new atoms or new external function references. However, fun, pid, and ref data types can embed atoms. They might fail to decode if one of these embedded atoms is new to the node. This may be an issue if encoded binaries are transferred between nodes or persisted between invocations of Erlang.
Diffstat (limited to 'erts/doc/src')
-rw-r--r--erts/doc/src/erlang.xml46
1 files changed, 44 insertions, 2 deletions
diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml
index 871fc0fd63..2541aa700b 100644
--- a/erts/doc/src/erlang.xml
+++ b/erts/doc/src/erlang.xml
@@ -342,8 +342,50 @@ iolist() = [char() | binary() | iolist()]
<desc>
<p>Returns an Erlang term which is the result of decoding
the binary object <c>Binary</c>, which must be encoded
- according to the Erlang external term format. See also
- <seealso marker="#term_to_binary/1">term_to_binary/1</seealso>.</p>
+ according to the Erlang external term format.</p>
+ <warning>
+ <p>When decoding binaries from untrusted sources, consider using
+ <c>binary_to_term/2</c> to prevent denial of service attacks.</p>
+ </warning>
+ <p>See also
+ <seealso marker="#term_to_binary/1">term_to_binary/1</seealso>
+ and
+ <seealso marker="#binary_to_term/2">binary_to_term/2</seealso>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:binary_to_term(Binary, Opts) -> term()</name>
+ <fsummary>Decode an Erlang external term format binary</fsummary>
+ <type>
+ <v>Opts = [safe]</v>
+ <v>Binary = ext_binary()</v>
+ </type>
+ <desc>
+ <p>As <c>binary_to_term/1</c>, but takes options that affect decoding
+ of the binary.</p>
+ <taglist>
+ <tag><c>safe</c></tag>
+ <item>
+ <p>Use this option when receiving binaries from an untrusted
+ source.</p>
+ <p>When enabled, it prevents decoding data that may be used to
+ attack the Erlang system. In the event of receiving unsafe
+ data, decoding fails with a badarg error.</p>
+ <p>Currently, this prevents creation of new atoms directly,
+ creation of new atoms indirectly (as they are embedded in
+ certain structures like pids, refs, funs, etc.), and creation of
+ new external function references. None of those resources are
+ currently garbage collected, so unchecked creation of them can
+ exhaust available memory.</p>
+ </item>
+ </taglist>
+ <p>Failure: <c>badarg</c> if <c>safe</c> is specified and unsafe data
+ is decoded.</p>
+ <p>See also
+ <seealso marker="#term_to_binary/1">term_to_binary/1</seealso>,
+ <seealso marker="#binary_to_term/1">binary_to_term/1</seealso>,
+ and <seealso marker="#list_to_existing_atom/1">
+ list_to_existing_atom/1</seealso>.</p>
</desc>
</func>
<func>