Tag: mslib

mslib – A library for decoding magnetic stripes

After a number of posts describing how to decode audio streams of magnetic stripes to bits and then characters, I now present a C library that does all that.

The creatively named “mslib” can take a signed 16bit little endian PCM stream of a magnetic stripe and decode it.

My own usage tests have been with 48khz, but it should allow higher frequencies and slightly lower ones.  When changing the frequency from 48khz, it may be required to alter the “peakOffset” and “peakThreshold” values using the functions defined and documented in mslib.h.

The code is written in C and available on github here.  It’s presently released under the GPLv3 and has a single library dependency of glib-2.0. [Edit: No longer has a glib dependency — should be entirely c99 compatible]

The library is tersely documented like most open source code, but comes with an example/test utility.  Decoding a stream consists of the follow steps:

  1. Create the mslib object and load the PCM stream as a signed array of short integers using ms_create().
  2. Create a list of peaks, used for decoding the stream to bits, using ms_peaks_find().
  3. Filter the list of peaks for duplicates using ms_peaks_filter().
  4. Decode the peaks to bits using ms_decode_peaks().  The bits as written on the card may now be fetched as a NULL terminated char array with ms_get_bitStream().
  5. Decode the bits to characters using ms_decode_bits().  The characters as written on the card may now be fetched as a NULL terminated char array with ms_get_charStream().

The library can successfully decode any magnetic stripe to bits (subject to a clean audio signal).  It will decode the bits to characters for streams encoded using the ABA and IATA encoding schemes as found on almost all magnetic stripes.

Development is still continuing, with a top TODO item of removing the glib dependency [Edit: glib has been removed in current builds].  Bug reports, comments and feature requests are welcome and can be left on github’s site.

Some example PCM streams that can be decoded with the utility:

capitalone.pcm – A Visa credit card

wamu.pcm – A Visa debit card

wamu-bad.pcm – An example of a bad swipe of the Visa debit card.

(All credit card numbers are of course no longer valid [not just expired].  All the streams are from track 2 and use ABA encoding)

MagRead

MagRead is a Qt based GUI application originally written for Maemo 5.

The application is designed to read all types of magnetic stripes that follow the ABA or IATA encoding schemes.  In addition, it attempts to format the data from cards it recognises.

Magnetic stripe data is read over the audio input jack on the mobile phone.  A hardware adapter is required, which primarily consists of something similar to an old cassette tape head.  The start of the application displays a minimalistic welcome screen:

MagRead Start Screen
Start screen for MagRead

At present, credit cards and identification cards are the only cards that will display with their data formatted.

Credit Cards

Visa, MasterCard, American Express and Discover are currently shown:

Visa Card
Capital One Visa Credit Card (inactive number)

If an expired credit card is swiped, the “Expiration Date” field will appear in red:

Debit Card (inactive number)
Washington Mutual Visa Debit Card (inactive number)

AAMVA Driver Licence/Identification Cards

Cards in compliance with AAMVA standards will also be recognised.  These are identification cards and driver licence cards issued by any government based in North America (approx. 22 US states/territories, several Canadian provinces and at least one Mexican state).

When swiped with a track 2 reader, the issuing authority (state/province/agency/territory) is displayed, along with the person’s unique ID number, date of expiration, date of birth, and their present age:

AAMVA Compliant CA DL
California Driver Licence (DL# Redacted)

Expired cards will put their expiration date in red, and include the word in caps “EXPIRED” underneath.  Additionally, if the person’s age is under 18, it will appear in red.  Those over 18 but under 21 will have their age appear in yellow.

Expired California Driver Licence
Expired California Driver Licence (DL# Redacted)

Miscellaneous Cards

Cards which are not identified simply have the data on them displayed:

Ralphs Rewards Card
Ralphs Rewards Card

Partial Reads

On the home screen, there is a “Show Partial Data” checkbox.  When checked, MagRead will display data read off of cards that my contain errors or be incomplete.  By default, only swipes that have passed several parity checks are displayed.

Ralphs Rewards Card -- Red |s indicate characters with bad parity checks
Capital One Visa Card Partial Read

MagRead is still in active development, but will be available for download shortly.  It will be released under the GPL.

At present, it is written in C and C++ and  designed to run on the Nokia N900 with Maemo 5 only.  Work is currently in progress to port the application to standard Qt 4.6, and it may be usable on Symbian devices with Qt support.