typhoon-protocol 0.1.0

A sample implementation of TYPHOON protocol
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
148
149
150
151
152
153
154
155
156
157
158
159
160

use x25519_dalek::EphemeralSecret;

use crate::bytes::{ByteBuffer, BytePool, DynamicByteBuffer, FixedByteBuffer};
use crate::certificate::ClientCertificate;
#[cfg(any(feature = "fast_software", feature = "fast_hardware"))]
use crate::certificate::ObfuscationBufferContainer;
use crate::crypto::error::{CryptoError, HandshakeError};
use crate::crypto::symmetric::{ObfuscationTranscript, Symmetric};
use crate::tailer::IdentityType;

/// Ephemeral client handshake state: X25519 secret, McEliece shared secret, nonce, initial key.
pub(crate) struct ClientData {
    pub ephemeral_key: EphemeralSecret,
    pub shared_secret: FixedByteBuffer<32>,
    pub nonce: FixedByteBuffer<32>,
    pub initial_key: FixedByteBuffer<32>,
}

/// Client-side cryptographic tool for TYPHOON protocol.
#[derive(Clone)]
pub struct ClientCryptoTool<T: IdentityType + Clone> {
    cert: ClientCertificate,
    identity: T,
    key: Symmetric,
    #[cfg(any(feature = "fast_software", feature = "fast_hardware"))]
    obfuscation_key: Symmetric,
}

impl<T: IdentityType + Clone> ClientCryptoTool<T> {
    /// Create a new ClientCryptoTool with the given certificate and identity.
    #[cfg(any(feature = "fast_software", feature = "fast_hardware"))]
    pub(crate) fn new(cert: ClientCertificate, identity: T, initial_key: &impl ByteBuffer) -> Self {
        let obfs_buffer = cert.obfuscation_buffer();
        Self {
            cert,
            identity,
            key: Symmetric::new(initial_key),
            obfuscation_key: Symmetric::new_split(&obfs_buffer, initial_key),
        }
    }

    /// Create a new ClientCryptoTool with the given certificate and identity.
    #[cfg(any(feature = "full_software", feature = "full_hardware"))]
    pub(crate) fn new(cert: ClientCertificate, identity: T, initial_key: &impl ByteBuffer) -> Self {
        Self {
            cert,
            identity,
            key: Symmetric::new(initial_key),
        }
    }

    /// Get the identity bytes.
    #[inline]
    pub fn identity(&self) -> T {
        self.identity.clone()
    }

    /// Client handshake step 1: generate ephemeral keys, encapsulate with McEliece, obfuscate.
    /// If `initial_data` is non-empty, encrypts it with the initial key and appends to the handshake.
    /// Returns (ClientData, handshake_secret, initial_encryption_key).
    pub(crate) fn create_handshake(&self, pool: &BytePool, initial_data: &[u8]) -> (ClientData, DynamicByteBuffer, FixedByteBuffer<32>) {
        self.cert.encapsulate_handshake_client(pool, initial_data)
    }

    /// Client handshake step 2: process server response, verify signature, derive session key.
    /// Returns (session_key, server_initial_data).
    pub(crate) fn process_handshake_response(&self, data: ClientData, handshake_secret: DynamicByteBuffer, pool: &BytePool) -> Result<(FixedByteBuffer<32>, DynamicByteBuffer), HandshakeError> {
        self.cert.decapsulate_handshake_client(data, handshake_secret, pool)
    }

    /// Encrypt payload data with session key.
    pub fn encrypt_payload(&mut self, plaintext: DynamicByteBuffer, additional_data: Option<&DynamicByteBuffer>) -> Result<DynamicByteBuffer, CryptoError> {
        self.key.encrypt_auth(plaintext, additional_data)
    }

    /// Decrypt payload data with session key.
    pub fn decrypt_payload(&mut self, ciphertext: DynamicByteBuffer, additional_data: Option<&DynamicByteBuffer>) -> Result<DynamicByteBuffer, CryptoError> {
        self.key.decrypt_auth(ciphertext, additional_data)
    }

    /// Obfuscate (encrypt) tailer bytes for sending.
    #[cfg(any(feature = "fast_software", feature = "fast_hardware"))]
    pub fn obfuscate_tailer(&mut self, plaintext: DynamicByteBuffer, _: &BytePool) -> Result<DynamicByteBuffer, CryptoError> {
        self.obfuscation_key.encrypt_auth(plaintext, None::<&DynamicByteBuffer>)
    }

    /// Obfuscate (encrypt) tailer bytes for sending.
    #[cfg(any(feature = "full_software", feature = "full_hardware"))]
    pub fn obfuscate_tailer(&mut self, plaintext: DynamicByteBuffer, pool: &BytePool) -> Result<DynamicByteBuffer, CryptoError> {
        self.cert.encrypt_obfuscate(plaintext, pool).map_err(|e| CryptoError::authentication_error(&e.to_string()))
    }

    /// Deobfuscate (decrypt) received tailer bytes.
    #[cfg(any(feature = "fast_software", feature = "fast_hardware"))]
    pub fn deobfuscate_tailer(&mut self, ciphertext: DynamicByteBuffer, pool: &BytePool) -> Result<(DynamicByteBuffer, ObfuscationTranscript), CryptoError> {
        self.obfuscation_key.decrypt_no_verify(ciphertext, pool)
    }

    /// Deobfuscate (decrypt) received tailer bytes.
    #[cfg(any(feature = "full_software", feature = "full_hardware"))]
    pub fn deobfuscate_tailer(&mut self, ciphertext: DynamicByteBuffer, _pool: &BytePool) -> Result<(DynamicByteBuffer, ObfuscationTranscript), CryptoError> {
        self.key.decrypt_auth(ciphertext, None::<&DynamicByteBuffer>).map(|r| (r, ObfuscationTranscript {}))
    }

    /// Verify the authentication (fast mode).
    #[cfg(any(feature = "fast_software", feature = "fast_hardware"))]
    pub fn verify_tailer(&mut self, transcript: ObfuscationTranscript) -> Result<(), CryptoError> {
        self.obfuscation_key.verify_decrypted(transcript, None::<&DynamicByteBuffer>)
    }

    /// Verify tailer (no-op in full mode).
    #[cfg(any(feature = "full_software", feature = "full_hardware"))]
    pub fn verify_tailer(&mut self, _: ObfuscationTranscript) -> Result<(), CryptoError> {
        Ok(())
    }

    /// Create a copy of this crypto tool with a different session key.
    #[cfg(any(feature = "fast_software", feature = "fast_hardware"))]
    pub fn with_key(&self, new_key: &impl ByteBuffer) -> Self {
        let obfs_buffer = self.cert.obfuscation_buffer();
        Self {
            cert: self.cert.clone(),
            identity: self.identity.clone(),
            key: Symmetric::new(new_key),
            obfuscation_key: Symmetric::new_split(&obfs_buffer, new_key),
        }
    }

    /// Create a copy of this crypto tool with a different session key.
    #[cfg(any(feature = "full_software", feature = "full_hardware"))]
    pub fn with_key(&self, new_key: &impl ByteBuffer) -> Self {
        Self {
            cert: self.cert.clone(),
            identity: self.identity.clone(),
            key: Symmetric::new(new_key),
        }
    }

    /// Create a copy of this crypto tool with a different session key and identity.
    #[cfg(any(feature = "fast_software", feature = "fast_hardware"))]
    pub fn with_key_and_identity(&self, new_key: &impl ByteBuffer, new_identity: T) -> Self {
        let obfs_buffer = self.cert.obfuscation_buffer();
        Self {
            cert: self.cert.clone(),
            identity: new_identity,
            key: Symmetric::new(new_key),
            obfuscation_key: Symmetric::new_split(&obfs_buffer, new_key),
        }
    }

    /// Create a copy of this crypto tool with a different session key and identity.
    #[cfg(any(feature = "full_software", feature = "full_hardware"))]
    pub fn with_key_and_identity(&self, new_key: &impl ByteBuffer, new_identity: T) -> Self {
        Self {
            cert: self.cert.clone(),
            identity: new_identity,
            key: Symmetric::new(new_key),
        }
    }
}