From 99f22a3755f74fedc8bc20505446a9e52ba56a7a Mon Sep 17 00:00:00 2001 From: Marc Brinkmann Date: Tue, 23 Feb 2021 14:42:24 +0100 Subject: [PATCH] Address questions regarding suitability for storage and untrusted inputs (#346) * Address questions regarding suitability for storage and untrusted inputs Puts some prominent text into the `readme.md` regarding some use cases that are likely to be common, along with a few hopefully helpful pointers to avoid footguns. Closes #345, closes #216, addresses #240, #266. * Fix typos in `readme.md` * Remove confusing sentence post 1.0, as requested --- README.md | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/README.md b/README.md index cf282a3..d743843 100644 --- a/README.md +++ b/README.md @@ -68,3 +68,40 @@ However, there are some implementation details to be aware of: `u32` is enough for all practical uses. * `str` is encoded as `(u64, &[u8])`, where the `u64` is the number of bytes contained in the encoded string. + +## Specification + +Bincode's format will eventually be codified into a specification, along with +its configuration options and default configuration. In the meantime, here are +some frequently asked questions regarding use of the crate: + +### Is Bincode suitable for storage? + +The encoding format is stable across minor revisions, provided the same +configuration is used. This should ensure that later versions can still read +data produced by a previous versions of the library if no major version change +has occured. + +Bincode is invariant over byte-order in the default configuration +(`bincode::options::DefaultOptions`), making an exchange between different +architectures possible. It is also rather space efficient, as it stores no +metadata like struct field names in the output format and writes long streams of +binary data without needing any potentially size-increasing encoding. + +As a result, Bincode is suitable for storing data. Be aware that it does not +implement any sort of data versioning scheme or file headers, as these +features are outside the scope of this crate. + +### Is Bincode suitable for untrusted inputs? + +Bincode attempts to protect against hostile data. There is a maximum size +configuration available (`bincode::config::Bounded`), but not enabled in the +default configuration. Enabling it causes pre-allocation size to be limited to +prevent against memory exhaustion attacks. + +Deserializing any incoming data will not cause undefined behavior or memory +issues, assuming that the deserialization code for the struct is safe itself. + +Bincode can be used for untrusted inputs in the sense that it will not create a +security issues in your application, provided the configuration is changed to enable a +maximum size limit. Malicious inputs will fail upon deserialization.