doc/path_notes.md

   1 # Notes on path
   2 <a id="Top"></a>
   3
   4 # Table of Contents
   5 - [Notes on path](#notes-on-path)
   6 - [Table of Contents](#table-of-contents)
   7 - [Installed elements](#installed-elements)
   8   - [Binaries](#binaries)
   9   - [Firmwares](#firmwares)
  10   - [Traces](#traces)
  11   - [JTAG-related stuff](#jtag-related-stuff)
  12   - [Proxmark3 client files: dictionaries](#proxmark3-client-files-dictionaries)
  13   - [Proxmark3 client files: cmd scripts](#proxmark3-client-files-cmd-scripts)
  14   - [Proxmark3 client files: Lua libraries and scripts](#proxmark3-client-files-lua-libraries-and-scripts)
  15   - [Proxmark3 client files: various resources](#proxmark3-client-files-various-resources)
  16   - [Documentation](#documentation)
  17 - [User files](#user-files)
  18   - [.history / log files](#history--log-files)
  19   - [Proxmark3 client files and traces](#proxmark3-client-files-and-traces)
  20 - [Searching files](#searching-files)
  21   - [TL;DR](#tldr)
  22   - [Gory details](#gory-details)
  23 - [Scripts](#scripts)
  24     - [Proxmark command script (.cmd)](#proxmark-command-script-cmd)
  25     - [Shebangs (on \*nix)](#shebangs-on-nix)
  26
  27
  28 With the recent (2019-09-01) changes and creation of `make install`  command it is easy to get lost.
  29
  30 If you install the Proxmark3 tools with `make install`, they will go under the prefix `/usr/local/` but if you install the tools from your distro, there are chances the path is `/usr` so you'll have to adapt the paths presented here.
  31
  32 # Installed elements
  33 ^[Top](#top)
  34
  35 ## Binaries
  36 ^[Top](#top)
  37
  38 The main Proxmark3 executables / shellscripts will be copied to
  39
  40 ```
  41 /usr/local/bin/
  42 ```
  43
  44 * executables: `proxmark3`
  45 * scripts: `pm3`, `pm3-flash`, `pm3-flash-all`, `pm3-flash-bootloader`, `pm3-flash-fullimage`
  46
  47 Some more executable / scripts will be copied to
  48
  49 ```
  50 /usr/local/share/proxmark3/tools
  51 ```
  52
  53 * executables: `mfkey32`, `mfkey32v2`, `mfkey64`, `nonce2key`
  54 * scripts: `pm3_eml2lower.sh`, `pm3_eml2upper.sh`, `pm3_mfdread.py`, `pm3_mfd2eml.py`, `pm3_eml2mfd.py`, `findbits.py`, `rfidtest.pl`, `xorcheck.py`
  55
  56
  57 ## Firmwares
  58 ^[Top](#top)
  59
  60 The recovery / firmware files will be copied to
  61
  62 ```
  63 /usr/local/share/proxmark3/firmware
  64 ```
  65
  66 * Proxmark3 firmware: `bootrom.elf`, `fullimage.elf`, `proxmark3_recovery.bin` (used for JTAG)
  67 * SIM firmware: `sim014.bin`, `sim014.sha512.txt`
  68
  69
  70 ## Traces
  71 ^[Top](#top)
  72
  73 Proxmark3 client has a lot of sample trace files for many different low frequency tags. They will be copied to
  74
  75 ```
  76 /usr/local/share/proxmark3/traces
  77 ```
  78
  79
  80 ## JTAG-related stuff
  81 ^[Top](#top)
  82
  83 JTAG configurations and helper scripts for OpenOCD will be copied to
  84
  85 `/usr/local/share/proxmark3/jtag_openocd`
  86
  87
  88 ## Proxmark3 client files: dictionaries
  89 ^[Top](#top)
  90
  91 Dictionaries used by the client will be copied to
  92
  93 ```
  94 /usr/local/share/proxmark3/dictionaries
  95 ```
  96
  97 Here you find the default dictionaries used for commands like `hf mf chk`, `hf mf fchk`, `lf t55xx chk`
  98 A dictionary file is a text based file with one key per line in hexadecimal form.
  99 The length of the key is decided by the Proxmark3 client for the different commands.  All chars afterwards on line is ignored.
 100 if key isn't a hex number, the key is ignored.
 101
 102 - t55xx, Mifare Ultralight/NTAG  - uses 4 hexbytes (11223344)
 103 - Mifare classic uses 6 hexbytes (112233445566)
 104 - iClass uses 8 hexbytes (1122334455667788)
 105
 106 See [here](#proxmark3-client-files-and-traces) how to add your own dictionaries.
 107
 108 ## Proxmark3 client files: cmd scripts
 109 ^[Top](#top)
 110
 111 Cmd scripts used by the client will be copied to
 112
 113 ```
 114 /usr/local/share/proxmark3/cmdscripts
 115 ```
 116
 117 See [here](#proxmark3-client-files-and-traces) how to add your own cmd scripts.
 118
 119 ## Proxmark3 client files: Lua libraries and scripts
 120 ^[Top](#top)
 121
 122 Lua libraries and scripts used by the client will be copied to
 123
 124 ```
 125 /usr/local/share/proxmark3/lualibs
 126 /usr/local/share/proxmark3/luascripts
 127 ```
 128
 129 `lualibs` contains the supporting lua libraries used for lua scripts. Basically reused functions in a lua file like converting string to hex etc.
 130
 131 See [here](#proxmark3-client-files-and-traces) how to add your own Lua scripts.
 132
 133 ## Proxmark3 client files: various resources
 134 ^[Top](#top)
 135
 136 Various resources used by the client will be copied to
 137
 138 ```
 139 /usr/local/share/proxmark3/resources
 140 ```
 141
 142 It comprises the needed files for commands like hardnested, fido, EMV, iClass.
 143
 144 See [here](#proxmark3-client-files-and-traces) how to add your own resources.
 145
 146 ## Documentation
 147 ^[Top](#top)
 148
 149 Documentation will be copied to
 150
 151 ```
 152 /usr/local/share/doc/proxmark3
 153 ```
 154
 155 # User files
 156 ^[Top](#top)
 157
 158 The client will make use of a personal directory `~/.proxmark3` (or more precisely `$HOME/.proxmark3`)
 159
 160 ## .history / log files
 161 ^[Top](#top)
 162
 163 We have now a rolling log file, created new per day.  All these logfiles and the history file are now located at
 164
 165 ```
 166 ~/.proxmark3/history.txt
 167 ~/.proxmark3/log_YYYYMMDD.txt
 168 ```
 169
 170 ## Proxmark3 client files and traces
 171 ^[Top](#top)
 172
 173 If you wants to add scripts, dictionaries or other resources, you can use the same structure as the installed directory structure and add your own files there, e.g.
 174
 175 ```
 176 ~/.proxmark3/cmdscripts/mycmdscript.cmd
 177 ~/.proxmark3/dictionaries/mydict.dic
 178 ~/.proxmark3/luascripts/myluascript.lua
 179 ~/.proxmark3/resources/oids.json
 180 ~/.proxmark3/traces/mylftrace.pm3
 181 ```
 182
 183 If you add a file with the same name as the file provided with the Proxmark3 installation, it will take precedence.
 184
 185 See also [Scripts](#scripts) on how to write your own scripts.
 186
 187 # Searching files
 188 ^[Top](#top)
 189
 190 With the directory structure explained above, the client applies some heuristics to find its files or the files you specified in command line.
 191
 192 ## TL;DR
 193 ^[Top](#top)
 194
 195 It adds the expected suffix if you didn't provide it yet, then it looks (by order of precedence):
 196
 197 1. in the current directory, or in the path if you provided also a path, so it works with autocompletion
 198 2. in the `~/.proxmark3` directory structure as seen above, so it works with your stuffs
 199 3. in the repo directory structure, so it works as usual if used from the Git repo
 200 4. in the installed directory structure, so it works when installed
 201
 202 ## Gory details
 203 ^[Top](#top)
 204
 205 The client is using _searchFile_ (in _client/fileutils.c_) when calling a Proxmark3 command with a filename or when the client needs to find its files.
 206 _searchFile_ takes as argument a relative path *pm3dir*, a file to search and possibly a *suffix*.
 207
 208 So for example when using _searchFile_ over a filename supposed to be a dictionary file, it's called with *pm3dir=dictionaries/* and *suffix=.dic*.
 209 When a user provides a filename (including possibly a path), _searchFile_ will search different locations and return as soon as a file is found:
 210
 211 * Add the suffix if the suffix is not yet present, so: *foo* -> *foo.dic* and *foo.dic* -> *foo.dic*
 212 * If the filename is an absolute path (*/tmp/foo.dic*), take it as it is, try to access the file and return.
 213 * If the filename is an explicit relative path (*./foo.dic*), take it as it is, try to access the file from the current directory and return.
 214 * Try to find the filename as relative path (*foo.dic* -> *./foo.dic*), so filenames provided by CLI autocompletion work as expected.
 215 * Try to find the filename in the *pm3dir* relative to the user directory *$HOME/.proxmark3* (*foo.dic* -> *~/.proxmark3/dictionaries/foo.dic*)
 216 * Try to find the filename in the *pm3dir* relative to where the client binary is when in the repo configuration (*foo.dic* -> *$(path_to_dir_of_proxmark3_bin)/dictionaries/foo.dic*), so when the client is executed from a repo workdir, filenames are searched in the expected location.
 217 * Try to find the filename in the *pm3dir* relative to where the client binary is when in the installed configuration (*foo.dic* -> *$(path_to_dir_of_proxmark3_bin)/../share/proxmark3/dictionaries/foo.dic* which resolves to e.g. */usr/share/proxmark3/dictionaries/foo.dic* or */usr/local/share/proxmark3/dictionaries/foo.dic*), so when the client is executed from a repo workdir, filenames are searched in the expected location.
 218
 219 # Scripts
 220 ^[Top](#top)
 221
 222 You can provide your own lua or cmd scripts.
 223 Look at existing scripts for ideas how to create your own scripts.
 224
 225 ### Proxmark command script (.cmd)
 226 ^[Top](#top)
 227
 228 For cmd scripts, the command line scripts, the client can run a text file containing Proxmark3 commands.
 229
 230 A samplefile could be like this.
 231 ```
 232 $> cat myscript.cmd
 233
 234 rem running some HF-based info commands
 235 hf 14a info
 236 hf mfu info
 237 rem done
 238 ```
 239
 240 You call it with:
 241
 242 `$> pm3 -s myscript.cmd`
 243
 244 The client will execute each one of the commands in order and then exit.   There is also a possibility to remain in the client afterwards with the -i parameter:
 245
 246 `$> pm3 -s myscript.cmd -i`
 247
 248 You can place it in `~/.proxmark3/cmdscripts/` and it will be found automatically.
 249
 250 You can skip the script file extension, it works equally well with.
 251
 252 `pm3 -s myscript`
 253
 254
 255 ### Shebangs (on *nix)
 256 ^[Top](#top)
 257
 258 You can also use the magic of shebangs to make an executable script, e.g. taking the example above, we can write:
 259
 260 ```
 261 $> cat myscript.cmd
 262
 263 #!/usr/bin/env -S pm3 -s
 264 hf 14a info
 265 hf mfu info
 266
 267 $> chmod +x myscript.cmd
 268 $> ./myscript.cmd
 269 ```
 270
 271 And it will be executed invoking the `pm3` script.
 272
 273 Use the following if your script is intended to work offline.
 274
 275 ```
 276 #!/usr/bin/env -S proxmark3 -s
 277 ```
 278
 279 Beware the shebang trick is not available on all the platforms, it requires your `env` to accept the `-S` switch.