doc/cipurse.md

   1 # Notes on CIPURSE card
   2 <a id="Top"></a>
   3
   4 # Table of Contents
   5
   6 - [Notes on CIPURSE card](#notes-on-cipurse-card)
   7 - [Table of Contents](#table-of-contents)
   8   - [Documentation](#documentation)
   9   - [Source code](#source-code)
  10   - [Communication channel with a card](#communication-channel-with-a-card)
  11   - [Card architecture](#card-architecture)
  12   - [Card structure](#card-structure)
  13   - [How to](#how-to)
  14   - [How to select application or file](#how-to-select-application-or-file)
  15   - [How to delete application or file](#how-to-delete-application-or-file)
  16   - [How to read file](#how-to-read-file)
  17   - [How to write file](#how-to-write-file)
  18   - [How to read file attributes](#how-to-read-file-attributes)
  19   - [How to set file attributes](#how-to-set-file-attributes)
  20   - [How to update key](#how-to-update-key)
  21     - [How to personalize card](#how-to-personalize-card)
  22
  23
  24 ## Documentation
  25 ^[Top](#top)
  26
  27 Useful links to documentation about CIPURSE.
  28 [full documentation accessible from osptalliance](https://www.osptalliance.org/)
  29 [Infineon cipurse](https://www.infineon.com/cms/en/product/security-smart-card-solutions/cipurse-products/)
  30 [Infineon cipurse card SLS 32TLC100(M)](https://www.infineon.com/cms/en/product/security-smart-card-solutions/cipurse-products/sls-32tlc100m/)
  31
  32
  33 ## Source code
  34 ^[Top](#top)
  35
  36 Useful links to Implementations / Source code on Github.
  37 [cipurse card emulation](https://github.com/duychuongvn/demo-nfc/tree/master/smart-ticket-demo/app/src/main/java/ch/smartlink/smartticketdemo/cipurse)
  38 [cipurse card core](https://github.com/duychuongvn/cipurse-card-core)
  39 [card side some code](https://github.com/duychuongvn/cipurse-card-side)
  40
  41
  42 ## Communication channel with a card
  43 ^[Top](#top)
  44
  45 The card has two secure channels - the reader to the card and the card to the reader.
  46
  47 And each channel has 3 modes: `open, MACed, Encrypted`
  48
  49 After authentication reader can specify the mode for each channel for each command.
  50
  51 Card answers if the mode that sets by the reader matches the mode of the file and the command matches the key via an access list.
  52
  53
  54 ## Card architecture
  55 ^[Top](#top)
  56
  57 The card has one master file with FID 0x3F00 that works as the root node.
  58
  59 The card has several applications inside the master file and the applications may have files. There are PxSE (special type) applications that work as an applications directory.
  60
  61 Each application has keys and an access control list that sets what commands can be issued in the session that authenticates with a specific key.
  62
  63 Master file have keys and an access control list that works at the card level.
  64
  65 Each file can only have an access control list that specifies what operation the key can do with this file.
  66
  67 Card have transaction mechanism. Transaction not needs for control structure at application level and to change files without
  68 transaction mechanism. All the rest changes needs to issue COMMIT command (`--commit` key)
  69
  70 ## Card structure
  71 ^[Top](#top)
  72
  73 - Master file (MF)
  74 - Keys
  75 - Group security levels and access rights
  76 - files under master file (EF). Usually have no access to them.
  77
  78 - PxSE files (directory files)
  79
  80 - Application 1. Have AID (up to 16-bytes) and FID (2-bytes id)
  81     - Application keys
  82     - Group security levels and access rights
  83     - Application files (EF). Have type (1-byte) and FID ((2-bytes id))
  84
  85 - Application 2
  86 - ...
  87
  88
  89 ## How to
  90
  91 ### How to select application or file
  92 ^[Top](#top)
  93
  94 **1. select PTSE**
  95 ```hf cipurse select --aid a0000005070100```
  96
  97 select it with display output in raw and tlv views options
  98 ```hf cipurse select --aid a0000005070100 -vt```
  99
 100 2. select application by Application ID (AID)
 101 ```hf cipurse select --aid 4144204631```
 102
 103 3. select application/file by file ID (FID)
 104 ```hf cipurse select --fid 2000```
 105
 106 4. select master file by file ID (FID)
 107 ```hf cipurse select --fid 3F00```
 108
 109 5. select default file (usually it master file)
 110 ```hf cipurse select --mfd```
 111
 112
 113 ### How to delete application or file
 114 ^[Top](#top)
 115
 116 1. delete PTSE by AID
 117 ```hf cipurse delete --aid a0000005070100```
 118
 119 2. delete application by AID
 120 ```hf cipurse delete --aid 4144204631```
 121
 122 3. delete application/top level file by FID
 123 ```hf cipurse delete --fid 2000```
 124
 125 3. delete file by FID from default application `AD F1`
 126
 127 ```hf cipurse delete --aid 4144204631 --chfid 0102```
 128
 129
 130 ### How to read file
 131 ^[Top](#top)
 132
 133 with default key and aid
 134 ```hf cipurse read --fid 0102```
 135
 136 with default key and specified aid
 137 ```hf cipurse read --aid a0000005070100```
 138
 139 with default key and aid without authentication
 140 ```hf cipurse read --fid 0102 --no-auth```
 141
 142
 143 ### How to write file
 144 ^[Top](#top)
 145
 146 with default key and aid
 147 ```hf cipurse read --fid 0102 -d abbbccdd```
 148
 149 with default key and specified aid
 150 ```hf cipurse read --aid a0000005070100 -d abbbccdd```
 151
 152 with default key and aid without authentication
 153 ```hf cipurse read --fid 0102 -d abbbccdd --no-auth```
 154
 155 with default key and aid, perform commit (works for files with transactions mechanism switched on)
 156 ```hf cipurse read --fid 0102 -d abbbccdd --commit```
 157
 158
 159 ### How to read file attributes
 160 ^[Top](#top)
 161
 162 read master file attributes
 163 ```hf cipurse aread --mfd```
 164
 165 read EF.ID_INFO root file attributes
 166 ```hf cipurse aread --fid 2ff7```
 167
 168 read PxSE application attributes
 169 ```hf cipurse aread --aid a0000005070100```
 170
 171 read application attributes
 172 ```hf cipurse aread --aid 4144204632```
 173
 174 read file (EF) attributes
 175
 176 ```hf cipurse aread --aid 4144204632 --chfid 0102```
 177
 178 or with default application
 179
 180 ```hf cipurse aread --aid 4144204632 --chfid 0102```
 181
 182
 183 ### How to set file attributes
 184 ^[Top](#top)
 185
 186 set elementary file attributes (EF)
 187
 188   full access wo keys
 189 ```hf cipurse awrite --chfid 0102 -d 020000ffffff```
 190
 191   read access wo keys and full with all 2 keys
 192 ```hf cipurse awrite --chfid 0102 -d 02000040ffff```
 193
 194 set EF.ID_INFO file attributes
 195 ```hf cipurse awrite --fid 2ff7 -d 080000C1C1C1C1C1C1C1C1C1``` (as default)
 196
 197 set master file (MF) file attributes
 198 ```hf cipurse awrite --mfd -d 080000FFFFFFFFFFFFFFFFFF86023232 --commit``` (full access with/wo keys and tag 86 is set by `22`)
 199
 200
 201 ### How to update key
 202 ^[Top](#top)
 203
 204 update key for master application
 205 ```hf cipurse updakey --newkeyn 1 --newkeya 00 --newkey 73737373737373737373737373737373 --commit```
 206
 207 update key for application
 208 ```hf cipurse updakey --aid 4144204631 --newkeyn 1 --newkeya 00 --newkey 73737373737373737373737373737373 --commit```
 209
 210
 211 ### How to personalize card
 212 ^[Top](#top)
 213
 214 **1. Format card (if it needs)**
 215 ```hf cipurse formatall```
 216
 217 **2. Create create PxSE file**
 218
 219 The following command creates PTSE file with FID 0x2000, AID A0000005070100, and space for 8 AIDs
 220
 221 ```hf cipurse create -d 9200123F00200008000062098407A0000005070100```
 222
 223 ```
 224 9200123F00200008000062098407A0000005070100
 225           ----                               FID
 226               --                             Num of AIDs in list
 227                             --------------   AID
 228 ```
 229
 230
 231 **3. Create application file**
 232
 233 ```hf cipurse create -d 92002438613F010A05020000FFFFFF021009021009621084054144204631D407A0000005070100A00F2873737373737373737373737373737373015FD67B000102030405060708090A0B0C0D0E0F01C6A13B```
 234
 235 This command creates a application with following details:
 236   - FID.................... 0x3F01
 237   - AID.................... 4144204631
 238   - App type............... 61
 239   - Max files count........ 10
 240   - Max SFID count......... 5
 241   - Minimum command's group security levels: plain/plain/plain/plain (0000)
 242   - Access rights.......... all two keys can do anything (FFFFFF)
 243   - Key attributes......... 021009
 244   - 2 keys.........
 245     - `73..73`     (add. info 01 / kvv 5FD67B)
 246     - `0001..0e0f` (01/C6A13B)
 247   - Register in the PxSE... A0000005070100
 248
 249 **4. Create elementary file(s) (EF) inside the application**
 250
 251 ```hf cipurse create --aid 4144204631 -d 92010C010001020030020000FFFFFF --commit```
 252
 253 ```
 254   - parent application ID.. 4144204631
 255   - file type.............. 0x01 (binary file wo transaction)
 256   - SFID................... 0x00
 257   - FID.................... 0x0102
 258   - File size.............. 0x0030 (48 bytes)
 259   - Number of keys......... 0x02 (as in the parent application)
 260   - Minimum command's group security levels: plain/plain/plain/plain (0000)
 261   - Access rights.......... all two keys can do anything (FFFFFF)
 262 ```
 263
 264 **5. Save data to elementary file(s) (EF)**
 265
 266 ```hf cipurse write --fid 0102 -d 010203040506070809```
 267
 268 or if file with transaction mechanism
 269
 270
 271 ```hf cipurse write --fid 0102 -d 010203040506070809 --commit```
 272
 273
 274 **6. Check file(s) contents (if needs)**
 275 ```hf cipurse read --fid 0102```
 276
 277
 278 **8. Set the keys and needed key attributes**
 279
 280 keys for application usually filled at create time with DGI `A00F`
 281
 282 keys for masterfile needs to be updated manually with command:
 283 ```hf cipurse updakey --newkeyn 1 --newkeya 00 --newkey 73737373737373737373737373737373 --commit```
 284
 285 update key for application (if needs)
 286 ```hf cipurse updakey --aid 4144204631 --newkeyn 1 --newkeya 00 --newkey 73737373737373737373737373737373 --commit```
 287
 288 update key attributes with default attributes
 289 ```hf cipurse updakey --aid 4144204631 --trgkeyn 1 --attr 02 -v --commit```
 290
 291
 292 **8. Set the file attributes**
 293
 294 Set file attributes for:
 295 1. All the elementary files (EF)
 296 2. Info files (EF.ID_INFO)
 297 3. Application(s)
 298 4. PxSE application
 299 5. Master file itself (MF)
 300
 301 *(in this specific order!!!)*
 302