Main Page   Data Structures   File List   Data Fields   Globals   Related Pages  

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.

funcard2.jpg

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.

purple.gif

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.

Software

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.

Design Decisions

Programming Language

The C programming language has been choosen instead of assembler, because:

Building Instructions

Standard Build

  1. 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.)

  2. 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.

  3. 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.

  4. To build the HEX files start make.

  5. 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

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:
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/

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:

EF Int Auth

Path: 3F00FF01

Content:

EF PIN

Path: 3F00FF02

Content:

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.

LED Effects (Fun command)

Header

CLA INS P1 P2 P3
80 06 Effect Parameter 00

Status words

SW Description
90 00 Command completed successfully

Description

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.

jupiter2.jpg

Change PIN.

Header

CLA INS P1 P2 P3
80 24 00 00 10

Command data

Byte(s) Description Length
1 - 8 Current PIN 8
9 - 16 New PIN 8

Status words

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

Description

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.

Create File.

Header

CLA INS P1 P2 P3
80 E0 00 00 06

Command data

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

Status words

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

Description

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.

Delete File.

Header

CLA INS P1 P2 P3
80 E4 00 00 02

Command data

Byte(s) Description Length
1 - 2 FID 2

Status words

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

Description

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.

External Authentication.

Header

CLA INS P1 P2 P3
80 82 00 00 08

Command data

Byte(s) Description Length
1 - 8 Encrypted Challenge 8

Status words

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

Description

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.

Get Challenge

Header

CLA INS P1 P2 P3
80 84 00 00 08

Response data

Byte(s) Description Length
1 - 8 Random Challenge 8

Status words

SW Description
90 00 Command completed successfully
67 00 Wrong Le
6A 86 Incorrect parameters P1-P2

Description

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.

Get Response.

Header

CLA INS P1 P2 P3
80 C0 00 00 Length

Response data after Internal Authenticate

Byte(s) Description Length
1 - 8 Internal Authentication key encrypted challenge 8

Response data after Select

Byte(s) Description Length
1 - 2 Size 2
3 - 4 FID 2
5 File type (DF: 38, EF: 00) 1
6 Access conditions 1

Status words

SW Description
90 00 Command completed successfully
69 85 Wrong condition (No data available)
6A 86 Incorrect parameters P1-P2
6C XX Wrong Le

Description

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.

Internal Authentication.

Header

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.

Command data

Byte(s) Description Length
1 - 8 Random Challenge 8

Status words

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

Description

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.

Read Binary.

Header

CLA INS P1 P2 P3
80 B0 Offset high Offest low Length

Response data

Byte(s) Description Length
1 - Length Data Length

Status words

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)

Description

Reads Lenght bytes from Offset of the currently selected EF.

Select File.

Header

CLA INS P1 P2 P3
80 A4 00 00 02

Command data

Byte(s) Description Length
1 - 2 FID 2

Status words

SW Description
61 06 Command completed successfully
67 00 Wrong Lc
6A 82 File not found
6A 86 Incorrect parameters P1-P2

Description

It tries to select a file with the specified FID and searches for it in the following order:

  1. EF in the current MF/DF
  2. DF in MF

If FID is 3F00, the MF is always selected.

Unblock PIN.

Header

CLA INS P1 P2 P3
80 2C 00 00 10

Command data

Byte(s) Description Length
1 - 8 PUK 8
9 - 16 New PIN 8

Status words

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

Description

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.

Update Binary.

Header

CLA INS P1 P2 P3
80 D6 Offset high Offset low Length

Command data

Byte(s) Description Length
1 - Length Data Length

Status words

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)

Description

Writes Lenght bytes to Offset of the currently selected EF.

Data updates are NOT protected with transactions.

Verify Key

Header

CLA INS P1 P2 P3
80 2A 00 00 10

Command data

Byte(s) Description Length
1 - 16 External Authentication Key 16

Status words

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

Description

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.

Verify PIN

Header

CLA INS P1 P2 P3
80 20 00 00 08

Command data

Byte(s) Description Length
1 - 8 PIN 8

Status words

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

Description

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.

Developers

License

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


Copyright 2002 by Matthias Bruestle. This is licensed under the GNU General Public License.