DISCLAIMER:

THIS DOCUMENT IS PART OF MAMP-OS SOFTWARE DEVELOPMENT KIT (SDK). READ THIS DOCUMENT AND THE 
PART "KNOWN ISSUES AND LIMITATIONS" AT THE END IN THIS DOCUMENT CAREFULLY AND COMPLETELY. SDK 
CONTENT IS ALLOWED ONLY TO BE USED WITH MAMP-OS SMART CARDS. SDK MAY BE DISTRIBUTED ONLY WITH 
ORIGINAL CONTENT AND REMARK OF ORIGIN.

SDK TOOLS AND SOURCE CODE EXAMPLES ARE PROVIDED AS IS AND USER IS RESPONSIBLE ALONE USING THEM. 
USER IS RESPONSIBLE TO PROVIDE AND USE PROPER EQUIPMENT. UPLOADING OF UNTESTED OR ERRONEOUS 
CODE MAY RENDER SMART CARD USELESS. SDK CONTENT IS NOT GUARANTEED TO BE ERROR FREE. UPDATES 
MIGHT CORRECT OR ENCHANCE ANY DETAILS. THERE IS NO COMMITMENT OF GUARANTEE FOR UPDATES. THE 
AUTHOR OF MAMP-OS HAS ABSOLUTELY NO RESPONSIBILTY AND CAN NOT BE HELD LIABLE TO USER CODE 
WRITTEN BY 3RD PARTIES OR ANY DAMAGED SMART CARDS OR ANY OTHER DAMAGE CAUSED BY THIS PRODUCT
OR USING THIS PRODUCT.



[Note: With MAMP-OS V1.2 it's no more possible to destroy the smart card.]




Setting up development environment to use example source:

Copy AVRASM32.EXE V1.52 into your working directory. Assemble source file (user.asm) by double
clicking on user.bat.

Upload user eeprom (useree.hex) and user code (user.hex) using MAMP-OS Terminal (mampos.exe).
MAMP-OS upload mode requires 3.579 MHz oscillator for 9600 baud.

Reset smart card, get MAMP-OS V1.0 ATR and push 'Upload' button. First user eeprom then user 
code will be uploaded automatically. Adjust baud rate setting within terminal and oscillator of 
smart card reader if user code is using different settings. Select 19200 baud for the example 
source. Reset again to see user code ATR.

KEEP EXAMPLE SOURCE COMMANDS AS THEY ARE WHILE STARTING UP WITH A NEW PROJECT. This will ensure 
that MAMP-OS upload mode can be entered again and again without unneccessarily destroying smart 
cards.

MAMP-OS Terminal can be compiled using Borland C++ Builder 3.



User Accessable Memories:

AT90SC3232C:

CODE:	$0000-1FFF	16384 bytes, 8192 words (virtual word address)
EEPROM:	$8000-$9FFF	8192 bytes (virtual byte address)
RAM:	$0400-$04FF	256 bytes (real byte address)

System calls seperate between EEPROM and RAM using most significant bit of address high byte. 
EEPROM: msb set, RAM: msb clear.
System call routines with RAM address as input will always correct address to $04xx.
Virtual addresses (EEPROM) will always be masked to the right EEPROM space.
Do not use absolute code addressing.


RAM is partitioned as follows:

$400-$4B7	184 bytes USER RAM
$4B8-$4C7	16 bytes aes key
$4C8-$4CF	8 bytes [MAMP-OS <-> user code] interface
$4D0-$4FF	48 bytes common stack


Do not use more than 24 bytes of the stack when using system calls.



Byte Format:

1 initial stop bit (while transmit)
1 start bit
8 data bits
1 optional even/odd parity bit
1 stop bit


	cbr	r16,_parity_enable	;8N1 - no parity
	sbr	r16,_parity_enable	;even/odd parity

	cbr	r16,_parity_even_odd	;8E1 - even parity
	sbr	r16,_parity_even_odd	;8O1 - odd parity

	cbr	r16,_convention		;direct convention
	sbr	r16,_convention		;inverse convention

	sts	RAM_byte_format,r16



Data can be transmitted in direct convention (ATR $3B) or in inverse convention (ATR $3F).

Defining ATR is completely under user control. Refer to ISO 7816 Part 3.



Baud Rate vs. Clock Frequencies:

	9600  baud  @  1, 2, 3, 3.579, 4, 4.915, 6  MHz
	19200 baud  @     2, 3, 3.579, 4, 4.915, 6  MHz
	38400 baud  @           3.579, 4, 4.915     MHz
	57600 baud  @                     4.915     MHz

Please note that 6 MHz is the upper operating limit. Not all smart cards will work with this 
frequency. If user code is set up with 9600 baud @ 6.000 MHz and that smart card doesn't work 
with this frequency, e.g. no ATR, then it is always possible to upload new code by using 3.579 
MHz oscillator in the smart card reader and selecting 5760 baud in terminal.


Example:

	ldi	r16,_baud_9600_3579
	sts	RAM_clock_baud,r16



Not Allowed Instructions:

	CALL, JMP, ICALL, IJMP, EICALL, EIJMP
	LPM, SPM, ELPM, ESPM
	MUL, MULS, MULSU, FMUL, FMULS, FMULSU
	IN, OUT
	MOVW
	RETI
	CBI, SBI, SBIC, SBIS
	CLI, SEI
	SLEEP



System Call Reference:


_sc_code_upload		;user code upload mode (9600 baud @ 3.57 MHz)

_sc_read_eeprom		;read from eeprom
input:	eeprom address $8000-$9FFF in z
output:	eeprom value at address (z) in r16
only r16 modified

_sc_write_eeprom	;write to eeprom
input:	eeprom address $8000-$9FFF in z, byte to be written to address (z) in r16
no registers modified

_sc_rx_byte		;receive one byte
output:	received byte in r16
only r16 modified

_sc_tx_byte		;transmit one byte
input:	byte to transmit in r16
no registers modified

_sc_RSA_modulus		;set RSA modulus
input:	eeprom address $8000-$9FFF or ram address $400-$4FF in z,
	RSA length in bytes in r16 ($40 / $60 / $80)
output:	status in r16 
only r16 modified

_sc_RSA_exponent	;set RSA exponent
input:	eeprom address $8000-$9FFF or ram address $400-$4FF in z,
	RSA length in bytes in r16 ($40 / $60 / $80)
output:	status in r16 
only r16 modified

_sc_RSA_data_in
input:	eeprom address $8000-$9FFF or ram address $400-$4FF in z,
	RSA length in bytes in r16 ($40 / $60 / $80)
output:	status in r16 (always successful)
only r16 modified

_sc_RSA_data_out
input:	eeprom address $8000-$9FFF or ram address $400-$4FF in z,
	RSA length in bytes in r16 ($40 / $60 / $80)
output:	status in r16 (always successful)
only r16 modified

_sc_AES_encrypt		;AES encryption
input:	plain data in r0-r15, key in RAM $4B8-$4C7
output:	encrypted data in r0-15
all registers and key in RAM modified

_sc_random16		;get 16 random bytes
output:	random bytes in r0-15
no other registers modidifed

_sc_header_T_0		;receive header (T=0 protocol)
not implemented

_sc_ack_T_0		;transmit INS (T=0 protocol)
not implemented

_sc_rx_T_0		;receive data (T=0 protocol)
not implemented

_sc_tx_T_0		;transmit data (T=0 protocol)
not implemented

_sc_RC_T_0		;transmit return code (T=0 protocol)
not implemented

_sc_rx_T_E		;receive request in T=E protocol
output:	RAM $400+: [LEAD_1] [HEADER_5] {[DATA]} CHK, max. data length is $80 bytes
no registers modified

_sc_tx_T_E		;transmit answer in T=E protocol
input:	RAM $400+: [LEAD_1] [HEADER_5 + RC_2] {[DATA]} CHK,  max. data length is $80 bytes
no registers modified


Example:

	ldi	r16,_sc_tx_byte		;set up to transmit one byte
	sts	RAM_system_call,r16

	ldi	r16,$80			;byte to send in r16, as example $80

	wdr				;system call

A system call is issued by executing WDR (watch dog reset) instruction.



KNOWN ISSUES AND LIMITATIONS:

Maximum data length is $80 = 128 bytes for all protocols.

T=0 protocol LEN = 0 to transmit 256 data bytes from smart card to terminal can't be realized 
with one system call _sc_tx_T_0. Instead use it twice.

T=0 protocol byte transmission error control and handling, which is mandatory, is not 
implemented.
The example source code is sending an appropriate return code instead, if a byte level parity 
mismatch is detected. Advantage is that card is not locked up and this solution is more near to 
OSI model. Disadvantage is that remaining bytes to receive are ignored and it's possible to 
have collision on I/O line.
//This may be corrected in source when T=0 protocol system calls are completed.

PTS (Protocol Type Selection) and FI, DI values are not used directly but there is variety of 
choice to select between terminal clock frequency and baud rate. Developer is free to implement 
any solution within user code.


T=0 protocol carries some disadvantages:

- Commands must be defined in pairs. A seperate command must be used for each direction of data 
flow. This is a security hole where memory can't be erased before each new command is received.
- For one action (put data / get resulting data) two requests are sent from terminal.
- INS may not be odd due to old Vpp based write access handling (historical).
- INS may not start with $6x or $9x, because the acknowledge byte would be interpreted as a 
return code or delay request.
- Byte error detection / correction is in 'wrong' level of OSI model.
- 3 unsuccessful attempts to receive a correct byte locks up card and reset by terminal is 
needed.
- No complete checksum protection of header or data, instead byte level 1 bit parity 
protection, which provides minor protection only.


The provided T=E protocol does have none of these disadvantages.
A parity mismatch, if parity enabled, will cause an early break from receiving all bytes of a 
request. Therefore it is recommended to use 8N1 with T=E protocol.


Here is the structure of implemented T=E protocol:

Terminal request:	[LEAD] [CMD] [INS] [REF1] [REF2] [LEN] [DATA_IN] [CHK]
Smart card answer:	[LEAD] [CMD] [INS] [REF1] [REF2] [RCH] [RCL] [LEN] [DATA_OUT] [CHK]


LEAD:

Leading byte is $80 for MAMP-OS and can be any value for user code.


CMD, INS, REF1, REF2, LEN:

MAMP-OS implements only CMD = $B0 and INS = $02 for code upload and INS = $03 for eeprom 
upload. LEN is in range of $04-$14.

User code is free to implement any of these values, except that LEN is limited to $80 bytes.


RCH, RCL:

Return code high and low byte in the answer.


CHK:

Checksum is XOR of all bytes including LEAD until excluding CHK. Initial value can be set up 
within user code. MAMP-OS uses $FF.



User code log after pushing 'Crypto' button:

<-- 3B 8D 0D 41 54 52 20 55 53 45 52 20 43 4F 44 45 1C 

;RSA 768 public encryption
--> 80 B2 00 00 00 60 80 01 02 03 04 05 06 07 10 11 12 13 14 15 16 17 20 21 22 23 24 25 26 27 30 31 32 33 34 35 36 37 40 41 42 43 44 45 46 47 50 51 52 53 54 55 56 57 60 61 62 63 64 65 66 67 70 71 72 73 74 75 76 77 80 81 82 83 84 85 86 87 90 91 92 93 94 95 96 97 A0 A1 A2 A3 A4 A5 A6 A7 B0 B1 B2 B3 B4 B5 B6 B7 2D 
<-- 80 B2 00 00 00 90 00 60 74 62 88 8A 97 B6 6F 10 1F 19 37 7B 5C 23 3E 5D C3 9D 7A 45 59 7E 5F C5 0D 96 BC EC 93 2B 4D 86 8A A0 86 4F 43 67 B9 7E 0F 74 76 A6 0E 14 F3 3C 80 40 EB F7 AB 9C E0 AF 81 B4 D5 9E AC 32 4C D6 04 1D 01 60 AE 69 F6 22 E9 93 0C F9 A9 6A 31 44 53 55 B8 59 0B AE 51 8D DB F9 83 FE 4D 29 8A F7 6F 

;RSA 768 private encryption
--> 80 B2 00 00 01 60 74 62 88 8A 97 B6 6F 10 1F 19 37 7B 5C 23 3E 5D C3 9D 7A 45 59 7E 5F C5 0D 96 BC EC 93 2B 4D 86 8A A0 86 4F 43 67 B9 7E 0F 74 76 A6 0E 14 F3 3C 80 40 EB F7 AB 9C E0 AF 81 B4 D5 9E AC 32 4C D6 04 1D 01 60 AE 69 F6 22 E9 93 0C F9 A9 6A 31 44 53 55 B8 59 0B AE 51 8D DB F9 83 FE 4D 29 8A F7 FE 
<-- 80 B2 00 00 01 90 00 60 80 01 02 03 04 05 06 07 10 11 12 13 14 15 16 17 20 21 22 23 24 25 26 27 30 31 32 33 34 35 36 37 40 41 42 43 44 45 46 47 50 51 52 53 54 55 56 57 60 61 62 63 64 65 66 67 70 71 72 73 74 75 76 77 80 81 82 83 84 85 86 87 90 91 92 93 94 95 96 97 A0 A1 A2 A3 A4 A5 A6 A7 B0 B1 B2 B3 B4 B5 B6 B7 BC 

;AES encryption example
--> 80 B2 10 00 00 20 00 11 22 33 44 55 66 77 88 99 AA BB CC DD EE FF 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F FD 
<-- 80 B2 10 00 00 90 00 10 69 C4 E0 D8 6A 7B 04 30 D8 CD B7 80 70 B4 C5 5A 94 

;Getting random numbers
--> 80 B2 20 00 00 00 ED 
<-- 80 B2 20 00 00 90 00 10 0D F2 A5 2F C1 CD 40 E7 AC AE 26 03 19 BC 55 21 45 
--> 80 B2 20 00 00 00 ED 
<-- 80 B2 20 00 00 90 00 10 AC 16 3A A6 33 1A F7 13 0B 04 92 B0 D4 23 45 32 2B 
--> 80 B2 20 00 00 00 ED 
<-- 80 B2 20 00 00 90 00 10 3E 3E B7 A1 42 0B 6B 8F 14 90 E2 1A C5 BF 6E E5 5B 


User code log after pushing 'PIN' button:

--> 80 B3 1E 00 00 08 12 34 56 78 11 11 11 11 D2 	;old PIN 12345678, new PIN 11111111
<-- 80 B3 1E 00 00 90 00 00 42 				;succesfully changed
--> 80 B3 AA 00 00 04 15 61 71 18 7F 			;wrong PIN code 15617118 !!!
<-- 80 B3 AA 00 00 90 01 00 F7 				;upload mode is not entered !!!
unknown rc
--> 80 B3 AA 00 00 04 11 11 11 11 62 			;PIN is correct, upload mode is entered
no answer

After a reset, MAMP-OS ATR is seen again: (adjust baud rate)

<-- 3B 8C 0E 4D 41 4D 50 2D 4F 53 20 56 31 2E 30 99

New user code may be uploaded now.



www.cashboxcard.com
contact@cashboxcard.com





Needed Tools:

High Security Smart Card




below are some needed tools and information:
Smart card with MAMP-OS in user code upload mode. 
Simple smart card reader (smart mouse). 
Microsoft Windows 95 or 98, Windows ME or Windows 2000 
Download MAMP-OS SDK for free! 
Runtime library vcl35.bpl 
AVR Studio which contains assembler and simulator. 
Text Pad to edit your source code. 
Hex Workshop to edit your data. 
Information about AES (Advanced Encryption Standard) 
AVR-GCC free C compiler.

