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
use std::env;
use std::fs::{File, OpenOptions};
use std::path::Path;
use std::io;
use std::io::Write;
use std::sync::Mutex;
#[cfg(feature = "logging")]
use crate::log::warn;
/// This trait represents the ability to do something useful
/// with key material, such as logging it to a file for debugging.
///
/// Naturally, secrets passed over the interface are *extremely*
/// sensitive and can break the security of past, present and
/// future sessions.
///
/// You'll likely want some interior mutability in your
/// implementation to make this useful.
///
/// See `KeyLogFile` that implements the standard `SSLKEYLOGFILE`
/// environment variable behaviour.
pub trait KeyLog : Send + Sync {
/// Log the given `secret`. `client_random` is provided for
/// session identification. `label` describes precisely what
/// `secret` means:
///
/// - `CLIENT_RANDOM`: `secret` is the master secret for a TLSv1.2 session.
/// - `CLIENT_EARLY_TRAFFIC_SECRET`: `secret` encrypts early data
/// transmitted by a client
/// - `SERVER_HANDSHAKE_TRAFFIC_SECRET`: `secret` encrypts
/// handshake messages from the server during a TLSv1.3 handshake.
/// - `CLIENT_HANDSHAKE_TRAFFIC_SECRET`: `secret` encrypts
/// handshake messages from the client during a TLSv1.3 handshake.
/// - `SERVER_TRAFFIC_SECRET_0`: `secret` encrypts post-handshake data
/// from the server in a TLSv1.3 session.
/// - `CLIENT_TRAFFIC_SECRET_0`: `secret` encrypts post-handshake data
/// from the client in a TLSv1.3 session.
/// - `EXPORTER_SECRET`: `secret` is the post-handshake exporter secret
/// in a TLSv1.3 session.
///
/// These strings are selected to match the NSS key log format:
/// https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/Key_Log_Format
fn log(&self, label: &str, client_random: &[u8], secret: &[u8]);
/// Indicates whether the secret with label `label` will be logged.
///
/// If `will_log` returns true then `log` will be called with the secret.
/// Otherwise, `log` will not be called for the secret. This is a
/// performance optimization.
fn will_log(&self, _label: &str) -> bool { true }
}
/// KeyLog that does exactly nothing.
pub struct NoKeyLog;
impl KeyLog for NoKeyLog {
fn log(&self, _: &str, _: &[u8], _: &[u8]) {}
#[inline]
fn will_log(&self, _label: &str) -> bool { false }
}
// Internal mutable state for KeyLogFile
struct KeyLogFileInner {
file: Option<File>,
buf: Vec<u8>,
}
impl KeyLogFileInner {
fn new(var: Result<String, env::VarError>) -> Self {
let path = match var {
Ok(ref s) => Path::new(s),
Err(env::VarError::NotUnicode(ref s)) => Path::new(s),
Err(env::VarError::NotPresent) => {
return KeyLogFileInner {
file: None,
buf: Vec::new(),
};
}
};
#[cfg_attr(not(feature = "logging"), allow(unused_variables))]
let file = match OpenOptions::new()
.append(true)
.create(true)
.open(path) {
Ok(f) => Some(f),
Err(e) => {
warn!("unable to create key log file {:?}: {}", path, e);
None
}
};
KeyLogFileInner {
file,
buf: Vec::new(),
}
}
fn try_write(&mut self, label: &str, client_random: &[u8], secret: &[u8]) -> io::Result<()> {
let mut file = match self.file {
None => { return Ok(()); }
Some(ref f) => f,
};
self.buf.truncate(0);
write!(self.buf, "{} ", label)?;
for b in client_random.iter() {
write!(self.buf, "{:02x}", b)?;
}
write!(self.buf, " ")?;
for b in secret.iter() {
write!(self.buf, "{:02x}", b)?;
}
writeln!(self.buf)?;
file.write_all(&self.buf)
}
}
/// `KeyLog` implementation that opens a file whose name is
/// given by the `SSLKEYLOGFILE` environment variable, and writes
/// keys into it.
///
/// If `SSLKEYLOGFILE` is not set, this does nothing.
///
/// If such a file cannot be opened, or cannot be written then
/// this does nothing but logs errors at warning-level.
pub struct KeyLogFile(Mutex<KeyLogFileInner>);
impl KeyLogFile {
/// Makes a new `KeyLogFile`. The environment variable is
/// inspected and the named file is opened during this call.
pub fn new() -> Self {
let var = env::var("SSLKEYLOGFILE");
KeyLogFile(Mutex::new(KeyLogFileInner::new(var)))
}
}
impl KeyLog for KeyLogFile {
fn log(&self, label: &str, client_random: &[u8], secret: &[u8]) {
#[cfg_attr(not(feature = "logging"), allow(unused_variables))]
match self.0.lock()
.unwrap()
.try_write(label, client_random, secret) {
Ok(()) => {},
Err(e) => {
warn!("error writing to key log file: {}", e);
}
}
}
}
#[cfg(all(test, target_os="linux"))]
mod test {
use super::*;
fn init() {
let _ = env_logger::builder().is_test(true).try_init();
}
#[test]
fn test_env_var_is_not_unicode() {
init();
let mut inner = KeyLogFileInner::new(Err(env::VarError::NotUnicode("/tmp/keylogfileinnertest".into())));
assert!(inner.try_write("label", b"random", b"secret").is_ok());
}
#[test]
fn test_env_var_is_not_set() {
init();
let mut inner = KeyLogFileInner::new(Err(env::VarError::NotPresent));
assert!(inner.try_write("label", b"random", b"secret").is_ok());
}
#[test]
fn test_env_var_cannot_be_opened() {
init();
let mut inner = KeyLogFileInner::new(Ok("/dev/does-not-exist".into()));
assert!(inner.try_write("label", b"random", b"secret").is_ok());
}
#[test]
fn test_env_var_cannot_be_written() {
init();
let mut inner = KeyLogFileInner::new(Ok("/dev/full".into()));
assert!(inner.try_write("label", b"random", b"secret").is_err());
}
}