alpine-protocol-rs 2.0.9

Authenticated Lighting Protocol (alpine): secure control-plane + streaming guard for lighting data.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147

use async_trait::async_trait;
use uuid::Uuid;

use super::{
    HandshakeContext, HandshakeError, HandshakeMessage, HandshakeOutcome, HandshakeParticipant,
    HandshakeTransport,
};
use crate::crypto::{compute_mac, KeyExchange};
use crate::messages::{
    CapabilitySet, DeviceIdentity, MessageType, SessionAck, SessionEstablished, SessionInit,
    SessionReady,
};

/// Controller-side handshake driver implementing the ALPINE 1.0 flow.
pub struct ClientHandshake<A, K>
where
    A: super::ChallengeAuthenticator + Send + Sync,
    K: KeyExchange + Send + Sync,
{
    pub identity: DeviceIdentity,
    pub capabilities: CapabilitySet,
    pub authenticator: A,
    pub key_exchange: K,
    pub context: HandshakeContext,
}

#[async_trait]
impl<A, K> HandshakeParticipant for ClientHandshake<A, K>
where
    A: super::ChallengeAuthenticator + Send + Sync,
    K: KeyExchange + Send + Sync,
{
    async fn run<T: HandshakeTransport + Send>(
        &self,
        transport: &mut T,
    ) -> Result<HandshakeOutcome, HandshakeError> {
        let controller_nonce = super::new_nonce().to_vec();
        let session_id = Uuid::new_v4();

        // 1) Controller -> device: session_init
        let init = SessionInit {
            message_type: MessageType::SessionInit,
            controller_nonce: controller_nonce.clone(),
            controller_pubkey: self.key_exchange.public_key(),
            requested: self.capabilities.clone(),
            session_id,
        };
        transport.send(HandshakeMessage::SessionInit(init)).await?;

        // 2) Device -> controller: session_ack
        let ack = match transport.recv().await? {
            HandshakeMessage::SessionAck(ack) => ack,
            other => {
                return Err(HandshakeError::Protocol(format!(
                    "expected SessionAck, got {:?}",
                    other
                )))
            }
        };
        validate_ack(&ack, session_id, &controller_nonce, &self.context)?;

        // 3) Verify device signature over the controller nonce.
        let sig_valid = self
            .authenticator
            .verify_challenge(&controller_nonce, &ack.signature);
        if !sig_valid {
            return Err(HandshakeError::Authentication(
                "device signature validation failed".into(),
            ));
        }

        // 4) Derive shared keys (HKDF over concatenated nonces).
        let mut salt = controller_nonce.clone();
        salt.extend_from_slice(&ack.device_nonce);
        let keys = self
            .key_exchange
            .derive_keys(&ack.device_pubkey, &salt)
            .map_err(|e| HandshakeError::Authentication(format!("{}", e)))?;

        // 5) Controller -> device: session_ready (MAC proves key possession).
        let mac = compute_mac(&keys, 0, session_id.as_bytes(), ack.device_nonce.as_slice())
            .map_err(|e| HandshakeError::Authentication(e.to_string()))?;
        let ready = SessionReady {
            message_type: MessageType::SessionReady,
            session_id,
            mac,
        };
        transport
            .send(HandshakeMessage::SessionReady(ready))
            .await?;

        // 6) Device -> controller: session_complete
        let complete = match transport.recv().await? {
            HandshakeMessage::SessionComplete(c) => c,
            other => {
                return Err(HandshakeError::Protocol(format!(
                    "expected SessionComplete, got {:?}",
                    other
                )))
            }
        };
        if !complete.ok {
            return Err(HandshakeError::Authentication(
                "device rejected session_ready".into(),
            ));
        }

        let established = SessionEstablished {
            session_id,
            controller_nonce,
            device_nonce: ack.device_nonce,
            capabilities: ack.capabilities,
            device_identity: ack.device_identity,
        };

        Ok(HandshakeOutcome { established, keys })
    }
}

fn validate_ack(
    ack: &SessionAck,
    session_id: Uuid,
    controller_nonce: &[u8],
    context: &HandshakeContext,
) -> Result<(), HandshakeError> {
    if ack.session_id != session_id {
        return Err(HandshakeError::Protocol(
            "session_id mismatch between init and ack".into(),
        ));
    }

    if ack.device_nonce.len() != controller_nonce.len() {
        return Err(HandshakeError::Protocol(
            "device nonce length mismatch".into(),
        ));
    }

    if let Some(expected) = &context.expected_controller {
        if expected != &session_id.to_string() {
            return Err(HandshakeError::Authentication(
                "controller identity rejected".into(),
            ));
        }
    }

    Ok(())
}