navcore_signalk_client/

trust.rs

//! Deciding which server is the boat's.
//!
//! # Why not the public certificate authorities
//!
//! A boat's server has no public name and no route to a public authority:
//! it answers to `something.local` on a network with no internet behind it,
//! so nothing like Let's Encrypt can ever vouch for it. The usual reflex is
//! a self-signed certificate plus a client that accepts any certificate,
//! and that combination is worse than it looks. It encrypts, so it feels
//! safe, but it authenticates nothing: a client that accepts anything
//! cannot tell the boat's server from whatever else answers on that
//! address, and the first thing it does after connecting is hand over a
//! bearer token good for a year.
//!
//! So the boat runs an authority of its own instead. One key, kept ashore,
//! signs the server's certificate; every device that should trust the boat
//! carries the authority's certificate -- public, harmless to copy. A
//! device then knows it is talking to *this* boat before it sends anything,
//! and adding a device means installing one file rather than weakening a
//! check.
//!
//! # Why the public roots are left out entirely
//!
//! [`Trust::boat_ca`] builds a store containing the boat's authority and
//! nothing else. Keeping the public roots alongside it would mean any of
//! several hundred authorities could also vouch for a server here, which is
//! a much larger surface than the one thing this is trying to establish.
//!
//! # Plain text is a decision, not a default
//!
//! [`Trust::plaintext`] exists for a server that has no TLS at all, which
//! is still the common case in the Signal K world. It carries an empty
//! store rather than a permissive one: point it at a `wss://` URL and the
//! handshake fails, loudly, instead of quietly accepting a stranger.

use std::sync::Arc;

use crate::ClientError;

/// Which servers this client is willing to believe.
#[derive(Clone)]
pub struct Trust {
    /// The accepted authorities, in DER. Empty for plain text.
    authorities: Arc<Vec<Vec<u8>>>,
}

impl Trust {
    /// No certificate is expected. For `http://` and `ws://` servers.
    ///
    /// A TLS server offered to this is refused, whatever it presents.
    #[must_use]
    pub fn plaintext() -> Self {
        Self {
            authorities: Arc::new(Vec::new()),
        }
    }

    /// Trust only servers whose certificate the boat's own authority
    /// signed.
    ///
    /// `pem` is the authority's certificate -- `boat-ca.crt`, the public
    /// half. Several may be concatenated, which is what makes replacing an
    /// authority possible without taking every device out of service on the
    /// same afternoon: carry both for one season, then drop the old one.
    ///
    /// # Errors
    ///
    /// If the PEM holds no certificate at all. A file that was truncated,
    /// or a private key handed over by mistake, has to fail here rather
    /// than produce a client that trusts nothing and blames the network.
    pub fn boat_ca(pem: &[u8]) -> Result<Self, ClientError> {
        let mut reader = std::io::BufReader::new(pem);
        let authorities: Vec<Vec<u8>> = rustls_pemfile::certs(&mut reader)
            .filter_map(Result::ok)
            .map(|der| der.to_vec())
            .collect();

        if authorities.is_empty() {
            return Err(ClientError::Trust(
                "no certificate in the authority file".to_owned(),
            ));
        }

        Ok(Self {
            authorities: Arc::new(authorities),
        })
    }

    /// Whether anything is trusted, i.e. whether TLS can succeed at all.
    #[must_use]
    pub fn is_plaintext(&self) -> bool {
        self.authorities.is_empty()
    }

    /// The authorities as rustls wants them, for the WebSocket.
    pub(crate) fn rustls_config(&self) -> Result<Arc<rustls::ClientConfig>, ClientError> {
        let mut roots = rustls::RootCertStore::empty();
        for der in self.authorities.iter() {
            roots
                .add(rustls::pki_types::CertificateDer::from(der.clone()))
                .map_err(|error| ClientError::Trust(error.to_string()))?;
        }

        // The provider is named rather than taken from process-wide state.
        // A library that installed a default would be making a decision on
        // behalf of whatever else links it, and one that read a default
        // would depend on load order to work.
        let provider = Arc::new(rustls::crypto::ring::default_provider());
        let config = rustls::ClientConfig::builder_with_provider(provider)
            .with_safe_default_protocol_versions()
            .map_err(|error| ClientError::Trust(error.to_string()))?
            .with_root_certificates(roots)
            .with_no_client_auth();

        Ok(Arc::new(config))
    }

    /// The authorities as ureq wants them, for the REST calls.
    pub(crate) fn ureq_certificates(&self) -> Vec<ureq::tls::Certificate<'static>> {
        self.authorities
            .iter()
            .map(|der| ureq::tls::Certificate::from_der(der).to_owned())
            .collect()
    }
}

impl std::fmt::Debug for Trust {
    /// Says how much is trusted, never what. A certificate is not a secret,
    /// but a log line full of DER helps nobody read a failure.
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        if self.is_plaintext() {
            write!(f, "Trust(plaintext)")
        } else {
            write!(f, "Trust({} authorities)", self.authorities.len())
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    /// A real certificate, so the parsing is tested against the thing it
    /// will meet rather than against a shape invented here.
    const CA_PEM: &str = include_str!("../tests/data/test-ca.crt");

    #[test]
    fn an_authority_is_read_from_pem() {
        let trust = Trust::boat_ca(CA_PEM.as_bytes()).expect("a certificate");
        assert!(!trust.is_plaintext());
        assert_eq!(trust.ureq_certificates().len(), 1);
        assert!(trust.rustls_config().is_ok());
    }

    #[test]
    fn several_authorities_can_be_carried_at_once() {
        // How an authority is replaced without a flag day: trust both for a
        // season, then drop the old one.
        let both = format!("{CA_PEM}{CA_PEM}");
        let trust = Trust::boat_ca(both.as_bytes()).expect("two certificates");
        assert_eq!(trust.ureq_certificates().len(), 2);
    }

    #[test]
    fn a_file_with_no_certificate_is_an_error() {
        // A truncated file, or a private key handed over by mistake. Both
        // would otherwise produce a client that trusts nothing and blames
        // the network for it.
        assert!(Trust::boat_ca(b"not a certificate").is_err());
        assert!(Trust::boat_ca(b"").is_err());
    }

    #[test]
    fn plaintext_trusts_nothing_rather_than_everything() {
        let trust = Trust::plaintext();
        assert!(trust.is_plaintext());
        assert!(trust.ureq_certificates().is_empty());
        // Still builds a config -- with an empty root store, so a TLS
        // server offered to it is refused instead of accepted.
        assert!(trust.rustls_config().is_ok());
    }
}