Hello hackers!

General remarks about contributing
----------------------------------

Contributions to the libfreefare are welcome!  Here are some directions to get
you started:

  1. Install Cutter
     Cutter is a cool unit test framework for C code.  You will need it to run
     the regression tests suite (`make check') and ensure that your code does
     not break other features.
     http://cutter.sourceforge.net/
     To cover all tests you'll need several blank cards:
     * MIFARE Ultralight
     * MIFARE Ultralight C with default key (BREAKMEIFYOUCAN!)
     * MIFARE Classic 4k with default keys (FFFFFFFFFF)
     * DESFire EV1 4k with default PICC key (0000000000000000)
     After "make check", you can run sub-sets of tests directly with cutter:
     $ cutter -n /ultralight/ test
     $ cutter -n /classic/ test
     $ cutter -n /desfire/ test


  2. Follow style conventions
     The source code of the library trend to follow some conventions so that it
     is consistent in style and thus easier to read.  Basically, it follows
     FreeBSD's style(9); adding 4-space indentation and 8-space tabs (which you
     should configure in your editor, e.g. `:set sw=4 ts=8' in vim).  You are
     also advised to `:set cinoptions=t0(0:0` so that you don't have to care
     about indentation anymore. For more details, please read the style(9) man
     page from FreeBSD's website:
     http://www.freebsd.org/cgi/man.cgi?query=style

  3. Write tests
     I told you cutter is lovely in #1 so you really should use it!  If you
     want to contribute code, write test: only code with appropriate tests will
     be considered.  And remember that TDD (Test Driven Development) is cool
     and writing all tests at the end deeply depressing, so test early, test
     often!


Adding support for a new type of card
-------------------------------------

Adding a new supported card to the libfreefare requires a few modification in
multiple places.  Here is a list of the things to do in order to have the
infrastructure ready for hacking the new card support:
  - Edit libfreefare/freefare.h:
      - Add your tag to the `mifare_tag_type' enum;
      - Add a <tag>_connect() and a <tag>_disconnect() function prototype;
  - Edit libfreefare/freefare.3:
      - Add your tag to the `mifare_tag_type' enum documentation;
  - Edit libfreefare/freefare_internal.h:
      - Add a new <tag>_tag struct.  It's very first member SHALL be `struct
	mifare_tag __tag';
      - Add a <tag>_tag_new() and a <tag>_tag_free() function prototype;
      - Add a ASSERT_<TAG>() macro to check the tag's type;
      - Add a <TAG>() macro to cast a generic tag to your type.
  - Edit libfreefare/freefare.c:
      - Add your tag type to the supported_tags array;
      - Edit the freefare_get_tags() function so that it calls <tag>_tag_new()
	when it finds your tag;
      - Edit the freefare_free_tags() function so that it calls
	<tag>_tag_free() to free your tags;
  - Create libfreefare/<tag>.c and implement all that's missing:
      - <tag>_tag_new() MUST allocate all data-structure the tag may need to
	use during it's lifetime.  We do not want to have any function to fail
	later because the running system is out of resources.  Buffers for
	cryptographic operations on random amount of data MAY however be
	(re)allocated on demand, in such case refrain from shrinking
	unnecessarily the buffer size.
      - <tag>_connect() SHOULD initialise data allocated by <tag>_tag_new().
	Keep in mind that a single tag may be disconnected from and connected
	to again, without being freed in the meantime.  Since all memory
	allocations are done in <tag>_tag_new(), your code SHOULD only care
	about initialising these data structures;
      - <tag>_disconnect() MAY do more that just send a disconnect command to
	the tag.  At time of writing I have no idea what it could be but who
	knows...
      - <tag>_tag_free() SHALL free all resources allocated for the tag
	(surprising, isn't it?)


Various guidelines
------------------

  - If a given card has different cryptographic modes, you SHOULD use
    switch/cases to handle specific branches of code, even when applicable to
    only one cypher.  The idea is that if you don't provide support for all
    cryptographic schemes, or if an evolution of the card provides more
    cryptographic possibilities, when adding support for a new cypher, the
    compiler can warn the developer about unhandled values in switch
    statements.  Please refer to the Mifare DESFire code for an example.
