Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
MIFARE_DESFIRE(3)      FreeBSD Library Functions Manual	     MIFARE_DESFIRE(3)

NAME
     mifare_desfire_connect, mifare_desfire_disconnect.
     mifare_desfire_authenticate, mifare_desfire_authenticate_aes,
     mifare_desfire_authenticate_iso, mifare_desfire_change_key_settings,
     mifare_desfire_get_key_settings, mifare_desfire_change_key,
     mifare_desfire_get_key_version, mifare_desfire_create_application,
     mifare_desfire_create_application_3k3des,
     mifare_desfire_create_application_aes,
     mifare_desfire_create_application_iso,
     mifare_desfire_create_application_3k3des_iso,
     mifare_desfire_create_application_aes_iso,
     mifare_desfire_delete_application,	mifare_desfire_get_application_ids,
     mifare_desfire_free_application_ids, mifare_desfire_get_df_names,
     mifare_desfire_select_application,	mifare_desfire_format_picc,
     mifare_desfire_get_version, mifare_desfire_free_mem,
     mifare_desfire_set_configuration, mifare_desfire_set_default_key,
     mifare_desfire_set_ats, mifare_desfire_get_card_uid,
     mifare_desfire_get_file_ids, mifare_desfire_get_iso_file_ids,
     mifare_desfire_get_file_settings, mifare_desfire_change_file_settings,
     mifare_desfire_create_std_data_file,
     mifare_desfire_create_std_data_file_iso,
     mifare_desfire_create_backup_data_file,
     mifare_desfire_create_backup_data_file_iso,
     mifare_desfire_create_value_file,
     mifare_desfire_create_linear_record_file,
     mifare_desfire_create_linear_record_file_iso,
     mifare_desfire_create_cyclic_record_file,
     mifare_desfire_create_cyclic_record_file_iso, mifare_desfire_delete_file,
     mifare_desfire_read_data, mifare_desfire_read_data_ex,
     mifare_desfire_write_data,	mifare_desfire_write_data_ex,
     mifare_desfire_get_value, mifare_desfire_get_value_ex,
     mifare_desfire_credit, mifare_desfire_credit_ex, mifare_desfire_debit,
     mifare_desfire_debit_ex, mifare_desfire_limited_credit,
     mifare_desfire_limited_credit_ex, mifare_desfire_write_record,
     mifare_desfire_write_record_ex, mifare_desfire_read_records,
     mifare_desfire_read_records_ex, mifare_desfire_clear_record_file,
     mifare_desfire_commit_transaction,	mifare_desfire_abort_transaction, --
     Mifare DESFire Manipulation Functions

LIBRARY
     Mifare card manipulation library (libfreefare, -lfreefare)

SYNOPSIS
     #include <freefare.h>

     int
     mifare_desfire_connect(MifareTag tag);

     int
     mifare_desfire_disconnect(MifareTag tag);

     int
     mifare_desfire_authenticate(MifareTag tag,	uint8_t	key_no,
	 MifareDESFireKey key);

     int
     mifare_desfire_authenticate_aes(MifareTag tag, uint8_t key_no,
	 MifareDESFireKey key);

     int
     mifare_desfire_authenticate_iso(MifareTag tag, uint8_t key_no,
	 MifareDESFireKey key);

     int
     mifare_desfire_change_key_settings(MifareTag tag, uint8_t settings);

     int
     mifare_desfire_get_key_settings(MifareTag tag, uint8_t *settings,
	 uint8_t *max_keys);

     int
     mifare_desfire_change_key(MifareTag tag, uint8_t key_no,
	 MifareDESFireKey new_key, MifareDESFireKey old_key);

     int
     mifare_desfire_get_key_version(MifareTag tag, uint8_t key_no,
	 uint8_t *version);

     int
     mifare_desfire_create_application(MifareTag tag, MifareDESFireAID aid,
	 uint8_t settings, uint8_t key_no);

     int
     mifare_desfire_create_application_aes(MifareTag tag,
	 MifareDESFireAID aid, uint8_t settings, uint8_t key_no);

     int
     mifare_desfire_create_application_3k3des(MifareTag	tag,
	 MifareDESFireAID aid, uint8_t settings, uint8_t key_no);

     int
     mifare_desfire_create_application_iso(MifareTag tag,
	 MifareDESFireAID aid, uint8_t settings, uint8_t key_no,
	 int want_iso_file_identifiers,	uint16_t iso_file_id,
	 uint8_t *iso_file_name, size_t	iso_file_name_len);

     int
     mifare_desfire_create_application_3k3des_iso(MifareTag tag,
	 MifareDESFireAID aid, uint8_t settings, uint8_t key_no,
	 int want_iso_file_identifiers,	uint16_t iso_file_id,
	 uint8_t *iso_file_name, size_t	iso_file_name_len);

     int
     mifare_desfire_create_application_aes_iso(MifareTag tag,
	 MifareDESFireAID aid, uint8_t settings, uint8_t key_no,
	 int want_iso_file_identifiers,	uint16_t iso_file_id,
	 uint8_t *iso_file_name, size_t	iso_file_name_len);

     int
     mifare_desfire_delete_application(MifareTag tag, MifareDESFireAID aid);

     int
     mifare_desfire_get_application_ids(MifareTag tag,
	 MifareDESFireAID *aids[], size_t *count);

     void
     mifare_desfire_free_application_ids(MifareDESFireAID aids[]);

     int
     mifare_desfire_get_df_names(MifareTag tag,	MifareDESFireDF	*dfs[],
	 size_t	*count);

     int
     mifare_desfire_select_application(MifareTag tag, MifareDESFireAID aid);

     int
     mifare_desfire_format_picc(MifareTag tag);

     int
     mifare_desfire_get_version(MifareTag tag,
	 struct	mifare_desfire_version_info *version_info);

     int
     mifare_desfire_free_mem(MifareTag tag, uint32_t *size);

     int
     mifare_desfire_set_configuration(MifareTag	tag, bool disable_format,
	 bool enable_random_uid);

     int
     mifare_desfire_set_default_key(MifareTag tag, MifareDESFireKey key);

     int
     mifare_desfire_set_ats(MifareTag tag, uint8_t *ats);

     int
     mifare_desfire_get_card_uid(MifareTag tag,	char **uid);

     int
     mifare_desfire_get_file_ids(MifareTag tag,	uint8_t	*files[],
	 size_t	*count);

     int
     mifare_desfire_get_iso_file_ids(MifareTag tag, uint16_t *files[],
	 size_t	*count);

     int
     mifare_desfire_get_file_settings(MifareTag	tag, uint8_t file_no,
	 struct	mifare_desfire_file_settings *settings);

     int
     mifare_desfire_change_file_settings(MifareTag tag,	uint8_t	file_no,
	 uint8_t communication_settings, uint16_t access_rights);

     int
     mifare_desfire_create_std_data_file(MifareTag tag,	uint8_t	file_no,
	 uint8_t communication_settings, uint16_t access_rights,
	 uint32_t file_size);

     int
     mifare_desfire_create_std_data_file_iso(MifareTag tag, uint8_t file_no,
	 uint8_t communication_settings, uint16_t access_rights,
	 uint32_t file_size, uint16_t iso_file_id);

     int
     mifare_desfire_create_backup_data_file(MifareTag tag, uint8_t file_no,
	 uint8_t communication_settings, uint16_t access_rights,
	 uint32_t file_size);

     int
     mifare_desfire_create_backup_data_file_iso(MifareTag tag,
	 uint8_t file_no, uint8_t communication_settings,
	 uint16_t access_rights, uint32_t file_size, uint16_t iso_file_id);

     int
     mifare_desfire_create_value_file(MifareTag	tag, uint8_t file_no,
	 uint8_t communication_settings, uint16_t access_rights,
	 int32_t lower_limit, int32_t upper_limit, int32_t value,
	 uint8_t limited_credit_enable);

     int
     mifare_desfire_create_linear_record_file(MifareTag	tag, uint8_t file_no,
	 uint8_t communication_settings, uint16_t access_rights,
	 uint32_t record_size, uint32_t	max_number_of_records);

     int
     mifare_desfire_create_linear_record_file_iso(MifareTag tag,
	 uint8_t file_no, uint8_t communication_settings,
	 uint16_t access_rights, uint32_t record_size,
	 uint32_t max_number_of_records);

     int
     mifare_desfire_create_cyclic_record_file(MifareTag	tag, uint8_t file_no,
	 uint8_t communication_settings, uint16_t access_rights,
	 uint32_t record_size, uint32_t	max_number_of_records,
	 uint16_t iso_file_id);

     int
     mifare_desfire_create_cyclic_record_file_iso(MifareTag tag,
	 uint8_t file_no, uint8_t communication_settings,
	 uint16_t access_rights, uint32_t record_size,
	 uint32_t max_number_of_records, uint16_t iso_file_id);

     int
     mifare_desfire_delete_file(MifareTag tag, uint8_t file_no);

     ssize_t
     mifare_desfire_read_data(MifareTag	tag, uint8_t file_no, off_t offset,
	 size_t	length,	void *data);

     ssize_t
     mifare_desfire_read_data_ex(MifareTag tag,	uint8_t	file_no, off_t offset,
	 size_t	length,	void *data, int	cs);

     ssize_t
     mifare_desfire_write_data(MifareTag tag, uint8_t file_no, off_t offset,
	 size_t	length,	void *data);

     ssize_t
     mifare_desfire_write_data_ex(MifareTag tag, uint8_t file_no,
	 off_t offset, size_t length, void *data, int cs);

     int
     mifare_desfire_get_value(MifareTag	tag, uint8_t file_no, int32_t *value);

     int
     mifare_desfire_get_value_ex(MifareTag tag,	uint8_t	file_no,
	 int32_t *value, int cs);

     int
     mifare_desfire_credit(MifareTag tag, uint8_t file_no, int32_t amount);

     int
     mifare_desfire_credit_ex(MifareTag	tag, uint8_t file_no, int32_t amount,
	 int cs);

     int
     mifare_desfire_debit(MifareTag tag, uint8_t file_no, int32_t amount);

     int
     mifare_desfire_debit_ex(MifareTag tag, uint8_t file_no, int32_t amount,
	 int cs);

     int
     mifare_desfire_limited_credit(MifareTag tag, uint8_t file_no,
	 int32_t amount);

     int
     mifare_desfire_limited_credit_ex(MifareTag	tag, uint8_t file_no,
	 int32_t amount, int cs);

     ssize_t
     mifare_desfire_write_record(MifareTag tag,	uint8_t	file_no, off_t offset,
	 size_t	length,	void *data);

     ssize_t
     mifare_desfire_write_record_ex(MifareTag tag, uint8_t file_no,
	 off_t offset, size_t length, void *data, int cs);

     ssize_t
     mifare_desfire_read_records(MifareTag tag,	uint8_t	file_no, off_t offset,
	 size_t	length,	void *data);

     ssize_t
     mifare_desfire_read_records_ex(MifareTag tag, uint7_t file_no,
	 off_t offset, size_t length, void *data, int cs);

     int
     mifare_desfire_clear_record_file(MifareTag	tag, uint8_t file_no);

     int
     mifare_desfire_commit_transaction(MifareTag tag);

     int
     mifare_desfire_abort_transaction(MifareTag	tag);

DESCRIPTION
     The mifare_desfire_*() functions allows management	of Mifare DESFire
     tags.

   Card-level operations
     The mifare_desfire_connect() and mifare_desfire_disconnect() functions
     activates and deactivates the provided tag.  All mifare_desfire_*() func-
     tions that	operates on a tag require it to	be on activated.

     After activation, the selected application	is the master application.  It
     is	possible to select another application using the
     mifare_desfire_select_application() function (see bellow).

     The mifare_desfire_get_version() function retrieve	various	information
     about the provided	tag, including UID, batch number, production date, and
     hardware and software information.	 Refer to the freefare.h header	file
     for details about the version_info	field.

     The mifare_desfire_free_mem() functions returns the size of the free mem-
     ory on the	PICC (in bytes).

     The mifare_desfire_set_configuration() function can be used to deactivate
     the format	function when setting disable_format to	a value	different from
     0,	or swicth the card to use random UDI setting enable_random_uid to a
     non-zero value.

     The mifare_desfire_set_default_key	function sets the key argument as the
     default key for new applications.

     The mifare_desfire_set_ats	function replace the ATS bytes returned	by
     PICC when it is selected.

     The mifare_desfire_get_card_uid function can be used with a PICC config-
     ured for using random UID to retrieve the original	UID of the target.

     The mifare_desfire_format_picc() function resets tag to factory defaults.
     For this function to work,	a previous authentication with the card	master
     key is required.

   Application-level operations
     The mifare_desfire_select_application() function makes the	application
     identified	by aid the active one.	Further	file operations	will be	per-
     formed in the context of this application.	 After a call to
     mifare_desfire_connect, the default application is	the card master	appli-
     cation.  It can be	selected again calling the
     mifare_desfire_select_application() function either with an aid with all
     its fields	set to 0, or by	providing the NULL aid.

     The mifare_desfire_authenticate() function	performs an authentication
     using the key number key_no on the	card and the key (3)DES	key on tag.

     The mifare_desfire_authenticate_aes() function performs an	authentication
     using an AES key.

     The mifare_desfire_authenticate_iso() function performs an	ISO authenti-
     cation using either a 3DES	or a 3K3DES key.

     The mifare_desfire_get_key_settings() function, returns the settings and
     the number	of keys	max_keys of the	selected application.

     The mifare_desfire_change_key_settings() function changes the selected
     application settings to settings.	The application	number of keys cannot
     be	changed	after the application has been created.

     The mifare_desfire_change_key() changes the key key_no from old_key to
     new_key on	tag.  Depending	on the application settings, a previous
     authentication with the same key or another key may be required.

     The mifare_desfire_get_key_version() function retrieves the version of
     the key with number key_no	of the selected	application.

     The mifare_desfire_create_application() function, creates an application
     with AID aid, the settings	key settings and key_no	authentication keys.
     Authentication keys are set to 0 after creation.

     The mifare_desfire_create_application_3k3des() and
     mifare_desfire_create_application_aes() functions acts as the
     mifare_desfire_create_application() function except that the whole	appli-
     cation is configured to use 3K3DES	or AES keys.  It is possible to	achive
     the same result using the mifare_desfire_create_application() function
     and ORing the key_no argument with	APPLICATION_CRYPTO_3K3DES or
     APPLICATION_CRYPTO_AES respectively.

     The mifare_desfire_create_application_iso() acts as the
     mifare_desfire_create_application() function but allows one to specify if
     the created files within the application shall have an ISO	file identi-
     fier setting want_iso_file_identifiers to a non-NULL value, a DF can be
     provided using iso_file_id, as long as an optional	file name
     iso_file_name of length iso_file_name_len (in bytes).

     The mifare_desfire_create_application_3k3des_iso()	and
     mifare_desfire_create_application_aes_iso() function acts as the regular
     mifare_desfire_create_application_3k3des()	and
     mifare_desfire_create_application_aes() functions,	providing the same
     extensions	ISO parameters of mifare_desfire_create_application_iso().

     The mifare_desfire_delete_application() deletes the application identi-
     fied by AID aid.

     The mifare_desfire_get_application_ids() function returns a list of all
     applications of the card.	The aids array has to be freed after usage
     calling mifare_desfire_free_application_ids().

     The mifare_desfire_get_df_names() retrieves the list of DF	dfs from tag
     and set count to the number of idems in the allocated array. Memory has
     to	be freed by the	user using free(3).

   File-level operations
     The mifare_desfire_get_file_ids() function	returns	the list of count
     files in the selected application as files.  The memory allocated for
     files has to be reclaimed using free(3).

     The mifare_desfire_get_iso_file_ids() function returns the	list of	count
     file ISO identifiers as files.  The memory	allocated for files has	to be
     reclaimed using free(3).

     The mifare_desfire_get_file_settings() function retrieves the settings of
     the file file_no of the selected application of tag.

     The mifare_desfire_change_file_settings() function	change the
     communication_settings and	access_rights of the file file_no of the
     selected application of tag.

     The mifare_desfire_create_*() family of functions create a	new file
     file_no with the provided communication_settings and access_rights	on
     tag.

     mifare_desfire_create_std_data_file()
	     creates a standard	data file of size file_size.

     mifare_desfire_create_backup_data_file()
	     creates a backup data file	of size	file_size.

     mifare_desfire_create_value_file()
	     creates a value file of value value constrained in	the range
	     lower_limit upper_limit, and with the limited_credit_enable set-
	     tings.

     mifare_desfire_create_linear_record_file()
	     creates a linear record file that can hold	max_number_of_records
	     records of	size record_size.

     mifare_desfire_create_cyclic_record_file()
	     creates a cyclic record file that can hold	max_number_of_records
	     records of	size record_size.

     The mifare_desfire_create_*_iso() family of functions acts	as the func-
     tions without the _iso suffix but provide an additionnal argument
     iso_file_id.

     The mifare_desfire_delete_file() removes the file file_no from the
     selected application of tag.

   Data-level operations
     The mifare_desfire_read_data() function reads length bytes	of data	from
     offset offset of the file file_no and copies it to	data.  If length is
     set to 0, the file	is read	to end.	The function returns the number	of
     bytes read.

     The mifare_desfire_write_data() function writes length bytes of data from
     offset offset of the file file_no and copies it to	data.  The function
     returns the number	of bytes written.

     The mifare_desfire_get_value() reads the value of the file	file_no	of the
     selected application.

     The mifare_desfire_credit() function adds amount to the value of the file
     file_no of	the selected application.

     The mifare_desfire_debit()	function substracts amount to the value	of the
     file file_no of the selected application.

     to	the value of the file file_no of the selected application.

     The mifare_desfire_limited_credit() function adds amount to the value of
     the file file_no of the selected application.

     The mifare_desfire_write_record() function	writes length records starting
     at	record offset of data in the file file_no and returns the number of
     bytes written.

     The mifare_desfire_read_records() function	reads length records starting
     at	record offset from the file file_no and	copy them to data, returning
     the number	of bytes read.

     The mifare_desfire_clear_record_file() function erase all records from
     the file file_no of the selected application.

     The mifare_desfire_commit_transaction() validates the set of pending
     changes on	the tag, while the mifare_desfire_abort_transaction() roll-
     backs the changes.

     All data-manipulation functions that read data from and write data	to
     files come	with an	*_ex() variant (e.g.  mifare_desfire_read_data_ex())
     which accepts an extra parameter cs that defines the communication	set-
     tings to use.  If not provided, the library will try to read-out this
     value from	the file's configuration.  Because reading this	information
     may be denied, the	*_ex() variant of functions still allows using the
     library for advanced usage.

RETURN VALUES
     Unless stated otherwise, all other	functions return a value greater than
     or	equal to 0 on success or -1 on failure.

SEE ALSO
     freefare(3)

AUTHORS
     Romain Tartiere <romain@il4p.org>

FreeBSD	Ports 11.2		March 26, 2011		    FreeBSD Ports 11.2

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | RETURN VALUES | SEE ALSO | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=mifare_desfire_connect&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help