berkus
/
bincode
mirror of https://git.sr.ht/~stygianentity/bincode
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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:
Marc Brinkmann 2021-02-23 14:42:24 +01:00 committed by GitHub
parent 5d6dfa1fb9
commit 99f22a3755
1 changed files with 37 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

37
README.md
View File

@ -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.