From d57c1143bb26ddb8e1d13422f83a2df6750eb520 Mon Sep 17 00:00:00 2001 From: nworbnhoj Date: Mon, 11 Sep 2023 09:35:49 +1000 Subject: [PATCH] TLS doco --- libs/tls/README.md | 41 ++++++++++++++++++++++++++++++++++++++ libs/tls/src/lib.rs | 48 ++++++++++++++++++++++++++++++++++++--------- 2 files changed, 80 insertions(+), 9 deletions(-) create mode 100644 libs/tls/README.md diff --git a/libs/tls/README.md b/libs/tls/README.md new file mode 100644 index 000000000..a0dda3812 --- /dev/null +++ b/libs/tls/README.md @@ -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 ` will initiate a modified tls handshake with ``, obtain the certificate chain offered by ``, 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 ` will attempt a normal tls handshake with `` 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 `. 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 ` +- 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 🤷 diff --git a/libs/tls/src/lib.rs b/libs/tls/src/lib.rs index 8f34bd601..a32798cec 100644 --- a/libs/tls/src/lib.rs +++ b/libs/tls/src/lib.rs @@ -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 { 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 { 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 { 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) {