visit Kofax web site

SPSmartcard.h File Reference

Detailed Description

SignWare Dynamic Development toolkit, access smart cards.

Author:
uko
This header defines an interface to smart cards. The functions declared in this header are not yet implemented for Linux.

The application should query the number of installed drivers, select the appropriate driver, and then create an SPSmartcard object. The application may then query the status of the selected smart card terminal, read data from, and write data to the inserted smart card.

The SPSmartcard object uses CT-API to connect to the device-dependent hardware driver for a specific card reader. PC-SC support is planned in the future.

Data exchange is based on ISO 7816-4 (Interindustry commands for interchange) and ISO 7816-8 (Commands for security operation). Note that smart cards typically support only a subset of the commands provided here. Always check the smart card documentation for supported commands.

Some smart cards require authentication to allow further commands, see the documentation of the smart card you intend to use.

Encryption functions use the libdes library written by Eric A. Young.


Defines

#define SP_SC_MFC   0x1100
 Smart card ID: Comcard MFC.
#define SP_SC_MFC_41   0x1101
 Smart card ID: Comcard MFC, Version 4.1.
#define SP_SC_MFC_43   0x1103
 Smart card ID: Comcard MFC, Version 4.3.
#define SP_SC_SMARTCAFE   0x1000
 Smart card ID: Giesecke & Devrient JavaCard.
#define SP_SC_SMARTCAFE_11   0x1001
 Smart card ID: Giesecke & Devrient JavaCard V1.1.
#define SP_SC_STARCOS   0x0F00
 Smart card ID: Giesecke & Devrient STARCOS smart cards.
#define SP_SC_STARCOS_S21   0x0F01
 Smart card ID: Giesecke & Devrient STARCOS S 2.1 smart cards.
#define SP_SC_STARCOS_SPK22   0x0F02
 Smart card ID: Giesecke & Devrient STARCOS SPK 2.2 smart cards.
#define SP_SC_STARCOS_SPK23   0x0F03
 Smart card ID: Giesecke & Devrient STARCOS SPK 2.3 smart cards.
#define SP_SC_TCOS   0x0900
 Smart card ID: TeleSec TCOS smart cards.
#define SP_SC_TCOS_44   0x0901
 Smart card ID: TeleSec TCOS with SLE44 chip.
#define SP_SC_TCOS_66   0x0902
 Smart card ID: TeleSec TCOS with SLE66 chip.
#define SP_SC_TCOS_66P   0x0903
 Smart card ID: TeleSec TCOS with SLE66p chip.
#define SP_SC_UNKNOWN   0x0000
 Smart card ID: unknown Smart card.
#define SP_SMARTCARD_CHANGED   2
 SPSmartcardGetStatus flag: The smart card in the reader was changed, data is no more reliable.
#define SP_SMARTCARD_INSERTED   1
 SPSmartcardGetStatus flag: A smart card is inserted in the reader.
#define SP_SMARTCARD_WRITE_PASSWORD   0x1000
 SPSmartcardGetStatus Flag: The smart card in the reader requires a password to write template data.

Functions

SPINT32 __cdecl SPSmartcardAPDU (pSPSMARTCARD_T pSmartcard, const SPUCHAR *pucCommand, SPINT32 iCommandLength, SPUCHAR *pucResult, SPINT32 *piResultLength, SPINT32 iCmdRespType)
 Send an APDU (Application protocol data unit) to the smart card.
SPINT32 __cdecl SPSmartcardCreate (pSPSMARTCARD_T *ppSmartcard, pSPSMARTCARDDRIVER_T pSmartcardDriver)
 Create a new SPSmartcard object from an SPSmartcardDriver object.
SPINT32 __cdecl SPSmartcardDisplayText (pSPSMARTCARD_T pSmartcard, const SPCHAR *pszDisplayText)
 Display a text on the smart card terminal.
SPINT32 __cdecl SPSmartcardFree (pSPSMARTCARD_T *ppSmartcard)
 Deallocate an SPSmartcard object.
SPINT32 __cdecl SPSmartcardGetCardType (pSPSMARTCARD_T pSmartcard, SPINT32 *piCardType)
 Get the type of the smart card that is currently inserted.
SPINT32 __cdecl SPSmartcardGetInput (pSPSMARTCARD_T pSmartcard, const SPCHAR *pszDisplayText, SPINT32 iOptionFlags, SPCHAR *pszInputBuffer, SPINT32 *piInputBufferLength)
 Get input from the smart card terminal.
SPINT32 __cdecl SPSmartcardGetLastResult (pSPSMARTCARD_T pSmartcard, SPINT32 *piResult)
 Get the result of the last SPSmartcardCommand or SPSmartcardAPDU operation.
SPINT32 __cdecl SPSmartcardGetStatus (pSPSMARTCARD_T pSmartcard, SPINT32 *piStatus)
 Get the status of an SPSmartcard object.
SPINT32 __cdecl SPSmartcardGotoState (pSPSMARTCARD_T pSmartcard, SPINT32 iNewState)
 Set a smart card driver state.
SPINT32 __cdecl SPSmartcardLoadTemplate (pSPSMARTCARD_T pSmartcard, pSPTEMPLATE_T *ppTemplate)
 Load a template from a smart card.
SPINT32 __cdecl SPSmartcardSaveTemplate (pSPSMARTCARD_T pSmartcard, pSPTEMPLATE_T pTemplate)
 Save a template on a smart card.
SPINT32 __cdecl SPSmartcardSaveTemplatePassword (pSPSMARTCARD_T pSmartcard, pSPTEMPLATE_T pTemplate, SPCHAR *pucPassword, SPINT32 iPasswordLen)
 Save a template in a password protected file on a smart card.

Define Documentation

#define SP_SC_MFC   0x1100
 

Smart card ID: Comcard MFC.

See also:
SP_SC_UNKNOWN

#define SP_SC_MFC_41   0x1101
 

Smart card ID: Comcard MFC, Version 4.1.

See also:
SP_SC_UNKNOWN

#define SP_SC_MFC_43   0x1103
 

Smart card ID: Comcard MFC, Version 4.3.

See also:
SP_SC_UNKNOWN

#define SP_SC_SMARTCAFE   0x1000
 

Smart card ID: Giesecke & Devrient JavaCard.

See also:
SP_SC_UNKNOWN

#define SP_SC_SMARTCAFE_11   0x1001
 

Smart card ID: Giesecke & Devrient JavaCard V1.1.

See also:
SP_SC_UNKNOWN

#define SP_SC_STARCOS   0x0F00
 

Smart card ID: Giesecke & Devrient STARCOS smart cards.

See also:
SP_SC_UNKNOWN

#define SP_SC_STARCOS_S21   0x0F01
 

Smart card ID: Giesecke & Devrient STARCOS S 2.1 smart cards.

See also:
SP_SC_UNKNOWN

#define SP_SC_STARCOS_SPK22   0x0F02
 

Smart card ID: Giesecke & Devrient STARCOS SPK 2.2 smart cards.

See also:
SP_SC_UNKNOWN

#define SP_SC_STARCOS_SPK23   0x0F03
 

Smart card ID: Giesecke & Devrient STARCOS SPK 2.3 smart cards.

See also:
SP_SC_UNKNOWN

#define SP_SC_TCOS   0x0900
 

Smart card ID: TeleSec TCOS smart cards.

See also:
SP_SC_UNKNOWN

#define SP_SC_TCOS_44   0x0901
 

Smart card ID: TeleSec TCOS with SLE44 chip.

See also:
SP_SC_UNKNOWN

#define SP_SC_TCOS_66   0x0902
 

Smart card ID: TeleSec TCOS with SLE66 chip.

See also:
SP_SC_UNKNOWN

#define SP_SC_TCOS_66P   0x0903
 

Smart card ID: TeleSec TCOS with SLE66p chip.

See also:
SP_SC_UNKNOWN

#define SP_SC_UNKNOWN   0x0000
 

Smart card ID: unknown Smart card.

Smart card ID's consist of a byte that describes the smart card family and a byte that describes the smart card type within its family.

#define SP_SMARTCARD_CHANGED   2
 

SPSmartcardGetStatus flag: The smart card in the reader was changed, data is no more reliable.

See also:
SPSmartcardGetStatus

#define SP_SMARTCARD_INSERTED   1
 

SPSmartcardGetStatus flag: A smart card is inserted in the reader.

See also:
SPSmartcardGetStatus

#define SP_SMARTCARD_WRITE_PASSWORD   0x1000
 

SPSmartcardGetStatus Flag: The smart card in the reader requires a password to write template data.

See also:
SPSmartcardGetStatus, SPSmartcardSaveTemplatePassword

Function Documentation

SPINT32 __cdecl SPSmartcardAPDU (  pSPSMARTCARD_T  pSmartcard,
const SPUCHAR *  pucCommand,
SPINT32  iCommandLength,
SPUCHAR *  pucResult,
SPINT32 *  piResultLength,
SPINT32  iCmdRespType
) 
 

Send an APDU (Application protocol data unit) to the smart card.

Use this function to send an APDU command to the smart card. If possible, the application should not call this function, but rather use the higher communication levels. This function is provided to support application-specific command extensions.

The application must set the open or connect state before sending any commands, and finally reset to the closed state.

Parameters:
pSmartcard [i] pointer to an SPSmartcard object.
pucCommand [i] pointer to a byte array containing the command bytes. The layout of an CT-API command is this:
  • byte 0: class byte
  • byte 1: parameter P1
  • byte 2: parameter P2
  • byte 3: optional Lc field
  • byte 4 etc: optional data
  • byte n - 1: optional Le field
iCommandLength [i] length (in bytes) of the byte array pointed to by pucCommand.
pucResult [o] pointer to a byte array that will be filled with the result. The layout of the result is this:
  • bytes 0 through *piResultLength - 2: optional result data
  • byte *piResultLength - 2: return code SW1
  • byte *piResultLength - 1: return code SW2
piResultLength [io] pointer to a variable that contains the size (in bytes) of the buffer pointed to by pucResult. The variable will be filled with the actual number of result bytes.
iCmdRespType [i] command and response length specifier:
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32)
See also:
SPSmartcardGetLastResult, SPSmartcardGetStatus, SPSmartcardGotoState
Todo:
Implement for Linux

SPINT32 __cdecl SPSmartcardCreate (  pSPSMARTCARD_T *  ppSmartcard,
pSPSMARTCARDDRIVER_T  pSmartcardDriver
) 
 

Create a new SPSmartcard object from an SPSmartcardDriver object.

This function copies the SPSmartcardDriver object.

Parameters:
ppSmartcard [o] pointer to a variable that will be filled with a pointer to a new SPSmartcard object. The caller is responsible for deallocating the new object by calling SPSmartcardFree.
pSmartcardDriver [i] pointer to an SPSmartcardDriver object.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32)
See also:
SPSmartcardFree, SPSmartcardDriverFree
Todo:
Implement for Linux

SPINT32 __cdecl SPSmartcardDisplayText (  pSPSMARTCARD_T  pSmartcard,
const SPCHAR *  pszDisplayText
) 
 

Display a text on the smart card terminal.

Parameters:
pSmartcard [i] pointer to an SPSmartcard object.
pszDisplayText [i] the text to be displayed.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32)
See also:
SPSmartcardGetStatus, SP_SMARTCARD_INSERTED
Todo:
Specify encoding of the text.
Todo:
Implement for Linux

SPINT32 __cdecl SPSmartcardFree (  pSPSMARTCARD_T *  ppSmartcard  ) 
 

Deallocate an SPSmartcard object.

All resources acquired for the SPSmartcard object will be released.

The SPSmartcard object must have been created by SPSmartcardCreate.

Parameters:
ppSmartcard [io] pointer to a variable containing a pointer to an SPSmartcard object. The variable will be set to NULL if this function succeeds.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32)
See also:
SPSmartcardCreate
Todo:
Implement for Linux

SPINT32 __cdecl SPSmartcardGetCardType (  pSPSMARTCARD_T  pSmartcard,
SPINT32 *  piCardType
) 
 

Get the type of the smart card that is currently inserted.

Parameters:
pSmartcard [i] pointer to an SPSmartcard object.
piCardType [o] pointer to a variable that will be filled with the type of the smart card: Other types may be returned, but these are not fully supported in this version of SignWare.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32)
See also:
SPSmartcardCreate, SPSmartcardGetStatus
Todo:
Implement for Linux

SPINT32 __cdecl SPSmartcardGetInput (  pSPSMARTCARD_T  pSmartcard,
const SPCHAR *  pszDisplayText,
SPINT32  iOptionFlags,
SPCHAR *  pszInputBuffer,
SPINT32 *  piInputBufferLength
) 
 

Get input from the smart card terminal.

Parameters:
pSmartcard [i] pointer to an SPSmartcard object.
iOptionFlags [i] 0 or a bitwise combination of these flags:
pszDisplayText [i] text to be displayed on the smart card terminal (only for terminals with integrated display) or NULL if no text is to be displayed.
pszInputBuffer [o] pointer to a buffer that will be filled with the input from the smart card terminal (typically 32 bytes long).
piInputBufferLength [io] pointer to a variable that contains the size (in bytes) of the buffer pointed to by pszInputBuffer. The variable will be filled with the actual number of bytes read from the keyboard into the buffer pointed to by pszInputBuffer.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32)
See also:
SPSmartcardDisplayText, SPSmartcardGetStatus, SP_SUPRESS_INPUT, SP_SMARTCARD_INSERTED
Todo:
Specify encoding of the text.
Todo:
Implement for Linux

SPINT32 __cdecl SPSmartcardGetLastResult (  pSPSMARTCARD_T  pSmartcard,
SPINT32 *  piResult
) 
 

Get the result of the last SPSmartcardCommand or SPSmartcardAPDU operation.

Each command returns a 2-byte status word. The typical "no error" result is 0x9000.

Parameters:
pSmartcard [i] pointer to an SPSmartcard object.
piResult [o] pointer to a variable that will be filled with the result of the last command.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32)
See also:
SPSmartcardAPDU, SPSmartcardCommand
Todo:
Declare SPSmartcardCommand or remove reference to it.
Todo:
Implement for Linux

SPINT32 __cdecl SPSmartcardGetStatus (  pSPSMARTCARD_T  pSmartcard,
SPINT32 *  piStatus
) 
 

Get the status of an SPSmartcard object.

Parameters:
pSmartcard [i] pointer to an SPSmartcard object.
piStatus [o] pointer to a variable that will be filled with the device status. The device status is 0 or a bitwise combination of these values:
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32)
See also:
SPSmartcardCreate
Todo:
Implement for Linux

SPINT32 __cdecl SPSmartcardGotoState (  pSPSMARTCARD_T  pSmartcard,
SPINT32  iNewState
) 
 

Set a smart card driver state.

The application is responsible for finally closing the driver.

Parameters:
pSmartcard [i] A valid pSPSMARTCARD_T object
iNewState [i] requested state
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32)
See also:
SP_SMARTCARD_CLOSED, SP_SMARTCARD_OPENED, SP_SMARTCARD_CONNECTED
Todo:
Implement for Linux

SPINT32 __cdecl SPSmartcardLoadTemplate (  pSPSMARTCARD_T  pSmartcard,
pSPTEMPLATE_T *  ppTemplate
) 
 

Load a template from a smart card.

Parameters:
pSmartcard [i] pointer to an SPSmartcard object.
ppTemplate [o] pointer to a variable that will be filled with a pointer to a new SPTemplate object. The caller is responsible for deallocating the new object by calling SPTemplateFree.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32)
See also:
SPSmartcardSaveTemplate, SPTemplateCreateFromSmartcard, SPTemplateFree
Todo:
Implement for Linux

SPINT32 __cdecl SPSmartcardSaveTemplate (  pSPSMARTCARD_T  pSmartcard,
pSPTEMPLATE_T  pTemplate
) 
 

Save a template on a smart card.

Parameters:
pSmartcard [i] pointer to an SPSmartcard object.
pTemplate [i] pointer to an SPTemplate object containing the template to be saved on the smart card.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32)
See also:
SPSmartcardLoadTemplate, SPSmartcardSaveTemplatePassword, SPTemplateCreateFromSmartcard
Todo:
Implement for Linux

SPINT32 __cdecl SPSmartcardSaveTemplatePassword (  pSPSMARTCARD_T  pSmartcard,
pSPTEMPLATE_T  pTemplate,
SPCHAR *  pucPassword,
SPINT32  iPasswordLen
) 
 

Save a template in a password protected file on a smart card.

Parameters:
pSmartcard [i] pointer to an SPSmartcard object.
pTemplate [i] pointer to an SPTemplate object containing the template to be saved on the smart card.
pucPassword [i] pointer to the password required for unprotecting the smart card.
iPasswordLen [i] length (in bytes) of the password pointed to by pucPassword.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32)
See also:
SPSmartcardLoadTemplate, SPSmartcardSaveTemplate, SPTemplateCreateFromSmartcard
Todo:
Implement for Linux