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

How to use FIDESMO API to operate MIFARE DESFire® EV1 cards

Preliminary steps

Creating a MIFARE DESFire® EV1 application

Sending MIFARE DESFire® EV1 APDUs to application

Deleting a MIFARE DESFire® EV1 application

NXP®, MIFARE, and DESFire® are registered trademarks of NXP® B.V. and are used under license.