use std::net::SocketAddr;
use std::sync::OnceLock;
use std::time::Duration;
use tokio::io::{AsyncReadExt, AsyncWriteExt};
use tokio::net::TcpStream;
use tokio::time::timeout;
use crate::config::limits::CONNECT_PROBE_TIMEOUT;
use crate::model::tls::{
CipherSuite, Interruption, TlsSupport, TlsVersion, UnfinishedVersion, VersionSupport,
};
use crate::protocols::tls::{self, Offer, RECORD_HEADER_LEN, ServerResponse};
use crate::system::descriptors;
use crate::transport::dial::Egress;
use crate::{info, warn};
pub const MAX_OFFERS_PER_VERSION: usize = CipherSuite::MOST_OFFERED_UNDER_ONE_VERSION;
pub const EXCHANGE_TIMEOUT: Duration = Duration::from_secs(2);
const RETRY_PAUSES: [Duration; 2] = [Duration::from_millis(250), Duration::from_secs(1)];
pub async fn enumerate_tls(addr: SocketAddr) -> TlsSupport {
enumerate_tls_while(addr, Egress::KERNEL, || true).await
}
pub(crate) async fn enumerate_tls_while(
addr: SocketAddr,
egress: Egress,
may_probe: impl Fn() -> bool,
) -> TlsSupport {
let may_probe = &may_probe;
let control = OnceLock::new();
let control = &control;
let (ssl30, tls10, tls11, tls12, tls13) = tokio::join!(
walk(addr, egress, TlsVersion::Ssl30, control, may_probe),
walk(addr, egress, TlsVersion::Tls10, control, may_probe),
walk(addr, egress, TlsVersion::Tls11, control, may_probe),
walk(addr, egress, TlsVersion::Tls12, control, may_probe),
walk(addr, egress, TlsVersion::Tls13, control, may_probe),
);
let mut support = TlsSupport::new();
for (found, unfinished) in [ssl30, tls10, tls11, tls12, tls13] {
if let Some(found) = found {
support.record(found);
}
if let Some(unfinished) = unfinished {
support.record_unfinished(unfinished);
}
}
support
}
async fn walk(
addr: SocketAddr,
egress: Egress,
version: TlsVersion,
control: &OnceLock<Control>,
may_probe: &impl Fn() -> bool,
) -> (Option<VersionSupport>, Option<UnfinishedVersion>) {
let mut remaining: Vec<CipherSuite> = CipherSuite::offered_under(version).collect();
let mut accepted: Vec<CipherSuite> = Vec::new();
let mut unrecognised: Vec<u16> = Vec::new();
let mut interruption = None;
let mut offers = 0;
while !remaining.is_empty() {
if offers == MAX_OFFERS_PER_VERSION {
warn!(
verbosity = 1,
"{addr} was still answering under {version} after {MAX_OFFERS_PER_VERSION} offers; \
the enumeration is incomplete"
);
break;
}
offers += 1;
let offer = Offer {
version,
suites: &remaining,
server_name: None,
};
let (named, suite, retry) = match ask(addr, egress, &offer, control, may_probe).await {
Answer::Hello {
version,
suite,
retry,
} => (version, suite, retry),
Answer::Declined => break,
Answer::Interrupted(why) => {
if why == Interruption::Unanswered {
warn!(
verbosity = 2,
"{addr} stopped answering under {version}; its enumeration there is incomplete"
);
}
interruption = Some(UnfinishedVersion::new(version, why));
break;
}
};
if named != Some(version) {
break;
}
if retry {
info!(
verbosity = 3,
"{addr} answered under {version} with a HelloRetryRequest naming 0x{suite:04X}"
);
}
match remaining.iter().position(|held| held.code() == suite) {
Some(at) => {
let chosen = remaining.remove(at);
let _ = control.set(Control {
version,
suite: chosen,
});
accepted.push(chosen);
}
None => {
warn!(
verbosity = 2,
"{addr} selected cipher suite 0x{suite:04X} under {version}, which was not offered"
);
unrecognised.push(suite);
break;
}
}
}
let found = (!accepted.is_empty() || !unrecognised.is_empty())
.then(|| VersionSupport::new(version, accepted, unrecognised));
(found, interruption)
}
#[derive(Debug, Clone, Copy)]
struct Control {
version: TlsVersion,
suite: CipherSuite,
}
impl Control {
fn offer(&self) -> Offer<'_> {
Offer {
version: self.version,
suites: std::slice::from_ref(&self.suite),
server_name: None,
}
}
}
enum Answer {
Hello {
version: Option<TlsVersion>,
suite: u16,
retry: bool,
},
Declined,
Interrupted(Interruption),
}
async fn ask(
addr: SocketAddr,
egress: Egress,
offer: &Offer<'_>,
control: &OnceLock<Control>,
may_probe: &impl Fn() -> bool,
) -> Answer {
let mut hung_up = false;
let mut pauses = RETRY_PAUSES.into_iter();
loop {
if !may_probe() {
return Answer::Interrupted(Interruption::Stopped);
}
match exchange(addr, egress, offer).await {
Exchange::Answered(ServerResponse::Hello {
version,
suite,
retry,
}) => {
return Answer::Hello {
version,
suite,
retry,
};
}
Exchange::Answered(_) | Exchange::Unreadable => return Answer::Declined,
Exchange::HungUp if hung_up => {
let Some(control) = control.get() else {
return Answer::Declined;
};
if !may_probe() {
return Answer::Interrupted(Interruption::Stopped);
}
if let Exchange::Answered(ServerResponse::Hello { .. }) =
exchange(addr, egress, &control.offer()).await
{
return Answer::Declined;
}
}
Exchange::HungUp => hung_up = true,
Exchange::Lost => {}
}
let Some(pause) = pauses.next() else {
return Answer::Interrupted(Interruption::Unanswered);
};
tokio::time::sleep(pause).await;
}
}
enum Exchange {
Answered(ServerResponse),
Unreadable,
HungUp,
Lost,
}
async fn exchange(addr: SocketAddr, egress: Egress, offer: &Offer<'_>) -> Exchange {
let hello = tls::client_hello(offer);
let _descriptor = descriptors::gate()
.acquire()
.await
.expect("the descriptor gate is never closed");
timeout(EXCHANGE_TIMEOUT, async {
let Ok(mut stream) = egress.connect_timed(addr, CONNECT_PROBE_TIMEOUT).await else {
return Exchange::Lost;
};
if stream.write_all(&hello).await.is_err() {
return Exchange::Lost;
}
match first_record(&mut stream).await {
Record::Whole(record) => {
tls::read_response(&record).map_or(Exchange::Unreadable, Exchange::Answered)
}
Record::Cut(partial) => {
tls::read_response(&partial).map_or(Exchange::HungUp, Exchange::Answered)
}
Record::Oversized => Exchange::Unreadable,
}
})
.await
.unwrap_or(Exchange::Lost)
}
enum Record {
Whole(Vec<u8>),
Cut(Vec<u8>),
Oversized,
}
async fn first_record(stream: &mut TcpStream) -> Record {
let mut buffer = Vec::with_capacity(1024);
let mut chunk = [0u8; 1024];
loop {
match tls::record_length(&buffer) {
Some(total) if buffer.len() >= total => return Record::Whole(buffer),
Some(_) => {}
None if buffer.len() >= RECORD_HEADER_LEN => return Record::Oversized,
None => {}
}
match stream.read(&mut chunk).await {
Ok(0) | Err(_) => return Record::Cut(buffer),
Ok(read) => buffer.extend_from_slice(&chunk[..read]),
}
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::model::tls::SuiteFault;
use std::collections::BTreeSet;
use std::sync::Arc;
use std::sync::atomic::{AtomicUsize, Ordering};
use tokio::net::TcpListener;
use crate::protocols::tls::HELLO_RETRY_RANDOM;
struct FakeTlsServer {
version: u16,
accepts: BTreeSet<u16>,
retry: bool,
version_in_extension: bool,
ignores_the_offer: Option<u16>,
hangs_up_on: fn(usize) -> bool,
refuses_by_hanging_up: bool,
seen: Arc<AtomicUsize>,
}
impl FakeTlsServer {
fn new(version: u16, accepts: impl IntoIterator<Item = u16>) -> Self {
Self {
version,
accepts: accepts.into_iter().collect(),
retry: false,
version_in_extension: false,
ignores_the_offer: None,
hangs_up_on: |_| false,
refuses_by_hanging_up: false,
seen: Arc::new(AtomicUsize::new(0)),
}
}
fn hanging_up_on(mut self, which: fn(usize) -> bool) -> Self {
self.hangs_up_on = which;
self
}
fn refusing_by_hanging_up(mut self) -> Self {
self.refuses_by_hanging_up = true;
self
}
fn answering_in_the_extension(mut self) -> Self {
self.version_in_extension = true;
self
}
fn retrying(mut self) -> Self {
self.retry = true;
self
}
fn always_naming(mut self, suite: u16) -> Self {
self.ignores_the_offer = Some(suite);
self
}
async fn spawn(self) -> (SocketAddr, Arc<AtomicUsize>) {
let listener = TcpListener::bind("127.0.0.1:0").await.expect("binds");
let addr = listener.local_addr().expect("has an address");
let seen = Arc::clone(&self.seen);
tokio::spawn(async move {
loop {
let Ok((mut stream, _)) = listener.accept().await else {
return;
};
let taken = self.seen.fetch_add(1, Ordering::SeqCst) + 1;
if (self.hangs_up_on)(taken) {
continue;
}
let mut buffer = vec![0u8; 4096];
let Ok(read) = stream.read(&mut buffer).await else {
continue;
};
let answer = self.answer(&buffer[..read]);
let _ = stream.write_all(&answer).await;
}
});
(addr, seen)
}
fn answer(&self, hello: &[u8]) -> Vec<u8> {
if let Some(fixed) = self.ignores_the_offer {
return self.server_hello(fixed);
}
if self.refuses_by_hanging_up && hello_version(hello) != Some(self.version) {
return Vec::new();
}
let refusal = match self.refuses_by_hanging_up {
true => Vec::new(),
false => alert(),
};
let Some(offered) = offered_suites(hello) else {
return refusal;
};
let Some(chosen) = offered.iter().find(|code| self.accepts.contains(code)) else {
return refusal;
};
self.server_hello(*chosen)
}
fn server_hello(&self, suite: u16) -> Vec<u8> {
let mut body = vec![2u8, 0, 0, 0];
let legacy = match self.version_in_extension {
true => 0x0303u16,
false => self.version,
};
body.extend_from_slice(&legacy.to_be_bytes());
match self.retry {
true => body.extend_from_slice(&HELLO_RETRY_RANDOM),
false => body.extend_from_slice(&[0x5A; 32]),
}
body.push(0); body.extend_from_slice(&suite.to_be_bytes());
body.push(0);
if self.version_in_extension {
let extensions = [
0x00,
0x2B,
0x00,
0x02,
(self.version >> 8) as u8,
self.version as u8,
];
body.extend_from_slice(&(extensions.len() as u16).to_be_bytes());
body.extend_from_slice(&extensions);
}
let length = (body.len() - 4) as u32;
body[1..4].copy_from_slice(&length.to_be_bytes()[1..]);
let mut record = vec![0x16, 0x03, 0x03];
record.extend_from_slice(&(body.len() as u16).to_be_bytes());
record.extend_from_slice(&body);
record
}
}
fn alert() -> Vec<u8> {
vec![0x15, 0x03, 0x03, 0x00, 0x02, 0x02, 0x28]
}
fn hello_version(hello: &[u8]) -> Option<u16> {
Some(u16::from_be_bytes([*hello.get(9)?, *hello.get(10)?]))
}
fn offered_suites(hello: &[u8]) -> Option<Vec<u16>> {
let after_random = 5 + 4 + 2 + 32;
let session_len = usize::from(*hello.get(after_random)?);
let rest = hello.get(after_random + 1 + session_len..)?;
let len = usize::from(u16::from_be_bytes([*rest.first()?, *rest.get(1)?]));
Some(
rest.get(2..2 + len)?
.as_chunks::<2>()
.0
.iter()
.map(|pair| u16::from_be_bytes(*pair))
.collect(),
)
}
#[tokio::test]
async fn every_accepted_suite_is_found_and_nothing_else_is() {
let accepted = [0xC02F, 0x009C, 0x000A];
let (addr, _) = FakeTlsServer::new(0x0303, accepted).spawn().await;
let support = enumerate_tls(addr).await;
assert!(support.accepts(TlsVersion::Tls12));
assert_eq!(support.floor(), Some(TlsVersion::Tls12));
assert_eq!(support.ceiling(), Some(TlsVersion::Tls12));
let found: BTreeSet<u16> = support.suites().iter().map(|suite| suite.code()).collect();
assert_eq!(found, accepted.into_iter().collect::<BTreeSet<_>>());
}
#[tokio::test]
async fn the_walk_costs_one_connection_per_suite_and_then_stops() {
let accepted = [0xC02F, 0x009C];
let (addr, seen) = FakeTlsServer::new(0x0303, accepted).spawn().await;
let support = enumerate_tls(addr).await;
assert_eq!(support.suites().len(), 2);
assert_eq!(
seen.load(Ordering::SeqCst),
3 + 4,
"the walk narrows and ends rather than repeating itself"
);
}
#[tokio::test]
async fn a_tls13_server_is_credited_to_thirteen_and_not_to_twelve() {
let (addr, _) = FakeTlsServer::new(0x0304, [0x1301, 0x1302])
.answering_in_the_extension()
.spawn()
.await;
let support = enumerate_tls(addr).await;
assert!(support.accepts(TlsVersion::Tls13));
assert!(
!support.accepts(TlsVersion::Tls12),
"the legacy field says 1.2 and means nothing"
);
assert_eq!(support.suites().len(), 2);
}
#[tokio::test]
async fn a_retrying_server_still_yields_its_suites() {
let (addr, _) = FakeTlsServer::new(0x0304, [0x1303])
.answering_in_the_extension()
.retrying()
.spawn()
.await;
let support = enumerate_tls(addr).await;
assert!(support.accepts(TlsVersion::Tls13));
assert_eq!(support.suites().len(), 1);
}
#[tokio::test]
async fn a_server_that_answers_with_another_version_is_not_credited_the_one_offered() {
let (addr, _) = FakeTlsServer::new(0x0303, [0x002F]).spawn().await;
let support = enumerate_tls(addr).await;
assert!(support.accepts(TlsVersion::Tls12));
for version in [TlsVersion::Ssl30, TlsVersion::Tls10, TlsVersion::Tls11] {
assert!(
!support.accepts(version),
"{version} was offered and answered with 1.2, which is a refusal"
);
}
assert!(support.deprecated_versions().next().is_none());
}
#[tokio::test]
async fn a_server_that_refuses_everything_yields_nothing() {
let (addr, _) = FakeTlsServer::new(0x0303, []).spawn().await;
let support = enumerate_tls(addr).await;
assert!(support.is_empty());
assert_eq!(support.floor(), None);
assert!(support.weakest().is_none());
}
#[tokio::test]
async fn a_closed_port_leaves_every_version_unfinished() {
let listener = TcpListener::bind("127.0.0.1:0").await.expect("binds");
let addr = listener.local_addr().expect("has an address");
drop(listener);
let support = enumerate_tls(addr).await;
assert!(support.versions().is_empty(), "nothing was accepted");
assert_eq!(
support.unfinished(),
TlsVersion::ALL
.map(|version| UnfinishedVersion::new(version, Interruption::Unanswered))
.as_slice()
);
}
#[tokio::test]
async fn a_server_still_speaking_tls_10_is_reported_as_such() {
let (addr, _) = FakeTlsServer::new(0x0301, [0x002F, 0x000A]).spawn().await;
let support = enumerate_tls(addr).await;
assert!(support.accepts(TlsVersion::Tls10));
assert_eq!(support.floor(), Some(TlsVersion::Tls10));
assert_eq!(
support.deprecated_versions().collect::<Vec<_>>(),
vec![TlsVersion::Tls10]
);
use crate::model::tls::{SuiteFault, SuiteStrength};
assert_eq!(support.weakest(), Some(SuiteStrength::Insecure));
assert!(support.faults().contains(&SuiteFault::SmallBlock));
}
#[tokio::test]
async fn a_server_naming_a_suite_it_was_not_offered_ends_the_walk() {
let (addr, seen) = FakeTlsServer::new(0x0303, [])
.always_naming(0xFF01)
.spawn()
.await;
let support = enumerate_tls(addr).await;
assert!(support.accepts(TlsVersion::Tls12));
assert!(
support.suites().is_empty(),
"nothing was graded, because nothing was recognised"
);
assert_eq!(
support.versions()[0].unrecognised(),
&[0xFF01],
"the number is kept rather than dropped"
);
assert!(
seen.load(Ordering::SeqCst) <= MAX_OFFERS_PER_VERSION,
"the walk ended on the first unoffered suite rather than looping"
);
}
#[tokio::test]
async fn a_peer_that_is_not_tls_settles_nothing() {
let listener = TcpListener::bind("127.0.0.1:0").await.expect("binds");
let addr = listener.local_addr().expect("has an address");
tokio::spawn(async move {
while let Ok((mut stream, _)) = listener.accept().await {
let mut scratch = [0u8; 1024];
let _ = stream.read(&mut scratch).await;
let _ = stream.write_all(b"HTTP/1.1 400 Bad Request\r\n\r\n").await;
}
});
let support = enumerate_tls(addr).await;
assert!(support.is_empty());
}
#[tokio::test]
async fn a_server_hello_arriving_in_pieces_is_still_read() {
let listener = TcpListener::bind("127.0.0.1:0").await.expect("binds");
let addr = listener.local_addr().expect("has an address");
let server = FakeTlsServer::new(0x0303, [0xC02F]);
tokio::spawn(async move {
while let Ok((mut stream, _)) = listener.accept().await {
let mut buffer = vec![0u8; 4096];
let Ok(read) = stream.read(&mut buffer).await else {
continue;
};
let answer = server.answer(&buffer[..read]);
let (head, tail) = answer.split_at(7);
let _ = stream.write_all(head).await;
tokio::time::sleep(Duration::from_millis(20)).await;
let _ = stream.write_all(tail).await;
}
});
let support = enumerate_tls(addr).await;
assert!(support.accepts(TlsVersion::Tls12));
assert_eq!(support.suites().len(), 1);
}
#[tokio::test]
async fn a_server_accepting_everything_is_enumerated_to_the_end() {
let every: Vec<u16> = CipherSuite::offered_under(TlsVersion::Tls12)
.map(|suite| suite.code())
.collect();
let (addr, _) = FakeTlsServer::new(0x0303, every.clone()).spawn().await;
let support = enumerate_tls(addr).await;
assert_eq!(
support.suites().len(),
every.len(),
"every suite the server accepts has to be found, not the first {MAX_OFFERS_PER_VERSION}"
);
}
#[tokio::test]
async fn a_connection_lost_mid_walk_does_not_end_the_walk() {
let every: Vec<u16> = CipherSuite::offered_under(TlsVersion::Tls12)
.map(|suite| suite.code())
.collect();
let (addr, _) = FakeTlsServer::new(0x0303, every.clone())
.hanging_up_on(|taken| taken == 20)
.spawn()
.await;
let support = enumerate_tls(addr).await;
assert_eq!(
support.suites().len(),
every.len(),
"the offer the lost connection carried is put again, and the walk goes on"
);
assert!(support.is_complete());
}
#[tokio::test]
async fn an_endpoint_that_goes_on_hanging_up_leaves_the_walk_unfinished() {
let every: Vec<u16> = CipherSuite::offered_under(TlsVersion::Tls12)
.map(|suite| suite.code())
.collect();
let (addr, _) = FakeTlsServer::new(0x0303, every.clone())
.hanging_up_on(|taken| taken >= 20)
.spawn()
.await;
let support = enumerate_tls(addr).await;
let found = support.suites().len();
assert!(
(1..every.len()).contains(&found),
"what was found before the endpoint went quiet is kept, and it is not \
everything: {found} of {}",
every.len()
);
assert_eq!(
support.unfinished(),
&[UnfinishedVersion::new(
TlsVersion::Tls12,
Interruption::Unanswered
)],
"the walk it cut short is named, and no other"
);
}
#[tokio::test]
async fn a_server_that_declines_by_hanging_up_leaves_nothing_unfinished() {
let accepted = [0xC02F, 0x009C];
let (addr, _) = FakeTlsServer::new(0x0303, accepted)
.refusing_by_hanging_up()
.spawn()
.await;
let support = enumerate_tls(addr).await;
let found: BTreeSet<u16> = support.suites().iter().map(|suite| suite.code()).collect();
assert_eq!(found, accepted.into_iter().collect::<BTreeSet<_>>());
assert_eq!(support.floor(), Some(TlsVersion::Tls12));
assert!(
support.is_complete(),
"every hang-up here was the server declining: {:?}",
support.unfinished()
);
}
#[tokio::test]
async fn the_high_severity_faults_survive_a_full_offer_list() {
let every: Vec<u16> = CipherSuite::offered_under(TlsVersion::Tls12)
.map(|suite| suite.code())
.collect();
let (addr, _) = FakeTlsServer::new(0x0303, every).spawn().await;
let support = enumerate_tls(addr).await;
let faults: BTreeSet<SuiteFault> = support.faults().into_iter().collect();
for expected in [
SuiteFault::NullCipher,
SuiteFault::Anonymous,
SuiteFault::Export,
SuiteFault::Rc4,
SuiteFault::Md5Mac,
SuiteFault::SmallBlock,
] {
assert!(
faults.contains(&expected),
"{expected} is carried by a suite this server accepts and has to be reported"
);
}
assert_eq!(
support.weakest(),
Some(crate::model::tls::SuiteStrength::Insecure)
);
}
#[test]
fn the_offer_ceiling_is_never_below_what_a_version_can_offer() {
for version in TlsVersion::ALL {
let offered = CipherSuite::offered_under(version).count();
assert!(
offered <= MAX_OFFERS_PER_VERSION,
"{version} offers {offered} suites against a ceiling of {MAX_OFFERS_PER_VERSION}, \
so a server accepting them all would be cut short"
);
}
}
#[tokio::test]
async fn a_finding_does_not_claim_a_handshake_the_scan_never_completed() {
let (addr, _) = FakeTlsServer::new(0x0301, [0x002F]).spawn().await;
let support = enumerate_tls(addr).await;
let findings = support.findings();
assert!(
!findings.is_empty(),
"a TLS 1.0 endpoint is worth reporting"
);
for finding in &findings {
let excerpt = finding.excerpt().as_str();
assert!(
!excerpt.contains("completed"),
"the excerpt claims a completed negotiation: {excerpt}"
);
}
}
#[tokio::test]
async fn a_retrying_server_is_not_reported_as_having_negotiated() {
let (addr, _) = FakeTlsServer::new(0x0301, [0x000A])
.retrying()
.spawn()
.await;
let support = enumerate_tls(addr).await;
assert!(
support.accepts(TlsVersion::Tls10),
"a retry still names a suite the server would use"
);
for finding in support.findings() {
assert!(
!finding.excerpt().as_str().contains("completed"),
"a HelloRetryRequest is the one answer that certainly completed nothing"
);
}
}
#[tokio::test]
async fn a_peer_that_hangs_up_mid_hello_settles_nothing() {
let listener = TcpListener::bind("127.0.0.1:0").await.expect("binds");
let addr = listener.local_addr().expect("has an address");
let server = FakeTlsServer::new(0x0304, [0x1301]).answering_in_the_extension();
tokio::spawn(async move {
while let Ok((mut stream, _)) = listener.accept().await {
let mut buffer = vec![0u8; 4096];
let Ok(read) = stream.read(&mut buffer).await else {
continue;
};
let answer = server.answer(&buffer[..read]);
let cut = 5 + 4 + 2 + 32 + 1 + 2 + 1;
let _ = stream.write_all(&answer[..cut.min(answer.len())]).await;
drop(stream);
}
});
let support = enumerate_tls(addr).await;
assert!(
support.is_empty(),
"a hello that never finished arriving is not an accepted version, \
and certainly not the 1.2 its legacy field claims"
);
}
}