From 97d3f12709fec2554caae400d45903f752b5ec19 Mon Sep 17 00:00:00 2001 From: Joseph Birr-Pixton Date: Tue, 15 Oct 2019 23:23:06 +0100 Subject: [PATCH] Improve readme/docs --- CONTRIBUTING.md | 51 ++++++++++++++++++++++++++++++++++++++++++++++++ Cargo.toml | 8 +++++++- README.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++--- 3 files changed, 107 insertions(+), 4 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..c97ccb2 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,51 @@ +# Contributing + +Thanks for considering helping this project. There are many +ways you can help: using the library and reporting bugs, +reporting usability issues, making additions and improvements +to the library, documentation and finding security bugs. + +## Reporting bugs + +Please file a github issue. Include as much information as +possible. Suspected protocol bugs are easier debugged with +a pcap or reproduction steps. + +Feel free to file github issues to get help, or ask a question. + +## Code changes + +Some ideas and guidelines for contributions: + +- For large features, file an issue prior to starting work. + This means everyone can see what is in progress prior to a PR. +- Feel free to submit a PR even if the work is not totally finished, + for feedback or to hand-over. +- Prefer not to reference github issue or PR numbers in commits. +- Try to keep code formatting commits separate from functional commits. +- I run `cargo outdated` prior to major releases; but PRs to update specific + dependencies are welcome. + +## Security bugs + +Please report security bugs by filing a github issue, or by +email to jbp@jbp.io if you want to disclose privately. I'll then: + +- Prepare a fix and regression tests. +- Backport the fix and make a patch release for most recent release. +- Submit an advisory to [rustsec/advisory-db](https://github.com/RustSec/advisory-db). +- Refer to the advisory on the main README.md and release notes. + +## Testing + +- Features involving additions to the public API should have (at least) + API-level tests (see [`tests/api.rs`](tests/api.rs)). +- Protocol additions should have some coverage -- consider enabling + corresponding tests in the bogo suite, or writing some adhoc tests. + +PRs which cause test failures or a significant coverage decrease +are unlikely to be accepted. + +## Licensing + +Contributions are made under [rustls-native-certs's licenses](LICENSE). diff --git a/Cargo.toml b/Cargo.toml index 9c33ac4..f10f37a 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,8 +1,14 @@ [package] name = "rustls-native-certs" version = "0.1.0" -authors = ["Joseph Birr-Pixton "] edition = "2018" +authors = ["Joseph Birr-Pixton "] +license = "Apache-2.0/ISC/MIT" +readme = "README.md" +description = "rustls-native-certs allows rustls to use the platform native certificate store" +homepage = "https://github.com/ctz/rustls-native-certs" +repository = "https://github.com/ctz/rustls-native-certs" +categories = ["network-programming", "cryptography"] [dependencies] rustls = "0.16.0" diff --git a/README.md b/README.md index 2404ff3..c8cf3d6 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,56 @@ +![Logo](https://raw.githubusercontent.com/ctz/rustls/master/admin/rustls-logo-web.png) -Nothing here yet. +**rustls-native-certs** allows [rustls](https://github.com/ctz/rustls) to use the +platform's native certificate store when operating as a TLS client. + +This is supported on Windows, macOS and Linux: + +- On Windows, certificates are loaded from the system certificate store. + The [`schannel`](https://github.com/steffengy/schannel-rs) crate is used to access + the Windows certificate store APIs. +- On macOS, certificates are loaded from the keychain. + The user, admin and system trust settings are merged together as documented + by Apple. The [`security-framework`](https://github.com/kornelski/rust-security-framework) + crate is used to access the keystore APIs. +- On Linux and other UNIX-like operating systems, the + [`openssl-probe`](https://github.com/alexcrichton/openssl-probe) crate is used to discover + the filename of the system CA bundle. + +# Status +rustls-native-certs is currently in development. + +If you'd like to help out, please see [CONTRIBUTING.md](CONTRIBUTING.md). + +[![Build Status](https://dev.azure.com/ctz99/ctz/_apis/build/status/ctz.rustls-native-certs?branchName=master)](https://dev.azure.com/ctz99/ctz/_build/latest?definitionId=5&branchName=master) + +## Release history: + +* Next release: + - Initial release. + +# API + +This library exposes a single function with this signature: + +```rust +pub fn load_native_certs() -> Result +``` + +On success, this returns a `rustls::RootCertStore` loaded with a snapshop of the +root certificates found on this platform. This function fails in a platform-specific +way, expressed in a `std::io::Error`. + +This function can be expensive: on UNIX-like platforms (although not macOS) this involves +reading and parsing a ~300KB text file. It is prudent, then, to call this function +sparingly. + +# Example + +(...) # License -Rustls is distributed under the following three licenses: +rustls-native-certs is distributed under the following three licenses: - Apache License version 2.0. - MIT license. @@ -12,4 +59,3 @@ Rustls is distributed under the following three licenses: These are included as LICENSE-APACHE, LICENSE-MIT and LICENSE-ISC respectively. You may use this software under the terms of any of these licenses, at your option. -