Rss Serial Protocol
Rss Serial Protocol
001
1.030.008.001
Revision 1.02
November 2002
CONFIDENTIAL
Prepared by
R&D Technology Solutionz Limited
for
Rapid Smartcard Solutionz
Table of Contents
1. DOCUMENT REVISION HISTORY............................................................................................1
1.1 CHANGE CONTROL.........................................................................................................................1
1.2 CONFIDENTIALITY AND COPYRIGHT...............................................................................................1
2. INTRODUCTION............................................................................................................................2
2.1 DOCUMENT OVERVIEW...................................................................................................................2
2.2 AUDIENCE.......................................................................................................................................2
2.3 CIRCULATION LIST..........................................................................................................................2
2.4 ATTACHMENTS................................................................................................................................2
2.5 LIMITATIONS...................................................................................................................................2
2.6 ACRONYMS.....................................................................................................................................2
2.7 REFERENCE DOCUMENTS...............................................................................................................3
3. OVERVIEW.....................................................................................................................................4
3.1 CONVENTIONS................................................................................................................................4
4. SERIAL PROTOCOL.....................................................................................................................5
4.1 COMMUNICATIONS PARAMETERS...................................................................................................5
4.1.1 Serial Parameters..................................................................................................................5
4.1.2 Hardware Handshaking.........................................................................................................5
4.1.3 DLE Stuffing..........................................................................................................................5
4.1.4 Timeouts.................................................................................................................................6
4.2 MESSAGE FORMAT..........................................................................................................................7
4.2.1 STX.........................................................................................................................................7
4.2.2 Token......................................................................................................................................7
4.2.3 Message Type.........................................................................................................................7
4.2.4 Data Length...........................................................................................................................7
4.2.5 ETX........................................................................................................................................7
4.2.6 Checksum...............................................................................................................................7
4.3 SERIAL ACKNOWLEDGEMENT.........................................................................................................8
4.3.1 Message Acknowledgement...................................................................................................8
4.3.2 Retries....................................................................................................................................8
5. MESSAGE TYPES..........................................................................................................................9
5.1 STATUS REQUEST..........................................................................................................................10
5.2 LED CONTROL.............................................................................................................................11
5.3 TAG PRESENT...............................................................................................................................12
5.4 MIFARE READ MAD.....................................................................................................................13
5.5 MIFARE UPDATE MAD.................................................................................................................14
5.6 MIFARE READ SECTOR.................................................................................................................15
5.7 MIFARE REWRITE SECTOR............................................................................................................16
5.8 MIFARE WRITE SECTOR................................................................................................................17
5.9 MIFARE VALUE TRANSACTION.....................................................................................................18
5.10 MIFARE LOAD KEY.......................................................................................................................19
5.11 SEND APDU.................................................................................................................................20
5.12 SEND DESELECT...........................................................................................................................21
5.13 INFORMATION MESSAGE...............................................................................................................22
5.14 ERROR MESSAGE..........................................................................................................................23
6. Transaction Flow..............................................................................................................................24
Filename= RSSSerialProtocol.doc
This document is the property of Rapid Smartcard Solutionz Limited. It may not be copied, distributed
or recorded on any electronic or other medium without the express written permission of Rapid
Smartcard Solutionz Limited.
All material contained in this document which is not readily available in the public domain is regarded
as confidential to Rapid Smartcard Solutionz Limited and may not be divulged to any third party
without the express written permission of Rapid Smartcard Solutionz Limited.
Rapid Smartcard Solutionz extends authorisation to R&D Technology Solutionz to use this document
for its intended purpose.
2. INTRODUCTION
2.2 Audience
This document is intended for developers and technicians looking to integrate a RSS ISO 14443
compliant reader with a controller.
2.4 Attachments
There are no attachments to this document.
2.5 Limitations
This document is intended for review, and as such is subject to change. Future revisions of this paper
will be distributed via email to those parties identified in section 2.3.
2.6 Acronyms
AC – Application Code [1]
ACK – Acknowledge (ASCII character 0x06)
AID – Application Identifier
APDU – Application Protocol Data Unit
CID – Card Identifier
DLE – Data Length Escape (ASCII character 0x10)
ETX – End of Transmission (ASCII character 0x03)
FCC – Function Cluster Code [1]
LSB – Least Significant Byte
MAD – Mifare Application Directory [1]
MSB – Most Significant Byte
NAK – Negative Acknowledge (ASCII character 0x15)
RF – Radio Frequency
3. OVERVIEW
A number of communications protocols exist for interacting with a RSS ISO 14443 compliant contact-
less reader, however they tend to be either too low-level or are biased towards a specific application,
such as access control.
The aim of this protocol is to serve as a higher-level abstraction that exposes the generic reader
functionality over a standard serial link without the controller device being required to perform a step-
by-step interaction with the card.
3.1 Conventions
The flowing conventions are used in this document:
The C programming language notation for hexadecimal values, the identifier ‘0x’ followed by one or
more pairs of hexadecimal digits, is used except where otherwise stated e.g. 0x01, 0xFF, 0x01FF
The ASCII letter codes are used for control codes in place of their hexadecimal representation to
distinguish them from data values e.g. STX is used in place of 0x02 when it indicates the start of frame.
A zero-length message is often used as a high level response. This consists of the standard message
format with both length bytes set to 0x00 and no data.
This is an asynchronous peer-to-peer protocol and either the controller or the reader can initiate
communications. The communications are full duplex and both devices are required to be able to
transmit and receive simultaneously.
4. SERIAL PROTOCOL
The following sections define the serial protocol used between the host and the RSS ISO14443 Reader.
Parameter Setting
Baud Rate 57,600
Bits per Character 8
Parity None
Stop Bits 1
Original message.
STX 0x01 0xA0 0x00 0x02 0x10 0x41 ETX 0xF3
DLE Stuffing.
STX 0x01 0xA0 0x00 DLE 0x02 DLE 0x10 0x41 ETX 0xF3
Notes:
The body of the message is between the STX and ETX and so the checksum does not require
a DLE.
The inserted DLE characters do not change any length variables in the message.
If the calculated checksum is 0x10 then care must be taken that the STX from the next
message is not misinterpreted.
4.1.4 Timeouts
Two different timeouts are observed over the serial link:
1) The time between characters in a message (inter-character timeout).
2) The time between sending a message and receiving an acknowledgement (response timeout).
If the inter-character timeout is exceeded then the receiver should send a NAK to the sender. If the
response timeout is exceeded, and the number of retries has not reached the maximum, then the
message should be resent.
Timeout Time
Inter-character 10 ms
Response timeout 300 ms
A message consists of two framing bytes (STX and ETX), a token, a message type, data length,
message data, and a checksum as shown below:
4.2.1 STX
This is a single byte start of frame marker represented by ASCII character 0x02.
4.2.2 Token
For every new message sent the token is incremented by one, with 0xFF rolling over to 0x00. This
allows the receiver to discard any duplicate messages by comparing the token for the message just
received with the token from the previous message received. On reset the token should be set to zero
and the previously received token set to 0xFF to avoid any conflict with the first received message.
The list of valid message types is given in the Message Types section of this document.
4.2.5 ETX
This is a single byte end of frame marker represented by ASCII character 0x03.
4.2.6 Checksum
The checksum is exclusive-or (XOR) of all the bytes in the message between the STX and ETX,
excluding any DLE characters that have inserted to escape command bytes. Note that the checksum is
not considered part of the body of the message and so does not require a DLE.
Note: The message type validity and the contents of the message data are not checked at this level.
4.3.2 Retries
If a message is responded to with a NAK then the sender will resend the message up to 3 times before
discarding it. A message that fails every retry is most likely to be incorrectly formatted, oversized,
and/or the receiver is no longer connected or receiving data.
5. MESSAGE TYPES
Originator: Controller
Format:
Message Type 0x20
Data Length 1
Data Field Size Value
Status Request 1 Byte 0x00
Response:
Message Type 0xA0
Data Length 1
Data Field Size Value
Current Status 1 Byte 0x00 – Normal Status,
0xFF – Major Error Status
Originator: Controller
Format:
Message Type 0x21
Data Length 1
Data Field Size Value
LED Control 1 Byte 0x00 – LED Display Reader Control,
0x01 – LED Display Off,
0x02 – LED Display On,
0x03 – LED Display Flash Fast,
0x04 – LED Display Flash Medium,
0x05 – LED Display Flash Slow
Response:
Message Type 0xA1
Data Length 0
Data Field Size Value
The LED Display Reader Control setting indicates that the reader has control of the LED display.
Originator: Reader
Format:
Message Type 0x30
Data Length varies
Data Field Size Value
Tag Type 1 Byte see table below
Tag ID 4 Bytes 0x00000000 - 0xFFFFFFFF
Card Identifier 1 Byte 0x00 – 0x0F
Tag Select Data varies varies
Response:
Message Type 0xB0
Data Length 0
Data Field Size Value
The tag select data consists of any information returned from the card during the initial negotiation
with the reader when the card entered the read zone.
Originator: Controller
Format:
Message Type 0x50
Data Length 4
Data Field Size Value
Tag ID 4 Bytes 0x00000000 - 0xFFFFFFFF
Response:
Message Type 0xD0
Data Length 32
Data Field Size Value
MAD 32 Bytes Formatted MAD Data
or
Message Type 0xD0
Data Length 1
Data Field Size Value
Read Error 1 Byte 0x00 – MAD not Present
0xFF – Tag not Present
The Mifare Standardization Group document Mifare Application Directory Standardization Note [1]
contains further documentation on the MAD.
Originator: Controller
Format:
Message Type 0x51
Data Length 0
Data Field Size Value
Tag ID 4 Bytes 0x00000000 - 0xFFFFFFFF
Write-key Offset 1 Byte 0x00 – 0x1F
Data Sector 1 Byte 0x00 – 0x0F
AID 2 Bytes FCC 0x00 – 0xFF, AC 0x00 – 0xFF
Response:
Message Type 0xD1
Data Length 1
Data Field Size Value
Update Status 1 Byte 0x00 – Update Successful,
0xF6 – Authentication Failed,
0xFF – Tag not Present
The Mifare Standardization Group document Mifare Application Directory Standardization Note [1]
contains further documentation on the MAD.
Originator: Controller
Format:
Message Type 0x52
Data Length 6
Data Field Size Value
Tag ID 4 Bytes 0x00000000 - 0xFFFFFFFF
Sector Number 1 Byte 0x00 – 0x0F
Read-key Offset 1 Byte 0x00 – 0x1F
Response:
Message Type 0xD2
Data Length 64
Data Field Size Value
Sector Data 64 Bytes Data from the sector
or
Message Type 0xD2
Data Length 1
Data Field Size Value
Read Error 1 Byte 0xF6 – Authentication Failed
0xFF – Tag not Present
Originator: Controller
Format:
Message Type 0x53
Data Length 54
Data Field Size Value
Tag ID 4 Bytes 0x00000000 - 0xFFFFFFFF
Sector Number 1 Byte 0x00 – 0x0F
Write-key Offset 1 Byte 0x00 – 0x1F
Write Data 48 Bytes Data to be written
Response:
Message Type 0xD3
Data Length 1
Data Field Size Value
Write Status 1 Bytes 0x00 – Transaction OK,
0xF1 – Write Error,
0xF6 – Authentication Failed,
0xFF – Tag not present
Note that the first block (block 0) of sector 0 is reserved for card information and is read-only; hence
the first 16 bytes of any data sent to be written to sector 0 will be ignored.
Originator: Controller
Format:
Message Type 0x54
Data Length 70
Data Field Size Value
Tag ID 4 Bytes 0x00000000 - 0xFFFFFFFF
Sector Number 1 Byte 0x00 – 0x0F
Write-key Offset 1 Byte 0x00 – 0x1F
Write Data 48 Bytes Data to be written
Access Block 16 Bytes Access Block data to be written
Response:
Message Type 0xD4
Data Length 1
Data Field Size Value
Write Status 1 Bytes 0x00 – Transaction OK,
0xF1 – Write Error,
0xF6 – Authentication Failed,
0xFF – Tag not present
If the key given by the write-key offset fails to authenticate with the sector then the reader will attempt
to use both the blank tag key (0xFFFFFFFFFFFF) and the Philips demonstration kit write-key
(0xB0B1B2B3B4B5) for authentication before failing.
Note that the first block (block 0) of sector 0 is reserved for card information and is read-only; hence
the first 16 bytes of any data sent to be written to sector 0 will be ignored.
Originator: Controller
Format:
Message Type 0x55
Data Length 13
Data Field Size Value
Tag ID 4 Bytes 0x00000000 - 0xFFFFFFFF
Key Offset 1 Byte 0x00 – 0x1F
Value Command 1 Byte 0x00 – Decrement,
0x01 – Increment,
0x02 – Restore
Value Sector 1 Byte 0x00 – 0x0F
Value Block 1 Byte 0x00 – 0x02
Transfer Block 1 Byte 0x00 – 0x02
Value 4 Bytes 0x00000000 – 0xFFFFFFFF
Response:
Message Type 0xD5
Data Length 1
Data Field Size Value
Value Status 1 Byte 0x00 – Transaction OK,
0x84 – Transaction Failed,
0xF6 – Authentication Failed,
0xFF – Tag not present
Note that the value should be in little endian format, e.g. the value 0x12345678 should be sent as
0x78563412.
Originator: Controller
Format:
Message Type 0x56
Data Length 7
Data Field Size Value
Key Location 1 Byte 0x00 – 0x1F
Key Data 6 Bytes 0x000000000000 – 0xFFFFFFFFFFFF
Response:
Message Type 0xD6
Data Length 1
Data Field Size Value
Load Status 1 Byte 0x00 – Key Load Successful,
0x01 – Invalid Key Location,
0x02 – Invalid Key Length
Originator: Controller
Format:
Message Type 0x60
Data Length varies
Data Field Size Value
Card Identifier 1 Byte 0x00 – 0x0F
Node Address 1 Byte 0x00
Command APDU 4 Bytes Header (CLA, INS, P1, P2)
Command APDU varies Body (Lc, Data, Le)
Response:
Message Type 0xE0
Data Length varies
Data Field Size Value
Response APDU varies Body (Data)
Response APDU varies Trailer (SW1, SW2)
See the ISO/IEC 7816 Part 4 standard for information on APDU commands.
Originator: Controller
Format:
Message Type 0x61
Data Length 1
Data Field Size Value
Card Identifier 1 Byte 0x00 – 0x0F
Response:
Message Type 0xE1
Data Length 1
Data Field Size Value
Result 1 Byte 0x00 – Success,
0xFF – Tag not present
Note: The Card Identifier (CID) in this message is not the same as the Tag ID
Originator: Reader
Format:
Message Type 0x70
Data Length varies
Data Field Size Value
Message Text varies ASCII Text String
Response:
None
On a reset the reader will send its version string, serial number, and protocol version in three separate
information messages.
Originator: Reader
Format:
Message Type 0x71
Data Length 2
Data Field Size Value
Error Code 2 Bytes 0x0000 – 0xFFFF
Response:
None
Code Description
0x0000 Unknown message type
0x0001 Invalid message format
0x0002 Invalid state for command
0x0003 Command not supported
0x0004 – 0x0FFF Reserved
0x1000 - 0x1FFF Internal Processing Errors
0x2000 – 0x3FFF Minor System Errors
0x4000 – 0x5FFF Major System Errors
0x5000 – 0xFFFF Reserved
6. TRANSACTION FLOW
Controller Reader
Status Request
Process MAD
Mifare Read Sector
Validate Data
LED Control (0x02 - Display On)
Perform Transaction
LED Control (0x01 - Display Off)
Legend:
Message Response
Processing
Processing