From b49fa0c82c30112ab9e01e4504215e69e979d457 Mon Sep 17 00:00:00 2001 From: Marc Brinkmann Date: Thu, 13 Aug 2020 10:43:10 +0200 Subject: [PATCH 1/2] 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. --- readme.md | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/readme.md b/readme.md index cf282a36..67e58530 100644 --- a/readme.md +++ b/readme.md @@ -68,3 +68,41 @@ 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. Beware that in the Rust ecosystem, for a `0.x` version, any change +in `x` is considered a **major** version change. + +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 oder 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 availble (`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 an +security issues in your application, provided the configuration is changed to enable a +maximum size limit. Malicious inputs will fail upon deserialization. From 699069abffd3884b315e6d697425afff2e9293cd Mon Sep 17 00:00:00 2001 From: Marc Brinkmann Date: Thu, 13 Aug 2020 12:43:10 +0200 Subject: [PATCH 2/2] Fix typos in `readme.md` --- readme.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/readme.md b/readme.md index 67e58530..97b95e94 100644 --- a/readme.md +++ b/readme.md @@ -90,19 +90,19 @@ 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 oder file headers, as these +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 availble (`bincode::config::Bounded`), but not enabled in the +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 an +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.