DEL-1 Guide.

SOSSE - Simple Operating System for Smartcard Education
Overview
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.

Hardware
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:
C1 (VCC): Vcc
C2 (RST): RESET
C3 (CLK): XTAL
C4: MOSI
C5 (VSS): Vss
C6: Not connected
C7 (I/O): MISO
C8: SCK
Additional to the smart cards, a programmer is needed. These are available at the same shops as the AVR cards.
Software
SOSSE has been developed using the GCC development tools. These are available at . There are the sources, binaries and RPMs for Linux and binaries for MS Windows.
Design Decisions
Programming Language
The C programming language has been choosen instead of assembler, because:
It is easier to understand C source code.
Modern smart card operating systems are probably all written mostly in C. Who does want to write and verify 128kB assembler code?
When new smart card architectures are available for SOSSE, these can be utilized more easily.
Building Instructions
Standard Build
Go to the src directory and edit config.h . This file contains the configuration data for the build process. The meaning of the options is described in the doxygen documention of config.h itself. (It is not possible to switch on all features, because then the code size is above 8kB.)
You can edit eedata.S if you want to change the EEPROM data loaded onto the AVR card. You might want to change the card serial number, the start value for the random number generator, the keys, the file permissions or the created files.
There are two defines in the Makefile, which could need editing. The first is the -mmcu setting in CC and the second is -mtiny-stack in CFLAGS. Adjust these to reflect your used AVR card.
To build the HEX files start make.
The resulting HEX files sosse.hex and eedata.hex (or BIN files sosse.bin and eedata.bin) have then to be loaded on the card with the programmer and an apropriate software. The destination for sosse.hex is the Flash and for eedata.hex the internal EEPROM.
Debugging
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.
CT-API driver
Building
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.
Supported CT-BCS commands
EJECT ICC: Supported with functional unit ICC1. P2 is ignored.
GET STATUS: Supported tag is 80. Possible card states are 01 and 05.
REQUEST ICC: Supported with functional unit ICC1 and response data none and complete ATR. Display settings are ignored.
RESET CT: Supported with functional unit CT and ICC1 and response data none and complete ATR. This command is the same as REQUEST ICC, but does support reseting the CT, which stops the ICC.
Proprietary command: EEPROM FILE
Header
CLA INS P1 P2 P3
20 E0 Flags RFU Length
Command data
Byte(s) Description Length
1 - Length File name Length
Status words
SW Description
90 00 Command completed successfully
Description
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.
More Information and Download
The web page with up to date information about SOSSE is at:

The download location of the SOSSE sources is at:

The documentation was generated using DoxyGen:

Special Files
These File are only used, when filesystem support is compiled in. Otherwise special absolut locations in EEPROM are used to hold the data.
EF Ext Auth
Path: 3F00FF00
Content:
16 Bytes Key
1 Byte Retry Counter (resets to 10)
EF Int Auth
Path: 3F00FF01
Content:
16 Bytes Key
1 Byte Retry Counter (unused)
EF PIN
Path: 3F00FF02
Content:
8 Bytes PIN
1 Byte Retry Counter (resets to 3)
8 Bytes PUK
1 Byte Retry Counter (resets to 10)
Commands
Write EEPROM. (Test command)
Header
CLA INS P1 P2 P3
80 02 Address high Address low Length
Command data
Byte(s) Description Length
1 - Length Data to write to Address Length
Status words
SW Description
90 00 Command completed successfully
65 00 Memory failure (unsuccessful writing)
67 00 Wrong Lc
Description
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.
Read EEPROM. (Test command)
Header
CLA INS P1 P2 P3
80 04 Address high Address low Length
Response data
Byte(s) Description Length
1 - Length Data read from Address Length
Status words
SW Description
90 00 Command completed successfully
Description
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.

"SAXAT"