APDUPlay configuration

APDUPlay's input and output files

The APDUPlay creates no output files by default and attempts to open one input file winscard_rules.txt. When configured via winscard_rules.txt, the following files are readed and/or created:

1. winscard_rules.txt - input file. Contains the configuration for all APDUPlay functionality.
2. apduplay_debug.txt - output file. Contains debugging information about the configuration used, exchanged APDUs and SCardXXX functions called.
3. winscard_log.txt - output file(s). Contains exchanged logged APDU commands.

File: winscard_rules.txt

Purpose: Contains the configuration for the APDUPlay functionality.

Location: First searched in the current folder of a target application. If not found, searched in the folder specified by APDUPLAY environmental variable.

File: apduplay_debug.txt

Purpose: Contains all debugging information about the configuration used, exchanged APDUs and SCardXXX functions called. The information from the new execution is always appended at the end of the apduplay_debug.txt file.

Location: By default, this file is stored at 'c:\Temp\apduplay_debug.txt'. The location of apduplay_debug.txt can be changed by setting APDUPLAY_DEBUG environmental variable with full new path specifying new location of apduplay_debug.txt.

File: winscard_log.txt

Purpose: Contains exchanged and logged APDU commands. The new file (with appended date and time) is created when a target application loads the APDUPlay's winscard.dll. The date and file can be matched against the entry inside the apduplay_debug.txt file.

Location: By default, this file is created in the current folder of a target application. The placement can be changed by key LOG_BASE_PATH loaded from winscard_rules.txt.

APDUPlay functionality configuration

The APDUPlay project will NOT create any file(s) or modify exchanged APDUs unless configured to do so. To make APDUPlay useful, the configuration must be performed via winscard_rules.txt file.

The placement of winscard_rules.txt file

APDUPlay's winscard.dll will try to locate, open and read winscard_rules.txt from the following locations (sorted with decreased priority):

1. The current folder of a target application (or its component responsible for smartcard handling).
2. The folder specified by "APDUPLAY" environmental variable.

The preferred option is to use the current folder to store both APDUPlay's winscard.dll and winscard_rules.txt file with configuration. This way, the configuration (as well as APDU logging and manipulation) is local to the particular target application and is not influencing other applications running on the same system.

However, the current folder of the target application might be difficult to locate (e.g., when an application is directly loading the library from system folder or using another component to handle smartcard communication - e.g., JavaRE). In such a case, set APDUPLAY system environmental variable to the folder containing the winscard_rules.txt file. E.g., APDUPLAY = D:\temp\apduplay\ (system variable, NOT entry in winscard_rules.txt). If winscard_rules.txt is not found in the current folder (step 1), location $APDUPLAY$\winscard_rules.txt is attempted.

winscard_rules.txt options

[WINSCARD]                                         <---- section for generic configuration
LOG_EXCHANGED_APDU = 1                             <---- enable logging of exchanged APDUs to winscard_log.txt file
MODIFY_APDU_BY_RULES = 1                           <---- enable modification of the exchanged APDUs
LOG_FUNCTIONS_CALLS = 1
AUTO_REQUEST_DATA = 1                              <---- enable automatic reading of response data when 0x61xx (SW_BYTES_REMAINING_00) is returned
LOG_BASE_PATH = ./                                 <---- output folder for output files  
READER_ORDERED_FIRST = first_reader                <---- name of the reader which should be listed first after SCardListReaders call (handy if target application only connects to the first provided reader)
FORCE_CONNECT_SHARED_MODE = 1                      <---- make connection to smartcard be shared instead of exclusive (SCardConnect)
FORCE_APDU_NONZERO_INPUT_DATA = 1                  <---- make input data always nonzero (single 0x00 is appended if LC==0) 

[REMOTE]                                           <---- section for configuration relevant for redirection to socket proxy 
REDIRECT = 1                                       <---- enable redirection to socket proxy
IP = 127.0.0.1                                     <---- IP of socket proxy
PORT = 4001                                        <---- port of socket proxy
REMOTE_READER_PREFIX = reader_prefix               <---- if provided, communication with any smartcard inserted into smartcard reader _starting_ with reader_prefix is redirected to socket proxy 
NEW_SOCKET_PER_COMMAND = 1                         <---- if provided and 1, then every command to remote proxy makes and closes a socket connection

[RULE1]                                            <---- first modification rule 
APDUIN = 1                                         <---- if 1, rule is checked and applied for the input APDU (application to card), if 0 then on the response APDU (smartcard to application)
MATCH1=in=1,cla=80,ins=ca,p1=9f,p2=17,data0=90 00  <---- apply rule when input APDU has CLA==0x80, INS==0xca ...
MATCH2=...                                         <---- multiple matching patterns can be specified. If so, apply rule when input APDU has CLA==0x80, INS==0xca ...
ACTION=in=1,cla=80,ins=cb,p1=9f,p2=17,data0=97 00  <---- if match, then change INS to 0xca and data[0] to 0x97 
USAGE = 1                                          <---- if 1, rule is in use. If 0, then rule is ignored  
[RULE2]                                            <---- another modification rule
...