Documentation

Getting Started

Windows Installation

All test programs etc. are Windows compatible, but you may need to make some adjustments to get python working smoothly under Windows if it's not already installed. In particular, you need to be able to run commands from the command line, so make sure you've followed the instruction to set up your PATH here. Python for Windows can be downloaded here (make sure you get ver 2.6 - ver 3 is not supported by RFIDIOt).

Device Types

There are two basic type of device supported by RFIDIOt: serial and PCSC. Note that both types may have a USB physical interface, but the low level communications protocol will be handled differently for each.

Serial devices

ACG LF/HF Serial/RS232
ACG LF/HF USB
ACG LAHF USB
FROSCH Serial/RS232
FROSCH USB
AIAK DemoTAG

PCSC devices

Device Drivers

Serial Drivers

Serial devices with an RS232 interface require no device drivers, so you can skip to the Dependencies section.

Serial devices with a USB interface use an FTDI serial converter, which requires an external driver (ftdi_sio). This should be autoloaded by your O/S, but if not you can get it from here:

Under Linux and OS/X, the device will normally appear as /dev/ttyUSBn, where 'n' is the device number, starting at 0. e.g. /dev/ttyUSB0. If you can't find it, run 'dmesg' and you should see the device loading:

	[ 3799.146735] usb 2-2: new full speed USB device using uhci_hcd and address 4
	[ 3797.292486] usb 2-2: configuration #1 chosen from 1 choice
	[ 3797.294329] ftdi_sio 2-2:1.0: FTDI USB Serial Device converter detected
	[ 3797.294373] /build/buildd/linux-2.6.24/drivers/usb/serial/ftdi_sio.c: Detected FT232RL
	[ 3797.294532] usb 2-2: FTDI USB Serial Device converter now attached to ttyUSB0

Common problems

Windows driver installed, but tools cannot open COM port

Under Windows, the device will be installed as a virtual COM port. It is important that this is lower than COM10, as external libraries used by RFIDIOt may have trouble addressing COM10 and above. If it appears above COM9, use the control panel hardware manager to renumber it.

Linux driver loads but no /dev/ttyUSBn created

Try:

	mknod /dev/ttyUSB0 c 188 0

PCSC Drivers

PCSC devices are supported by the pcscd daemon, which is part of the pcscs-lite project, in conjunction with specific device driver 'bundles', which are either part of pcscs-lite, or distributed separately by the manufacturer:

OmniKey CardMan 5321 - Manufacturer driver
SCM SDI010 - Manufacturer driver
Tikitag/Touchatag - pcsc-lite native
ACS - pcsc-lite native

If you are running OS-X Jaguar (10.2) or later, pcsc-lite is already installed, but you may still need additional drivers.

Otherwise, first install pcscs-lite and ccid driver s, then additional drivers if required. You can test that your reader is working by running 'pcsc_scan' or 'pcsctest', which should show your device registering cards being placed on and removed from the reader coil. Once this is working, you can move on to the Dependencies section.

Common problems

OmniKey CardMan 5321 only registers contact cards, not contactless

You need to disable support from the native pcscs-lite drivers and use the omniKey manufacturer driver instead. You do this by editing the pcsc bundle or removing it altogether if you don't need to support any other devices. To remove it, simply move the following sub-directory to a backup location and restart pcscd:

	/usr/local/pcsc/drivers/ifd-ccid.bundle

To leave the driver in place, but remove CardMan 5321 device support, edit the following file:

        /usr/local/pcsc/drivers/ifd-ccid.bundle/Contents/Info.plist

note that on some distributions, this may also be found here:

	/etc/libccid_Info.plist

Look for the Vendor array:

  <key>ifdVendorID</key>
	<array>

and within that, the OmniKey vendor ID, which you can find by running 'lsusb':

	$ lsusb

	Bus 005 Device 002: ID 413c:a005 Dell Computer Corp. 
	Bus 005 Device 001: ID 0000:0000  
	Bus 004 Device 001: ID 0000:0000  
	Bus 003 Device 002: ID 076b:5321 OmniKey AG 
	Bus 003 Device 001: ID 0000:0000  
	Bus 002 Device 004: ID 045e:0040 Microsoft Corp. Wheel Mouse Optical
	Bus 002 Device 003: ID 0b97:7762 O2 Micro, Inc. Oz776 SmartCard Reader
	Bus 002 Device 002: ID 0b97:7761 O2 Micro, Inc. 
	Bus 002 Device 001: ID 0000:0000  
	Bus 001 Device 001: ID 0000:0000

so in this case, our device is vendor number '076B', which you should be able to find within the array:

	<string>0x04E6</string>
	<string>0x04E6</string>
	<string>0x076B</string>
	<string>0x076B</string>
	<string>0x076B</string>

Note that there may be more than one entry for this vendor, as this array is linked to another which contains individual product reference numbers. It is vital, therefore, that you only remove one entry, or you will skew the arrays which will cause unpredictable results.

Now find the product in the Product array (in this case '5321'):

        <key>ifdProductID</key>
        <array>

	<string>0x5121</string>
	<string>0x5125</string>
	<string>0x5321>/string>
	<string>0x6622</string>
	<string>0xA022</string>

and remove that line too.

Finally, in the Friendly Name array, remove the human readable description:

	<key>ifdFriendlyName</key>
 <array>

	<string>OmniKey CardMan 5121</string>
	<string>OmniKey CardMan 5125</string>
	<string>OmniKey CardMan 5321</string>
	<string>OmniKey CardMan 6121</string>
	<string>Teo by Xiring</string>

Now restart pcscd in the foreground, and check that it uses the manufacturer's driver:

        $ sudo pcscd -f
	00000000 pcscdaemon.c:280:main() pcscd set to foreground with debug send to stderr
	00000570 pcscdaemon.c:518:main() pcsc-lite 1.5.0 daemon ready.
	00309648 hotplug_libusb.c:477:HPAddHotPluggable() Adding USB device: 003:002
	00000075 readerfactory.c:1082:RFInitializeReader() Attempting startup of OMNIKEY CardMan 5x21 00 00 using /usr/local/pcsc/drivers/ifdokrfid_lnx-2.6.0.bundle/Contents/Linux/ifdokrfid.so
	00000434 readerfactory.c:949:RFBindFunctions() Loading IFD Handler 3.0
	OK OMNIKEY CardMan RFID  IA32 v2.6.0 support@omnikey.com

Omnikey CardMan 5321 fails to load with Manufacturer's driver

Run pcscd in the foreground so you can watch the error log, and if you get something like this:

	13431722 hotplug_libhal.c:305:get_driver() Looking a driver for VID: 0x076B, PID: 0x5321
	00000058 hotplug_libhal.c:342:HPAddDevice() Adding USB device: usb_device_76b_5321_noserial_if0
	01001266 readerfactory.c:1135:RFInitializeReader() Attempting startup of OMNIKEY CardMan 5x21 00 00 using /usr/lib/pcsc/drivers/ifdokrfid_lnx-2.6.0.bundle/Contents/Linux/ifdokrfid.so
	00074319 readerfactory.c:1002:RFBindFunctions() Loading IFD Handler 3.0
	OK OMNIKEY CardMan RFID IA32 v2.6.0 support@omnikey.com
	00000913 readerfactory.c:1174:RFInitializeReader() Open Port 200000 Failed (usb:076b/5321:libhal:/org/freedesktop/Hal/devices/usb_device_76b_5321_noserial_if0)
	00000377 readerfactory.c:1047:RFUnloadReader() Unloading reader driver.
	00000353 readerfactory.c:254:RFAddReader() OMNIKEY CardMan 5x21 init failed.
	00000301 hotplug_libhal.c:395:HPAddDevice() Failed adding USB device: usb_device_76b_5321_noserial_if0

You need to rebuild pcsc-lite without HAL support.

Error message 'Did you set DRIVER_OPTION_CCID_EXCHANGE_AUTHORIZED in ifdDriverOptions in libccid_Info.plist?'

Tikitag/Touchatag readers need the CCID_EXCHANGE_AUTHORIZED option set for pcscd. Edit the file:

	/usr/local/pcsc/drivers/ifd-ccid.bundle/Contents/Info.plist

note that on some distributions, this may also be found here:

	/etc/libccid_Info.plist

find the section:

        <key>ifdDriverOptions</key>
        <string>0x0000</string>

and change the value to 0x0001:

        <key>ifdDriverOptions</key>
        <string>0x0001</string>

Now restart pcscd.

Error message 'AttributeError: rfidiot instance has no attribute 'readername''

Check that the reader number is correctly set in RFIDIOtconfig.py - you can find out your reader number by running any command with the '-L' flag. e.g.

    ./cardselect.py -L

Dependencies

RFIDIOt uses a number of external libraries which will also need to be installed:

Configuration

RFIDIOt is configured by entries in a file called 'RFIDIOtconfig.py', which is expected to be in the working directory, or the import path of your python installation. For simple setups, with only one device, configuring this one file is all that is required.

The options that need to be specified are:

Reader Type:

ACS
PCSC
FROSCH
DEMOTAG

Reader Port (Serial Only):

/dev/ttyXXX

Reader BAUD Rate (Serial Only):

9600
57600
115200
230400
460800

To configure the reader type, find the reader type section:

	# reader type (can be overridden with -R)
	#readertype= RFIDIOt.rfidiot.READER_ACG
	#readertype= RFIDIOt.rfidiot.READER_FROSCH
	#readertype= RFIDIOt.rfidiot.READER_DEMOTAG
	# READER_PCSC is a meta type. Actual subtype will be auto-determined.
	readertype= RFIDIOt.rfidiot.READER_PCSC

and ensure that only one type is uncommented. In this case, PCSC is set. If your device is PCSC, then this is the only option you need to set as the port, speed and sub-type (Omnikey, Tikitag etc.) will be determined automatically.

To configure to port, find the serial port section:

	# serial port (can be overridden with -l)
	# ignored for PCSC
	#line= "/dev/ttyS0"
	#line= "/dev/ttyS1"
	line= "/dev/ttyUSB0"
	# for Windows
	#line= "COM4"

and ensure only one entry is uncommented. In this case '/dev/ttyUSB0'.

Finally, to set the serial port speed:

	# serial port speed (can be overridden with -s)
	# ignored for PCSC
	speed= 9600
	#speed= 57600
	#speed= 115200
	#speed= 230400
	#speed= 460800

Each of these options can be overridden on the command line by using the appropriate option flag, e.g. '-s' for speed. All test programs will accept '-h' to display help, giving details of all possible options. To set the port to /dev/ttyUSB1 and the reader type to ACG, you would specify:

	-l /dev/ttyUSB1 -R RFIDIOt.rfidiot.READER_ACG

For more complex setups, options specified in this file can be overridden by a local file, the location of which is specified by one of the following (in search order):

$(RFIDIOtconfig_opts)
./RFIDIOtconfig.opts
/etc/RFIDIOtconfig.opts

options should be specified on the first line as if typed on the command line, e.g.

	-s 9600 -l /dev/ttyUSB1 -R RFIDIOt.rfidiot.READER_ACG

command line options will take precedence over this file.

Test/Example Programs

RFIDIOt is a collection of routines designed to abstract the hardware from the function, so that a single program can provide the same functionality regardless of what reader type is plugged in. However, because different readers have different capabilities, not all functions are supported on all readers, and it is therefore not possible to run all commands against all hardware types.

Test programs are provided as examples of how to perform certain functions, and my be useful in their own right, but not all programs have been tested against all TAGs that they may be applicable to, so please report any problems you come across.

All test programs support the '-h' option, which will give you detailed help on options and arguments. Options are applied by RFIDIOt itself, and so are generic for all programs, and inappropriate options (e.g. -g 'No GUI' for a program that doesn't have a GUI anyway) will be ignored.

cardselect.py

Readers: ACG, Frosch, PCSC
TAGS: ALL

Show a TAG's UID.

copytag.py

Readers: ACG, Frosch, PCSC
TAGS: ALL Non-authenticated

Attempt to copy data blocks of non password or crypto protected TAG to a blank of the same type.

eeprom.py

Readers: ACG
TAGS: n/a

Display contents of an ACG reader's EEPROM. Refer to ACG user manuals for detailed description.

fdxbnum.py

Readers: ACG LF, ACG LAHF, Frosch
TAGS: Q5, Hitag2

Program a TAG with an ISO-11784/5 (FDX-B) UID, or decode values read from an existing TAG.

formatmifare1kvalue.py

Readers: ACG HF, ACG LAHF, PCSC
TAGS: Mifare1K

Format Mifare1K data blocks according to the MIFARE value block standard (with value of 0.00).

froschtest.py

Readers: Frosch
TAGS: Hitag1, Hitag2, HitagS

Test read functionality of Frosch reader.

hidprox.py

Readers: PCSC
TAGS: HID ProxCard

Read Prox Facility Code and Card Number.

Note that this command only seems to work reliably with the OmniKey 5325 reader. Due to the way the 5125 polls the tags, it is somewhat hit and miss if you will get a good read or not.

hitag2brute.py

Readers: Frosch, ACG LF, ACG LAHF
TAGS: Hitag2

Attempt to login to Hitag2 password protected TAG with random passwords.

hitag2reset.py

Readers: Frosch
TAGS: Hitag2

Reset Hitag2 to native r/w mode. If a Hitag2 TAG has been set to emulate Unique or FDX-B, this is a required step before it can be re-used.

isotype.py

Readers: ACG HF, ACG LAHF, PCSC
TAGS: ISO 14443 A/B, ISO 15693, ISO 18000-3, NFC, I-CODE, HID iCLASS, FeliCa, Innovision Jewel, Mifare, JCOP

Attempt to determine HF TAG type and, where appropriate, show ATR/ATS values.

jcopmifare.py

Readers: ACG HF, ACG LAHF, PCSC
TAGS: JCOP

Provide READ/WRITE access to Mifare blocks on JCOP card running jcopmifare applet (jcop_mifare_access.cap), or set RANDOM_UID mode.

jcop_mifare_access.cap

Readers: PCSC
TAGS: JCOP

Java applet to be installed to JCOP card for Mifare block access and setting of RANDOM_UID mode. See Makefile for installation instructions. Full source not available.

jcopsetatrhist.py

Readers: ACG HF, ACG LAHF, PCSC
TAGS: JCOP

Set ATR Historical Bytes on JCOP card running jcopatrhist applet (jcop_set_atr_hist.cap).

jcop_set_atr_hist.cap

Readers: PCSC
TAGS: JCOP

Java applet to be installed to JCOP card for setting of ATR Historical Bytes. See java subdirectory for full source, Makefile etc.

jcoptool.py

Readers: ACG HF, ACG LAHF, PCSC
TAGS: JCOP

Show some useful information about JCOP card including manufacture date, mask etc. and installed applications.

lfxtype.py

Readers: ACG LF, ACG LAHF, Frosch
TAGS: EM4x02, EM4x50, EM4x05 (ISO 11784/5 FDX-B), Hitag 1 / 2 / S, Q5, TI 64 bit R/O & R/W, TI 1088 bit Multipage

Attempt to determine LF TAG type, and, if appropriate, emulation mode it is running in.

loginall.py

Readers: ACG HF, ACG LAHF, PCSC
TAGS: Mifare

Attempt to login to each sector of a Mifare TAG with standard transport keys.

mifarekeys.py

Readers: n/a
TAGS: JCOP

Calculate 3DES keys for access to Mifare sectors on JCOP cards running Mifare access applet (jcop_mifare_access.cap).

mrpkey.py

Readers: ACS HF, ACS LAHF, PCSC
TAGS: ISO-14443 ePassport/eID, JCOP JMRTD/vonJeek, NFC vonJeek

Read/Write/Clone contents of Machine Readable Travel Document.

multiselect.py

Readers: ACG, Frosch, PCSC
TAGS: ALL

Repeatedly select and display TAG UID.

pn532emulate.py

Readers: PCSC
TAGS: ISO-14443-3, ISO-14443-4, Mifare, Felica

Switch NXP PN532 into emulation mode and set various parameters to be sent to initiator, then process a single APDU.

This command will only work with readers that contain an NXP PN532 chip, and then only if support for that specific reader has been added. Readers currently supported are:

ACS ACR 38U-CCID
Alcatel-Lucent TikiTag / TouchaTag

pn532mitm.py

Readers: PCSC
TAGS: ISO-14443-3, ISO-14443-4, Mifare, Felica

PN532 Man-In-The-Middle. Drive two NXP PN532 devices: one as a reader, and one as an emulator, and log all traffic that passes between them. Both readers can be on a single machine, or traffic can be relayed via a TCP socket between two separate systems.

This command will only work with readers that contain an NXP PN532 chip, and then only if support for that specific reader has been added. Readers currently supported are:

ACS ACR 38U-CCID
Alcatel-Lucent TikiTag / TouchaTag

q5reset.py

Readers: ACG LF, ACG LAHF
TAGS: Q5

Reset Q5 TAG into default r/w mode and set UID. This command will recover a Q5 TAG that has been put into an unusable state by programming an invalid configuration block, and can also be used to change the UID.

readlfx.py

Readers: ACG LF, ACG LAHF, Frosch
TAGS: EM4x50, EM4x05 (ISO 11784/5 FDX-B), Hitag 1 / 2 / S, Q5, TI 64 bit R/O & R/W, TI 1088 bit Multipage

Read LF TAG datablocks.

readmifaresimple.py

Readers: ACG HF, ACG LAHF, PCSC
TAGS: Mifare1K, Mifare4K

Read all data blocks from Mifare TAGs, using transport (or specified) keys and optionally copy data to a blank or reset TAG to factory defaults.

readmifareultra.py

Readers: ACG HF, ACG LAHF, PCSC
TAGS: Mifare UltraLight

Read Mifare UltraLight data blocks.

readtag.py

Readers: ACG, Frosch, PCSC
TAGS: All non-authenticated

Read all data blocks from non password or crypto protected TAGs.

transit.py

Readers: ACG LF
TAGS: Q5

Program Q5 to emulate FDI Matalec 'TRANSIT 500' or 'TRANSIT 999'.

sod.py

Readers: n/a
TAGS: n/a

Attempt to find X509 data in EF_SOD.BIN as read by mrpkey.py from a MRTD.

testacg.sh

Readers: ACG LF, ACG HF
TAGS: ANY

Test an ACG LF or ACG HF reader by selecting a TAG and displaying it's UID.

testlahf.sh

Readers: ACG LAHF
TAGS: ANY

Test an ACG LAHF reader by selecting a TAG and displaying it's UID on both the LF and HF elements.

unique.py

Readers: ACG LF, Frosch
TAGS: Q5, Hitag2

Set EM4x02 (Unique/Mira) UID and emulation mode on Q5 or Hitag2.

writelfx.py

Readers: ACG LF, ACG LAHF, Frosch
TAGS: Q5, Hitag 1/2/S

Read and then write back all LF data blocks.

writemifare1k.py

Readers: ACG HF, PCSC
TAGS: Mifare1K

Write random data to all Mifare1K data blocks using transport keys.

Copyright 2010, Adam Laurie. Page last updated Saturday March 20th, 2010.