alien-signing 3.3.67

Signed statements, signer lists, signing settings and the install ledger for installs that run only what the vendor signed
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
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
//! The channel of a signed exec session, without any network code.
//!
//! 1. The enforcer sends a [`Challenge`]: a fresh nonce and an ephemeral
//!    X25519 key for this session.
//! 2. The engineer's device signs a `session/v1` statement naming that nonce,
//!    that key and the client's own ephemeral key.
//! 3. Both sides run `Noise_KK_25519_ChaChaPoly_SHA256` with the two keys,
//!    bound to the statement's digest, so the session is the one that was
//!    signed. Every later frame is encrypted and numbered: whoever relays
//!    the frames reads nothing, and a frame it injects, drops, reorders or
//!    replays fails to decrypt.
//! 4. The enforcer appends every frame to a hash-chained [`Transcript`].

use alien_error::AlienError;
use base64::engine::general_purpose::STANDARD;
use base64::Engine as _;
use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};
use sha2::{Digest, Sha256};

use crate::envelope::Kind;
use crate::error::{ErrorData, Result};

/// Longest exec session a statement may allow.
pub const MAX_SESSION_SECONDS: u32 = 30 * 60;

/// What a session runs.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct SessionTarget {
    /// Machine id, for machine sessions.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub machine: Option<String>,
    /// Workload name, for replica sessions.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub workload: Option<String>,
}

/// `session/v1`: one exec session.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct SessionBody {
    /// Unique session id; an enforcer refuses one it has seen.
    pub session_id: String,
    /// What the session reaches.
    pub target: SessionTarget,
    /// Program and arguments, or absent for the default shell.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub argv: Option<Vec<String>>,
    /// Whether a terminal is allocated.
    pub tty: bool,
    /// Longest the session may last.
    pub max_duration_seconds: u32,
    /// Who asked, for the transcript.
    pub requester: String,
    /// Why, for the transcript.
    pub reason: String,
    /// The enforcer's fresh nonce, base64.
    pub verifier_nonce: String,
    /// The enforcer's ephemeral public key for this session, base64.
    pub verifier_key: String,
    /// The client's ephemeral public key, base64.
    pub client_key: String,
}

/// What the enforcer handed out for one session request.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SessionChallenge {
    /// Nonce the enforcer generated, base64.
    pub nonce: String,
    /// Enforcer's ephemeral public key, base64.
    pub verifier_key: String,
    /// When the nonce was issued.
    pub issued_at: DateTime<Utc>,
    /// How long a nonce stays usable.
    pub nonce_lifetime_seconds: u32,
}

impl SessionBody {
    /// Check the session against the challenge the enforcer issued. The
    /// caller also records the session id and refuses one it has seen.
    pub fn check(&self, challenge: &SessionChallenge, now: DateTime<Utc>) -> Result<()> {
        if self.verifier_nonce != challenge.nonce {
            return Err(refused(
                Kind::Session,
                "the nonce is not the one this enforcer issued",
            ));
        }
        if self.verifier_key != challenge.verifier_key {
            return Err(refused(
                Kind::Session,
                "the session is bound to another enforcer key",
            ));
        }
        let age = now.signed_duration_since(challenge.issued_at).num_seconds();
        if age < 0 || age > i64::from(challenge.nonce_lifetime_seconds) {
            return Err(refused(Kind::Session, "the nonce has expired"));
        }
        if self.max_duration_seconds == 0 || self.max_duration_seconds > MAX_SESSION_SECONDS {
            return Err(refused(
                Kind::Session,
                format!("a session may last 1 to {MAX_SESSION_SECONDS} seconds"),
            ));
        }
        if self.session_id.is_empty() || self.client_key.is_empty() {
            return Err(refused(
                Kind::Session,
                "the session id and client key are required",
            ));
        }
        Ok(())
    }
}

const NOISE_PATTERN: &str = "Noise_KK_25519_ChaChaPoly_SHA256";
/// Largest Noise message.
const MAX_MESSAGE: usize = 65535;
/// Plaintext room in one Noise message, after the tag and the frame kind.
pub const MAX_FRAME_PAYLOAD: usize = MAX_MESSAGE - 16 - 1;
/// How long a challenge's nonce stays usable.
pub const NONCE_LIFETIME_SECONDS: u32 = 120;

/// An X25519 key pair for one session.
pub struct SessionKeys {
    private: Vec<u8>,
    public: Vec<u8>,
}

impl SessionKeys {
    /// A new key pair.
    pub fn generate() -> Result<Self> {
        let keypair = builder()?
            .generate_keypair()
            .map_err(|error| channel_error(format!("could not generate a session key: {error}")))?;
        Ok(Self {
            private: keypair.private,
            public: keypair.public,
        })
    }

    /// The public key, base64.
    pub fn public_key(&self) -> String {
        STANDARD.encode(&self.public)
    }
}

/// What the enforcer sends first.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct Challenge {
    /// Session id the enforcer was asked to open.
    pub session_id: String,
    /// Fresh random nonce, base64.
    pub nonce: String,
    /// The enforcer's ephemeral public key for this session, base64.
    pub verifier_key: String,
    /// When the enforcer issued it.
    pub issued_at: DateTime<Utc>,
}

impl Challenge {
    /// A new challenge for `session_id` with `keys`.
    pub fn new(session_id: &str, keys: &SessionKeys) -> Result<Self> {
        let mut nonce = [0u8; 32];
        getrandom::fill(&mut nonce)
            .map_err(|error| channel_error(format!("no randomness: {error}")))?;
        Ok(Self {
            session_id: session_id.to_string(),
            nonce: STANDARD.encode(nonce),
            verifier_key: keys.public_key(),
            issued_at: Utc::now(),
        })
    }

    /// What [`SessionBody::check`] compares the statement to.
    pub fn expectation(&self) -> SessionChallenge {
        SessionChallenge {
            nonce: self.nonce.clone(),
            verifier_key: self.verifier_key.clone(),
            issued_at: self.issued_at,
            nonce_lifetime_seconds: NONCE_LIFETIME_SECONDS,
        }
    }
}

/// One side of the handshake, before it completes.
pub struct Handshake {
    state: snow::HandshakeState,
}

/// Which side of the channel this is.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Side {
    /// The engineer's CLI, which starts the handshake.
    Client,
    /// The enforcer.
    Enforcer,
}

impl Handshake {
    /// Start a handshake. `own` are this side's session keys, `remote_key` the
    /// other side's public key (base64) and `statement_digest` the signed
    /// session statement's digest, which both sides mix in.
    pub fn new(
        side: Side,
        own: &SessionKeys,
        remote_key: &str,
        statement_digest: &str,
    ) -> Result<Self> {
        let remote = STANDARD
            .decode(remote_key)
            .map_err(|_| channel_error("the remote session key is not base64"))?;
        if remote.len() != 32 {
            return Err(channel_error("the remote session key is not 32 bytes"));
        }
        let prologue = prologue(statement_digest);
        let builder = builder()?
            .local_private_key(&own.private)
            .map_err(|error| channel_error(format!("bad local key: {error}")))?
            .remote_public_key(&remote)
            .map_err(|error| channel_error(format!("bad remote key: {error}")))?
            .prologue(&prologue)
            .map_err(|error| channel_error(format!("bad prologue: {error}")))?;
        let state = match side {
            Side::Client => builder.build_initiator(),
            Side::Enforcer => builder.build_responder(),
        }
        .map_err(|error| channel_error(format!("could not start the handshake: {error}")))?;
        Ok(Self { state })
    }

    /// The next handshake message to send.
    pub fn write(&mut self) -> Result<Vec<u8>> {
        let mut message = vec![0u8; MAX_MESSAGE];
        let length = self
            .state
            .write_message(&[], &mut message)
            .map_err(|error| channel_error(format!("handshake failed: {error}")))?;
        message.truncate(length);
        Ok(message)
    }

    /// Read the other side's handshake message.
    pub fn read(&mut self, message: &[u8]) -> Result<()> {
        let mut payload = vec![0u8; MAX_MESSAGE];
        self.state
            .read_message(message, &mut payload)
            .map_err(|error| channel_error(format!("handshake failed: {error}")))?;
        Ok(())
    }

    /// Finish into an encrypted channel.
    pub fn finish(self) -> Result<Channel> {
        if !self.state.is_handshake_finished() {
            return Err(channel_error("the handshake is not finished"));
        }
        let transport = self
            .state
            .into_transport_mode()
            .map_err(|error| channel_error(format!("handshake failed: {error}")))?;
        Ok(Channel { transport })
    }
}

/// What one frame carries.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum FrameKind {
    /// Terminal or process bytes.
    Data,
    /// A JSON control message (resize, exit, error).
    Control,
}

/// An encrypted, numbered channel.
pub struct Channel {
    transport: snow::TransportState,
}

impl Channel {
    /// Encrypt one frame.
    pub fn seal(&mut self, kind: FrameKind, payload: &[u8]) -> Result<Vec<u8>> {
        if payload.len() > MAX_FRAME_PAYLOAD {
            return Err(channel_error("the frame is too large"));
        }
        let mut plaintext = Vec::with_capacity(payload.len() + 1);
        plaintext.push(match kind {
            FrameKind::Data => 0,
            FrameKind::Control => 1,
        });
        plaintext.extend_from_slice(payload);
        let mut message = vec![0u8; plaintext.len() + 16];
        let length = self
            .transport
            .write_message(&plaintext, &mut message)
            .map_err(|error| channel_error(format!("could not encrypt a frame: {error}")))?;
        message.truncate(length);
        Ok(message)
    }

    /// Decrypt one frame. A frame that was changed, injected, replayed or
    /// reordered fails, and the channel can't be used after that.
    pub fn open(&mut self, message: &[u8]) -> Result<(FrameKind, Vec<u8>)> {
        let mut plaintext = vec![0u8; message.len()];
        let length = self
            .transport
            .read_message(message, &mut plaintext)
            .map_err(|_| {
                channel_error("a frame failed to decrypt: it was changed, injected or replayed")
            })?;
        plaintext.truncate(length);
        let (kind, payload) = plaintext
            .split_first()
            .ok_or_else(|| channel_error("an empty frame"))?;
        let kind = match kind {
            0 => FrameKind::Data,
            1 => FrameKind::Control,
            _ => return Err(channel_error("an unknown frame kind")),
        };
        Ok((kind, payload.to_vec()))
    }
}

/// Direction of a transcript entry.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub enum Direction {
    /// From the engineer to the enforcer.
    In,
    /// From the enforcer to the engineer.
    Out,
}

/// One transcript entry. Each names the hash of the one before, so an entry
/// that is removed or changed breaks the chain.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct TranscriptEntry {
    /// Session id.
    pub session_id: String,
    /// Position in the session, from 0. Entry 0 holds the statement.
    pub index: u64,
    /// `sha256:<hex>` of the previous entry, or the statement digest for entry 0.
    pub previous: String,
    /// When it was recorded.
    pub at: DateTime<Utc>,
    /// Direction, for frames.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub direction: Option<Direction>,
    /// Base64 of the frame, or of the statement JSON for entry 0.
    pub data: String,
}

impl TranscriptEntry {
    /// `sha256:<hex>` of this entry's JSON.
    pub fn digest(&self) -> String {
        let bytes = serde_json::to_vec(self).expect("an entry always serializes");
        format!("sha256:{}", hex::encode(Sha256::digest(bytes)))
    }
}

/// A hash-chained transcript of one session.
pub struct Transcript {
    session_id: String,
    index: u64,
    previous: String,
}

impl Transcript {
    /// Start with the signed statement as entry 0.
    pub fn start(
        session_id: &str,
        statement_digest: &str,
        statement_json: &str,
    ) -> (Self, TranscriptEntry) {
        let entry = TranscriptEntry {
            session_id: session_id.to_string(),
            index: 0,
            previous: statement_digest.to_string(),
            at: Utc::now(),
            direction: None,
            data: STANDARD.encode(statement_json),
        };
        let transcript = Self {
            session_id: session_id.to_string(),
            index: 1,
            previous: entry.digest(),
        };
        (transcript, entry)
    }

    /// Record one frame.
    pub fn record(&mut self, direction: Direction, bytes: &[u8]) -> TranscriptEntry {
        let entry = TranscriptEntry {
            session_id: self.session_id.clone(),
            index: self.index,
            previous: self.previous.clone(),
            at: Utc::now(),
            direction: Some(direction),
            data: STANDARD.encode(bytes),
        };
        self.index += 1;
        self.previous = entry.digest();
        entry
    }
}

/// Check that `entries` form one unbroken chain from the statement.
pub fn verify_transcript(statement_digest: &str, entries: &[TranscriptEntry]) -> Result<()> {
    let mut previous = statement_digest.to_string();
    for (index, entry) in entries.iter().enumerate() {
        if entry.index != index as u64 || entry.previous != previous {
            return Err(channel_error(format!(
                "the transcript breaks at entry {index}"
            )));
        }
        previous = entry.digest();
    }
    Ok(())
}

fn builder() -> Result<snow::Builder<'static>> {
    let params: snow::params::NoiseParams = NOISE_PATTERN
        .parse()
        .map_err(|error| channel_error(format!("bad noise pattern: {error:?}")))?;
    Ok(snow::Builder::new(params))
}

fn prologue(statement_digest: &str) -> Vec<u8> {
    format!("session/v1 {statement_digest}").into_bytes()
}

fn channel_error(reason: impl Into<String>) -> AlienError<ErrorData> {
    AlienError::new(ErrorData::BodyRefused {
        kind: "session/v1".to_string(),
        reason: reason.into(),
    })
}

fn refused(kind: Kind, reason: impl Into<String>) -> AlienError<ErrorData> {
    AlienError::new(ErrorData::BodyRefused {
        kind: kind.as_str().to_string(),
        reason: reason.into(),
    })
}

#[cfg(test)]
mod tests {
    use super::*;

    fn pair(digest_client: &str, digest_enforcer: &str) -> Result<(Channel, Channel)> {
        let client_keys = SessionKeys::generate()?;
        let enforcer_keys = SessionKeys::generate()?;
        let mut client = Handshake::new(
            Side::Client,
            &client_keys,
            &enforcer_keys.public_key(),
            digest_client,
        )?;
        let mut enforcer = Handshake::new(
            Side::Enforcer,
            &enforcer_keys,
            &client_keys.public_key(),
            digest_enforcer,
        )?;
        enforcer.read(&client.write()?)?;
        client.read(&enforcer.write()?)?;
        Ok((client.finish()?, enforcer.finish()?))
    }

    #[test]
    fn frames_cross_the_channel_and_nothing_else_does() {
        let (mut client, mut enforcer) = pair("sha256:s", "sha256:s").unwrap();
        let first = client.seal(FrameKind::Data, b"ls -la\n").unwrap();
        let second = client.seal(FrameKind::Data, b"whoami\n").unwrap();
        assert!(
            !first.windows(6).any(|window| window == b"ls -la"),
            "the relay sees ciphertext"
        );

        // A relay that drops the first frame or injects its own breaks the channel.
        let mut skipped = pair("sha256:s", "sha256:s").unwrap();
        let a = skipped.0.seal(FrameKind::Data, b"one").unwrap();
        let b = skipped.0.seal(FrameKind::Data, b"two").unwrap();
        skipped
            .1
            .open(&b)
            .expect_err("a reordered or dropped frame fails");
        drop(a);

        assert_eq!(
            enforcer.open(&first).unwrap(),
            (FrameKind::Data, b"ls -la\n".to_vec())
        );
        enforcer.open(&first).expect_err("a replayed frame fails");

        let (mut client2, mut enforcer2) = pair("sha256:s", "sha256:s").unwrap();
        let mut forged = client2.seal(FrameKind::Data, b"exit\n").unwrap();
        forged[3] ^= 0x01;
        enforcer2.open(&forged).expect_err("a changed frame fails");
        drop((second, client2));

        let reply = enforcer
            .seal(FrameKind::Control, br#"{"type":"exit","exitCode":0}"#)
            .unwrap();
        assert_eq!(client.open(&reply).unwrap().0, FrameKind::Control);
    }

    #[test]
    fn the_handshake_is_bound_to_the_signed_statement() {
        assert!(
            pair("sha256:signed", "sha256:other").is_err(),
            "a different statement can't complete the handshake"
        );
    }

    #[test]
    fn the_handshake_needs_the_keys_the_statement_names() {
        let client_keys = SessionKeys::generate().unwrap();
        let enforcer_keys = SessionKeys::generate().unwrap();
        let relay_keys = SessionKeys::generate().unwrap();
        // The relay substitutes its own key for the enforcer's.
        let mut client = Handshake::new(
            Side::Client,
            &client_keys,
            &relay_keys.public_key(),
            "sha256:s",
        )
        .unwrap();
        let mut enforcer = Handshake::new(
            Side::Enforcer,
            &enforcer_keys,
            &client_keys.public_key(),
            "sha256:s",
        )
        .unwrap();
        assert!(enforcer.read(&client.write().unwrap()).is_err());
    }

    #[test]
    fn a_transcript_with_a_removed_or_changed_entry_is_caught() {
        let (mut transcript, first) = Transcript::start("ses_1", "sha256:statement", "{}");
        let mut entries = vec![first];
        entries.push(transcript.record(Direction::In, b"rm -rf /tmp/x\n"));
        entries.push(transcript.record(Direction::Out, b"done\n"));
        verify_transcript("sha256:statement", &entries).unwrap();

        let mut removed = entries.clone();
        removed.remove(1);
        verify_transcript("sha256:statement", &removed).expect_err("a removed entry is caught");
        let mut changed = entries.clone();
        changed[1].data = STANDARD.encode(b"ls\n");
        verify_transcript("sha256:statement", &changed).expect_err("a changed entry is caught");
        verify_transcript("sha256:other", &entries).expect_err("another statement is caught");
    }
}