This commit is contained in:
nworbnhoj 2023-09-11 09:35:49 +10:00
parent 8ab3aa85be
commit d57c1143bb
2 changed files with 80 additions and 9 deletions

41
libs/tls/README.md Normal file
View file

@ -0,0 +1,41 @@
== TLS ==
A tls library focused on explicitly trusting Certificate Authority Certificates (requires `--feature tls`).
Typically, operating systems and browsers embed a list of implicitly trusted Root CA certificates.
The tls handshake involves the host offering the client a Certificate signed for authenticity by a CA, with a chain of signatures back to a Root CA. If the client trusts at least one Certificate in this chain of trust, then the handshake may progress to an encrypted connection.
It does not seem in keeping with the Precursor/Xous idea to ask users to trust any such list of Root CA Certificates.
This tls library enables the user to obtain and save trusted CA certificates to the PDDB as a personalised set of trusted Root CA certificates on which to establish a tls connection. This can be as simple for the user as responding to a modal, when making a first connection to an as yet un-trusted host. Just a couple of clicks. The developer need only call `Tls::check_trust()`.
Note that hosts with self-signed Certificates may be probed and trusted (e.g. [chat.signal.org](https://chat.signal.org))
A small set of shellchat commands are included to enact the base functionality:
- `net tls probe <host>` will initiate a modified tls handshake with `<host>`, obtain the certificate chain offered by `<host>`, and immediately terminate the connection. A call to Tls::check_trust() will present the CA certificate chain in a modal to be individually selected and saved to PDDB if trusted.
- `net tls test <host>` will attempt a normal tls handshake with `<host>` based on the trusted Root CA certificates in the PDDB. If the connection is successful, then a simple `get` is emitted, the response accepted, and the connection closed.
- `net tls mozilla` trusts and saves all Root CA's in the [webpki-roots crate](https://crates.io/crates/webpki-roots) - which contains Mozilla's root certificates. (requires `--feature rootCA`)
- `net list` lists all trusted certificates in the PDDB
- `net deleteall` deletes all trusted certificates in the PDDB
These functions are gated by 2 feature flags:
- `tls` includes [der](https://crates.io/crates/der), [ring](https://crates.io/crates/ring) (local patch), [rustls](https://crates.io/crates/rustls), [webpki](https://crates.io/crates/webpki) & [x509-parser](https://crates.io/crates/x509-parser)
- `rootCA` includes the [webpki-roots crate](https://crates.io/crates/webpki-roots)
In keeping with `rustls` & `webpki`, only the critical components of each x509-Certificate are stored in the PDDB under the `tls.trusted` dictionary - as a `rkyv` archive of a `tls::RustTlsOwnedTrustAuthority` object.
The rustls [dangerous_configuration](https://github.com/betrusted-io/xous-core/pull/394/commits/4ea0c8457de8f855723af76546b6ecb7e54661f7) feature is required to modify the tls handshake during a `net tls probe <host>`. This is because, by default, `rustls` drops the connection (and certificate chain) if there is no match to a trusted Root CA Certificate in the `RootStore`. During a `probe` we need to briefly trust all CA certificates in order to get hold of the CA certificate chain, and inspect it.
The shellchat `net tls` commands are are called from `services/shellchat/src/cmds/net_cmd.rs`, but located in `libs/tls/src/cmd.rs` in order to contain the size of `services/shellchat/src/cmds/net_cmd.rs` and to keep the tls cmds close to the implementation.
Native `pddb` calls are used throuought (`std::fs` free)
Considerations:
- there is an outstanding **issue** where the `checkbox` modal does not display options with multiple lines correctly. This impacts the display of fingerprints for some certificates with longer subjects.
- It may be worth considering rendering public `pddb::KEY_NAME_LEN` to allow developer to avoid sending overly long key's which will be rejected by the pddb.
- probably need a shellchat `net tls delete <cert>`
- some broken code is included for a future fix if required [RustlsOwnedTrustAnchor::publik_key()](https://github.com/betrusted-io/xous-core/pull/394/commits/4e0298c17ad2c51aa220a88dc69bf2f56e51076f)
- some hosts (eg bunnyfoo.com) emit an `unexpected eof` error during tls handshake 🤷

View file

@ -31,9 +31,17 @@ impl Tls {
}
}
// presents a modal to the user to select trusted tls certificates
// and saves the selected certificates to the pddb
// returns a count of trusted certificates
/// Presents a modal to the user to select trusted tls certificates
/// and saves the selected certificates to the pddb
///
/// # Arguments
///
/// * `certificates` - the certificates to be presented
///
/// # Returns
///
/// a count of trusted certificates
///
pub fn check_trust(&self, certificates: &[Certificate]) -> usize {
let xns = XousNames::new().unwrap();
let modals = Modals::new(&xns).unwrap();
@ -92,8 +100,12 @@ impl Tls {
}
}
// deletes ALL tls trust-anchors from the pddb
// returns the number of certs deleted
/// Deletes ALL tls trust-anchors from the pddb
///
/// # Returns
///
/// the number of trust-anchors deleted
///
pub fn del_all_cert(&self) -> Result<usize, Error> {
let count = match self.pddb.list_keys(TLS_TRUSTED_DICT, None) {
Ok(list) => list.len(),
@ -116,7 +128,12 @@ impl Tls {
Ok(count)
}
// deletes a tls trust-anchor from the pddb
/// Deletes a tls trust-anchor from the pddb
///
/// # Arguments
///
/// * `key` - the pddb-key containing the unwanted trust-anchor
///
pub fn del_cert(&self, key: &str) -> Result<(), Error> {
match self.pddb.delete_key(TLS_TRUSTED_DICT, key, None) {
Ok(_) => {
@ -131,7 +148,12 @@ impl Tls {
return Ok(());
}
// saves a tls trust-anchor to the pddb
/// Saves a tls trust-anchor to the pddb
///
/// # Arguments
///
/// * `ta` - a trusted trust-anchor
///
pub fn save_cert(&self, ta: &RustlsOwnedTrustAnchor) -> Result<(), Error> {
let key = ta.pddb_key();
match self.pddb.get(
@ -175,8 +197,12 @@ impl Tls {
Ok(())
}
// retrieves a tls trust-anchor from the pddb
/// Returns a tls trust-anchor from the pddb
///
/// # Arguments
///
/// * `key` - pddb key holding the trust-anchor
///
pub fn get_cert(&self, key: &str) -> Option<RustlsOwnedTrustAnchor> {
match self.pddb.get(
TLS_TRUSTED_DICT,
@ -215,6 +241,8 @@ impl Tls {
}
}
/// Returns a Vec of all trusted trust-anchors
///
pub fn trusted(&self) -> Vec<RustlsOwnedTrustAnchor> {
match self.pddb.list_keys(TLS_TRUSTED_DICT, None) {
Ok(list) => list
@ -229,6 +257,8 @@ impl Tls {
}
}
/// Returns a RootCertStore containing all trusted trust-anchors
///
pub fn root_store(&self) -> RootCertStore {
let mut root_store = RootCertStore::empty();
match self.pddb.list_keys(TLS_TRUSTED_DICT, None) {