.\" Copyright (C) 2010 Romain Tartiere
.\"
.\" This program is free software: you can redistribute it and/or modify it
.\" under the terms of the GNU Lesser General Public License as published by the
.\" Free Software Foundation, either version 3 of the License, or (at your
.\" option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful, but WITHOUT
.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
.\" more details.
.\"
.\" You should have received a copy of the GNU Lesser General Public License
.\" along with this program.  If not, see <http://www.gnu.org/licenses/>
.\"
.\" $Id$
.\"
.Dd March 30, 2010
.Dt MAD 3
.Os
.\"  _   _
.\" | \ | | __ _ _ __ ___   ___
.\" |  \| |/ _` | '_ ` _ \ / _ \
.\" | |\  | (_| | | | | | |  __/
.\" |_| \_|\__,_|_| |_| |_|\___|
.\"
.Sh NAME
.Nm mad_new ,
.Nm mad_read ,
.Nm mad_write ,
.Nm mad_get_version ,
.Nm mad_set_version ,
.Nm mad_get_card_publisher_sector ,
.Nm mad_set_card_publisher_sector ,
.Nm mad_get_aid ,
.Nm mad_set_aid ,
.Nm mad_free ,
.Nd "Mifare Application Directory (MAD) Manipulation Functions"
.\"  _     _ _
.\" | |   (_) |__  _ __ __ _ _ __ _   _
.\" | |   | | '_ \| '__/ _` | '__| | | |
.\" | |___| | |_) | | | (_| | |  | |_| |
.\" |_____|_|_.__/|_|  \__,_|_|   \__, |
.\"                               |___/
.Sh LIBRARY
Mifare card manipulation library (libfreefare, \-lfreefare)
.\"  ____                              _
.\" / ___| _   _ _ __   ___  _ __  ___(_)___
.\" \___ \| | | | '_ \ / _ \| '_ \/ __| / __|
.\"  ___) | |_| | | | | (_) | |_) \__ \ \__ \
.\" |____/ \__, |_| |_|\___/| .__/|___/_|___/
.\"        |___/            |_|
.Sh SYNOPSIS
.In freefare.h
.Ft "Mad"
.Fn mad_new "uint8_t version"
.Ft "Mad"
.Fn mad_read "MifareTag tag"
.Ft "int"
.Fn mad_write "MifareTag tag" "Mad mad" "MifareClassicKey key_b_sector_00" "MifareClassicKey key_b_sector_10"
.Ft "int"
.Fn mad_get_version "Mad mad"
.Ft "void"
.Fn mad_set_version "Mad mad" "uint8_t version"
.Ft "MifareClassicSectorNumber"
.Fn mad_get_card_publisher_sector "Mad mad"
.Ft "int"
.Fn mad_set_card_publisher_sector "Mad mad" "MifareClassicSectorNumber cps"
.Ft "int"
.Fn mad_get_aid "Mad mad" "MifareClassicSectorNumber sector" "MadAid *aid"
.Ft "int"
.Fn mad_set_aid "Mad mad" "MifareClassicSectorNumber sector" "MadAid aid"
.Ft "void"
.Fn mad_free "Mad mad"
.\"  ____                      _       _   _
.\" |  _ \  ___  ___  ___ _ __(_)_ __ | |_(_) ___  _ __
.\" | | | |/ _ \/ __|/ __| '__| | '_ \| __| |/ _ \| '_ \
.\" | |_| |  __/\__ \ (__| |  | | |_) | |_| | (_) | | | |
.\" |____/ \___||___/\___|_|  |_| .__/ \__|_|\___/|_| |_|
.\"                             |_|
.Sh DESCRIPTION
Mifare Application Directories (MAD) can be easily manipulated using the
.Fn mad_*
set of functions.
.Pp
A
.Vt mad
can be loaded form a Mifare Classic
.Vt tag
using
.Fn mad_read
or generated from scratch using
.Fn mad_new
and providing the
.Vt version
of the
.Vt mad
to generate. After using a
.Vt mad ,
the memory can be reclaimed using
.Fn mad_free .
.Pp
A
.Vt mad
can be written to a Mifare Classic
.Vt tag
using
.Fn mad_write
and providing the B keys required for writing to sectors 0,
.Vt key_b_sector_00,
and the one required for writing to sectors 10,
.Vt key_b_sector_10 .
When writing a MAD version 1
.Vt mad ,
the
.Vt key_b_sector_10 .
.Pp
The
.Vt version
of a MAD
.Vt mad
can be read using
.Fn mad_get_version
and changed using
.Fn mad_set_version .
.Pp
The card publisher sector number
.Vt cps
can be read read using
.Fn mad_get_card_publisher_sector
and writen using
.Fn mad_set_card_publisher_sector .
.Pp
Sectors allocation in the
.Vt mad
is handled by the
.Fn mad_get_aid
and
.Fn mad_set_aid
functions.  These functions fill-in or read the Application Identifier,
.Vt aid
for the given
.Vt sector .
.\"  ___                 _                           _        _   _                           _
.\" |_ _|_ __ ___  _ __ | | ___ _ __ ___   ___ _ __ | |_ __ _| |_(_) ___  _ __    _ __   ___ | |_ ___  ___
.\"  | || '_ ` _ \| '_ \| |/ _ \ '_ ` _ \ / _ \ '_ \| __/ _` | __| |/ _ \| '_ \  | '_ \ / _ \| __/ _ \/ __|
.\"  | || | | | | | |_) | |  __/ | | | | |  __/ | | | || (_| | |_| | (_) | | | | | | | | (_) | ||  __/\__ \
.\" |___|_| |_| |_| .__/|_|\___|_| |_| |_|\___|_| |_|\__\__,_|\__|_|\___/|_| |_| |_| |_|\___/ \__\___||___/
.\"               |_|
.\".Sh IMPLEMENTATION NOTES
.\"  ____      _                                 _
.\" |  _ \ ___| |_ _   _ _ __ _ __   __   ____ _| |_   _  ___  ___
.\" | |_) / _ \ __| | | | '__| '_ \  \ \ / / _` | | | | |/ _ \/ __|
.\" |  _ <  __/ |_| |_| | |  | | | |  \ V / (_| | | |_| |  __/\__ \
.\" |_| \_\___|\__|\__,_|_|  |_| |_|   \_/ \__,_|_|\__,_|\___||___/
.\"
.Sh RETURN VALUES
The
.Fn mad_new
function return
.Va NULL
on failure and allocates memory that has to be freed using
.Fn mad_free
on success.
Unless stated otherwise, all other functions return a value greater than or equal to
.Va 0
on success or
.Va -1
on failure.
.\"  ____                    _
.\" / ___|  ___  ___    __ _| |___  ___
.\" \___ \ / _ \/ _ \  / _` | / __|/ _ \
.\"  ___) |  __/  __/ | (_| | \__ \ (_) |
.\" |____/ \___|\___|  \__,_|_|___/\___/
.\"
.Sh SEE ALSO
.Xr freefare 3 ,
.Xr mifare_application 3 ,
.Xr mifare_classic 3
.\"     _         _   _
.\"    / \  _   _| |_| |__   ___  _ __ ___
.\"   / _ \| | | | __| '_ \ / _ \| '__/ __|
.\"  / ___ \ |_| | |_| | | | (_) | |  \__ \
.\" /_/   \_\__,_|\__|_| |_|\___/|_|  |___/
.\"
.Sh AUTHORS
.An Romain Tartiere Aq romain@blogreen.org
.An Romuald Conty Aq romuald@libnfc.org