$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)