doc/trace_notes.md

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