$Id: messageformats.txt,v 1.7 2003/04/22 22:59:22 aquamaniac Exp $


Messages Recognized by the Libchipcard daemon
=============================================


Reader Number and Reader Id
---------------------------
Please do not confuse "reader id" and "reader number".
On each daemon each reader has a unique id. However, if a reader is allocated
by a client (such as the tool hbcicard) then a pointer to this reader is
stored in the clients reader table. Now the "reader number" is the index into
that table. This blocks each client from using the readers allocated by other
clients.
As you can see when looking for a reader we cannot get a reader number in
return of the corresponding request, since the reader number is only assigned
upon allocation. So in these cases we get the unique "reader id". 
This id is then used to allocate the reader.
Sounds complicated but it works just fine ;-)

In the list below a request is the message a client sends to the daemon, while
a response is the answer of the daemon to the request.

The daemon never sends unrequested messages, and it will never actively
connect to a client.


Message Header
--------------
A message generally has the following header:
INT   : message code
INT   : message version
INT   : message id (not for key exchange messages)
INT   : reply id   (not for key exchange messages)

The message code is the type of message (like Ping Request or Ping Response).
The message version has the following meaning: 0xAABB. AA is the major
version of the message, BB is the minor version. The minor version may differ
on client and server side, but the major version MUST be equal. The
server and the client will refuse to accept messages where the major
version differs. The major version number changes if the new format of
a message is incompatible with the old format. Changes of the minor
version only show modifications which do not affect compatibility.


Key Exchange Messages
=====================

Session Key Request
-------------------
INT   : message code
INT   : message version
STRING: public rsa key (in IPCMessage-format)
STRING: client identification string


Session Key Response
--------------------
INT   : message code
INT   : message version
STRING: blowfish session key, encrypted with the clients public rsa key


Open Request
------------
This message is used for unencrypted channels instead of "Session Key
Request". It can only be used for secure channels, like those via unix
domain sockets.

INT   : message code
INT   : message version
STRING: client identification string


Open Response
-------------
 no params


Encrypted Message
-----------------
INT   : message code
INT   : message version
STRING: encrypted message



General Messages
================
Each of the messages below has a header as described above.


Ping Request
------------
This message can be used to check for the existence of a chipcard daemon.
This message has been used while developing the key exchange protocol, it is 
not used by any client. However, the server responds with a "Ping Response" in
any case.

 no params


Ping Response
-------------
 no params


Allocate Reader Request
-----------------------
This message is send to allocate a known reader. The client gets to
know a reader by using the requests "Find Reader" or "Wait For Reader".
Please note that allocating a reader does not connect the card inserted
to the reader, and this request does not lock the reader exclusively to
the client. So multiple clients may allocate the same reader. The
reader is locked upon the "Connect Request".

INT:  reader id


Allocate Reader Response
------------------------
INT: reader id
INT: reader flags
INT: reader type


Release Reader Request
----------------------
The client needs to release a reader it previously allocated. However,
upon disconnection of the client all its readers will be released
anyway.

INT: reader number


Release Reader Response
-----------------------
 no params


Connect Reader Request
----------------------
This actually connects the card inserted to the reader. This also locks
the reader exclusively for the client so that no other client may
access this reader. This request will be denied if another client
already connected the card. Please note that no nested connects are
allowed. If this client already connected this reader no further action
is performed.

INT: reader number
INT: waitflag (if 0 then the server will immediately try to connect)


Connect Reader Response
-----------------------
INT   : result code (CTSERVICE_RESULT_xyz values)
STRING: ATR string (answer to reset, only if result code indicates OK)


Disconnect Reader Request
-------------------------
This disconnects the card inserted into the reader and unlocks the
reader. So after this request has been acknowledged the reader may be
used by other clients again. Since no nested connects are allowed this
request will disconnect and unlock the reader regardless of how often
the reader has been connected.

INT   : reader number


Disconnect Reader Response
--------------------------
INT   : result code (CTSERVICE_RESULT_xyz values)


Command Reader Request
----------------------
This request sends an APDU to a card. Therefore the reader must be
allocated and connected.

INT   : reader number
STRING: APDU to send to the card


Command Reader Response
-----------------------
INT   : result code (CTSERVICE_RESULT_xyz values)
STRING: response (to the APDU, only if result indicates OK)


Find Reader Request
-------------------
STRING: reader type
INT   : reader flags
INT   : reader flags mask


Find Reader Response
--------------------
INT   : number of readers found
INT[] : ids of the readers found


Stat Reader Request
-------------------
INT   : reader number


Stat Reader Response
--------------------
INT   : result code (CTSERVICE_RESULT_xyz values)
INT   : status (only if result indicates OK)
STRING: ATR (only if result indicates OK)



Wait For Reader Request
-----------------------
This message is send to indicate that the client is waiting for a
reader. The type of the reader and the status the client is waiting for
are indicated by the parameters.

STRING: reader type 
INT   : reader flags        (src/libchipcard/engine/reader/ctcore_public.h)
INT   : reader flags mask   (src/libchipcard/engine/reader/ctcore_public.h)
INT   : reader status       (src/libchipcard/engine/reader/ctcore_public.h)
INT   : reader status mask  (src/libchipcard/engine/reader/ctcore_public.h)
INT   : must_change
INT   : reader status delta (src/libchipcard/engine/reader/ctcore_public.h)


Wait For Reader Response
------------------------
This response is only send if a reader matching the parameters given to
the request is available. In this case such a message will be send for
every matching reader. Otherwise no response will be send.

INT   : reader status
INT   : reader id
INT   : reader flags
STRING: reader type
INT   : reader name


Stop Wait For Reader Request
----------------------------
This message is send to indicate that the client doesn't want to wait
any longer for a reader. After sending this message no "Wait For Reader
Response" will be send even if a matching reader is available.

INT   : request id of the Wait Reader Request to stop


Stop Wait For Reader Response
-----------------------------
INT   : result code (CTSERVICE_RESULT_xyz values)


