rustls 0.5.0

Rustls is a modern TLS library written in Rust.
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

use std::{fmt, error};
use std::error::Error;
use msgs::enums::{ContentType, HandshakeType, AlertDescription};
use webpki;

/// rustls reports protocol errors using this type.
#[derive(Debug, PartialEq, Clone)]
pub enum TLSError {
  /// We received a TLS message that isn't valid right now.
  /// `expect_types` lists the message types we can expect right now.
  /// `got_type` is the type we found.  This error is typically
  /// caused by a buggy TLS stack (the peer or this one), a broken
  /// network, or an attack.
  InappropriateMessage { expect_types: Vec<ContentType>, got_type: ContentType },

  /// We received a TLS handshake message that isn't valid right now.
  /// `expect_types` lists the handshake message types we can expect
  /// right now.  `got_type` is the type we found.
  InappropriateHandshakeMessage { expect_types: Vec<HandshakeType>, got_type: HandshakeType },

  /// The peer sent us a syntactically incorrect TLS message.
  CorruptMessage,

  /// The peer sent us a TLS message with invalid contents.
  CorruptMessagePayload(ContentType),

  /// The peer didn't give us any certificates.
  NoCertificatesPresented,

  /// We couldn't decrypt a message.  This is invariably fatal.
  DecryptError,

  /// The peer doesn't support a protocol version/feature we require.
  /// The parameter gives a hint as to what version/feature it is.
  PeerIncompatibleError(String),

  /// The peer deviated from the standard TLS protocol.
  /// The parameter gives a hint where.
  PeerMisbehavedError(String),

  /// We received a fatal alert.  This means the peer is unhappy.
  AlertReceived(AlertDescription),

  /// The presented certificate chain is invalid.
  WebPKIError(webpki::Error),

  /// A catch-all error for unlikely errors.
  General(String)
}

fn join<T: fmt::Debug>(vec: &Vec<T>) -> String {
  vec
    .iter()
    .map(|x| format!("{:?}", x))
    .collect::<Vec<String>>()
    .join(" or ")
}

impl fmt::Display for TLSError {
  fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
    match *self {
      TLSError::InappropriateMessage { ref expect_types, ref got_type }
        => write!(f, "{}: got {:?} when expecting {}",
                  self.description(), got_type,
                  join::<ContentType>(&expect_types)),
      TLSError::InappropriateHandshakeMessage { ref expect_types, ref got_type }
        => write!(f, "{}: got {:?} when expecting {}",
                  self.description(), got_type,
                  join::<HandshakeType>(&expect_types)),
      TLSError::CorruptMessagePayload(ref typ)
        => write!(f, "{} of type {:?}", self.description(), typ),
      TLSError::PeerIncompatibleError(ref why) | TLSError::PeerMisbehavedError(ref why)
        => write!(f, "{}: {}", self.description(), why),
      TLSError::AlertReceived(ref alert)
        => write!(f, "{}: {:?}", self.description(), alert),
      TLSError::WebPKIError(ref err)
        => write!(f, "{}: {:?}", self.description(), err),
      TLSError::CorruptMessage
        | TLSError::NoCertificatesPresented
        | TLSError::DecryptError
        => write!(f, "{}", self.description()),
      _ => write!(f, "{}: {:?}", self.description(), self)
    }
  }
}

impl error::Error for TLSError {
  fn description(&self) -> &str {
    match *self {
      TLSError::InappropriateMessage { .. } => "received unexpected message",
      TLSError::InappropriateHandshakeMessage { .. } => "received unexpected handshake message",
      TLSError::CorruptMessage => "received corrupt message",
      TLSError::CorruptMessagePayload(_) => "received corrupt message",
      TLSError::NoCertificatesPresented => "peer sent no certificates",
      TLSError::DecryptError => "cannot decrypt peer's message",
      TLSError::PeerIncompatibleError(_) => "peer is incompatible",
      TLSError::PeerMisbehavedError(_) => "peer misbehaved",
      TLSError::AlertReceived(_) => "received fatal alert",
      TLSError::WebPKIError(_) => "invalid certificate",
      TLSError::General(_) => "unexpected error" // (please file a bug)
    }
  }
}

#[cfg(test)]
mod tests {
  #[test]
  fn smoke() {
    use super::TLSError;
    use std::error::Error;
    use msgs::enums::{ContentType, HandshakeType, AlertDescription};
    use webpki;

    let all = vec![
      TLSError::InappropriateMessage {
        expect_types: vec![ ContentType::Alert ],
        got_type: ContentType::Handshake
      },
      TLSError::InappropriateHandshakeMessage {
        expect_types: vec![ HandshakeType::ClientHello, HandshakeType::Finished ],
        got_type: HandshakeType::ServerHello
      },
      TLSError::CorruptMessage,
      TLSError::CorruptMessagePayload(ContentType::Alert),
      TLSError::NoCertificatesPresented,
      TLSError::DecryptError,
      TLSError::PeerIncompatibleError("no tls1.2".to_string()),
      TLSError::PeerMisbehavedError("inconsistent something".to_string()),
      TLSError::AlertReceived(AlertDescription::ExportRestriction),
      TLSError::WebPKIError(webpki::Error::ExtensionValueInvalid),
      TLSError::General("undocumented error".to_string())
    ];

    for err in all {
      println!("{:?}:", err);
      println!("  desc '{}'", err.description());
      println!("  fmt '{}'", err);
    }
  }
}