README.md
1THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHORS DISCLAIM ALL WARRANTIES WITH
2REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
3AND FITNESS. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY SPECIAL, DIRECT,
4INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
5LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
6OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
7PERFORMANCE OF THIS SOFTWARE.
8
9
10
11untrusted.rs
12============
13
14Safe, fast, zero-panic, zero-crashing, zero-allocation parsing of untrusted
15inputs in Rust.
16
17untrusted.rs is 100% Rust with no use of `unsafe`. It never uses the heap.
18No part of untrusted.rs's API will ever panic or cause a crash. It is
19`#![no_std]` and so it works perfectly with both libcore- and libstd- based
20projects. It does not depend on any crates other than libcore.
21
22untrusted.rs is intended to be used with the latest version of Rust Stable.
23It should usually work with the latest Rust Beta and Rust Nightly versions
24too. Using a version of untrusted.rs other than the latest release available
25on crates.io is not recommended.
26
27
28
29Documentation
30-------------
31
32See the documentation at
33https://briansmith.org/rustdoc/untrusted/.
34
35To use untrusted.rs in your project, add a dependency to your
36Cargo.toml like this:
37
38```
39[dependencies]
40untrusted = "0.2"
41```
42
43
44
45Examples
46--------
47
48[*ring*](https://github.com/briansmith/ring)'s parser for the subset of ASN.1
49DER it needs to understand,
50[`ring::der`](https://github.com/briansmith/ring/blob/master/src/der.rs), is
51built on top of untrusted.rs. *ring* also uses untrusted.rs to parse ECC public
52keys, RSA PKCS#1 1.5 padding, and everything else.
53
54All of [webpki](https://github.com/briansmith/webpki)'s parsing of X.509
55certificates (also ASN.1 DER) is done using untrusted.rs.
56
57
58
59Contributing
60------------
61
62Patches welcome!
63
64When contributing changes, state that you agree to license your contribution
65under the same terms as the existing code by putting this at the bottom of your
66commit message:
67
68```
69
70I agree to license my contributions to each file under the terms given
71at the top of each file I changed.
72```
73
74Currently, the biggest needs for this library are:
75
76* Unit tests.
77* Documentation.
78* More examples.
79* Static analysis and fuzzing.
80
81
82
83Online Automated Testing
84------------------------
85
86Travis CI is used for Android, Linux, and Mac OS X. The tests are run for the
87current release of each Rust channel (Stable, Beta, Nightly). Since
88untrusted.rs only depends on libcore and it only uses 100% cross-platform code
89without using `unsafe`, it should work anywhere as long as these platforms are
90passing.
91
92<a title="Build Status" href=https://travis-ci.org/briansmith/untrusted><img src=https://travis-ci.org/briansmith/untrusted.svg?branch=master></a>
93
94
95
96Bug Reporting
97-------------
98
99Please report bugs either as pull requests or as issues in [the issue
100tracker](https://github.com/briansmith/untrusted/issues). untrusted.rs has a
101**full disclosure** vulnerability policy. **Please do NOT attempt to report
102any security vulnerability in this code privately to anybody.**
103
104
105
106License
107-------
108
109See [LICENSE.txt](LICENSE.txt), an ISC-style (simplified MIT) license.
110
