Smart card interface functional specification
Distribution: COMPANY CONFIDENTIAL
Project: NC model 1
Issue: 0.03
Author(s): Rich Buckley
Date: 15-Nov-96
Last Issue: 0.02
Contents.
0.01 04-Jul-96 First created based on original spec 0.03.
0.02 01-Aug-96 Corrected type
0.03 15-Nov-96 Corrected in line with development.
The api provided by the SCInterface module uses swis provided by the SCTransport module to access the functions documented above as part of the level 2 api. The following swis are provided.
SWI SCInterface_Create (0x04d340)
On entry
r0 - flags word with bit meanings
bit 0 : 0 - validate filenames, 1 - ignore validation
bit 1 : 0 - create file, 1 - create directory
r1 -> file path string in the form '/x/y/z' where x,y,z are
two byte hex numbers. For example /4e43/0001
r2 - size of file or directory to create
r3 - code access conditions for various operations coded as
for files for directories
nibble 0 - update unused
1 - read/seek execute
2 - create create/extend
3 - delete delete
4 - invalidate invalidate
5 - rehabilitate rehabilitate
where each nibble is either
0x0 : ALW, 0x1 : CHV1, 0x2 : CHV2
0xa : ADM1, 0xb : ADM2, 0xc : ADM3
0xd : ADM4, 0xe : ADM5, 0xf : NEV
On exit
r0 = return code as documented below
This swi creates a file/directory on the smart card. Dynamic file creation is not implemented on some cards.
SWI SCInterface_Delete (0x04d341)
On entry
r0 - flags word with bit meanings
bit 0 : 0 - validate filenames, 1 - ignore validation
r1 -> file path string in the form '/x/y/z' where x,y,z are
two byte hex numbers.
r2 -> chv access code
r3 - number of bytes in CHV access code
On exit
r0 = return code as documented below
This swi deletes a file/directory on the smart card. Dynamic file creation is not implemented on some cards.
SWI SCInterface_Read (0x04d342)
On entry
r0 - flags word with bit meaning
bit 0 : 0 - validate filenames, 1 - ignore validation
r1 -> file path string in the form '/x/y/z' where x,y,z are
two byte hex numbers.
r2 - byte offset into file to start read
r3 -> data area to copy results
r4 - number of bytes to read
r5 -> chv access code
r6 - number of bytes in CHV access code
On exit
r0 = return code as documented below
Reads data from a file on the smart card
SWI SCInterface_Write (0x04d343)
On entry
r0 - flags word with bit meaning
bit 0 : 0 - validate filenames, 1 - ignore validation
r1 -> file path string in the form '/x/y/z' where x,y,z are
two byte hex numbers.
r2 - byte offset into file to start write
r3 -> data area containg data to write
r4 - number of bytes to write
r5 -> chv access code
r6 - number of bytes in CHV access code
On exit
r0 = return code as documented below
This swi reads data from a file on the smart card.
SWI SCInterface_GetATR (0x04d344)
On entry
r0 - flags word with bit meaning
On exit
r0 = return code as documented below
r1 -> struct {BYTE hist[15]; int hist_len}
Returns the smart card ATR used to identify the card and type.
SWI SCInterface_ChangeCHV (0x04d345)
On entry
r0 - flags word with bit meaning
r1 -> directory path string in the form '/x/y/z' where x,y,z
are two byte hex numbers.
r2 - code access conditions
0x1 : CHV1
0x2 : CHV2
r3 -> existing access code
r4 - number of bytes in existing access code
r5 -> new access code
r6 - number of bytes in new access code
On exit
r0 = return code as documented below
Change the access code for a given access condition.
SWI SCInterface_EnableCHV (0x04d346)
On entry
r0 - flags word with bit meaning
bit 0 : 0 - validate filenames, 1 - ignore validation
bit 1 : 0 - disable access code test, 1 - enable access code test
r1 -> directory path string in the form '/x/y/z' where x,y,z
are two byte hex numbers.
r2 - code access conditions
0x1 : CHV1
0x2 : CHV2
r3 -> access code
r4 - number of bytes in access code
On exit
r0 = return code as documented below
Enable/disable CHV access code
SWI SCInterface_UnBlockCHV (0x04d347)
On entry
r0 - flags word with bit meaning
bit 0 : 0 - validate filenames, 1 - ignore validation
r1 -> directory path string in the form '/x/y/z' where x,y,z
are two byte hex numbers.
r2 - code access conditions
0x1 : CHV1
0x2 : CHV2
r3 -> unblock CHV access code
r4 - number of bytes in unblock CHV access code
r5 -> new CHV access code
r6 - number of bytes in new CHV access code
On exit
r0 = return code as documented below
Will unblock the CHV access code fail attempt counter.
SWI SCInterface_FileInfo (0x04d348)
On entry
r0 - flags word with bit meaning
bit 0 : 0 - validate filenames, 1 - ignore validation
r1 -> directory path string in the form '/x/y/z' where x,y,z
are two byte hex numbers.
r2 -> data area to copy results
r3 - size of data area
On exit
r0 = return code as documented below
Will return a block of data relating to a file or directory. Block is formatted as documented in the Orga manual page 90 or the InCard manual page 26. Items of interest to Ant maybe file size = data[2]<<8 | data[3]
SWI SCInterface_InternalAuth (0x04d349)
On entry
r0 - flags word with bit meaning
r2 - logical key number
r3 -> challenge
r4 - size of challenge
r5 -> data area to hold response
r6 - size of data area
On exit
r0 = return code as documented below
Will encrypt a block of data using a specified key number typically this would be a challenge response type thing.
SWI SCInterface_Status (0x04d34a)
On entry
On exit
r0 - status word with meaning given by
typedef enum {StatusIdle, StatusNoCard,
StatusBusy, StatusError} t_interface_status;
r1 - error status if r0==StatusError
Will return the current status of the SCInterface module. To be used in polled mode operation. Performing this swi will clear the error condition flag.
Events
Since all the above swis occur asynchronously, a riscos event is generated to indicate command completion plus a number of card in/out events. The following events are generated :
#define Event_Expansion (21) /* r0 on receipt of an event */
#define Event_Expansion_SCInterface (0) /* r1 on receipt of an event */
reason codes passed in event r2
#define Event_CardOK (0) /* card inserted and understood */
#define Event_CardBad (1) /* card inserted and not understood */
#define Event_CardRemoved (2) /* card has been removed */
#define Event_Complete (3) /* previous command completed */
And the following reason codes can be returned from every swi or returned as a parameter (r3) in the event Event_Complete.
/* reported from swis and events */
#define SC_SUCCESS (0x0) /* command successful */
/* reported from swis only */
#define SC_NOCARD (0x01) /* smart card not inserted */
#define SC_FORMAT (0x02) /* file path format error */
#define SC_NESTED (0x03) /* too many nexted subdirectories */
#define SC_UNDERSTAND (0x04) /* do not understand inserted card */
#define SC_BUSY (0x05) /* still processing previous command */
#define SC_RESERVED (0x06) /* smart card reserved filename specified */
#define SC_NOTIMPLEMENTED (0x07) /* command not implemented on this card */
/* reported from events only */
#define SC_NOTFOUND (0x10) /* requested file not found */
#define SC_TRANSPORT (0x11) /* error returned from SCTransport */
#define SC_SPACE (0x12) /* not enough space to fit requested data */
#define SC_EXISTS (0x13) /* file already exists */
#define SC_STORAGE (0x14) /* storage problem */
#define SC_NOSELECT (0x15) /* no file selected */
#define SC_NOTVALID (0x16) /* outside valid area */
#define SC_INCONSIST (0x17) /* file type is inconsistant with command */
#define SC_UNKNOWNRESP (0x18) /* unknown response code returned */
#define SC_P1P2INVALID (0x19) /* incorrect parameter values p1,p2 */
#define SC_P3INVALID (0x1a) /* incorrect parameter value p3 */
#define SC_TECHPROBLEM (0x1b) /* technical problem with no diagnostics */
#define SC_WRONGCLASS (0x1c) /* wrong instruction class byte */
/* reported from events and relating to access conditions */
#define SC_NOACCESSCODE (0x20) /* no access code defined */
#define SC_FAILACCESSCODE (0x21) /* failed access code verification */
#define SC_NOACCESSCHANGE (0x22) /* change CHV not possible */
#define SC_BLOCKEDACCESS (0x23) /* CHV failure counter has blocked */
#define SC_NEVERACCESS (0x24) /* file has NVR access defined */
None defined.
A NC1 and smart card daughter board provided as first deliverables of contract with Card Dynamics.
Using available hardware.
The module will be built as part of the Omega build tree for inclusion in main ROM.