* Text changes
[docelic/atmos.git] / README
1
2 ========= ATMOS =========
3
4 ***** ****** *** ** **** ****
5 ** ** ** ** * * ** ******** ***
6 ** * ** ** ** * ** ******** ***
7 ** ** ** ** ** **** ****
8
9 ** Free Operating System for Atmel-based Smart Cards **
10
11 http://www.spinlocksolutions.com/atmos/
12 Davor Ocelic, docelic@spinlocksolutions.com
13
14 Table of Contents:
15
16 0) Introduction
17 1) Compiling Atmos for specified Atmel chip / smart card
18 2) Loading files onto smart card using programmer hardware
19 3) Smart Card reader setup (installing the reader software)
20 4) Alternative build/compile modes (workstation-compatible & CT-API)
21
22
23 0) Introduction
24
25 Atmos is an operating system for Atmel's 8-bit AVR-based smart cards,
26 released under the GNU GPL license.
27
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.
31
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.
36
37
38 1) Compiling Atmos for specified Atmel chip / smart card
39
40 cd src
41 editor config.h (enable/disable build options)
42 editor Makefile (verify settings for $ARCH, $PROG and $PORT)
43 editor eedata.S (can change EEPROM data loaded on card, such as
44 serial number, RNG seed, keys or file permissions)
45 make (result files are atmos.{bin,hex} and eedata.{bin,hex}.
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.)
50
51
52 2) Loading files onto smart card using programmer hardware
53
54 After you have compiled ATMOS for a certain AVR chip, you can load it
55 onto the smartcard or a standalone Atmel chip.
56
57 The compiled 'atmos' and 'eedata' files go to:
58 atmos.hex or .bin -> Flash memory
59 eedata.hex or .bin -> internal EEPROM memory
60
61 The writing is done using 'avrdude' software, so make sure you have it
62 installed. Also make sure you've edited Makefile and set PROG= to
63 a proper value (see 'avrdude -c list' for a list of valid options).
64
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):
67
68 make write (= write-eeprom write-flash)
69 make verify (= verify-eeprom verify-flash)
70
71
72 3) Smart Card reader setup (installing the reader software)
73
74 (Replace libtowitoko with your appropriate terminal-specific library,
75 or install the excellent generic libccid):
76
77 apt-get install libtowitoko2 libtowitoko-dev
78 apt-get install pcscd
79
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):
83
84 Jul 13 15:24:53 ubuntu2 pcscd:
85 eventhandler.c:438:EHStatusHandlerThread()
86 Card inserted into Towitoko Chipdrive USB 00 00
87
88 Jul 13 15:24:53 ubuntu2 pcscd:
89 eventhandler.c:449:EHStatusHandlerThread()
90 Card ATR: ......
91
92 Jul 13 15:24:48 ubuntu2 pcscd:
93 eventhandler.c:365:EHStatusHandlerThread()
94 Card Removed From Towitoko Chipdrive USB 00 00
95
96 (If the card isn't programmed yet, Card ATR will report no value which is fine).
97
98
99 4) Alternative build/compile modes
100
101 ATMOS can be compiled in a few different modes:
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
106 - as a CT-API driver implementing a virtual card and terminal (Makefile.ctapi)
107
108 To invoke builds for the last two types, you need to specify 'make -f MAKEFILE'.
109
110 Also, before switching modes, you need to pay attention to always clean the
111 build tree by invoking 'make -f MAKEFILE clean', or you will end up mixing
112 binaries and get errors about wrong binary types etc. To ease this cleanup
113 process, the default Makefile's clean action calls all three cleans.
114 Therefore, just 'make clean' will always do what you need.
115
116 So let's take a closer look at how to build each mode:
117
118 * AVR target (Makefile):
119
120 Install gcc-avr and avr-libc
121 Install doxygen, texinfo and tetex-bin
122 Compile with 'make'
123
124 * Emulation on a PC (Makefile.emu)
125
126 To ease debugging and testing, you can compile the package for the
127 usual desktop computer (no any smart card hardware necessary).
128
129 Compile with 'make -f Makefile.emu'
130
131 Result files will be atmos-emu, authtest, enctest and fstest.
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).
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:
141
142 Keeper library: http://www.inf.bme.hu/~mszeredi/keeper/
143 SCEZ-ng library: http://www.freshmeat.net/projects/scez
144
145 Both libs can also be downloaded from:
146 ftp://ftp.franken.de/pub/crypt/chipcards/scez/
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).
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
158
159 * CT-API driver emulating card in a terminal
160
161 Not much to say about this build mode; it's a leftover from SOSSE, and I
162 haven't used it:
163
164 make -f Makefile.ctapi
165
166 -------------------------------------------------------------------------
167
168 ATMOS is copyright 2008-2009 Davor Ocelic <docelic@spinlocksolutions.com>
169 Spinlock Solutions, http://www.spinlocksolutions.com/
170
171 ATMOS 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/>
178