SOSSE is a simple operating system for smart cards which is opensource and free. It has been developed to provide a smart card platform for learning, experimenting and implementing inovative concepts. The hardware platform choosen for this project are the Funcards based on commercial-of-the-shelf AVR microcontrollers, because the hardware documentation is available without non-disclosure agreement.
All of the currently supported cards use the AVR-Microcontrollers from Atmel. The are e.g. called Funcard, Jupiter or Pink card. The used AVRs are the AT90S2323, AT90S2343, AT90S8515 and AT90S8535. There are even a few boards with the ATmega161 available. The data sheets for all Atmel AVR microcontrollers are available on the Atmel website.
The pinout of the AVR cards is as follows:
Additional to the smart cards, a programmer is needed. These are available at the same shops as the AVR cards.
SOSSE has been developed using the GCC development tools. These are available at http://combio.de/avr/. There are the sources, binaries and RPMs for Linux and binaries for MS Windows.
The C programming language has been choosen instead of assembler, because:
Test programms which run natively on the host operating system are built running:
make -f Makefile.emu
These can be used for comfortable debugging and testing using the normal GNU debugger. When the reset sequence is implemented, this can be used to simulate a SOSSE smart card via e.g. a Season interface.
A virtual card sitting in a virtual reader can be build with:
make -f Makefile.ctapi
This builds a CT-API driver, which can be used to test applications and to debug using a normal debugger.
CLA | INS | P1 | P2 | P3 |
20 | E0 | Flags | RFU | Length |
Byte(s) | Description | Length |
1 - Length | File name | Length |
SW | Description |
90 00 | Command completed successfully |
This command sets the parameter for EEPROM loading and saving for the virtual card.
If bit 1 of P1 is set, the EEPROM is saved at stopping of the ICC and if bit 2 is set, the EEPROM loaded at starting of the ICC. The file name for this operation is specified in the data field of the command.
The proprietary commands must be executed before a REQUEST ICC and RESET CT, because the parameters are held in RAM, which is separated by a fork at card reset.
A success of the command means only, that the variables have correctly been set. It does not verify, that the file is createable, readable or writeable.
The web page with up to date information about SOSSE is at:
http://www.mbsks.franken.de/sosse/
The download location of the SOSSE sources is at:
ftp://ftp.franken.de/pub/crypt/chipcards/sosse/
The documentation was generated using DoxyGen:
http://www.doxygen.org/
These File are only used, when filesystem support is compiled in. Otherwise special absolut locations in EEPROM are used to hold the data.
Path: 3F00FF00
Content:
Path: 3F00FF01
Content:
Path: 3F00FF02
Content:
CLA | INS | P1 | P2 | P3 |
80 | 02 | Address high | Address low | Length |
Byte(s) | Description | Length |
1 - Length | Data to write to Address | Length |
SW | Description |
90 00 | Command completed successfully |
65 00 | Memory failure (unsuccessful writing) |
67 00 | Wrong Lc |
This command can be used to directly write into EEPROM. The start address is specified in P1P2 and the data length in P3. If there exists an internal and external EEPROM, the address convention of the HAL is used. Currently the internal EEPROM is in the address range 0 - sizeof internal EEPROM. The external EEPROM starts directly afterwards.
This command should be disabled by setting CONF_WITH_TESTCMDS to 0 for a production version.
Data updates are NOT protected with transactions.
CLA | INS | P1 | P2 | P3 |
80 | 04 | Address high | Address low | Length |
Byte(s) | Description | Length |
1 - Length | Data read from Address | Length |
SW | Description |
90 00 | Command completed successfully |
This command can be used to directly read from EEPROM. The start address is specified in P1P2 and the data length in P3. If there exists an internal and external EEPROM, the address convention of the HAL is used. Currently the internal EEPROM is in the address range 0 - sizeof internal EEPROM. The external EEPROM starts directly afterwards.
This command should be disabled by setting CONF_WITH_TESTCMDS to 0 for a production version.
CLA | INS | P1 | P2 | P3 |
80 | 06 | Effect | Parameter | 00 |
SW | Description |
90 00 | Command completed successfully |
This command does control the LEDs present on some PCB AVR cards and shows some nice effects.
Effect type 0x01 does switch the LEDs specified in P2 on. Each bit controlls one LED. Which LED is controlled may be card dependent. Currently bits 0 - 6 control the leds beginning from the left, when looking down at them with the contacts to the top.
Effect type 0x02 does implement a runlight with the left 4 LED block. It may need adjustment on other cards to select the correct LEDs.
This command is only enabled when setting CONF_WITH_FUNNY to 1.
CLA | INS | P1 | P2 | P3 |
80 | 24 | 00 | 00 | 10 |
Byte(s) | Description | Length |
1 - 8 | Current PIN | 8 |
9 - 16 | New PIN | 8 |
SW | Description |
90 00 | Command completed successfully |
63 CX | Verification failed, retry counter specified |
67 00 | Wrong Lc |
69 83 | Authentication method blocked |
6A 86 | Incorrect parameters P1-P2 |
6A 88 | Referenced data not found |
This command changes the PIN of the card. The first four bytes of the data is the current PIN, which is checked for correctness. The second four bytes of the data is the new PIN, which will be written. On success the AUTH_FLAG_PIN bit in authstate is set, on fauilure it is cleared.
Warning: Currently the retry counter is not handled in a secure way. For more information see e.g. Rankl/Effing.
PIN update is protected with transactions.
CLA | INS | P1 | P2 | P3 |
80 | E0 | 00 | 00 | 06 |
Byte(s) | Description | Length |
1 - 2 | Size | 2 |
3 - 4 | FID | 2 |
5 | File type (DF: 38, EF: 00) | 1 |
6 | Access conditions (DF: Create/Delete, EF: Update/Read) | 1 |
SW | Description |
90 00 | Command completed successfully |
67 00 | Wrong Lc |
69 82 | Security status not satisfied |
69 86 | Command not allowed (no DF selected) |
6A 80 | Incorrect arameters in the data field |
6A 84 | Not enough free space in DF |
6A 86 | Incorrect parameters P1-P2 |
6A 89 | File exists already |
This command creates an elementary or dedicated file. To succeed the current file must be a dedicated file or the master file and the access conditions for file creation must be fulfilled.
The data of the command is the file header. It consists of a 2-byte size, 2-byte FID, 1-byte type and 1-byte access conditions. Size can't be 0000. The FID can't be 3F00 or FFFF. Valid file types are 00 for EF and 38 for DF. The access conditions are described in the next tables.
File type | High Nibble | Low Nibble |
DF | Create File | Delete File |
EF | Update | Read |
Nibble Value | Access condition |
0 | Always |
1 | PIN verified |
2 | External Authentication key verified |
3 | PIN or External Authentication Key verified |
4 | PIN and External Authentication Key verified |
F | Never |
File header updates are protected with transactions.
CLA | INS | P1 | P2 | P3 |
80 | E4 | 00 | 00 | 02 |
Byte(s) | Description | Length |
1 - 2 | FID | 2 |
SW | Description |
90 00 | Command completed successfully |
67 00 | Wrong Lc |
69 82 | Security status not satisfied |
69 86 | Command not allowed (no DF selected) |
6A 82 | File not found |
6A 86 | Incorrect parameters P1-P2 |
The file with the specified FID is deleted from the current file, which must be a DF or the MF. Also the access conditions for delete must be satisfied and the specified file must be the last one in the DF/MF. Deletion of a DF, which contains EFs, is possible.
File header updates are protected with transactions.
CLA | INS | P1 | P2 | P3 |
80 | 82 | 00 | 00 | 08 |
Byte(s) | Description | Length |
1 - 8 | Encrypted Challenge | 8 |
SW | Description |
90 00 | Command completed successfully |
63 CX | Verification failed, retry counter specified |
67 00 | Wrong Lc |
69 83 | Authentication method blocked |
69 85 | Conditions of use not satisfied |
6A 86 | Incorrect parameters P1-P2 |
6A 88 | Referenced data not found |
Directly before this command a 8 byte challenge must be fetched from the card with the Get Challenge command. This challenge must then be encrypted with the TEA algorithm and the External Authentication key. For authentication the resulting data must then be sent back via this command.
Warning: Currently the retry counter is not handled in a secure way. For more information see e.g. Rankl/Effing.
CLA | INS | P1 | P2 | P3 |
80 | 84 | 00 | 00 | 08 |
Byte(s) | Description | Length |
1 - 8 | Random Challenge | 8 |
SW | Description |
90 00 | Command completed successfully |
67 00 | Wrong Le |
6A 86 | Incorrect parameters P1-P2 |
Returns a challenge usable for the External Authentication command, which must then be the next issued command.
Warning: On the current hardware this challenge is produced with a PRNG based on TEA. It is not evaluated, if the current mechanism is appropriate for this task.
CLA | INS | P1 | P2 | P3 |
80 | C0 | 00 | 00 | Length |
Byte(s) | Description | Length |
1 - 8 | Internal Authentication key encrypted challenge | 8 |
Byte(s) | Description | Length |
1 - 2 | Size | 2 |
3 - 4 | FID | 2 |
5 | File type (DF: 38, EF: 00) | 1 |
6 | Access conditions | 1 |
SW | Description |
90 00 | Command completed successfully |
69 85 | Wrong condition (No data available) |
6A 86 | Incorrect parameters P1-P2 |
6C XX | Wrong Le |
This command fetches data from Internal Authentication and Select. These commands signal the availability of data with the status word 61XX. For more details about the data returned after a Select, see at the Create command.
CLA | INS | P1 | P2 | P3 |
80 | 88 | 00 | Decrypt | 08 |
This command decrypts the data if P2 is 01. This functionality is only enabled when CONF_WITH_DECRYPT is set to 1.
Byte(s) | Description | Length |
1 - 8 | Random Challenge | 8 |
SW | Description |
61 08 | Command completed successfully (Data available) |
67 00 | Wrong Lc |
69 85 | Conditions of use not satisfied |
6A 86 | Incorrect parameters P1-P2 |
6A 88 | Referenced data not found |
Provieds a random challenge to the card. It encryptes the challenge with TEA and the Internal Authentication key and makes it available via Get Response. For the successful execution either the PIN or the External Authentication key must have been successfully verified previously.
Because of possibility to decrypt data, this command can easily be used to implement some form of Remotely Keyed Encryption.
CLA | INS | P1 | P2 | P3 |
80 | B0 | Offset high | Offest low | Length |
Byte(s) | Description | Length |
1 - Length | Data | Length |
SW | Description |
90 00 | Command completed successfully |
69 82 | Security status not satisfied |
69 86 | Command not allowed (no EF selected) |
6A 82 | File not found |
6A 84 | File to short |
6B 00 | Wrong parameters (offset outside EF) |
Reads Lenght bytes from Offset of the currently selected EF.
CLA | INS | P1 | P2 | P3 |
80 | A4 | 00 | 00 | 02 |
Byte(s) | Description | Length |
1 - 2 | FID | 2 |
SW | Description |
61 06 | Command completed successfully |
67 00 | Wrong Lc |
6A 82 | File not found |
6A 86 | Incorrect parameters P1-P2 |
It tries to select a file with the specified FID and searches for it in the following order:
If FID is 3F00, the MF is always selected.
CLA | INS | P1 | P2 | P3 |
80 | 2C | 00 | 00 | 10 |
Byte(s) | Description | Length |
1 - 8 | PUK | 8 |
9 - 16 | New PIN | 8 |
SW | Description |
90 00 | Command completed successfully |
63 CX | Verification failed, retry counter specified |
67 00 | Wrong Lc |
69 83 | Authentication method blocked |
6A 86 | Incorrect parameters P1-P2 |
6A 88 | Referenced data not found |
This command changes the PIN of the card and resets the retry counter of this PIN. The first eight bytes of the data is the PUK, which is checked for correctness. The second four bytes of the data is the new PIN, which will be written. On success the AUTH_FLAG_PIN bit in authstate is set, on fauilure it is cleared.
Warning: Currently the retry counter is not handled in a secure way. For more information see e.g. Rankl/Effing.
PIN update is protected with transactions.
CLA | INS | P1 | P2 | P3 |
80 | D6 | Offset high | Offset low | Length |
Byte(s) | Description | Length |
1 - Length | Data | Length |
SW | Description |
90 00 | Command completed successfully |
65 00 | Memory failure (unsuccessful writing) |
67 00 | Wrong Le |
69 82 | Security status not satisfied |
69 86 | Command not allowed (no EF selected) |
6A 82 | File not found |
6A 84 | File to short |
6B 00 | Wrong parameters (offset outside EF) |
Writes Lenght bytes to Offset of the currently selected EF.
Data updates are NOT protected with transactions.
CLA | INS | P1 | P2 | P3 |
80 | 2A | 00 | 00 | 10 |
Byte(s) | Description | Length |
1 - 16 | External Authentication Key | 16 |
SW | Description |
90 00 | Command completed successfully |
63 CX | Verification failed, retry counter specified |
67 00 | Wrong Lc |
69 83 | Authentication method blocked |
6A 86 | Incorrect parameters P1-P2 |
6A 88 | Referenced data not found |
Verifies the External Authentication key as 16 byte plain text in the data part of the command. On success the AUTH_FLAG_KEY bit in authstate is set, on failure it is cleared.
Warning: Currently the retry counter is not handled in a secure way. For more information see e.g. Rankl/Effing.
CLA | INS | P1 | P2 | P3 |
80 | 20 | 00 | 00 | 08 |
Byte(s) | Description | Length |
1 - 8 | PIN | 8 |
SW | Description |
90 00 | Command completed successfully |
63 CX | Verification failed, retry counter specified |
67 00 | Wrong Lc |
69 83 | Authentication method blocked |
6A 86 | Incorrect parameters P1-P2 |
6A 88 | Referenced data not found |
This command verifies the PIN. The four data bytes contain the user supplied PIN, which is checked for correctness. On success the AUTH_FLAG_PIN bit in authstate is set, on fauilure it is cleared.
Warning: Currently the retry counter is not handled in a secure way. For more information see e.g. Rankl/Effing.
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA