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.