* Text changes
[docelic/atmos.git] / README
9bf87bfd 1
2 ========= ATMOS =========
47f64179 4 ***** ****** *** ** **** ****
fda5895c 5 ** ** ** ** * * ** ******** ***
6 ** * ** ** ** * ** ******** ***
7 ** ** ** ** ** **** ****
9 ** Free Operating System for Atmel-based Smart Cards **
0f862422 11 http://www.spinlocksolutions.com/atmos/
fda5895c 12 Davor Ocelic, docelic@spinlocksolutions.com
14Table of Contents:
160) Introduction
171) Compiling Atmos for specified Atmel chip / smart card
fda5895c 182) Loading files onto smart card using programmer hardware
193) Smart Card reader setup (installing the reader software)
204) Alternative build/compile modes (workstation-compatible & CT-API)
230) Introduction
25 Atmos is an operating system for Atmel's 8-bit AVR-based smart cards,
26 released under the GNU GPL license.
28 The end goal of the project is to develop as ISO- and PKCS#11-compatible OS
29 as possible, so that we can take advantage of the complete set of existing
30 fully-functional PKCS#11 programs that exist for Linux.
32 The work is currently progressing using Atmel chips such as atmega163,
33 atmega161, at90s8535, at90s8515 and at90s2323, but support for Atmel's
34 cryptographically enabled Secure AVR series is planned for some future
35 time.
fda5895c 36
5b6d2e31 37
fa0cde35 381) Compiling Atmos for specified Atmel chip / smart card
9bf87bfd 39
40 cd src
41 editor config.h (enable/disable build options)
07a6fced 42 editor Makefile (verify settings for $ARCH, $PROG and $PORT)
9bf87bfd 43 editor eedata.S (can change EEPROM data loaded on card, such as
b419c82b 44 serial number, RNG seed, keys or file permissions)
fa0cde35 45 make (result files are atmos.{bin,hex} and eedata.{bin,hex}.
c59e69bf 46 Bin files are raw files, .hex files are in Intel hex
47 format. They're the same but hex is nicer to read. Hex
48 file can be loaded onto the card just as well as .bin,
49 provided that your programmer supports Intel hex input.)
9bf87bfd 50
fda5895c 51
522) Loading files onto smart card using programmer hardware
54 After you have compiled ATMOS for a certain AVR chip, you can load it
55 onto the smartcard or a standalone Atmel chip.
57 The compiled 'atmos' and 'eedata' files go to:
58 atmos.hex or .bin -> Flash memory
59 eedata.hex or .bin -> internal EEPROM memory
9bf87bfd 60
c59e69bf 61 The writing is done using 'avrdude' software, so make sure you have it
832b3aad 62 installed. Also make sure you've edited Makefile and set PROG= to
c59e69bf 63 a proper value (see 'avrdude -c list' for a list of valid options).
fda5895c 64
c59e69bf 65 The Makefile already supports 2 targets for loading the files. (Targets
66 consist of 2 commands each which can be called individually as well):
5b6d2e31 67
fda5895c 68 make write (= write-eeprom write-flash)
69 make verify (= verify-eeprom verify-flash)
5b6d2e31 70
5b6d2e31 71
723) Smart Card reader setup (installing the reader software)
c59e69bf 74(Replace libtowitoko with your appropriate terminal-specific library,
75or install the excellent generic libccid):
5b6d2e31 77 apt-get install libtowitoko2 libtowitoko-dev
78 apt-get install pcscd
fda5895c 80 After the above, your reader should blink or give other indication when
81 inserting the card; also the syslog should get messages like this (unless
82 they're disabled in your pcscd or syslog configuration):
84 Jul 13 15:24:53 ubuntu2 pcscd:
85 eventhandler.c:438:EHStatusHandlerThread()
86 Card inserted into Towitoko Chipdrive USB 00 00
88 Jul 13 15:24:53 ubuntu2 pcscd:
89 eventhandler.c:449:EHStatusHandlerThread()
c59e69bf 90 Card ATR: ......
fda5895c 91
92 Jul 13 15:24:48 ubuntu2 pcscd:
93 eventhandler.c:365:EHStatusHandlerThread()
94 Card Removed From Towitoko Chipdrive USB 00 00
fa0cde35 96(If the card isn't programmed yet, Card ATR will report no value which is fine).
fda5895c 97
994) Alternative build/compile modes
8b6e1772 100
832b3aad 101ATMOS can be compiled in a few different modes:
8b6e1772 102
103 - for the Atmel AVR chip (standard Makefile), like you've been reading above
104 - as a binary running on your workstation (Makefile.emu), great for testing
105 and programming
832b3aad 106 - as a CT-API driver implementing a virtual card and terminal (Makefile.ctapi)
b419c82b 107
fa0cde35 108To invoke builds for the last two types, you need to specify 'make -f MAKEFILE'.
b419c82b 109
110Also, before switching modes, you need to pay attention to always clean the
111build tree by invoking 'make -f MAKEFILE clean', or you will end up mixing
112binaries and get errors about wrong binary types etc. To ease this cleanup
113process, the default Makefile's clean action calls all three cleans.
114Therefore, just 'make clean' will always do what you need.
b419c82b 115
fa0cde35 116So let's take a closer look at how to build each mode:
832b3aad 117
fa0cde35 118* AVR target (Makefile):
8b6e1772 119
b419c82b 120 Install gcc-avr and avr-libc
fa0cde35 121 Install doxygen, texinfo and tetex-bin
b419c82b 122 Compile with 'make'
8b6e1772 123
fa0cde35 124* Emulation on a PC (Makefile.emu)
fda5895c 125
126 To ease debugging and testing, you can compile the package for the
127 usual desktop computer (no any smart card hardware necessary).
fda5895c 128
fa0cde35 129 Compile with 'make -f Makefile.emu'
fda5895c 130
fa0cde35 131 Result files will be atmos-emu, authtest, enctest and fstest.
0f862422 132
133 ./atmos-emu is the file you can run and talk to it as if it were
134 a smartcard. Other three are filesystem, authentication and encryption
135 tests. (Note: test programs test features and encryption algorithm that
136 have been enabled in config.h).
0f862422 137
138 Note: two optional libraries can be downloaded and built, and then used
139 with Atmos and Makefile.emu, but won't be covered here as we don't need
140 them:
142 Keeper library: http://www.inf.bme.hu/~mszeredi/keeper/
143 SCEZ-ng library: http://www.freshmeat.net/projects/scez
fda5895c 144
145 Both libs can also be downloaded from:
146 ftp://ftp.franken.de/pub/crypt/chipcards/scez/
fda5895c 147
148 Note: the original author had worked on SCEZ and SCEZ-ng,
149 and seems to have abandoned SCEZ-ng halfway through.
150 Before I figured we don't need SCEZ at all, I continued the
151 work on the SCEZ-ng source and have brought it to a decent
152 form (compilation & structure fixes -- no technical changes
153 compared to old SCEZ).
fda5895c 154
155 So that version of SCEZ-ng, if you want it for some reason,
156 can be obtained through Git with:
157 git clone git://git.hcoop.net/git/docelic/scez.git
fda5895c 158
0425aef5 159* CT-API driver emulating card in a terminal
fda5895c 160
161Not much to say about this build mode; it's a leftover from SOSSE, and I
162haven't used it:
fda5895c 164 make -f Makefile.ctapi
0425aef5 166-------------------------------------------------------------------------
5b6d2e31 167
b419c82b 168ATMOS is copyright 2008-2009 Davor Ocelic <docelic@spinlocksolutions.com>
a65be974 169 Spinlock Solutions, http://www.spinlocksolutions.com/
974047dc 170
171ATMOS is based on 2003 SOSSE by Matthias Bruestle <m@mbsks.franken.de>:
172 SOSSE is documented inside the source. Printable/browsable documentation
173 is generated with doxygen. A "make" in the top level directory will
174 also build the documentation. If you do not have doxygen installed and
175 do not want to install it, you find the most important documentation in
176 "src/main.h". You can also browse it online at:
177 <http://www.mbsks.franken.de/sosse/>
974047dc 178