Improve readme/docs

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 [email protected] 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).

Cargo.toml

@@ -1,8 +1,14 @@
 [package]
 name = "rustls-native-certs"
 version = "0.1.0"
-authors = ["Joseph Birr-Pixton <[email protected]>"]
 edition = "2018"
+authors = ["Joseph Birr-Pixton <[email protected]>"]
+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"

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<rustls::RootCertStore, std::io::Error>
+```
+
+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.
-