doc/trace_notes.md

   1 <a id="top"></a>
   2 # Notes about the tracelog
   3
   4 ## Table of Contents
   5  * [Command](#trace-command)
   6  * [File format](#tracelog-format)
   7  * [Wireshark dissector interoperability](#trace-and-wireshark)
   8
   9
  10 ## Trace command
  11 ^[Top](#top)
  12
  13 The `trace` command lists the data exchange by the proxmark3 and a tag or a reader in human readable form.
  14
  15 With `trace list` a table is shown which gives timing information, the src of the data bytes, the transmitted/received bytes itself, a check if the CRC was correct and some decoding of the command.
  16
  17 ### Timing
  18 ^[Top](#top)
  19
  20 The Start and the End column lists timestamps when the transmission of the shown data started (time of first bit) and when it ended (end of last modulation).
  21
  22 The unit for this time information depends on the protocol in use:
  23
  24 * ISO14443A and Thinfilm: all times are in carrier periods (1/13.56MHz)
  25 * For Legic timing information depends also on direction:
  26  * Reader Mode: Timings are in ticks (1us == 1.5ticks)
  27  * Tag Mode: Timings are in sub carrier periods (1/212 kHz == 4.7us)
  28 * Hitag1 / Hitag2 / HitagS: Elementary Time Unit (ETU) is 8µs
  29 * iCLASS, ISO15693, ISO18092 and FeliCa have no accurate timing information at the moment
  30 * For others timing is not available
  31
  32 By specifying the option ```f``` (e.g. ```trace list -t 14a -f```) the frame delay times are shown. (So you don't have to do the math by your own).
  33
  34 ### Sources
  35 ^[Top](#top)
  36
  37 If the data is marked as a response the source is shown as Tag. Otherwise it is marked as Reader (Rdr).
  38
  39 ### Data
  40 ^[Top](#top)
  41
  42 This column shows the raw bytes transmitted over the air. With option ```c``` CRC bytes are marked in square brackets.
  43
  44 ### CRC
  45 ^[Top](#top)
  46
  47 Marks if the transmitted CRC matches with the calculated CRC.
  48
  49 ### Annotation
  50 ^[Top](#top)
  51
  52 Annotations provide a rough decoding of the transmitted data. For ISO14443A a more detailed decoding is available with Wireshark (s. next chapter)
  53
  54 ## Tracelog format
  55 ^[Top](#top)
  56
  57 The binary format for the dynamic tracelog is as following.
  58
  59 ```
  60  /*
  61    Traceformat:
  62    32 bits timestamp (little endian)
  63    16 bits duration (little endian)
  64    15 bits data length (little endian) (0x7FFF)
  65    1 bit isResponse (0=reader to tag, 1=tag to reader)
  66    data length Bytes data
  67    x Bytes parity,  where x == ceil(data length/8)
  68 */
  69
  70 typedef struct {
  71     uint32_t timestamp;
  72     uint16_t duration;
  73     uint16_t data_len : 15;
  74     bool isResponse : 1;
  75     uint8_t frame[];
  76     // data_len         bytes of data
  77     // ceil(data_len/8) bytes of parity
  78 } PACKED tracelog_hdr_t;
  79
  80 #define TRACELOG_HDR_LEN        sizeof(tracelog_hdr_t)
  81 #define TRACELOG_PARITY_LEN(x)  (((x)->data_len - 1) / 8 + 1)
  82 ```
  83
  84 ## Trace and Wireshark
  85 ^[Top](#top)
  86
  87 To get a more detailed explanation of the transmitted data for ISO14443A traces the output can be converted to a pcapng file to read it with [Wireshark](https://www.wireshark.org/).
  88
  89 To do so
  90
  91 * use `trace list -t 14a -x`
  92 * copy the output (starting with the timestamp) into a textfile
  93 * run `text2pcap -t "%S." -l 264 -n <input-text-file> <output-pcapng-file>`
  94 * now open your pcapng file in Wireshark or read it with the CLI version `tshark`
  95
  96 An example frame
  97
  98 with `trace list -t 14a`:
  99
 100 ```
 101 19072 |      29536 | Rdr |93  70  88  04  cf  ff  bc  7f  bb  |  ok | SELECT_UID
 102 ```
 103
 104 the same data with `tshark -r foo.pcapng -V -x`:
 105
 106 ```
 107 Frame 5: 13 bytes on wire (104 bits), 13 bytes captured (104 bits) on interface 0
 108     Interface id: 0 (unknown)
 109         Interface name: unknown
 110     Encapsulation type: ISO 14443 contactless smartcard standards (177)
 111     Arrival Time: Aug 17, 2019 23:17:00.000002606 CEST
 112     [Time shift for this packet: 0.000000000 seconds]
 113     Epoch Time: 1566076620.000002606 seconds
 114     [Time delta from previous captured frame: 0.000000840 seconds]
 115     [Time delta from previous displayed frame: 0.000000840 seconds]
 116     [Time since reference or first frame: 0.000001907 seconds]
 117     Frame Number: 5
 118     Frame Length: 13 bytes (104 bits)
 119     Capture Length: 13 bytes (104 bits)
 120     [Frame is marked: False]
 121     [Frame is ignored: False]
 122     [Protocols in frame: iso14443]
 123 ISO 14443
 124     Pseudo header
 125         Version: 0x00
 126         Event: Data transfer PCD -> PICC (0xfe)
 127         Length field: 9
 128     Message: Select
 129         SEL: 0x93
 130         NVB: 0x70
 131         CT: 0x88
 132         UID_CLn: 04cfff
 133         BCC: 0xbc
 134         CRC: 0xbb7f [correct]
 135         [CRC Status: Good]
 136
 137 0000  00 fe 00 09 93 70 88 04 cf ff bc 7f bb            .....p.......
 138 ```
 139
 140 If the Wireshark ISO14443a dissector is missing some commands or needs some other rework please [file a bug](https://bugs.wireshark.org/bugzilla/).