Chameleon-Mini
DESFireInstructions.h
1 /*
2 The DESFire stack portion of this firmware source
3 is free software written by Maxie Dion Schmidt (@maxieds):
4 You can redistribute it and/or modify
5 it under the terms of this license.
6 
7 This program is distributed in the hope that it will be useful,
8 but WITHOUT ANY WARRANTY; without even the implied warranty of
9 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
10 
11 The complete source distribution of
12 this firmware is available at the following link:
13 https://github.com/maxieds/ChameleonMiniFirmwareDESFireStack.
14 
15 Based in part on the original DESFire code created by
16 @dev-zzo (GitHub handle) [Dmitry Janushkevich] available at
17 https://github.com/dev-zzo/ChameleonMini/tree/desfire.
18 
19 This notice must be retained at the top of all source files where indicated.
20 */
21 
22 /*
23  * DESFireInstructions.h :
24  * Maxie D. Schmidt (github.com/maxieds)
25  */
26 
27 #ifndef __DESFIRE_INS_COMMANDS_H__
28 #define __DESFIRE_INS_COMMANDS_H__
29 
30 #include "DESFireFirmwareSettings.h"
31 #include "DESFireCrypto.h"
32 
33 #define DESFIRE_VERSION1_BYTES_PROCESSED (8)
34 #define DESFIRE_VERSION2_BYTES_PROCESSED (8)
35 #define DESFIRE_VERSION3_BYTES_PROCESSED (15)
36 
37 typedef struct DESFIRE_FIRMWARE_PACKING {
38  uint8_t NextIndex;
39  uint8_t CryptoMethodType;
40  uint8_t ActiveCommMode;
41  uint8_t KeyId;
42  uint8_t RndB[CRYPTO_CHALLENGE_RESPONSE_BYTES] DESFIRE_FIRMWARE_ARRAY_ALIGNAT;
43 } DesfireSavedCommandStateType;
44 extern DesfireSavedCommandStateType DesfireCommandState;
45 
46 typedef struct DESFIRE_FIRMWARE_PACKING {
47  BYTE BytesProcessed;
48  BOOL IsComplete;
49 } TransferStatus;
50 
51 typedef enum DESFIRE_FIRMWARE_ENUM_PACKING {
52 
53  /* DESFire native command support: */
54  NO_COMMAND_TO_CONTINUE = 0x00,
55  CMD_AUTHENTICATE = 0x0A, /* Authenticate Legacy */
56  CMD_AUTHENTICATE_ISO = 0x1A,
57  CMD_AUTHENTICATE_AES = 0xAA,
58  CMD_AUTHENTICATE_EV2_FIRST = 0x71, /* See page 32 of AN12343.pdf */
59  CMD_AUTHENTICATE_EV2_NONFIRST = 0x77, /* See page 32 of AN12343.pdf */
60  CMD_CHANGE_KEY_SETTINGS = 0x54,
61  CMD_SET_CONFIGURATION = 0x5C,
62  CMD_CHANGE_KEY = 0xC4,
63  CMD_GET_KEY_VERSION = 0x64,
64  CMD_CREATE_APPLICATION = 0xCA,
65  CMD_DELETE_APPLICATION = 0xDA,
66  CMD_GET_APPLICATION_IDS = 0x6A,
67  CMD_FREE_MEMORY = 0x6E,
68  CMD_GET_DF_NAMES = 0x6D,
69  CMD_GET_KEY_SETTINGS = 0x45,
70  CMD_SELECT_APPLICATION = 0x5A,
71  CMD_FORMAT_PICC = 0xFC,
72  CMD_GET_VERSION = 0x60,
73  CMD_GET_CARD_UID = 0x51,
74  CMD_GET_FILE_IDS = 0x6F,
75  CMD_GET_FILE_SETTINGS = 0xF5,
76  CMD_CHANGE_FILE_SETTINGS = 0x5F,
77  CMD_CREATE_STDDATA_FILE = 0xCD,
78  CMD_CREATE_BACKUPDATA_FILE = 0xCB,
79  CMD_CREATE_VALUE_FILE = 0xCC,
80  CMD_CREATE_LINEAR_RECORD_FILE = 0xC1,
81  CMD_CREATE_CYCLIC_RECORD_FILE = 0xC0,
82  CMD_DELETE_FILE = 0xDF,
83  CMD_GET_ISO_FILE_IDS = 0x61,
84  CMD_READ_DATA = 0xBD,
85  CMD_WRITE_DATA = 0x3D,
86  CMD_GET_VALUE = 0x6C,
87  CMD_CREDIT = 0x0C,
88  CMD_DEBIT = 0xDC,
89  CMD_LIMITED_CREDIT = 0x1C,
90  CMD_WRITE_RECORD = 0x3B,
91  CMD_READ_RECORDS = 0xBB,
92  CMD_CLEAR_RECORD_FILE = 0xEB,
93  CMD_COMMIT_TRANSACTION = 0xC7,
94  CMD_ABORT_TRANSACTION = 0xA7,
95  CMD_CONTINUE = 0xAF,
96 
97  /* ISO7816 Command Set Support: */
98  CMD_ISO7816_SELECT = 0xA4,
99  CMD_ISO7816_GET_CHALLENGE = 0x84,
100  CMD_ISO7816_EXTERNAL_AUTHENTICATE = 0x82,
101  CMD_ISO7816_INTERNAL_AUTHENTICATE = 0x88,
102  CMD_ISO7816_READ_BINARY = 0xB0,
103  CMD_ISO7816_UPDATE_BINARY = 0xD6,
104  CMD_ISO7816_READ_RECORDS = 0xB2,
105  CMD_ISO7816_APPEND_RECORD = 0xE2,
106 
107  /* Space for undocumented command codes --
108  * Need command codes and parameters to make these work moving forward: */
109  //CMD_READ_SIGNATURE /* See page 87 of AN12343.pdf (for Mifare DESFire Light tags) */
110 
111 } DESFireCommandType;
112 
113 typedef uint16_t (*InsCodeHandlerFunc)(uint8_t *Buffer, uint16_t ByteCount);
114 
115 typedef struct {
116  DESFireCommandType insCode;
117  InsCodeHandlerFunc insFunc;
118  const __flash char *insDesc;
119 } DESFireCommand;
120 
121 extern const __flash DESFireCommand DESFireCommandSet[];
122 
123 /* Helper and batch process functions */
124 uint16_t CallInstructionHandler(uint8_t *Buffer, uint16_t ByteCount);
125 uint16_t ExitWithStatus(uint8_t *Buffer, uint8_t StatusCode, uint16_t DefaultReturnValue);
126 uint16_t CmdNotImplemented(uint8_t *Buffer, uint16_t ByteCount);
127 
128 /*
129  * The following section implements:
130  * DESFire EV0 / D40 specific commands
131  */
132 
133 /* General commands */
134 uint16_t EV0CmdGetVersion1(uint8_t *Buffer, uint16_t ByteCount);
135 uint16_t EV0CmdGetVersion2(uint8_t *Buffer, uint16_t ByteCount);
136 uint16_t EV0CmdGetVersion3(uint8_t *Buffer, uint16_t ByteCount);
137 uint16_t EV0CmdFormatPicc(uint8_t *Buffer, uint16_t ByteCount);
138 uint16_t DesfireCmdGetCardUID(uint8_t *Buffer, uint16_t ByteCount);
139 uint16_t DesfireCmdSetConfiguration(uint8_t *Buffer, uint16_t ByteCount); // ?? Docs ??
140 uint16_t DesfireCmdFreeMemory(uint8_t *Buffer, uint16_t ByteCount); // returns free memory on the tag
141 
142 /* Key management commands */
143 uint16_t EV0CmdChangeKey(uint8_t *Buffer, uint16_t ByteCount);
144 uint16_t EV0CmdGetKeySettings(uint8_t *Buffer, uint16_t ByteCount);
145 uint16_t EV0CmdChangeKeySettings(uint8_t *Buffer, uint16_t ByteCount);
146 uint16_t DesfireCmdGetKeyVersion(uint8_t *Buffer, uint16_t ByteCount);
147 
148 /* Application management commands */
149 uint16_t EV0CmdGetApplicationIds1(uint8_t *Buffer, uint16_t ByteCount);
150 uint16_t EV0CmdCreateApplication(uint8_t *Buffer, uint16_t ByteCount);
151 uint16_t EV0CmdDeleteApplication(uint8_t *Buffer, uint16_t ByteCount);
152 uint16_t EV0CmdSelectApplication(uint8_t *Buffer, uint16_t ByteCount);
153 uint16_t DesfireCmdGetDFNames(uint8_t *Buffer, uint16_t ByteCount);
154 
155 /* File management commands */
156 uint16_t EV0CmdCreateStandardDataFile(uint8_t *Buffer, uint16_t ByteCount);
157 uint16_t EV0CmdCreateBackupDataFile(uint8_t *Buffer, uint16_t ByteCount);
158 uint16_t EV0CmdCreateValueFile(uint8_t *Buffer, uint16_t ByteCount);
159 uint16_t EV0CmdCreateLinearRecordFile(uint8_t *Buffer, uint16_t ByteCount);
160 uint16_t EV0CmdCreateCyclicRecordFile(uint8_t *Buffer, uint16_t ByteCount);
161 uint16_t EV0CmdDeleteFile(uint8_t *Buffer, uint16_t ByteCount);
162 uint16_t EV0CmdGetFileIds(uint8_t *Buffer, uint16_t ByteCount);
163 uint16_t EV0CmdGetFileSettings(uint8_t *Buffer, uint16_t ByteCount);
164 uint16_t EV0CmdChangeFileSettings(uint8_t *Buffer, uint16_t ByteCount);
165 
166 /* Data manipulation commands */
167 // NOTE: Page 57: Read file functions:
168 uint16_t EV0CmdReadData(uint8_t *Buffer, uint16_t ByteCount);
169 uint16_t EV0CmdWriteData(uint8_t *Buffer, uint16_t ByteCount);
170 uint16_t EV0CmdGetValue(uint8_t *Buffer, uint16_t ByteCount);
171 uint16_t EV0CmdCredit(uint8_t *Buffer, uint16_t ByteCount);
172 uint16_t EV0CmdDebit(uint8_t *Buffer, uint16_t ByteCount);
173 uint16_t EV0CmdLimitedCredit(uint8_t *Buffer, uint16_t ByteCount);
174 uint16_t EV0CmdReadRecords(uint8_t *Buffer, uint16_t ByteCount);
175 uint16_t EV0CmdWriteRecord(uint8_t *Buffer, uint16_t ByteCount);
176 uint16_t EV0CmdClearRecords(uint8_t *Buffer, uint16_t ByteCount);
177 
178 /* Transaction handling commands */
179 uint16_t EV0CmdCommitTransaction(uint8_t *Buffer, uint16_t ByteCount);
180 uint16_t EV0CmdAbortTransaction(uint8_t *Buffer, uint16_t ByteCount);
181 
182 /* EV1/EV2 supported commands */
183 uint16_t EV0CmdAuthenticateLegacy1(uint8_t *Buffer, uint16_t ByteCount);
184 uint16_t EV0CmdAuthenticateLegacy2(uint8_t *Buffer, uint16_t ByteCount);
185 uint16_t DesfireCmdAuthenticate3KTDEA1(uint8_t *Buffer, uint16_t ByteCount);
186 uint16_t DesfireCmdAuthenticate3KTDEA2(uint8_t *Buffer, uint16_t ByteCount);
187 uint16_t DesfireCmdAuthenticateAES1(uint8_t *Buffer, uint16_t ByteCount);
188 uint16_t DesfireCmdAuthenticateAES2(uint8_t *Buffer, uint16_t ByteCount);
189 
190 /* ISO7816 command handling */
191 uint16_t ISO7816CmdSelect(uint8_t *Buffer, uint16_t ByteCount);
192 uint16_t ISO7816CmdSelectEF(uint8_t *Buffer, uint16_t ByteCount);
193 uint16_t ISO7816CmdSelectDF(uint8_t *Buffer, uint16_t ByteCount);
194 uint16_t ISO7816CmdGetChallenge(uint8_t *Buffer, uint16_t ByteCount);
195 uint16_t ISO7816CmdExternalAuthenticate(uint8_t *Buffer, uint16_t ByteCount);
196 uint16_t ISO7816CmdInternalAuthenticate(uint8_t *Buffer, uint16_t ByteCount);
197 uint16_t ISO7816CmdReadBinary(uint8_t *Buffer, uint16_t ByteCount);
198 uint16_t ISO7816CmdUpdateBinary(uint8_t *Buffer, uint16_t ByteCount);
199 uint16_t ISO7816CmdReadRecords(uint8_t *Buffer, uint16_t ByteCount);
200 uint16_t ISO7816CmdAppendRecord(uint8_t *Buffer, uint16_t ByteCount);
201 
202 #endif