1 package edu.uci.iotproject;
3 import edu.uci.iotproject.util.PcapPacketUtils;
4 import org.pcap4j.core.PcapPacket;
5 import org.pcap4j.packet.IpV4Packet;
6 import org.pcap4j.packet.Packet;
7 import org.pcap4j.packet.TcpPacket;
12 * Models a (TCP) conversation/connection/session/flow (packet's belonging to the same session between a client and a
14 * Holds a list of {@link PcapPacket}s identified as pertaining to the flow. Note that this list is <em>not</em>
15 * considered when determining equality of two {@code Conversation} instances in order to allow for a
16 * {@code Conversation} to function as a key in data structures such as {@link java.util.Map} and {@link java.util.Set}.
17 * See {@link #equals(Object)} for the definition of equality.
19 * @author Janus Varmarken {@literal <jvarmark@uci.edu>}
20 * @author Rahmadi Trimananda {@literal <rtrimana@uci.edu>}
22 public class Conversation {
24 /* Begin instance properties */
26 * The IP of the host that is considered the client (i.e. the host that initiates the conversation)
27 * in this conversation.
29 private final String mClientIp;
32 * The port number used by the host that is considered the client in this conversation.
34 private final int mClientPort;
37 * The IP of the host that is considered the server (i.e. is the responder) in this conversation.
39 private final String mServerIp;
42 * The port number used by the server in this conversation.
44 private final int mServerPort;
47 * The list of packets (with payload) pertaining to this conversation.
49 private final List<PcapPacket> mPackets;
52 * If {@link #isTls()} is {@code true}, this list contains the subset of {@link #mPackets} which are TLS Application
55 private final List<PcapPacket> mTlsApplicationDataPackets;
58 * Contains the sequence numbers used thus far by the host that is considered the <em>client</em> in this
59 * {@code Conversation}.
60 * Used for filtering out retransmissions.
62 private final Set<Integer> mSeqNumbersClient;
65 * Contains the sequence numbers used thus far by the host that is considered the <em>server</em> in this
66 * {@code Conversation}.
67 * Used for filtering out retransmissions.
69 private final Set<Integer> mSeqNumbersSrv;
72 * List of SYN packets pertaining to this conversation.
74 private final List<PcapPacket> mSynPackets;
77 * List of pairs FINs and their corresponding ACKs associated with this conversation.
79 private final List<FinAckPair> mFinPackets;
82 * List of RST packets associated with this conversation.
84 private final List<PcapPacket> mRstPackets;
87 * Boolean to mark the packet as Application Data based on the previous packet that reaches MTU
89 private boolean mApplicationData;
90 /* End instance properties */
93 * Factory method for creating a {@code Conversation} from a {@link PcapPacket}.
94 * @param pcapPacket The {@code PcapPacket} that wraps a TCP segment for which a {@code Conversation} is to be initiated.
95 * @param clientIsSrc If {@code true}, the source address and source port found in the IP datagram and TCP segment
96 * wrapped in the {@code PcapPacket} are regarded as pertaining to the client, and the destination
97 * address and destination port are regarded as pertaining to the server---and vice versa if set
99 * @return A {@code Conversation} initiated with ip:port for client and server according to the direction of the packet.
101 public static Conversation fromPcapPacket(PcapPacket pcapPacket, boolean clientIsSrc) {
102 IpV4Packet ipPacket = pcapPacket.get(IpV4Packet.class);
103 TcpPacket tcpPacket = pcapPacket.get(TcpPacket.class);
104 String clientIp = clientIsSrc ? ipPacket.getHeader().getSrcAddr().getHostAddress() :
105 ipPacket.getHeader().getDstAddr().getHostAddress();
106 String srvIp = clientIsSrc ? ipPacket.getHeader().getDstAddr().getHostAddress() :
107 ipPacket.getHeader().getSrcAddr().getHostAddress();
108 int clientPort = clientIsSrc ? tcpPacket.getHeader().getSrcPort().valueAsInt() :
109 tcpPacket.getHeader().getDstPort().valueAsInt();
110 int srvPort = clientIsSrc ? tcpPacket.getHeader().getDstPort().valueAsInt() :
111 tcpPacket.getHeader().getSrcPort().valueAsInt();
112 return new Conversation(clientIp, clientPort, srvIp, srvPort);
116 * Constructs a new {@code Conversation}.
117 * @param clientIp The IP of the host that is considered the client (i.e. the host that initiates the conversation)
118 * in the conversation.
119 * @param clientPort The port number used by the client for the conversation.
120 * @param serverIp The IP of the host that is considered the server (i.e. is the responder) in the conversation.
121 * @param serverPort The port number used by the server for the conversation.
123 public Conversation(String clientIp, int clientPort, String serverIp, int serverPort) {
124 this.mClientIp = clientIp;
125 this.mClientPort = clientPort;
126 this.mServerIp = serverIp;
127 this.mServerPort = serverPort;
128 this.mPackets = new ArrayList<>();
129 this.mTlsApplicationDataPackets = new ArrayList<>();
130 this.mSeqNumbersClient = new HashSet<>();
131 this.mSeqNumbersSrv = new HashSet<>();
132 this.mSynPackets = new ArrayList<>();
133 this.mFinPackets = new ArrayList<>();
134 this.mRstPackets = new ArrayList<>();
135 this.mApplicationData = false;
139 * Add a packet to the list of packets associated with this conversation.
140 * @param packet The packet that is to be added to (associated with) this conversation.
141 * @param ignoreRetransmissions Boolean value indicating if retransmissions should be ignored.
142 * If set to {@code true}, {@code packet} will <em>not</em> be added to the
143 * internal list of packets pertaining to this {@code Conversation}
144 * <em>iff</em> the sequence number of {@code packet} was already
145 * seen in a previous packet.
147 public void addPacket(PcapPacket packet, boolean ignoreRetransmissions) {
148 // Precondition: verify that packet does indeed pertain to conversation.
149 onAddPrecondition(packet);
150 if (ignoreRetransmissions && isRetransmission(packet)) {
151 // Packet is a retransmission. Ignore it.
154 // Select direction-dependent set of sequence numbers seen so far and update it with sequence number of new packet.
155 addSeqNumber(packet);
156 // Finally add packet to list of packets pertaining to this conversation.
157 mPackets.add(packet);
158 // Preserve order of packets in list: sort according to timestamp.
159 if (mPackets.size() > 1 &&
160 mPackets.get(mPackets.size()-1).getTimestamp().isBefore(mPackets.get(mPackets.size()-2).getTimestamp())) {
161 Collections.sort(mPackets, (o1, o2) -> {
162 if (o1.getTimestamp().isBefore(o2.getTimestamp())) { return -1; }
163 else if (o2.getTimestamp().isBefore(o1.getTimestamp())) { return 1; }
167 // If TLS, inspect packet to see if it's a TLS Application Data packet, and if so add it to the list of TLS
168 // Application Data packets.
170 TcpPacket tcpPacket = packet.get(TcpPacket.class);
171 Packet tcpPayload = tcpPacket.getPayload();
172 if (tcpPayload == null) {
175 byte[] rawPayload = tcpPayload.getRawData();
176 // The SSL record header is at the front of the payload and is 5 bytes long.
177 // The SSL record header type field (the first byte) is set to 23 if it is an Application Data packet.
178 if (rawPayload != null && rawPayload.length >= 5) {
179 if (rawPayload[0] == 23) {
180 mTlsApplicationDataPackets.add(packet);
181 // Consider the following packet a data packet if this packet's size == MTU size 1448
182 if (rawPayload.length >= 1448)
183 mApplicationData = true;
184 } else if (rawPayload[0] == 20) {
185 // Do nothing for now - CHANGE_CIPHER_SPEC
186 } else if (rawPayload[0] == 21) {
187 // Do nothing for now - ALERT
188 } else if (rawPayload[0] == 22) {
189 // Do nothing for now - HANDSHAKE
191 // If it is TLS with payload, but rawPayload[0] != 23
192 if (mApplicationData == true) {
193 // It is a continuation of the previous packet if the previous packet reaches MTU size 1448 and
194 // it is not either type 20, 21, or 22
195 mTlsApplicationDataPackets.add(packet);
196 if (rawPayload.length < 1448)
197 mApplicationData = false;
205 * Get a list of packets pertaining to this {@code Conversation}.
206 * The returned list is a read-only list.
207 * @return the list of packets pertaining to this {@code Conversation}.
209 public List<PcapPacket> getPackets() {
210 // Return read-only view to prevent external code from manipulating internal state (preserve invariant).
211 return Collections.unmodifiableList(mPackets);
215 * Records a TCP SYN packet as pertaining to this conversation (adds it to the the internal list).
216 * Attempts to add duplicate SYN packets will be ignored, and the caller is made aware of the attempt to add a
217 * duplicate by the return value being {@code false}.
219 * @param synPacket A {@link PcapPacket} wrapping a TCP SYN packet.
220 * @return {@code true} if the packet was successfully added to this {@code Conversation}, {@code false} otherwise.
222 public boolean addSynPacket(PcapPacket synPacket) {
223 onAddPrecondition(synPacket);
224 final IpV4Packet synPacketIpSection = synPacket.get(IpV4Packet.class);
225 final TcpPacket synPacketTcpSection = synPacket.get(TcpPacket.class);
226 if (synPacketTcpSection == null || !synPacketTcpSection.getHeader().getSyn()) {
227 throw new IllegalArgumentException("Not a SYN packet.");
229 // We are only interested in recording one copy of the two SYN packets (one SYN packet in each direction), i.e.,
230 // we want to discard retransmitted SYN packets.
231 if (mSynPackets.size() >= 2) {
234 // Check the set of recorded SYN packets to see if we have already recorded a SYN packet going in the same
235 // direction as the packet given in the argument.
236 boolean matchingPrevSyn = mSynPackets.stream().anyMatch(p -> {
237 IpV4Packet pIp = p.get(IpV4Packet.class);
238 TcpPacket pTcp = p.get(TcpPacket.class);
239 boolean srcAddrMatch = synPacketIpSection.getHeader().getSrcAddr().getHostAddress().
240 equals(pIp.getHeader().getSrcAddr().getHostAddress());
241 boolean dstAddrMatch = synPacketIpSection.getHeader().getDstAddr().getHostAddress().
242 equals(pIp.getHeader().getDstAddr().getHostAddress());
243 boolean srcPortMatch = synPacketTcpSection.getHeader().getSrcPort().valueAsInt() ==
244 pTcp.getHeader().getSrcPort().valueAsInt();
245 boolean dstPortMatch = synPacketTcpSection.getHeader().getDstPort().valueAsInt() ==
246 pTcp.getHeader().getDstPort().valueAsInt();
247 return srcAddrMatch && dstAddrMatch && srcPortMatch && dstPortMatch;
249 if (matchingPrevSyn) {
252 // Update direction-dependent set of sequence numbers and record/log packet.
253 addSeqNumber(synPacket);
254 return mSynPackets.add(synPacket);
257 mSynPackets.stream().anyMatch(p -> {
258 IpV4Packet pIp = p.get(IpV4Packet.class);
259 TcpPacket pTcp = p.get(TcpPacket.class);
260 boolean srcAddrMatch = synPacketIpSection.getHeader().getSrcAddr().getHostAddress().
261 equals(pIp.getHeader().getSrcAddr().getHostAddress());
262 boolean dstAddrMatch = synPacketIpSection.getHeader().getDstAddr().getHostAddress().
263 equals(pIp.getHeader().getDstAddr().getHostAddress());
264 boolean srcPortMatch = synPacketTcpSection.getHeader().getSrcPort().valueAsInt() ==
265 pTcp.getHeader().getSrcPort().valueAsInt();
266 boolean dstPortMatch = synPacketTcpSection.getHeader().getDstPort().value() ==
267 pTcp.getHeader().getDstPort().value();
269 boolean fourTupleMatch = srcAddrMatch && dstAddrMatch && srcPortMatch && dstPortMatch;
271 boolean seqNoMatch = synPacketTcpSection.getHeader().getSequenceNumber() ==
272 pTcp.getHeader().getSequenceNumber();
274 if (fourTupleMatch && !seqNoMatch) {
275 // If the four tuple that identifies the conversation matches, but the sequence number is different,
276 // it means that this SYN packet is, in fact, an attempt to establish a **new** connection, and hence
277 // the given packet is NOT part of this conversation, even though the ip:port combinations are (by
278 // chance) selected such that they match this conversation.
279 throw new IllegalArgumentException("Attempt to add SYN packet that belongs to a different conversation " +
280 "(which is identified by the same four tuple as this conversation)");
282 return fourTupleMatch && seqNoMatch;
288 * Get a list of SYN packets pertaining to this {@code Conversation}.
289 * The returned list is a read-only list.
290 * @return the list of SYN packets pertaining to this {@code Conversation}.
292 public List<PcapPacket> getSynPackets() {
293 return Collections.unmodifiableList(mSynPackets);
297 * Adds a TCP FIN packet to the list of TCP FIN packets associated with this conversation.
298 * @param finPacket The TCP FIN packet that is to be added to (associated with) this conversation.
300 public void addFinPacket(PcapPacket finPacket) {
301 // Precondition: verify that packet does indeed pertain to conversation.
302 onAddPrecondition(finPacket);
303 // TODO: should call addSeqNumber here?
304 addSeqNumber(finPacket);
305 mFinPackets.add(new FinAckPair(finPacket));
309 * Attempt to ACK any FIN packets held by this conversation.
310 * @param ackPacket The ACK for a FIN previously added to this conversation.
312 public void attemptAcknowledgementOfFin(PcapPacket ackPacket) {
313 // Precondition: verify that the packet pertains to this conversation.
314 onAddPrecondition(ackPacket);
315 // Mark unack'ed FIN(s) that this ACK matches as ACK'ed (there might be more than one in case of retransmissions..?)
316 mFinPackets.replaceAll(finAckPair -> !finAckPair.isAcknowledged() && finAckPair.isCorrespondingAckPacket(ackPacket) ? new FinAckPair(finAckPair.getFinPacket(), ackPacket) : finAckPair);
320 * Retrieves an unmodifiable view of the list of {@link FinAckPair}s associated with this {@code Conversation}.
321 * @return an unmodifiable view of the list of {@link FinAckPair}s associated with this {@code Conversation}.
323 public List<FinAckPair> getFinAckPairs() {
324 return Collections.unmodifiableList(mFinPackets);
328 * Get if this {@code Conversation} is considered to have been gracefully shut down.
329 * A {@code Conversation} has been gracefully shut down if it contains a FIN+ACK pair for both directions
330 * (client to server, and server to client).
331 * @return {@code true} if the connection has been gracefully shut down, false otherwise.
333 public boolean isGracefullyShutdown() {
334 // The conversation has been gracefully shut down if we have recorded a FIN from both the client and the server which have both been ack'ed.
335 return mFinPackets.stream().anyMatch(finAckPair -> finAckPair.isAcknowledged() && PcapPacketUtils.isSource(finAckPair.getFinPacket(), mClientIp, mClientPort)) &&
336 mFinPackets.stream().anyMatch(finAckPair -> finAckPair.isAcknowledged() && PcapPacketUtils.isSource(finAckPair.getFinPacket(), mServerIp, mServerPort));
340 * Add a TCP segment for which the RST flag is set to this {@code Conversation}.
341 * @param packet A {@link PcapPacket} wrapping a TCP segment pertaining to this {@code Conversation} for which the
344 public void addRstPacket(PcapPacket packet) {
347 * When now also keeping track of RST packets, should we also...?
348 * 1) Prevent later packets from being added once a RST segment has been added?
349 * 2) Extend 'isGracefullyShutdown()' to also consider RST segments, or add another method, 'isShutdown()' that
350 * both considers FIN/ACK (graceful) as well as RST (abrupt/"ungraceful") shutdown?
351 * 3) Should it be impossible to associate more than one RST segment with each Conversation?
353 onAddPrecondition(packet);
354 TcpPacket tcpPacket = packet.get(TcpPacket.class);
355 if (tcpPacket == null || !tcpPacket.getHeader().getRst()) {
356 throw new IllegalArgumentException("not a RST packet");
358 mRstPackets.add(packet);
362 * Get the TCP segments pertaining to this {@code Conversation} for which it was detected that the RST flag is set.
363 * @return the TCP segments pertaining to this {@code Conversation} for which it was detected that the RST flag is
366 public List<PcapPacket> getRstPackets() {
367 return Collections.unmodifiableList(mRstPackets);
370 // =========================================================================================================
371 // We simply reuse equals and hashCode methods of String.class to be able to use this class as a key
375 * <em>Note:</em> currently, equality is determined based on pairwise equality of the elements of the four tuple
376 * ({@link #mClientIp}, {@link #mClientPort}, {@link #mServerIp}, {@link #mServerPort}) for {@code this} and
378 * @param obj The object to test for equality with {@code this}.
379 * @return {@code true} if {@code obj} is considered equal to {@code this} based on the definition of equality given above.
382 public boolean equals(Object obj) {
383 return obj instanceof Conversation && this.toString().equals(obj.toString());
387 public int hashCode() {
388 return toString().hashCode();
390 // =========================================================================================================
393 public String toString() {
394 return String.format("%s:%d %s:%d", mClientIp, mClientPort, mServerIp, mServerPort);
398 * Invoke to verify that the precondition holds when a caller attempts to add a packet to this {@code Conversation}.
399 * An {@link IllegalArgumentException} is thrown if the precondition is violated.
400 * @param packet the packet to be added to this {@code Conversation}
402 private void onAddPrecondition(PcapPacket packet) {
403 // Apply precondition to preserve class invariant: all packets in mPackets must match the 4 tuple that
404 // defines the conversation.
405 IpV4Packet ipPacket = Objects.requireNonNull(packet.get(IpV4Packet.class));
406 // For now we only support TCP flows.
407 TcpPacket tcpPacket = Objects.requireNonNull(packet.get(TcpPacket.class));
408 String ipSrc = ipPacket.getHeader().getSrcAddr().getHostAddress();
409 String ipDst = ipPacket.getHeader().getDstAddr().getHostAddress();
410 int srcPort = tcpPacket.getHeader().getSrcPort().valueAsInt();
411 int dstPort = tcpPacket.getHeader().getDstPort().valueAsInt();
412 String clientIp, serverIp;
413 int clientPort, serverPort;
414 if (ipSrc.equals(mClientIp)) {
416 clientPort = srcPort;
418 serverPort = dstPort;
421 clientPort = dstPort;
423 serverPort = srcPort;
425 if (!(clientIp.equals(mClientIp) && clientPort == mClientPort &&
426 serverIp.equals(mServerIp) && serverPort == mServerPort)) {
427 throw new IllegalArgumentException(
428 String.format("Attempt to add packet that does not pertain to %s",
429 Conversation.class.getSimpleName()));
435 * Determines if the TCP packet contained in {@code packet} is a retransmission of a previously seen (logged)
441 * the current implementation, which uses a set of previously seen sequence numbers, will consider a segment
442 * with a reused sequence number---occurring as a result of sequence number wrap around for a very long-lived
443 * connection---as a retransmission (and may therefore end up discarding it even though it is in fact NOT a
444 * retransmission). Ideas?
447 * @param packet The packet.
448 * @return {@code true} if {@code packet} was determined to be a retransmission, {@code false} otherwise.
450 public boolean isRetransmission(PcapPacket packet) {
451 // Extract sequence number.
452 int seqNo = packet.get(TcpPacket.class).getHeader().getSequenceNumber();
453 switch (getDirection(packet)) {
454 case CLIENT_TO_SERVER:
455 return mSeqNumbersClient.contains(seqNo);
456 case SERVER_TO_CLIENT:
457 return mSeqNumbersSrv.contains(seqNo);
459 throw new AssertionError(String.format("Unexpected value of enum '%s'",
460 Direction.class.getSimpleName()));
466 * Is this {@code Conversation} a TLS session?
469 * <em>Note: the current implementation simply examines the port number(s) for 443; it does <b>not</b> verify if the
470 * application data is indeed encrypted.</em>
472 * @return {@code true} if this {@code Conversation} is interpreted as a TLS session, {@code false} otherwise.
474 public boolean isTls() {
477 * - may want to change this to be "return mServerPort == 443 || mClientPort == 443;" in order to also detect
478 * TLS in those cases where it is not possible to correctly label who is the client and who is the server,
479 * i.e., when the trace does not contain the SYN/SYNACK exchange.
480 * - current implementation relies on the server using the conventional TLS port number; may instead want to
481 * inspect the first 4 bytes of each potential TLS packet to see if they match the SSL record header.
483 * 08/31/18: Added unconvetional TLS ports used by WeMo plugs and LiFX bulb.
485 return mServerPort == 443 || mServerPort == 8443 || mServerPort == 41143;
489 * If this {@code Conversation} is backing a TLS session (i.e., if the value of {@link #isTls()} is {@code true}),
490 * get the packets labeled as TLS Application Data packets. This is a subset of the full set of payload-carrying
491 * packets (as returned by {@link #getPackets()}). An exception is thrown if this method is invoked on a
492 * {@code Conversation} for which {@link #isTls()} returns {@code false}.
494 * @return A list containing exactly those packets that could be identified as TLS Application Data packets (through
495 * inspecting of the SSL record header). The list may be empty, if no TLS application data packets have been
496 * recorded for this {@code Conversation}.
498 public List<PcapPacket> getTlsApplicationDataPackets() {
500 throw new NoSuchElementException("cannot get TLS Application Data packets for non-TLS TCP conversation");
502 return Collections.unmodifiableList(mTlsApplicationDataPackets);
506 * Extracts the TCP sequence number from {@code packet} and adds it to the proper set of sequence numbers by
507 * analyzing the direction of the packet.
508 * @param packet A TCP packet (wrapped in a {@code PcapPacket}) that was added to this conversation and whose
509 * sequence number is to be recorded as seen.
511 private void addSeqNumber(PcapPacket packet) {
512 // Note: below check is redundant if client code is correct as the call to check the precondition should already
513 // have been made by the addXPacket method that invokes this method. As such, the call below may be removed in
514 // favor of speed, but the improvement will be minor, hence the added safety may be worth it.
515 onAddPrecondition(packet);
516 // Extract sequence number.
517 int seqNo = packet.get(TcpPacket.class).getHeader().getSequenceNumber();
518 // Determine direction of packet and add packet's sequence number to corresponding set of sequence numbers.
519 switch (getDirection(packet)) {
520 case CLIENT_TO_SERVER:
521 // Client to server packet.
522 mSeqNumbersClient.add(seqNo);
524 case SERVER_TO_CLIENT:
525 // Server to client packet.
526 mSeqNumbersSrv.add(seqNo);
529 throw new AssertionError(String.format("Unexpected value of enum '%s'",
530 Direction.class.getSimpleName()));
535 * Determine the direction of {@code packet}. An {@link IllegalArgumentException} is thrown if {@code packet} does
536 * not pertain to this conversation.
538 * @param packet The packet whose direction is to be determined.
539 * @return A {@link Direction} indicating the direction of the packet.
541 public Direction getDirection(PcapPacket packet) {
542 IpV4Packet ipPacket = packet.get(IpV4Packet.class);
543 String ipSrc = ipPacket.getHeader().getSrcAddr().getHostAddress();
544 String ipDst = ipPacket.getHeader().getDstAddr().getHostAddress();
545 // Determine direction of packet.
546 if (ipSrc.equals(mClientIp) && ipDst.equals(mServerIp)) {
547 // Client to server packet.
548 return Direction.CLIENT_TO_SERVER;
549 } else if (ipSrc.equals(mServerIp) && ipDst.equals(mClientIp)) {
550 // Server to client packet.
551 return Direction.SERVER_TO_CLIENT;
553 throw new IllegalArgumentException("getDirection: packet not related to " + getClass().getSimpleName());
558 * Utility enum for expressing the direction of a packet pertaining to this {@code Conversation}.
560 public enum Direction {
564 public String toCompactString() {
570 public String toCompactString() {
577 * Get a compact string representation of this {@code Direction}.
578 * @return a compact string representation of this {@code Direction}.
580 abstract public String toCompactString();