Skip to main content

passalong_ssh/
host_key.rs

1//! Strict server host key pinning: the server's key must equal the
2//! configured one. There is no trust-on-first-use and no `known_hosts`
3//! fallback.
4
5use russh::keys::{HashAlg, PublicKey};
6
7use crate::error::SshError;
8
9/// The server public key from `server.ssh.host_key`.
10#[derive(Debug, Clone)]
11pub struct PinnedHostKey {
12    key: PublicKey,
13}
14
15impl PinnedHostKey {
16    /// Parses an OpenSSH public key line such as `ssh-ed25519 AAAA… comment`.
17    /// A leading host field, as printed by `ssh-keyscan`, is tolerated.
18    ///
19    /// # Errors
20    ///
21    /// [`SshError::InvalidHostKey`] when no public key can be read.
22    pub fn parse(line: &str) -> Result<Self, SshError> {
23        let line = line.trim();
24        let key = PublicKey::from_openssh(line)
25            .or_else(|first| match line.split_once(char::is_whitespace) {
26                Some((_, rest)) if !rest.trim().is_empty() => {
27                    PublicKey::from_openssh(rest.trim()).map_err(|_| first)
28                }
29                _ => Err(first),
30            })
31            .map_err(|err| {
32                SshError::InvalidHostKey(format!(
33                    "expected an OpenSSH public key such as `ssh-ed25519 AAAA...` ({err})"
34                ))
35            })?;
36        #[cfg(not(feature = "rsa"))]
37        if key.algorithm().is_rsa() {
38            return Err(SshError::RsaUnsupported {
39                what: "server.ssh.host_key".to_owned(),
40            });
41        }
42        Ok(Self { key })
43    }
44
45    /// Whether `presented` is this key. Comments are ignored.
46    pub fn matches(&self, presented: &PublicKey) -> bool {
47        self.key.key_data() == presented.key_data()
48    }
49
50    /// The key's SHA-256 fingerprint, as `ssh-keygen -l` prints it.
51    pub fn fingerprint(&self) -> String {
52        fingerprint(&self.key)
53    }
54}
55
56/// SHA-256 fingerprint of any public key.
57pub(crate) fn fingerprint(key: &PublicKey) -> String {
58    key.fingerprint(HashAlg::Sha256).to_string()
59}
60
61/// A server host key seen during discovery, not yet trusted.
62#[derive(Debug, Clone, PartialEq, Eq)]
63pub struct DiscoveredKey {
64    /// The key as an OpenSSH `type base64` line, ready for
65    /// `server.ssh.host_key`.
66    pub openssh_line: String,
67    /// SHA-256 fingerprint, as `ssh-keygen -l` prints it.
68    pub fingerprint: String,
69    /// Algorithm name, such as `ssh-ed25519`.
70    pub algorithm: String,
71}
72
73impl DiscoveredKey {
74    pub(crate) fn from_key(key: &PublicKey) -> Result<Self, SshError> {
75        let line = key.to_openssh().map_err(|err| {
76            SshError::InvalidHostKey(format!("cannot encode the server's key: {err}"))
77        })?;
78        // Keep `type base64` only; a comment is meaningless for a host key.
79        let openssh_line = line
80            .split_whitespace()
81            .take(2)
82            .collect::<Vec<_>>()
83            .join(" ");
84        Ok(Self {
85            openssh_line,
86            fingerprint: fingerprint(key),
87            algorithm: key.algorithm().as_str().to_owned(),
88        })
89    }
90}
91
92#[cfg(test)]
93pub(crate) mod tests {
94    use super::*;
95    use crate::error::SshError;
96
97    // Throwaway public keys generated for these tests; public keys are not secrets.
98    pub const KEY_A: &str = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIF2M9DqIpW9GMebpvjNg+bobwAbQKRBqPVMatyvyI4gq passalong-test-a";
99    pub const KEY_B: &str = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIMKy9BQGg0B6NYvYwyrJzGCOHCXKQBj7E/5jvWJSEDCi passalong-test-b";
100    pub const KEY_C: &str = "ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBDjE+RqfPVU1q3oRZ0A7kEGVjiycIFrzmrvdTMY9XxA5RwiwmWJ1Ra9XgfC5jOjwYXCvbge0k6d0MwNVN8fH/Rg= passalong-test-c";
101    const KEY_A_FINGERPRINT: &str = "SHA256:5Si4lWKPwa0+I2wCQf3eOtcF8jWo30BWybHoXLTxABo";
102    pub const KEY_RSA: &str = "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCc20+WNqOOyD5NLL1a8IdPRt24TG6uZkCYiCtewTNxHslQawoxE/Z0njaK8Xs2Bqsd0eEGhw2cnnMqXHlNVfWHQ3NhfBe5BXGZSin2dEVZw2nlEfI5Y2uEEVBFTir7EodMI/pJwqPEFZELPC4nm70XjDRDXBvwZDEwrzF1S/5NXZ6Xa4LG/9UOsq05C5bIlqR32/GBBfLWi8PThy1LTg6u4EJE1ovHz4xWQBGCLc/eFnwxePRrMSI1RYQzZ3u6RuCiGXmCsKba7BxaRt5/lEb1PKTPTyi50Y03mcrG4kxA2NXGFH4FAp4T7ICw9JL1z6yXwdWreWjKq9mERVctMLcL passalong-test-rsa";
103    #[cfg(feature = "rsa")]
104    const KEY_RSA_FINGERPRINT: &str = "SHA256:LY/lOwQzQWODS5oQTLX9+HhSPwqy6sX7OY+mTMZV+2w";
105
106    fn public(line: &str) -> russh::keys::PublicKey {
107        russh::keys::PublicKey::from_openssh(line).unwrap()
108    }
109
110    #[test]
111    fn parses_openssh_key_lines_with_or_without_a_comment() {
112        let pinned = PinnedHostKey::parse(KEY_A).unwrap();
113        assert_eq!(pinned.fingerprint(), KEY_A_FINGERPRINT);
114        let bare = KEY_A.rsplit_once(' ').unwrap().0;
115        assert_eq!(
116            PinnedHostKey::parse(bare).unwrap().fingerprint(),
117            KEY_A_FINGERPRINT
118        );
119        assert_eq!(
120            PinnedHostKey::parse(&format!("  {bare}\n"))
121                .unwrap()
122                .fingerprint(),
123            KEY_A_FINGERPRINT
124        );
125    }
126
127    #[test]
128    fn accepts_ssh_keyscan_output_with_its_host_prefix() {
129        let line = format!("[192.168.1.10]:2222 {KEY_A}");
130        assert_eq!(
131            PinnedHostKey::parse(&line).unwrap().fingerprint(),
132            KEY_A_FINGERPRINT
133        );
134        let line = format!("192.168.1.10 {}", KEY_C);
135        assert!(PinnedHostKey::parse(&line).is_ok());
136    }
137
138    #[test]
139    fn matches_only_the_same_key_whatever_its_comment() {
140        let pinned = PinnedHostKey::parse(KEY_A).unwrap();
141        let recommented = KEY_A.replace("passalong-test-a", "someone@else");
142        assert!(pinned.matches(&public(&recommented)));
143        assert!(!pinned.matches(&public(KEY_B)), "different ed25519 key");
144        assert!(!pinned.matches(&public(KEY_C)), "different key type");
145    }
146
147    #[test]
148    fn rejects_anything_that_is_not_a_public_key() {
149        for bad in [
150            "",
151            "   ",
152            "ssh-ed25519",
153            "ssh-ed25519 not*base64",
154            "AAAAC3NzaC1lZDI1NTE5",
155            "host ssh-ed25519",
156            "a b c d",
157        ] {
158            match PinnedHostKey::parse(bad) {
159                Err(SshError::InvalidHostKey(_)) => {}
160                other => panic!("{bad:?}: {other:?}"),
161            }
162        }
163    }
164
165    #[test]
166    fn a_discovered_key_carries_its_line_fingerprint_and_algorithm() {
167        let found = DiscoveredKey::from_key(&public(KEY_A)).unwrap();
168        assert_eq!(found.fingerprint, KEY_A_FINGERPRINT);
169        assert_eq!(found.algorithm, "ssh-ed25519");
170        assert!(
171            found.openssh_line.starts_with("ssh-ed25519 AAAA"),
172            "{}",
173            found.openssh_line
174        );
175        assert_eq!(
176            PinnedHostKey::parse(&found.openssh_line)
177                .unwrap()
178                .fingerprint(),
179            KEY_A_FINGERPRINT
180        );
181        let ecdsa = DiscoveredKey::from_key(&public(KEY_C)).unwrap();
182        assert_eq!(ecdsa.algorithm, "ecdsa-sha2-nistp256");
183    }
184
185    #[cfg(not(feature = "rsa"))]
186    #[test]
187    fn rsa_host_keys_need_the_rsa_feature() {
188        match PinnedHostKey::parse(KEY_RSA) {
189            Err(err @ SshError::RsaUnsupported { .. }) => {
190                let message = err.to_string();
191                assert!(message.starts_with("server.ssh.host_key: "), "{message}");
192                assert!(message.contains("--features rsa"), "{message}");
193            }
194            other => panic!("unexpected {other:?}"),
195        }
196    }
197
198    #[cfg(feature = "rsa")]
199    #[test]
200    fn rsa_host_keys_parse_with_the_rsa_feature() {
201        assert_eq!(
202            PinnedHostKey::parse(KEY_RSA).unwrap().fingerprint(),
203            KEY_RSA_FINGERPRINT
204        );
205    }
206}