How to use FIDESMO API to operate MIFARE DESFire® EV1 cards
Service Providers (SP) can make use of Fidesmo API methods to handle Secure Elements (SE), i.e. chips.
The full Fidesmo API is documented in this page. Here some code
examples are shown, they depict how SPs can make use of the three MIFARE DESFire®-related methods of that API to
operate on the MIFARE DESFire® implementation of Fidesmo chips. For the sake of clarity this page shows how
those requests would be built using bash
, but when sent from an SP they would be of course built in
the same language the SP is coded.
To fully benefit from this examples developers should have a good knowledge of DESFire® EV1® specifications. Also, readers of this material should be familiar with Fidesmo architecture, in the description of Fidesmo architecture there is a good introductory explanation of how Fidesmo works and key concepts such as Service Provider. Finally, it is strongly advised to read the doc explaining how Fidesmo enables developers to operate MIFARE DESFire® EV1 chips.
Preliminary steps
As it is explained in the description of Fidesmo
architecture, SP developers must first create a Fidesmo
developer account, and then create a new
Fidesmo application which will be associated to the SP. The new application will be assigned an id and
key, that would be the id and key used in the code snippets in the next sections. Finally, before sending
requests to Fidesmo backend it is needed to setup a session between the backend and the SP (the Setup
Phase mentioned in the description of Fidesmo
architecture). Once the session is created the SP will have a sessionId
that will be
used in all the requests of that session.
Creating a MIFARE DESFire® EV1 application
As described in Fidesmo API, the creation of a MIFARE DESFire® app is done through a POST
request to https://api.fidesmo.com/desfire/ev1/createApp
URL. This
request must carry in its body the required parameters in JSON format: AID of the application, application
master key, and both key settings. All values are in hexadecimal format. Like any call to Fidesmo API, the
POST
request must include as headers the session ID and callback URL where the result of the
request will be notified to, along with the application id and key of the application the SP is associated to
(see previous section). The session ID was provided by Fidesmo backend in the service delivery request
message (again, see description of Fidesmo's
architecture), the callback URL can be any address the SP can listen to. The following example shows
how to build and send a request to create a MIFARE DESFire® app.
$ export APP_ID="FEDCBA98" # Application id in Fidesmo dev portal $ export APP_KEY="01234567-ABCD-ABCD-ABCD-0123456789AB" # Application key in Fidesmo dev portal $ export SESSION_ID="01234567-ABCD-ABCD-ABCD-0123456789AB" # Given by Fidesmo backend once session is established $ export CALLBACK_URL="http://mysp.com/operationsresults" # Where backend shall send the op result $ export AID="1234AB" # AID of new DESFire® application $ export AMK="00112233445566778899AABBCCDDEEFF" # Application master key of new DESFire® app $ export KEY_SETTING_1="AB" # Key setting first byte $ export KEY_SETTING_2="CD" # Key setting second byte $ curl \ -H "app_id: $APP_ID" \ -H "app_key: $APP_KEY" \ -H "sessionId: $SESSION_ID" \ -H "callbackUrl: $CALLBACK_URL" \ -H "Content-Type: application/json" \ -d "{\"aid\":\"$AID\", \"amk\":\"$AMK\", \"keySetting1\": \"$KEY_SETTING_1\", \"keySetting2\": \"$KEY_SETTING_2\"}" \ -X POST https://api.fidesmo.com/desfire/ev1/createApp
Sending MIFARE DESFire® EV1 APDUs to application
MIFARE DESFire® APDUs are sent as an array de strings (one per APDU) in hex format. Requests are sent to
https://api.fidesmo.com/desfire/ev1/transceive
URL. Fidesmo backend will
send to the callbackUrl
the result of each command as another array.
$ export APP_ID="FEDCBA98" # Application id in Fidesmo dev portal $ export APP_KEY="01234567-ABCD-ABCD-ABCD-0123456789AB" # Application key in Fidesmo dev portal $ export SESSION_ID="01234567-ABCD-ABCD-ABCD-0123456789AB" # Given by Fidesmo backend once session is established $ export CALLBACK_URL="http://mysp.com/operationsresults" # Where backend shall send the op result $ export COMMANDS="[\"01234567\", \"89ABCDEF\"]" # DESFire APDU commands, hex format $ curl \ -H "app_id: $APP_ID" \ -H "app_key: $APP_KEY" \ -H "sessionId: $SESSION_ID" \ -H "callbackUrl: $CALLBACK_URL" \ -H "Content-Type: application/json" \ -d "{\"commands\": $COMMANDS}" \ -X POST https://api.fidesmo.com/desfire/ev1/transceive
Reply will contain a JSON document with a responses
field. Each String
in
responses
is a response in HEX format. Responses are in the same order than the original MIFARE
DESFire® commands that were sent to the backend.
Deleting a MIFARE DESFire® EV1 application
Requests to delete MIFARE DESFire® applications are similar to the ones to create them, but with less
parameters. It only requires the application AID and AMK (to check that the user requesting the app is its
owner). Requests are sent to
https://api.fidesmo.com/desfire/ev1/deleteApp
URL. Code would be as
follows:
$ export APP_ID="FEDCBA98" # Application id in Fidesmo dev portal $ export APP_KEY="01234567-ABCD-ABCD-ABCD-0123456789AB" # Application key in Fidesmo dev portal $ export SESSION_ID="01234567-ABCD-ABCD-ABCD-0123456789AB" # Given by Fidesmo backend once session is established $ export CALLBACK_URL="http://mysp.com/operationsresults" # Where backend shall send the op result $ export AID="1234AB" # AID of new DESFire® application $ export AMK="00112233445566778899AABBCCDDEEFF" # Application master key of new DESFire® app $ export KEY_SETTING_1="AB" # Key setting first byte $ export KEY_SETTING_2="CD" # Key setting second byte $ curl \ -H "app_id: $APP_ID" \ -H "app_key: $APP_KEY" \ -H "sessionId: $SESSION_ID" \ -H "callbackUrl: $CALLBACK_URL" \ -H "Content-Type: application/json" \ -d "{\"aid\":\"$AID\", \"amk\":\"$AMK\"}" \ -X POST https://api.fidesmo.com/desfire/ev1/deleteApp
NXP®, MIFARE, and DESFire® are registered trademarks of NXP® B.V. and are used under license.