use alloc::collections::BTreeMap;
use alloc::string::String;
use alloc::vec::Vec;
use serde::{Deserialize, Serialize};
use zeroize::{Zeroize, ZeroizeOnDrop};
use crate::types::{Duration, ProtocolVersion, Timestamp};
use super::{
AccessToken, ChallengeResponse, CommunicationProtocol, ConnectError, Deployment,
EndpointDescription, HmacBinding, HmacHashingAlgorithm, NodeDescription, NodeId, NodeIdAlias,
PairingToken, Role,
};
pub const PAIRING_BUDGET: Duration = Duration::from_secs(15);
pub const MINIMUM_SERVER_DELAY: Duration = Duration::from_secs(1);
#[derive(Clone, Zeroize, ZeroizeOnDrop, Serialize, Deserialize)]
#[serde(transparent)]
pub struct PairingAttemptId(String);
impl PairingAttemptId {
pub const MIN_LEN: usize = 32;
#[must_use]
pub fn new(value: impl Into<String>) -> Self {
Self(value.into())
}
pub fn from_entropy(bytes: &[u8]) -> Result<Self, ConnectError> {
if bytes.len() < 24 {
return Err(ConnectError::WeakSecret {
got: bytes.len(),
need: 24,
});
}
Ok(Self(super::base64_encode(bytes)))
}
#[must_use]
pub fn as_str(&self) -> &str {
&self.0
}
#[must_use]
pub fn verify(&self, presented: &str) -> bool {
use subtle::ConstantTimeEq as _;
self.0.len() == presented.len() && bool::from(self.0.as_bytes().ct_eq(presented.as_bytes()))
}
}
impl core::fmt::Debug for PairingAttemptId {
fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
f.write_str("PairingAttemptId(<redacted>)")
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct PairingRequest {
pub client_node_description: NodeDescription,
pub client_endpoint_description: EndpointDescription,
#[serde(skip_serializing_if = "Option::is_none")]
pub node_id: Option<NodeId>,
#[serde(skip_serializing_if = "Option::is_none")]
pub node_id_alias: Option<NodeIdAlias>,
pub supported_communication_protocols: Vec<CommunicationProtocol>,
pub supported_s2_message_versions: Vec<ProtocolVersion>,
pub supported_hmac_hashing_algorithms: Vec<HmacHashingAlgorithm>,
pub client_hmac_challenge: String,
#[serde(default, skip_serializing_if = "core::ops::Not::not")]
pub force_pairing: bool,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct PairingAccepted {
pub pairing_attempt_id: PairingAttemptId,
pub server_node_description: NodeDescription,
pub server_endpoint_description: EndpointDescription,
pub selected_hmac_hashing_algorithm: HmacHashingAlgorithm,
pub client_hmac_challenge_response: String,
pub server_hmac_challenge: String,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[non_exhaustive]
pub enum PairingErrorMessage {
InvalidCombinationOfRoles,
IncompatibleS2MessageVersions,
IncompatibleHmacHashingAlgorithms,
IncompatibleCommunicationProtocols,
NodeNotFound,
NoNodeIdProvided,
NoValidPairingTokenOnPairingServer,
ParsingError,
Other,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct PairingRefused {
pub error_message: PairingErrorMessage,
#[serde(skip_serializing_if = "Option::is_none")]
pub additional_info: Option<String>,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ConnectionDetails {
pub initiate_session_url: String,
pub access_token: AccessToken,
#[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
pub certificate_fingerprint: BTreeMap<String, String>,
}
impl ConnectionDetails {
pub const SHA256: &'static str = "SHA256";
#[must_use]
pub fn new(initiate_session_url: impl Into<String>, access_token: AccessToken) -> Self {
Self {
initiate_session_url: initiate_session_url.into(),
access_token,
certificate_fingerprint: BTreeMap::new(),
}
}
#[must_use]
pub fn with_ca_fingerprint(mut self, sha256: &[u8; 32]) -> Self {
use core::fmt::Write as _;
let mut hex = String::with_capacity(64);
for b in sha256 {
let _ = write!(hex, "{b:02x}");
}
self.certificate_fingerprint
.insert(String::from(Self::SHA256), hex);
self
}
#[must_use]
pub fn ca_fingerprint(&self) -> Option<[u8; 32]> {
let hex = self.certificate_fingerprint.get(Self::SHA256)?;
match super::HmacBinding::from_hex_fingerprint(hex).ok()? {
super::HmacBinding::LeafFingerprint(bytes) => bytes.try_into().ok(),
super::HmacBinding::DomainName(_) => None,
}
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ConnectionDetailsRequest {
pub server_hmac_challenge_response: String,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ConnectionDetailsPost {
pub server_hmac_challenge_response: String,
pub connection_details: ConnectionDetails,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub struct FinalizePairing {
pub success: bool,
}
#[derive(Debug, Clone)]
pub struct Pairing {
pub local: NodeId,
pub remote: NodeDescription,
pub remote_endpoint: EndpointDescription,
pub details: ConnectionDetails,
pub communication_server: Role,
pub s2_message_versions: Vec<ProtocolVersion>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum PairingStep {
Start,
AwaitingAcceptance,
Authenticated,
DetailsExchanged,
Paired,
Failed,
}
impl PairingStep {
const fn name(self) -> &'static str {
match self {
PairingStep::Start => "the start of pairing",
PairingStep::AwaitingAcceptance => "the server's acceptance",
PairingStep::Authenticated => "connection details",
PairingStep::DetailsExchanged => "finalization",
PairingStep::Paired => "a completed pairing",
PairingStep::Failed => "a failed pairing",
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum NextStep {
RequestConnectionDetails,
PostConnectionDetails,
}
#[derive(Debug)]
pub struct PairingClient {
local: NodeDescription,
local_endpoint: EndpointDescription,
code: super::PairingCode,
binding: Option<HmacBinding>,
started: Timestamp,
step: PairingStep,
challenge: Option<Vec<u8>>,
s2_message_versions: Vec<ProtocolVersion>,
protocols: Vec<CommunicationProtocol>,
force: bool,
accepted: Option<PairingAccepted>,
attempt_id: Option<PairingAttemptId>,
details: Option<ConnectionDetails>,
communication_server: Option<Role>,
}
impl PairingClient {
#[must_use]
pub fn start(
local: NodeDescription,
local_endpoint: EndpointDescription,
code: super::PairingCode,
now: Timestamp,
) -> Self {
Self {
local,
local_endpoint,
code,
binding: None,
started: now,
step: PairingStep::Start,
challenge: None,
s2_message_versions: alloc::vec![
crate::types::WireProfile::V1_0_0.connect_version(),
crate::types::WireProfile::V0_0_2Beta.connect_version(),
],
protocols: alloc::vec![CommunicationProtocol::WebSocket],
force: false,
accepted: None,
attempt_id: None,
details: None,
communication_server: None,
}
}
#[must_use]
pub fn with_s2_message_versions(mut self, versions: Vec<ProtocolVersion>) -> Self {
self.s2_message_versions = versions;
self
}
#[must_use]
pub fn forcing(mut self) -> Self {
self.force = true;
self
}
#[must_use]
pub const fn step(&self) -> PairingStep {
self.step
}
#[must_use]
pub fn attempt_id(&self) -> Option<&PairingAttemptId> {
self.attempt_id.as_ref()
}
pub fn request_pairing(&mut self, challenge: &[u8]) -> Result<PairingRequest, ConnectError> {
self.expect(PairingStep::Start)?;
if challenge.len() < 32 {
self.step = PairingStep::Failed;
return Err(ConnectError::WeakSecret {
got: challenge.len(),
need: 32,
});
}
self.challenge = Some(challenge.to_vec());
self.step = PairingStep::AwaitingAcceptance;
Ok(PairingRequest {
client_node_description: self.local.clone(),
client_endpoint_description: self.local_endpoint.clone(),
node_id: None,
node_id_alias: self.code.alias.clone(),
supported_communication_protocols: self.protocols.clone(),
supported_s2_message_versions: self.s2_message_versions.clone(),
supported_hmac_hashing_algorithms: alloc::vec![HmacHashingAlgorithm::Sha256],
client_hmac_challenge: super::base64_encode(challenge),
force_pairing: self.force,
})
}
pub fn accept(
&mut self,
accepted: PairingAccepted,
binding: HmacBinding,
server_deployment: Deployment,
now: Timestamp,
) -> Result<NextStep, ConnectError> {
self.expect(PairingStep::AwaitingAcceptance)?;
self.attempt_id = Some(accepted.pairing_attempt_id.clone());
self.within_budget(now)?;
self.binding = Some(binding);
if !self
.local
.role
.can_pair_with(accepted.server_node_description.role)
{
self.step = PairingStep::Failed;
return Err(ConnectError::SameRole(self.local.role));
}
let challenge = self.challenge.as_ref().ok_or(ConnectError::OutOfOrder {
got: "the server's acceptance",
expected: "the start of pairing",
})?;
let binding = self.binding.as_ref().ok_or(ConnectError::ChallengeFailed)?;
let expected = ChallengeResponse::compute(challenge, &self.code.token, binding)?;
if !expected.verify(&accepted.client_hmac_challenge_response) {
self.step = PairingStep::Failed;
return Err(ConnectError::ChallengeFailed);
}
let server_deployment = accepted
.server_endpoint_description
.deployment
.unwrap_or(server_deployment);
let local_deployment = self.local_endpoint.deployment.unwrap_or(Deployment::Lan);
let (cem, rm) = if self.local.role == Role::Cem {
(local_deployment, server_deployment)
} else {
(server_deployment, local_deployment)
};
let communication_server = Deployment::communication_server(cem, rm);
self.communication_server = Some(communication_server);
self.accepted = Some(accepted);
self.step = PairingStep::Authenticated;
Ok(if communication_server == self.local.role {
NextStep::PostConnectionDetails
} else {
NextStep::RequestConnectionDetails
})
}
pub fn server_challenge_response(&self) -> Result<String, ConnectError> {
let accepted = self.accepted.as_ref().ok_or(ConnectError::OutOfOrder {
got: "a challenge response",
expected: "the server's acceptance",
})?;
let binding = self.binding.as_ref().ok_or(ConnectError::OutOfOrder {
got: "a challenge response",
expected: "the server's acceptance",
})?;
let challenge = super::base64_decode(&accepted.server_hmac_challenge)
.ok_or(ConnectError::ChallengeFailed)?;
Ok(ChallengeResponse::compute(&challenge, &self.code.token, binding)?.as_base64())
}
pub fn request_connection_details(&self) -> Result<ConnectionDetailsRequest, ConnectError> {
Ok(ConnectionDetailsRequest {
server_hmac_challenge_response: self.server_challenge_response()?,
})
}
pub fn post_connection_details(
&mut self,
details: ConnectionDetails,
now: Timestamp,
) -> Result<ConnectionDetailsPost, ConnectError> {
if details.ca_fingerprint().is_none() {
return Err(ConnectError::OutOfOrder {
got: "connection details without a SHA256 CA fingerprint",
expected: "certificateFingerprint.SHA256",
});
}
let response = self.server_challenge_response()?;
self.connection_details(details.clone(), now)?;
Ok(ConnectionDetailsPost {
server_hmac_challenge_response: response,
connection_details: details,
})
}
pub fn connection_details(
&mut self,
details: ConnectionDetails,
now: Timestamp,
) -> Result<(), ConnectError> {
self.expect(PairingStep::Authenticated)?;
self.within_budget(now)?;
self.details = Some(details);
self.step = PairingStep::DetailsExchanged;
Ok(())
}
pub fn finalize(&mut self, now: Timestamp) -> Result<(FinalizePairing, Pairing), ConnectError> {
self.expect(PairingStep::DetailsExchanged)?;
self.within_budget(now)?;
let accepted = self.accepted.take().ok_or(ConnectError::OutOfOrder {
got: "finalization",
expected: "the server's acceptance",
})?;
let details = self.details.take().ok_or(ConnectError::OutOfOrder {
got: "finalization",
expected: "connection details",
})?;
self.step = PairingStep::Paired;
Ok((
FinalizePairing { success: true },
Pairing {
local: self.local.id,
remote: accepted.server_node_description,
remote_endpoint: accepted.server_endpoint_description,
details,
communication_server: self.communication_server.unwrap_or(Role::Cem),
s2_message_versions: self.s2_message_versions.clone(),
},
))
}
pub fn abandon(&mut self) -> FinalizePairing {
self.step = PairingStep::Failed;
FinalizePairing { success: false }
}
fn expect(&mut self, step: PairingStep) -> Result<(), ConnectError> {
if self.step == step {
return Ok(());
}
let got = self.step.name();
self.step = PairingStep::Failed;
Err(ConnectError::OutOfOrder {
got,
expected: step.name(),
})
}
fn within_budget(&mut self, now: Timestamp) -> Result<(), ConnectError> {
if now.saturating_duration_since(self.started) > PAIRING_BUDGET {
self.step = PairingStep::Failed;
return Err(ConnectError::Expired {
what: "pairing",
limit: PAIRING_BUDGET,
});
}
Ok(())
}
}
#[derive(Debug)]
pub struct PairingServer {
local: NodeDescription,
local_endpoint: EndpointDescription,
binding: HmacBinding,
s2_message_versions: Vec<ProtocolVersion>,
protocols: Vec<CommunicationProtocol>,
attempt: Option<Attempt>,
last_finished: Option<Timestamp>,
pending: Option<(Timestamp, PairingAccepted)>,
}
#[derive(Debug)]
struct Attempt {
id: PairingAttemptId,
started: Timestamp,
expected_response: ChallengeResponse,
client: NodeDescription,
client_endpoint: EndpointDescription,
s2_message_versions: Vec<ProtocolVersion>,
details: Option<ConnectionDetails>,
verified: bool,
client_is_communication_server: bool,
}
impl PairingServer {
#[must_use]
pub fn new(
local: NodeDescription,
local_endpoint: EndpointDescription,
binding: HmacBinding,
) -> Self {
Self {
local,
local_endpoint,
binding,
s2_message_versions: alloc::vec![
crate::types::WireProfile::V1_0_0.connect_version(),
crate::types::WireProfile::V0_0_2Beta.connect_version(),
],
protocols: alloc::vec![CommunicationProtocol::WebSocket],
attempt: None,
last_finished: None,
pending: None,
}
}
#[must_use]
pub fn with_s2_message_versions(mut self, versions: Vec<ProtocolVersion>) -> Self {
self.s2_message_versions = versions;
self
}
pub fn request_pairing(
&mut self,
request: &PairingRequest,
token: &PairingToken,
server_challenge: &[u8],
attempt_id: PairingAttemptId,
now: Timestamp,
) -> Result<(Timestamp, PairingAccepted), ConnectError> {
if let Some(attempt) = &self.attempt
&& now.saturating_duration_since(attempt.started) <= PAIRING_BUDGET
{
return Err(ConnectError::RateLimited);
}
if let Some(finished) = self.last_finished
&& now.saturating_duration_since(finished) < MINIMUM_SERVER_DELAY
{
return Err(ConnectError::RateLimited);
}
let result = self.answer(request, token, server_challenge, attempt_id, now);
if result.is_err() {
self.last_finished = Some(now);
self.attempt = None;
}
result
}
fn answer(
&mut self,
request: &PairingRequest,
token: &PairingToken,
server_challenge: &[u8],
attempt_id: PairingAttemptId,
now: Timestamp,
) -> Result<(Timestamp, PairingAccepted), ConnectError> {
use PairingErrorMessage as E;
if !self
.local
.role
.can_pair_with(request.client_node_description.role)
{
return Err(refused(E::InvalidCombinationOfRoles));
}
if !request
.supported_hmac_hashing_algorithms
.contains(&HmacHashingAlgorithm::Sha256)
{
return Err(refused(E::IncompatibleHmacHashingAlgorithms));
}
if !request
.supported_communication_protocols
.iter()
.any(|p| self.protocols.contains(p))
{
return Err(refused(E::IncompatibleCommunicationProtocols));
}
let common = request
.supported_s2_message_versions
.iter()
.filter(|v| self.s2_message_versions.iter().any(|ours| ours.matches(v)))
.cloned()
.collect::<Vec<_>>();
if common.is_empty() && !request.force_pairing {
return Err(refused(E::IncompatibleS2MessageVersions));
}
if request.node_id.is_some() && request.node_id_alias.is_some() {
return Err(refused(E::ParsingError));
}
let client_challenge = super::base64_decode(&request.client_hmac_challenge)
.ok_or_else(|| refused(E::ParsingError))?;
let client_response = ChallengeResponse::compute(&client_challenge, token, &self.binding)?;
let expected_response = ChallengeResponse::compute(server_challenge, token, &self.binding)?;
let accepted = PairingAccepted {
pairing_attempt_id: attempt_id.clone(),
server_node_description: self.local.clone(),
server_endpoint_description: self.local_endpoint.clone(),
selected_hmac_hashing_algorithm: HmacHashingAlgorithm::Sha256,
client_hmac_challenge_response: client_response.as_base64(),
server_hmac_challenge: super::base64_encode(server_challenge),
};
let client_deployment = request
.client_endpoint_description
.deployment
.unwrap_or(Deployment::Lan);
let own_deployment = self.local_endpoint.deployment.unwrap_or(Deployment::Lan);
let (cem, rm) = if self.local.role == Role::Cem {
(own_deployment, client_deployment)
} else {
(client_deployment, own_deployment)
};
let client_is_communication_server =
Deployment::communication_server(cem, rm) == request.client_node_description.role;
self.attempt = Some(Attempt {
id: attempt_id,
started: now,
expected_response,
client: request.client_node_description.clone(),
client_endpoint: request.client_endpoint_description.clone(),
s2_message_versions: common,
details: None,
verified: false,
client_is_communication_server,
});
let send_after = now.checked_add(MINIMUM_SERVER_DELAY).unwrap_or(now);
self.pending = Some((send_after, accepted.clone()));
Ok((send_after, accepted))
}
#[must_use]
pub fn poll_timeout(&self) -> Option<Timestamp> {
self.pending.as_ref().map(|(at, _)| *at).or_else(|| {
self.attempt
.as_ref()
.map(|a| a.started.checked_add(PAIRING_BUDGET).unwrap_or(a.started))
})
}
pub fn poll_response(&mut self, now: Timestamp) -> Option<PairingAccepted> {
let (at, _) = self.pending.as_ref()?;
if now < *at {
return None;
}
self.pending.take().map(|(_, accepted)| accepted)
}
#[must_use]
pub fn authenticates(&self, bearer: &str) -> bool {
self.attempt.as_ref().is_some_and(|a| a.id.verify(bearer))
}
pub fn verify_client(&mut self, response: &str, now: Timestamp) -> Result<(), ConnectError> {
let Some(attempt) = self.attempt.as_mut() else {
return Err(ConnectError::OutOfOrder {
got: "a challenge response",
expected: "the start of pairing",
});
};
if now.saturating_duration_since(attempt.started) > PAIRING_BUDGET {
self.fail(now);
return Err(ConnectError::Expired {
what: "pairing",
limit: PAIRING_BUDGET,
});
}
if !attempt.expected_response.verify(response) {
self.fail(now);
return Err(ConnectError::ChallengeFailed);
}
attempt.verified = true;
Ok(())
}
#[must_use]
pub fn client_is_communication_server(&self) -> Option<bool> {
self.attempt
.as_ref()
.map(|a| a.client_is_communication_server)
}
pub fn connection_details(
&mut self,
details: ConnectionDetails,
now: Timestamp,
) -> Result<ConnectionDetails, ConnectError> {
self.record_details(details, false, now)
}
pub fn accept_connection_details(
&mut self,
details: ConnectionDetails,
now: Timestamp,
) -> Result<(), ConnectError> {
if details.ca_fingerprint().is_none() {
self.fail(now);
return Err(refused(PairingErrorMessage::ParsingError));
}
self.record_details(details, true, now).map(|_| ())
}
fn record_details(
&mut self,
details: ConnectionDetails,
posted_by_client: bool,
now: Timestamp,
) -> Result<ConnectionDetails, ConnectError> {
let (verified, client_is_server) = self
.attempt
.as_ref()
.map(|a| (a.verified, a.client_is_communication_server))
.ok_or(ConnectError::OutOfOrder {
got: "connection details",
expected: "the start of pairing",
})?;
if !verified {
return Err(ConnectError::ChallengeFailed);
}
if client_is_server != posted_by_client {
let (got, expected) = if posted_by_client {
("postConnectionDetails", "requestConnectionDetails")
} else {
("requestConnectionDetails", "postConnectionDetails")
};
self.fail(now);
return Err(ConnectError::OutOfOrder { got, expected });
}
if let Some(attempt) = self.attempt.as_mut() {
attempt.details = Some(details.clone());
}
Ok(details)
}
pub fn finalize(
&mut self,
body: FinalizePairing,
now: Timestamp,
) -> Result<Option<Pairing>, ConnectError> {
let Some(attempt) = self.attempt.take() else {
return Err(ConnectError::OutOfOrder {
got: "finalization",
expected: "the start of pairing",
});
};
self.last_finished = Some(now);
self.pending = None;
if now.saturating_duration_since(attempt.started) > PAIRING_BUDGET {
return Err(ConnectError::Expired {
what: "pairing",
limit: PAIRING_BUDGET,
});
}
if !body.success {
return Ok(None);
}
if !attempt.verified {
return Err(ConnectError::ChallengeFailed);
}
let details = attempt.details.ok_or(ConnectError::OutOfOrder {
got: "finalization",
expected: "connection details",
})?;
let client_deployment = attempt
.client_endpoint
.deployment
.unwrap_or(Deployment::Lan);
let own_deployment = self.local_endpoint.deployment.unwrap_or(Deployment::Lan);
let (cem, rm) = if self.local.role == Role::Cem {
(own_deployment, client_deployment)
} else {
(client_deployment, own_deployment)
};
Ok(Some(Pairing {
local: self.local.id,
remote: attempt.client,
remote_endpoint: attempt.client_endpoint,
details,
communication_server: Deployment::communication_server(cem, rm),
s2_message_versions: attempt.s2_message_versions,
}))
}
fn fail(&mut self, now: Timestamp) {
self.attempt = None;
self.pending = None;
self.last_finished = Some(now);
}
}
fn refused(message: PairingErrorMessage) -> ConnectError {
ConnectError::Refused(PairingRefused {
error_message: message,
additional_info: None,
})
}
#[cfg(test)]
mod tests {
use super::*;
use crate::connect::proto::{PairingCode, TokenKind};
use alloc::string::ToString;
const CLIENT_CHALLENGE: [u8; 32] = [0xA5; 32];
const SERVER_CHALLENGE: [u8; 32] = [0x5A; 32];
const ATTEMPT: [u8; 24] = [0x33; 24];
fn binding() -> HmacBinding {
HmacBinding::DomainName("pairing.example.com".to_string())
}
fn code() -> PairingCode {
PairingCode::parse("evse7-A1b2C3", TokenKind::Static).expect("a legal code")
}
fn node(id: &str, role: Role) -> NodeDescription {
NodeDescription {
id: NodeId::parse(id).expect("a legal id"),
brand: "Acme".to_string(),
logo_url: None,
kind: if role == Role::Cem { "CEM" } else { "EVSE" }.to_string(),
model_name: "Charger 9000".to_string(),
user_defined_name: None,
role,
}
}
fn endpoint(deployment: Deployment) -> EndpointDescription {
EndpointDescription {
name: Some("Test endpoint".to_string()),
logo_url: None,
deployment: Some(deployment),
}
}
fn details() -> ConnectionDetails {
ConnectionDetails::new(
"https://pairing.example.com/",
AccessToken::from_entropy(&[1u8; 32]).expect("32 bytes"),
)
.with_ca_fingerprint(&[0xCA; 32])
}
fn t(secs: i64) -> Timestamp {
Timestamp::from_unix(1_700_000_000 + secs, 0)
}
fn attempt_id() -> PairingAttemptId {
PairingAttemptId::from_entropy(&ATTEMPT).expect("24 bytes")
}
struct Run {
client: PairingClient,
server: PairingServer,
}
fn setup(
client_role: Role,
client_deployment: Deployment,
server_deployment: Deployment,
) -> Run {
Run {
client: PairingClient::start(
node("cem-1", client_role),
endpoint(client_deployment),
code(),
t(0),
),
server: PairingServer::new(
node("rm-1", client_role.other()),
endpoint(server_deployment),
binding(),
),
}
}
#[test]
fn a_pairing_runs_to_completion_and_both_sides_agree() {
let Run {
mut client,
mut server,
} = setup(Role::Cem, Deployment::Lan, Deployment::Lan);
let request = client.request_pairing(&CLIENT_CHALLENGE).unwrap();
let (send_after, accepted) = server
.request_pairing(
&request,
&code().token,
&SERVER_CHALLENGE,
attempt_id(),
t(0),
)
.unwrap();
assert_eq!(send_after, t(1));
let accepted = {
assert!(server.poll_response(t(0)).is_none());
server.poll_response(t(1)).unwrap_or(accepted)
};
let next = client
.accept(accepted, binding(), Deployment::Lan, t(1))
.unwrap();
assert_eq!(next, NextStep::PostConnectionDetails);
let post = client.post_connection_details(details(), t(1)).unwrap();
assert!(server.authenticates(client.attempt_id().unwrap().as_str()));
server
.verify_client(&post.server_hmac_challenge_response, t(1))
.unwrap();
server
.accept_connection_details(post.connection_details, t(1))
.unwrap();
let (body, mine) = client.finalize(t(2)).unwrap();
assert!(body.success);
let theirs = server.finalize(body, t(2)).unwrap().expect("a pairing");
assert_eq!(client.step(), PairingStep::Paired);
assert_eq!(mine.remote.id, theirs.local);
assert_eq!(theirs.remote.id, mine.local);
assert_eq!(mine.communication_server, Role::Cem);
assert_eq!(theirs.communication_server, Role::Cem);
}
#[test]
fn a_wan_pairing_server_supplies_the_details_instead() {
let Run {
mut client,
mut server,
} = setup(Role::Cem, Deployment::Lan, Deployment::Wan);
let request = client.request_pairing(&CLIENT_CHALLENGE).unwrap();
let (_, accepted) = server
.request_pairing(
&request,
&code().token,
&SERVER_CHALLENGE,
attempt_id(),
t(0),
)
.unwrap();
let next = client
.accept(accepted, binding(), Deployment::Lan, t(1))
.unwrap();
assert_eq!(next, NextStep::RequestConnectionDetails);
let ask = client.request_connection_details().unwrap();
server
.verify_client(&ask.server_hmac_challenge_response, t(1))
.unwrap();
let given = server.connection_details(details(), t(1)).unwrap();
client.connection_details(given, t(1)).unwrap();
let (body, pairing) = client.finalize(t(2)).unwrap();
assert_eq!(pairing.communication_server, Role::Rm);
assert!(server.finalize(body, t(2)).unwrap().is_some());
}
#[test]
fn a_server_that_omits_its_deployment_is_taken_to_be_where_it_was_reached() {
let outcome = |reached: Deployment| {
let Run {
mut client,
mut server,
} = setup(Role::Cem, Deployment::Lan, Deployment::Wan);
let request = client.request_pairing(&CLIENT_CHALLENGE).unwrap();
let (_, mut accepted) = server
.request_pairing(
&request,
&code().token,
&SERVER_CHALLENGE,
attempt_id(),
t(0),
)
.unwrap();
accepted.server_endpoint_description.deployment = None;
client.accept(accepted, binding(), reached, t(1)).unwrap()
};
assert_eq!(outcome(Deployment::Wan), NextStep::RequestConnectionDetails);
assert_eq!(outcome(Deployment::Lan), NextStep::PostConnectionDetails);
}
#[test]
fn the_wrong_branch_of_step_six_fails_the_attempt() {
let Run {
mut client,
mut server,
} = setup(Role::Cem, Deployment::Lan, Deployment::Wan);
let request = client.request_pairing(&CLIENT_CHALLENGE).unwrap();
let (_, accepted) = server
.request_pairing(
&request,
&code().token,
&SERVER_CHALLENGE,
attempt_id(),
t(0),
)
.unwrap();
client
.accept(accepted, binding(), Deployment::Lan, t(1))
.unwrap();
let ask = client.request_connection_details().unwrap();
server
.verify_client(&ask.server_hmac_challenge_response, t(1))
.unwrap();
assert_eq!(server.client_is_communication_server(), Some(false));
assert!(matches!(
server.accept_connection_details(details(), t(1)),
Err(ConnectError::OutOfOrder { .. })
));
assert!(
server.client_is_communication_server().is_none(),
"the attempt is failed, not merely refused"
);
}
#[test]
fn posted_details_without_a_ca_fingerprint_are_refused() {
let bare = ConnectionDetails::new("https://cem.local/", AccessToken::new("x".repeat(43)));
assert!(bare.ca_fingerprint().is_none());
let pinned = bare.clone().with_ca_fingerprint(&[0xAB; 32]);
assert_eq!(pinned.ca_fingerprint(), Some([0xAB; 32]));
assert_eq!(
pinned
.certificate_fingerprint
.get("SHA256")
.map(String::as_str),
Some("ab".repeat(32).as_str()),
"plain lowercase hexadecimal on the wire"
);
let mut colons = bare;
colons
.certificate_fingerprint
.insert("SHA256".to_string(), alloc::vec!["AB"; 32].join(":"));
assert_eq!(colons.ca_fingerprint(), Some([0xAB; 32]));
}
#[test]
fn the_response_may_not_be_sent_before_the_mandatory_second() {
let Run {
mut client,
mut server,
} = setup(Role::Cem, Deployment::Lan, Deployment::Lan);
let request = client.request_pairing(&CLIENT_CHALLENGE).unwrap();
server
.request_pairing(
&request,
&code().token,
&SERVER_CHALLENGE,
attempt_id(),
t(0),
)
.unwrap();
assert_eq!(server.poll_timeout(), Some(t(1)));
assert!(server.poll_response(t(0)).is_none());
assert!(
server
.poll_response(Timestamp::from_unix(1_700_000_000, 999_000_000))
.is_none()
);
assert!(server.poll_response(t(1)).is_some());
assert!(server.poll_response(t(2)).is_none());
}
#[test]
fn a_second_attempt_for_the_same_node_is_refused() {
let Run {
mut client,
mut server,
} = setup(Role::Cem, Deployment::Lan, Deployment::Lan);
let request = client.request_pairing(&CLIENT_CHALLENGE).unwrap();
server
.request_pairing(
&request,
&code().token,
&SERVER_CHALLENGE,
attempt_id(),
t(0),
)
.unwrap();
assert!(matches!(
server.request_pairing(
&request,
&code().token,
&SERVER_CHALLENGE,
attempt_id(),
t(1)
),
Err(ConnectError::RateLimited)
));
assert!(
server
.request_pairing(
&request,
&code().token,
&SERVER_CHALLENGE,
attempt_id(),
t(16)
)
.is_ok()
);
}
#[test]
fn a_wrong_token_costs_the_attacker_a_second_too() {
let Run {
mut client,
mut server,
} = setup(Role::Cem, Deployment::Lan, Deployment::Lan);
let request = client.request_pairing(&CLIENT_CHALLENGE).unwrap();
let wrong = PairingToken::parse("Z9y8X7", TokenKind::Static).unwrap();
let (_, accepted) = server
.request_pairing(&request, &wrong, &SERVER_CHALLENGE, attempt_id(), t(0))
.unwrap();
assert!(matches!(
client.accept(accepted, binding(), Deployment::Lan, t(1)),
Err(ConnectError::ChallengeFailed)
));
let Run {
mut client,
mut server,
} = setup(Role::Cem, Deployment::Lan, Deployment::Lan);
let request = client.request_pairing(&CLIENT_CHALLENGE).unwrap();
let (_, accepted) = server
.request_pairing(
&request,
&code().token,
&SERVER_CHALLENGE,
attempt_id(),
t(0),
)
.unwrap();
client
.accept(accepted, binding(), Deployment::Lan, t(1))
.unwrap();
let forged = ChallengeResponse::compute(&SERVER_CHALLENGE, &wrong, &binding())
.unwrap()
.as_base64();
assert!(matches!(
server.verify_client(&forged, t(1)),
Err(ConnectError::ChallengeFailed)
));
assert!(!server.authenticates(attempt_id().as_str()));
}
#[test]
fn a_man_in_the_middle_cannot_relay_the_exchange() {
let attacker = HmacBinding::DomainName("pairing.example.com.evil.test".to_string());
let mut client = PairingClient::start(
node("cem-1", Role::Cem),
endpoint(Deployment::Lan),
code(),
t(0),
);
let mut server =
PairingServer::new(node("rm-1", Role::Rm), endpoint(Deployment::Lan), attacker);
let request = client.request_pairing(&CLIENT_CHALLENGE).unwrap();
let (_, accepted) = server
.request_pairing(
&request,
&code().token,
&SERVER_CHALLENGE,
attempt_id(),
t(0),
)
.unwrap();
assert!(matches!(
client.accept(accepted, binding(), Deployment::Lan, t(1)),
Err(ConnectError::ChallengeFailed)
));
assert_eq!(client.step(), PairingStep::Failed);
}
#[test]
fn the_fifteen_second_budget_is_enforced_on_both_sides() {
let Run {
mut client,
mut server,
} = setup(Role::Cem, Deployment::Lan, Deployment::Lan);
let request = client.request_pairing(&CLIENT_CHALLENGE).unwrap();
let (_, accepted) = server
.request_pairing(
&request,
&code().token,
&SERVER_CHALLENGE,
attempt_id(),
t(0),
)
.unwrap();
assert!(matches!(
client.accept(accepted, binding(), Deployment::Lan, t(16)),
Err(ConnectError::Expired { .. })
));
assert!(matches!(
server.verify_client("anything", t(16)),
Err(ConnectError::Expired { .. })
));
}
#[test]
fn the_steps_cannot_be_taken_out_of_order() {
let Run { mut client, .. } = setup(Role::Cem, Deployment::Lan, Deployment::Lan);
assert!(matches!(
client.finalize(t(0)),
Err(ConnectError::OutOfOrder { .. })
));
assert_eq!(client.step(), PairingStep::Failed);
assert!(client.request_pairing(&CLIENT_CHALLENGE).is_err());
}
#[test]
fn two_nodes_of_the_same_role_are_refused_by_both_sides() {
let mut client = PairingClient::start(
node("cem-1", Role::Cem),
endpoint(Deployment::Lan),
code(),
t(0),
);
let mut server = PairingServer::new(
node("cem-2", Role::Cem),
endpoint(Deployment::Lan),
binding(),
);
let request = client.request_pairing(&CLIENT_CHALLENGE).unwrap();
let err = server
.request_pairing(
&request,
&code().token,
&SERVER_CHALLENGE,
attempt_id(),
t(0),
)
.unwrap_err();
assert!(matches!(
err,
ConnectError::Refused(PairingRefused {
error_message: PairingErrorMessage::InvalidCombinationOfRoles,
..
})
));
}
#[test]
fn incompatible_versions_are_refused_unless_forced() {
let mut client = PairingClient::start(
node("cem-1", Role::Cem),
endpoint(Deployment::Lan),
code(),
t(0),
)
.with_s2_message_versions(alloc::vec![crate::types::ProtocolVersion::new("9.9.9")]);
let mut server =
PairingServer::new(node("rm-1", Role::Rm), endpoint(Deployment::Lan), binding());
let request = client.request_pairing(&CLIENT_CHALLENGE).unwrap();
assert!(matches!(
server.request_pairing(
&request,
&code().token,
&SERVER_CHALLENGE,
attempt_id(),
t(0)
),
Err(ConnectError::Refused(PairingRefused {
error_message: PairingErrorMessage::IncompatibleS2MessageVersions,
..
}))
));
let mut client = PairingClient::start(
node("cem-1", Role::Cem),
endpoint(Deployment::Lan),
code(),
t(0),
)
.with_s2_message_versions(alloc::vec![crate::types::ProtocolVersion::new("9.9.9")])
.forcing();
let mut server =
PairingServer::new(node("rm-1", Role::Rm), endpoint(Deployment::Lan), binding());
let request = client.request_pairing(&CLIENT_CHALLENGE).unwrap();
assert!(
server
.request_pairing(
&request,
&code().token,
&SERVER_CHALLENGE,
attempt_id(),
t(16)
)
.is_ok()
);
}
#[test]
fn a_client_without_sha256_is_refused() {
let Run {
mut client,
mut server,
} = setup(Role::Cem, Deployment::Lan, Deployment::Lan);
let mut request = client.request_pairing(&CLIENT_CHALLENGE).unwrap();
request.supported_hmac_hashing_algorithms.clear();
assert!(matches!(
server.request_pairing(
&request,
&code().token,
&SERVER_CHALLENGE,
attempt_id(),
t(0)
),
Err(ConnectError::Refused(PairingRefused {
error_message: PairingErrorMessage::IncompatibleHmacHashingAlgorithms,
..
}))
));
}
#[test]
fn a_short_challenge_never_reaches_the_wire() {
let Run { mut client, .. } = setup(Role::Cem, Deployment::Lan, Deployment::Lan);
assert!(matches!(
client.request_pairing(&[0u8; 16]),
Err(ConnectError::WeakSecret { need: 32, .. })
));
}
#[test]
fn the_attempt_id_is_a_bearer_and_is_compared_in_constant_time() {
let Run {
mut client,
mut server,
} = setup(Role::Cem, Deployment::Lan, Deployment::Lan);
let request = client.request_pairing(&CLIENT_CHALLENGE).unwrap();
server
.request_pairing(
&request,
&code().token,
&SERVER_CHALLENGE,
attempt_id(),
t(0),
)
.unwrap();
assert!(server.authenticates(attempt_id().as_str()));
assert!(!server.authenticates("something else entirely"));
assert!(!server.authenticates(""));
assert_eq!(attempt_id().as_str().len(), PairingAttemptId::MIN_LEN);
assert!(PairingAttemptId::from_entropy(&[0u8; 23]).is_err());
assert_eq!(
alloc::format!("{:?}", attempt_id()),
"PairingAttemptId(<redacted>)"
);
}
#[test]
fn a_client_that_gives_up_says_so_and_no_pairing_is_stored() {
let Run {
mut client,
mut server,
} = setup(Role::Cem, Deployment::Lan, Deployment::Lan);
let request = client.request_pairing(&CLIENT_CHALLENGE).unwrap();
let (_, accepted) = server
.request_pairing(
&request,
&code().token,
&SERVER_CHALLENGE,
attempt_id(),
t(0),
)
.unwrap();
client
.accept(accepted, binding(), Deployment::Lan, t(1))
.unwrap();
let body = client.abandon();
assert!(!body.success);
assert!(server.finalize(body, t(2)).unwrap().is_none());
}
#[test]
fn the_request_body_is_the_shape_the_openapi_defines() {
let Run { mut client, .. } = setup(Role::Cem, Deployment::Lan, Deployment::Lan);
let request = client.request_pairing(&CLIENT_CHALLENGE).unwrap();
let json = serde_json::to_value(&request).expect("serializable");
for key in [
"clientNodeDescription",
"clientEndpointDescription",
"supportedCommunicationProtocols",
"supportedS2MessageVersions",
"supportedHmacHashingAlgorithms",
"clientHmacChallenge",
] {
assert!(json.get(key).is_some(), "missing required property {key}");
}
assert!(json.get("nodeId").is_none());
assert!(json.get("nodeIdAlias").is_some());
assert!(json.get("forcePairing").is_none());
assert_eq!(
json["clientNodeDescription"]["role"].as_str(),
Some("CEM"),
"the role enum is spelled as the schema spells it"
);
}
}