[−][src]Crate tls_parser
TLS Parser
A TLS parser, implemented with the nom parser combinator framework.
The goal of this parser is to implement TLS messages analysis, for example to use rules from a network IDS, for ex during the TLS handshake.
It implements structures and parsing functions for records and messages, but need additional code to handle fragmentation, or to fully inspect messages. Parsing some TLS messages requires to know the previously selected parameters. See the rusticata TLS parser for a full example.
The code is available on Github and is part of the Rusticata project.
Parsing records
The main parsing functions are located in the tls.rs file. The entry functions are:
parse_tls_plaintext
: parses a record as plaintextparse_tls_encrypted
: read an encrypted record. The parser has no crypto or decryption features, so the content will be left as opaque data.
Examples
extern crate nom; extern crate tls_parser; use nom::{Err, IResult}; use tls_parser::parse_tls_plaintext; let bytes : &[u8]= include_bytes!("../assets/client_hello_dhe.bin"); // [ 0x16, 0x03, 0x01 ... ]; let res = parse_tls_plaintext(&bytes); match res { Ok((rem,record)) => { // rem is the remaining data (not parsed) // record is an object of type TlsRecord }, Err(Err::Incomplete(needed)) => { eprintln!("Defragmentation required (TLS record)"); }, Err(e) => { eprintln!("parse_tls_record_with_header failed: {:?}",e); } }
Note that knowing if a record is plaintext or not is the responsibility of the caller.
As reading TLS records may imply defragmenting records, some functions are provided to only read the record as opaque data (which ensures the record is complete and gives the record header) and then reading messages from data.
Here is an example of two-steps parsing:
// [ 0x16, 0x03, 0x01 ... ]; match parse_tls_raw_record(bytes) { Ok((rem, ref r)) => { match parse_tls_record_with_header(r.data, &r.hdr) { Ok((rem2,ref msg_list)) => { for msg in msg_list { // msg has type TlsMessage } } Err(Err::Incomplete(needed)) => { eprintln!("incomplete record") } Err(_) => { eprintln!("error while parsing record") } } } Err(Err::Incomplete(needed)) => { eprintln!("incomplete record header") } Err(_) => { eprintln!("error while parsing record header") } }
Some additional work is required if reading packets from the network, to support reassembly of TCP segments and reassembly of TLS records.
For a complete example of a TLS parser supporting defragmentation and states, see the rusticata/src/tls.rs file of the rusticata crate.
State machine
A TLS state machine is provided in tls_states.rs. The state machine is separated from the parsing functions, and is almost independent. It is implemented as a table of transitions, mainly for the handshake phase.
After reading a TLS message using the previous functions, the TLS state can be
updated using the tls_state_transition
function. If the transition succeeds,
it returns Ok(new_state)
, otherwise it returns Err(error_state)
.
struct ParseContext { state: TlsState, } match tls_state_transition(ctx.state, msg, to_server) { Ok(s) => { ctx.state = s; Ok(()) } Err(_) => { ctx.state = TlsState::Invalid; Err("Invalid state") } }
Implementation notes
When parsing messages, if a field is an integer corresponding to an enum of known values, it is not parsed as an enum type, but as an integer. While this complicates accesses, it allows to read invalid values and continue parsing (for an IDS, it's better to read values than to get a generic parse error).
Re-exports
pub extern crate rusticata_macros; |
Structs
CertificateStatusType | |
DTLSClientHello | |
DTLSHelloVerifyRequest | |
DTLSMessageHandshake | DTLS Generic handshake message |
DTLSPlaintext | DTLS Plaintext record |
DTLSRawRecord | |
DTLSRecordHeader | DTLS Plaintext record header |
DigitallySigned | DigitallySigned structure from [RFC2246] section 4.7 has no algorithm definition. This should be deprecated in favor if DigitallySigned structure from [RFC5246] section 4.7 |
ECCurve | Elliptic curve |
ECCurveType | Elliptic curve types, as defined in the IANA EC Curve Type Registry Registry |
ECParameters | Elliptic curve parameters, defined in RFC4492 section 5.4 |
ECPoint | EC Point |
ExplicitPrimeContent | Elliptic curve parameters, conveyed verbosely as a prime field, as defined in RFC4492 section 5.4 |
HashAlgorithm | Hash algorithms, as defined in [RFC5246] |
KeyShareEntry | |
KeyUpdateRequest | Key update request (TLS 1.3) |
NamedGroup | Named curves, as defined in RFC4492, RFC7027, RFC7919 and IANA Supported Groups Registry |
OidFilter | |
PskKeyExchangeMode | |
RawCertificate | A raw certificate, which should be a DER-encoded X.509 certificate. |
SNIType | |
ServerDHParams | Diffie-Hellman parameters, defined in [RFC5246] section 7.4.3 |
ServerECDHParams | ECDH parameters defined in RFC4492 section 5.4 |
SignAlgorithm | Signature algorithms, as defined in [RFC5246] |
SignatureAndHashAlgorithm | |
SignatureScheme | Signature algorithms, as defined in [RFC8446] 4.2.3 |
TlsAlertDescription | TLS alert description |
TlsAlertSeverity | TLS alert severity |
TlsCertificateContents | The certificate chain, usually composed of the certificate, and all required certificate authorities. |
TlsCertificateRequestContents | Certificate request, as defined in RFC5246 section 7.4.4 |
TlsCertificateStatusContents | Certificate status response, as defined in RFC6066 section 8 |
TlsCipherSuite | TLS Ciphersuite |
TlsCipherSuiteID | |
TlsClientHelloContents | TLS Client Hello (from TLS 1.0 to TLS 1.2) |
TlsCompressionID | |
TlsEncrypted | Encrypted TLS record (containing opaque data) |
TlsEncryptedContent | TLS encrypted data |
TlsExtensionType | TLS extension types, defined in the IANA Transport Layer Security (TLS) Extensions registry |
TlsHandshakeType | Handshake type |
TlsHeartbeatMessageType | Heartbeat type, as defined in RFC6520 section 3 |
TlsHelloRetryRequestContents | TLS Hello Retry Request (TLS 1.3) |
TlsMessageAlert | TLS alert message |
TlsMessageApplicationData | TLS application data |
TlsMessageHeartbeat | TLS heartbeat message, as defined in RFC6520 |
TlsNewSessionTicketContent | Session ticket, as defined in RFC5077 |
TlsNextProtocolContent | Next protocol response, defined in draft-agl-tls-nextprotoneg-03 |
TlsPlaintext | TLS plaintext record |
TlsRawRecord | Tls Record with raw (unparsed) data |
TlsRecordHeader | TLS record header |
TlsRecordType | Content type, as defined in IANA TLS ContentType registry |
TlsServerHelloContents | TLS Server Hello (from TLS 1.0 to TLS 1.2) |
TlsServerHelloV13Draft18Contents | TLS Server Hello (TLS 1.3 draft 18) |
TlsServerKeyExchangeContents | Server key exchange parameters |
TlsVersion | TLS version |
Enums
DTLSMessage | DTLS plaintext message |
DTLSMessageHandshakeBody | DTLS Generic handshake message |
ECParametersContent | Elliptic curve parameters content (depending on EC type) |
Err | The |
StateChangeError | Error types for the state machine |
TlsCipherAu | Authentication methods |
TlsCipherEnc | Encryption methods |
TlsCipherEncMode | Encryption modes |
TlsCipherKx | Key exchange methods |
TlsCipherMac | Message Authentication Code (MAC) methods |
TlsClientKeyExchangeContents | Client key exchange parameters |
TlsExtension | TLS extensions |
TlsMessage | TLS plaintext message |
TlsMessageHandshake | Generic handshake message |
TlsState | TLS machine possible states |
Constants
MAX_RECORD_LEN | Max record size (RFC8446 5.1) |
Statics
CIPHERS |
Functions
Type Definitions
IResult | Holds the result of parsing functions |