1  # safelog
 2  
 3  Mark data as sensitive for logging purposes.
 4  
 5  Some information is too sensitive to routinely write to system logs, but
 6  must nonetheless sometimes be displayed.  This crate provides a way to mark
 7  such information, and log it conditionally, but not by default.
 8  
 9  ### Examples
10  
11  There are two main ways to mark a piece of data as sensitive: by storing it
12  within a [`Sensitive`] object long-term, or by wrapping it in a
13  [`Sensitive`] object right before passing it to a formatter:
14  
15  ```rust
16  use safelog::{Sensitive, sensitive};
17  
18  // With this declaration, a student's name and gpa will be suppressed by default
19  // when passing the student to Debug.
20  #[derive(Debug)]
21  struct Student {
22     name: Sensitive<String>,
23     grade: u8,
24     homeroom: String,
25     gpa: Sensitive<f32>,
26  }
27  
28  // In this function, a user's IP will not be printed by default.
29  fn record_login(username: &str, ip: &std::net::IpAddr) {
30      println!("Login from {} at {}", username, sensitive(ip));
31  }
32  ```
33  
34  You can disable safe-logging globally (across all threads) or locally
35  (across a single thread).
36  
37  ```rust
38  # let debug_mode = true;
39  # let log_encrypted_data = |_|();
40  # let big_secret = ();
41  use safelog::{disable_safe_logging, with_safe_logging_suppressed};
42  
43  // If we're running in debug mode, turn off safe logging
44  // globally.  Safe logging will remain disabled until the
45  // guard object is dropped.
46  let guard = if debug_mode {
47     // This call can fail if safe logging has already been enforced.
48     disable_safe_logging().ok()
49  } else {
50     None
51  };
52  
53  // If we know that it's safe to record sensitive data with a given API,
54  // we can disable safe logging temporarily. This affects only the current thread.
55  with_safe_logging_suppressed(|| log_encrypted_data(big_secret));
56  ```
57  
58  ### An example deployment
59  
60  This crate was originally created for use in the `arti` project, which tries
61  to implements the Tor anonymity protocol in Rust.  In `arti`, we want to
62  avoid logging information by default if it could compromise users'
63  anonymity, or create an incentive for attacking users and relays in order to
64  access their logs.
65  
66  In general, Arti treats the following information as [`Sensitive`]:
67    * Client addresses.
68    * The destinations (target addresses) of client requests.
69  
70  Arti does _not_ label all private information as `Sensitive`: when
71  information isn't _ever_ suitable for logging, we omit it entirely.
72  
73  License: MIT OR Apache-2.0