path: root/2005/rfid-lk2005/librfid.xml

<section>
<title>librfid - A free software RFID stack</title>
<para>
The librfid project intends to provide a free software reader-side
implementation of common RFID protocols such as ISO 14443, ISO 15693.
</para> 
<para>
Careful design and various abstraction layers should enable it to include
support for various readers and protocols, even though as of now only a single
reader and ISO 14443(A+B) is implemented.
</para>



<section>
<title>Data Structures</title>
<para>
The librfid codebase is very modular and therefore data-centric.  It is
therefore important to understand the various data structures and how they
interact.
</para>

<section>
<title>struct rfid_asic</title>
<para>
A struct rfid_asic is the integral part of every supported reader.  
</para>
<para>A
separation between ASIC and reader makes sense, since almost all of the
existing readers use one of the few available ASIC solutions from Philips, TI
and the like.
</para>
</section>

<section>
<title>struct rfid_asic_transport</title>
<para>
A struct <structname>rfid_asic_transport</structname> connects a struct rfid_asic to librfid.  
</para>
<para>
This transport is usually limited to very few essential primitives. With the
Philips CL RC632, the asic transport has to provide four primitives: read/write
register, and read/write FIFO.
</para>
</section>

<section>
<title>struct rfid_reader</title>
<para>
A struct <structname>rfid_reader</structname> contains information about the
specific configuration of the ASIC as well as the transport.  
</para>
</section>

<section>
<title>struct rfid_layer2</title>
<para>
A struct <structname>rfid_layer2</structname> implements the anticollision procedure, such as ISO
14443-3.
</para>
</section>

<section>
<title>struct rfid_protocol</title>
<para>
A struct <structname>rfid_protocol</structname> implements a transport protocol, such as ISO 14443-4
</para>
</section>

<section>
<title>Runtime handles</title>
<para>
Each of the structures described above, have a _handle structure.  The _handle
(e.g. rfid_layer2_handle) saves instance-local state and allows the stack to
identify the user.
</para>
</section>

</section> <!-- data structures -->

<section>
<title>Protocol Stack</title>
<para>
In the typical current setup (CardMan 5121 reader, ISO14443-123A, ISO14443-4),
those data structures are stacked on top of each other like this:
<screen>
rfid_protocol_tcl
rfid_layer2_iso14443a
CM5121 reader
CL RC632 asic
PC_to_RDR_Escape transport
USB-CCID
libusb
</screen>
</para>
</section>

<section>
<title>Interaction with OpenCT</title>

<section>
<title>What is OpenCT</title>
<para>
OpenCT is a free software smart card reader driver package, originally
developed for the OpenSC (http://www.opensc.org) project.  As of now, it only
supports contact based smart cards.
</para>
</section>

<section>
<title>Integration with OpenCT</title>
<para>
First of all, why use OpenCT at all?  Because like other "consumer" RFID
readers, the 5121 supports contact based and contactless operation.  Its
contact based operation is already supported by the OpenCT ifd-ccid driver.
</para>
<para>
Also, many "legacy" smart card applications expect to talk to a PC/SC or CT-API
interface.  OpenCT already provides a "ifdehandler" backend for pcsc-lite, as
well as a CT-API wrapper.  In addition, OpenCT suports a client/server
architecture where readers can be shared in a network. If librfid was
integrated with OpenCT, it could directly benefit from those features.
</para>
<para>
On the other hand, there are many usage cases, where neither dual-interface
operation nor a PC/SC API is applicable.  This includes usage of passive (state
machine) tags that do not speak sophisticate transport protocols such as
14443-4.  Therefore, OpenCT integration on both backend and frontend can only
be provided optionally, ant not made mandatory.
</para>

<para>
The overall integration with OpenCT is:
</para>
<para>
Export the PC_TO_RDR_ESCAPE based interface to the RFID Reader ASIC (Philips
RC632) as a virtual slot (always the last slot number 2 of the cm5121).  This
virtual slot supports only one special protocol: The "ESCAPE" protocol.
</para>
<para>
The RFID software stack opens this virtual slot to talk to the RFID
Reader ASIC using the OpenCT API (CT_Card_Transact).
</para>
<para>
The RFID software stack implements the various protocols and protocol layers
</para>
<para>
The RFID software stack registers a number of slots as ifd-handler with
OpenCT.  The slots provide access to protocols like T=CL.                       </para>
</section>

</section>

<section>
<title>Application Interfaces</title>

<section>
<title>Native API</title>
<para>
The native API is the API that librfid uses internally.  It reflects all 
features, and by it's very nature not compatible to any standard.
Also, it is the only API that is fully supported at the time this paper was written.
</para>
<para>
The API is not very comfortable, as many calls have to be made, and everything is explicit.  There is no support for advanced features such as auto-detecting the standard/protocol a given tag supports.
</para>
<para>
An application will likely start with <function>rfid_init()</function>,
followed by <function>rfid_reader_open()</function>, <function>rfid_layer2_init()</function>, <function>rfid_layer2_open()</function>,
<function>rfid_protocol_init()</function> and <function>rfid_orotocol_open()</function>.
</para>
<para>
Data is transcieved to and from the tag by calling <function>rfid_protocol_transcieve()</function>.
</para>
<para>
For an example on how to use the API, please look at the
<filename>librfid/openct-secape.c</filename> program in the librfid source
tree.
</para>

<section>
<title>OpenCT, CT-API, PC/SC</title>
<para>
librfid will not by itself provide any of those interfaces, but rather
implement an OpenCT backend driver (ifd-librfid). 
</para>
<para>
At the time of writing, such a backend did not yet exist.
</para>
</section>

</section> <!-- API's -->

<section>
<title>Future Development</title>
<para>
librfid is currently in an early alpha/beta state.  It is not yet ready for
production use.  Apart from a hand full of minor fixes from MaskTech GmbH, 
it's a one-man project.  It's also not a project that I can focus on, because
its main author has many other project and considers librfid more or less a
"pet project".
</para>
<para>
Therefore, skilled developers are needed.  If you want to experiment with RFID
technology, and really learn about the protocols instead of just using
something ready-built, librfid should provide you with a good basis.
</para>
<para>
The initial code is there, you can do something useful (namely: Talk to
ISO14443-A and -B cards using T=CL protocol).  If you feel like adding support
for some other reader device, or further protocols, any help is appreciated.
</para>
<para>
There's now also a development mailinglist at <email>librfid-devel@lists.gnumonks.org</email>.
</para>
</section>

</section>

</section>