mirror of https://git.sr.ht/~stygianentity/bincode
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
This commit is contained in:
parent
5d6dfa1fb9
commit
99f22a3755
37
README.md
37
README.md
|
|
@ -68,3 +68,40 @@ However, there are some implementation details to be aware of:
|
||||||
`u32` is enough for all practical uses.
|
`u32` is enough for all practical uses.
|
||||||
* `str` is encoded as `(u64, &[u8])`, where the `u64` is the number of
|
* `str` is encoded as `(u64, &[u8])`, where the `u64` is the number of
|
||||||
bytes contained in the encoded string.
|
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.
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue