SIO - Serial I/O Library

SIO.001 (Initial)
T J Hudson tjh@cryptsoft.com
19 October 1997


Table of Contents


1. Introduction

sio is a library of routines for doing cross-platform serial I/O between most Unix varients and WIN32. WIN16 support is currently not in the code (as I don't have a need for it just at the moment).

sio is a collection of routines I've written at various times to handle serial comms that has been reworked into a much nicer interface on which portable application logic can be layered.

sio includes a test program (stest) designed for interfacing with low-level Smartcard readers. stest also has a SCAM low-level driver emulation mode for use with the dumbmouse reader. Using the perl-based SCAM code to probe cards is fairly straight forward.

The current documentation can be found at http://www.cryptsoft.com/scard/sio.html and the source code can be downloaded from ftp://ftp.cryptsoft.com/scard/.

1.1. Copyright

Copyright 1993-1997, Tim Hudson. All rights reserved.

You can do what you like with this code except pretend that you wrote it provided that any derivative of this code includes the above comments unchanged. If you put this in a product then I would like to know about it. Credits in the documentation would be nice but are not essential.

1.2. References

Smartcard Handbook - Wolfgang Rankl, Wolfgang Effing
ISBN 0471967203
pp 440

(Translation of Handbuch der Chipkarten - Carl Hanser Verlag)

2. API

To use sio simply include sio.h. Read the header file for the current up to date list of functions.

int getATR(char *devicename)
{
  SIO_INFO *si;
  int ch;
  unsigned char achar;

  si=SIO_Open(devicename);
  if (si!=NULL) {
    /* setup for 9600, 8 data, 2 stop, even parity */
    SIO_SetSpeed(s,9600);
    SIO_SetDataBits(s,8);
    SIO_SetStopBits(s,2);
    SIO_SetParity(s,SIO_PARITY_EVEN);
    SIO_SetIOMode(s,SIO_IOMODE_INDIRECT);

    /* now actually change the line settings */
    SIO_WriteSettings(s);

    /* trigger ATR from a Smartcard */
    SIO_DropRTS(s);
    SIO_RaiseRTS(s);

    /* read data until there is none available for
     * the timeout period
     */
    while ((ch=SIO_ReadChar(s))!=-1) {
      achar=(unsigned char)(ch & 0xff);
      SIO_DumpBuffer(stderr,&achar,1,2);
    }

    /* finished ... cleanup time */
    SIO_Close(si);
  }
}

2.1. SIO_INFO

SIO_INFO holds all the relevant information related to a given serial connection. The state that is maintained is deliberately hidden from external view. If you stick to using the defined interfaces then your code will be portable (at least the part that talks to sio) between Unix and WIN32.

2.2. SIO_GetVersion

#define SIO_VERSION_MAJOR       1
#define SIO_VERSION_MINOR       1
int SIO_GetVersion(int *vmajor, int *vminor);

SIO_GetVersion returns the major and minor version number of the library.

2.3. SIO_Open

SIO_INFO *SIO_Open(char *device);

2.4. SIO_Close

int SIO_Close(SIO_INFO *s);

2.5. SIO_SetLogFile

int SIO_SetLogFile(SIO_INFO *s,char *name);

All data read or written will be logged to the specified file. The file is created or it is truncated if it already exists. The data is logged before any data conversion when writing and after any data conversion or echo suppression when reading. This gives the logical application level view of the data rather than the low-level serial view.

2.6. SIO_DumpBuffer

void SIO_DumpBuffer(FILE *fp,char *buf,int len,int text);

Dump a data buffer in different formats.

2.7. SIO_ReadSettings

int SIO_ReadSettings(SIO_INFO *s);

The current serial device parameters are fetched and converted into the sio view of the serial device.

2.8. SIO_WriteSettings

int SIO_WriteSettings(SIO_INFO *s);

The current sio view of the serial device is used to update the serial device parameters. Don't forget to call this function otherwise any parameter updates that effect the serial device will not actually be in effect yet.

2.9. SIO_GetSettingsString

char *SIO_GetSettingsString(SIO_INFO *s);

Return a terse text representation of the current sio comms settings.

2.10. SIO_SetSettingsString

int SIO_SetSettingsString(SIO_INFO *s,char *str);

Using the same format returned by SIO_GetSettingsString update the internal sio comms settings. Don't forget to call SIO_WriteSettings to update the device settings to match.

2.11. SIO_WaitForData

int SIO_WaitForData(SIO_INFO *s,int timedelay);

Wait up to timedelay microseconds for data activity.

2.12. SIO_ReadChar

int SIO_ReadChar(SIO_INFO *s);

Read a single character. Returns -1 if no data available.

2.13. SIO_ReadBuffer

int SIO_ReadBuffer(SIO_INFO *s,char *buf,int len);

2.14. SIO_WriteChar

int SIO_WriteChar(SIO_INFO *s,int data);

2.15. SIO_WriteBuffer

int SIO_WriteBuffer(SIO_INFO *s,char *buf,int len);

3. Smartcard Functions

sio also comes with a number of Smartcard related functions. To use these you need to also include sct0.h

3.1. SCT0_Reset

int SCT0_Reset(SIO_INFO *s);

Reset the Smartcard - should respond with ATR

3.2. SCT0_GetATR

int SCT0_GetATR(SIO_INFO *s,char *buf,int bufsize);

Request ATR from smartcard. SCT0_GetATR calls SCT0_Reset to perform a standard Smartcard reset.

3.3. SCT0_ScanForATR

int SCT0_ScanForATR(SIO_INFO *s,char *buf, int bufsize);

Try all communication settings until a valid ATR is returned. Using this function you can rapidly locate what parameter combination is required for any Smartcard.

SCT0_ScanForATR returns the length of the ATR (or 0 if no valid setting is found). The valid ATR is copied into buf assuming that there is enough space.

3.4. SCT0_ScanClasses

int SCT0_ScanClasses(SIO_INFO *s, char *classlist);

Scan for valid command classes. classlist should be an array of 256 chars (one for each class) and on return each index in the array will be set to 1 if the Smartcard responded indicating that the class was valid or 0 if an error was reported.

3.5. SCT0_ScanInstructions

int SCT0_ScanInstructions(SIO_INFO *s,char theclass,char *inslist);

Scan for valid instructions in a particular class. inslist should be an array of 256 chars (one for each instruction) and on return each index in the array will be set to 1 if the instruction is valid or 0 if it is not.


Note: some instructions (not many) may be valid without any parameters and in which case they will be executed during this scan.

3.6. SCT0_ScanFiles

int SCT0_ScanFiles(SIO_INFO *s,char theclass,char thefile,char *filelist);

Scan for all files by FileID that start with the given byte of thefile. filelist should be an array of 256 chars (one for each file) and on return each index in the array will be set to 1 if the file thefileindex exists or 0 if it does not.