This document explains how to configure logging for PCSClite
both server-side and client-side.  Specifically this document
covers:

  1. Client-side logging:

     A. libpcscshim.so.1 (to collect 'shim logs')
     B. uttsc-shim (to use libpcscshim with Sun Ray Windows Connector)

  2. Server-side logging:

     A. pcscd instance logging
     B. IFD handler logging
     C. pcscd launcher logging
 
PC/SC CLIENT-SIDE DEBUGGING (libpcsclite.so.1):

---------------------------------------------------------------------------
DESCRIPTION OF WHAT A SHIM LOG IS (E.G. WHAT libpcscshim.so does)
---------------------------------------------------------------------------

libpcscshim is a library that interposes itself (e.g. sits between)
a client application and the PC/SC API provider, libpcsclite.so.1
This interception of the client/library traffic occurs at runtime,
based on the setting of key environment variables directing the OS
to find libpcscshim.so.1 and to indicate to libpcscshim.so.1 which
options to use.

This is the layout of the shim logging interposing scenario:

        +---------------------+
        | Client Application  |
        +----------+----------+
                   |
         - - - - - + - - - - -
         | libpcscshim.so.1  |  <-- 'interposed' via LD_PRELOAD
         - - - - - + - - - - - 
                   |
         +---------+----------+
         | libpcsclite.so.1   |  PCSClite API implementation
         +--------------------+

When a client application invokes PCSCLite API functions
which all becin with the SCard prefix, each call is logged by 
libpcschim to a file specified to libpcscshim at startup via
an environment variable.

In the log file, each entry logs a function call, and the direction
of the transaction is indicate with an arrow, as follows:

    ->  : Prefixes calls made from client to the library.
    <-  : Prefixes return from library function to the client

Input-only and input/output parameters are formatted and logged
during the first phase, i.e., when the client invokes the function
implemented in libpcsclite.so.1 (a call which is intercepted
by libpcscshim.so.1).

Output-only parameters are not logged in the first phase, but rather,
they are deferred until the return phase logging.

In 2nd phase, i.e. returning from the function, the input-only parameters 
are omitted, to prevent redundancy.

To make it easier to read the shim log file:
 
1.   String pointers are not displayed as hexadecimal numbers,
     but as the dereferenced character data itself.

2.   Binary data pointers are displayed as hex dumps of the 
     dereferenced data.

3.   Named constants and named bitmask values are displayed 
     as the constants that define the parameter values rather
     than the meaningless numeric form.

-------------------------------------------------------
HOW TO CONFIGURE libpcscshim.so.1 INTERPOSER LIBRARY:
--------------------------------------------------------

There are two basic interposing scenarios:

   1.  Collecting shim logs for Sun Ray Window Connector
   2.  Collecting shim logs for most other applications.

This section will explain how to configure libpcscshim
to work in both modes, however for collecting shim logs
with Sun Ray Windows Connector, the uttsc-shim package simplies
things substantially for the administrator and is the preferred
approach.

The main difference between interposing on Sun Ray Windows Connector 
and interposing on other clients is that with SRWC (the connector),
the products use of the setgid bit complicates the use of LD_PRELOAD.
Fortunately, Sun Ray Windows connector's uttsc command provides
another mechanism for interposing, via a different environment variable,
to bypass complications with setgid and the OS.

	---------------------------------------------------
	    Normal (I.E. Non-SRWC) Interposing instructions
	---------------------------------------------------

	fFf libpcscshim is in the current directory you run your
	application from and you're using a bash-like shell,
	you an set the LD_PRELOAD environment variable as follows,
	to tell the Solaris dynamic linker to load libpcscshim.so.1
	in front of libpcsclite.so.1, so that any calls that would
	normally be passed directly to libpcsclite.so.1 will
	reach libpcscshim first:

	$ LD_PRELOAD=$PWD/libpcscshim.so.1

	(LD_PRELOAD should only be set for the duration of the run of the
	target application, as it might interfere with other UNIX commands
	issued beyond that).  The shim requires some arguments to be 
	passed through a seperate environment variable: "LIBPCSCSHIM". 

	Required arguments are:

		-l   Required. Switches on API transaction logging feature
		-i   Specifies path of target library to interpose on
		-o   <filename>   Specifies file to log shim data to
                                  (that is, where to log transactions)

	Example (configuring shim log creation bash shell):

        $ export LIBPCSCSHIM="-l -i /usr/lib/libpcsclite.so.1 -o /tmp/shim.log"
        $ LD_PRELOAD=$PWD/libpcscshim.so.1  ./my_pcsclite_app

	   (NOTE: If libpcscshim is not in your current directory, replace 
		  $PWD with the full path of libpcscshim.so.1)


	---------------------------------------------
	  Sun Ray Connector Interposing Instructions
	---------------------------------------------

	Because Sun Ray Connector uses setgid and has other security
	measures (to support Trusted Extensions), LD_PRELOAD cannot
	be used. Instead, a special hook or backdoor is provided by 
	uttsc to specify the library to call in place of libpcsclite.
	That environment variable is named SUN_LIB_PCSCLITE, and is
	used as follows:.


        $ export LIBPCSCSHIM="-l -i /usr/lib/libpcsclite.so.1 -o /tmp/shim.log"
        $ export SUN_LIB_PCSCLITE=$PWD/libpcscshim.so.1  

	   (NOTE: If libpcscshim is not in your current directory, replace 
	          $PWD with the full path of libpcscshim.so.1)


Once the environment variables are set up for libpcscshim as described
above, when the application is launched the logging will occur 
automatically, as long as the libpcsclite client-application is launched
from the process or shell where the environment variabls are set.

----------------------------------------------------------------------------
USING THE UTTSC-SHIM PACKAGE
----------------------------------------------------------------------------

	The uttsc-shim package, is also in the pcsctools suite.
	It layers over libpcscshim and provides a functional configuration
	the momement the uttsc-package is installed. 

	It sets up where to put the shim logs, and has a default mode
	which can be overridden by the administrator indicating
	the desired log file path to where the logs should go.
	That is configured in:

	/etc/smartcard/pcscd-SunRay.conf
	
PCSClite SERVER-SIDE DEBUGGING
----------------------------------------------------------------------------

The pcscd daemon provided by the SUNWpcsc package runs in two modes.  In one 
mode, pcscd behaves as a launcher daemon (a daemon that spawns worker daemons
known  pcscd instances).  The same pcscd binary is used in both launcher and
instance mode: /usr/lib/smartcard/pcscd

The pcscd launcher is managed by the Solaris SMF framework, and end users
never launch it from the command line.  Attempting to do so would be
inconvenient at best. SMF plugin scripts configure pcscd automatically,
and the launcher becomes active as soon a the SUNWpcsc package is installed..

The launcher in turn starts up pcscd instances on an on-demand basis,
whenever a client of libpcsclite calls SCardEstablishContext(), and
no no pcscd is already running to handle the associated Sun Ray session.

Instance logging is usually of more interest than launcher logging, 
and IFD handler logging is usually of more interest than instance logging.
IFD handlers are the smart card reader drivers managed by pcscd instances.

Launcher problems are rare, and instance logs don't provide much information
besides summaries of the RPC-like transactions working through the pcscd
instance.  Little useful detail is provided in an instance log, but
some is.

The mode pcscd has been started in (i.e. launcher mode or instance mode)
can be determined by studying ps -ef output.

If the -L flag is present, as in  'pcscd -L ...', then that is the 
single pcscd launcher on the Solaris system.
  
Instances launched by the launcher appear as 'pcscd -I -x <dpy#>'
The argument after the -x flag identifies the $DISPLAY number
the instance serves (i.e. the Sun Ray session, and the respective
DTU's smart card reader).

   -------------------------------------
    CONFIGURING pcscd INSTANCE DEBUGGING
   -------------------------------------

     Bugs that involve smartcard transactions that occur in a pcscd instance
     are initially diagnosed using tools like pstack and core dumps,
     as well as by enabling instance debugging, which is not enabled
     by default.  

     To enable debug logging for the instance:

     1.  Edit /etc/smartcard/pcscd-SunRay.conf 

     2.  Uncomment the commented lines,

		LOG_FILE
		LOG_LEVEL
		LOG_TYPE

     By default the log fill will be put in a file called /tmp/instance.log

     Any absolute path can be specified , but if the leading '/' is ommitted,
     the file will be created as a subdirectory of /tmp/SUNWut/pcsc/<dpy#>
     where <dpy#> is the number before the ":" in the $DISPLAY variable.
   
     The log file is only created only after the instance is re-launched.
     If a pcscd -I instance is already running for the display, terminate
     kill -9 (and the corresponding utaction script can be terminated 
     by the user with kill -9 too).  The next time the client application
     is started, causing the pcscd launcher to start an instance,
     the instance log file will be created.


    --------------------------------
    CONFIGURING LAUNCHER DEBUGGING
    --------------------------------

     The launcher is generally not a debugging target, but it can
     be set up to provide log data.

     $ svcadm disable pcscd   # Tell SMF to stop pcscd and not restart it
     $ sleep 1                # necessary only if running these cmds in a script
     $ rm -rf /tmp/SUNWut/pcscd/* /var/run/pcscd/*
     $ sh /lib/svc/method/pcscd-svc debug

    The output will log directly to the window where these steps
    have been taken, and the output can be captured with cut and paste,
    or the tee command can be used or other mechanisms for capturing
    the data.

    It is not advised to collect launcher debuggging output unless 
    requested by support, or you have a good reason to believe
    the problem experienced is directly related to launching
    or instances failing to start, etc...

-------------------
IFD Handler Logging
-------------------

IFD handler logging can be very helpful for diagnosing various 
PCSClite-related smartcard stack issues, as it is conveniently 
positioned at a nexus between 

	1. pcscd instance
	2. Sun Ray Device Manager
	3. Sun Ray DTU firmware (RDD, scbus driver)
	
The IFD handler can log the following kinds of data in a clear
timestamped clearly formatted way (this pertains to the new
IFD handler delivere with SRSS 4.2, and not prior):

	1. APDU logging
	   A. Showing APDU data as hexdumps
	   B. Displaying decoded APDU data

	2. DM scbus event logging.

        3. RDD scbus transaction logging.

        4. PCSClite/IFD handler interface logging

        5. IFD handler internal event logging

The ifd handler, delivered in the binary /opt/SUNWuts/lib/ifdh_scbus.so.1
has its logging configured via environment variables.  These environment
variables are generally set via the pcscd instance when it loads
the configuration file /etc/smartcard/pcscd-SunRay.conf.

By default IFD handler logging is disabled because the parameters
that define the related environment variables are commented out
by default in /etc/smartcard/pcscd-SunRay.conf.

To enable the most simple kinds of IFD handler logging, uncomment
the following lines in /etc/smartcard/pcscd-SunRay.conf:

   $IFDH_SCBUS_DEBUG_LOGFILE =  /tmp/ifdlog
   $IFDH_SCBUS_DEBUG_LEVEL = BINARY

The next time the pcscd instance is started the log file will be
created and stored in /tmp/ifdlog, overwriting any previous file
there.   

The BINARY level of debugging will display all of the log types
shown above in great detail, except IFD handler internal event
logging, which should be unnecessary except when trying to 
diagnose subtle behaviors in the IFD handler itself not directly
related to the smart card interaction.  It is a catch all mode,
a bit verbose.

Other modes that can be specified are via additional parameters:
(Note: These flags are provided via the libutdlog service):

   $IFDH_SCBUS_DEBUG_LEVEL = FATAL
                             ERROR
                             WARN
                             INFO
                             VERBOSE
                             BINARY
                             POLLING

  $IFDH_SCBUS_DEBUG_FLAGS = FILEINFO
                            NOINDENT
                            NOWRAP
                            ABSTIME
                            NOWHERE
                            EVENT

The debug level flags are self explanatory.  Errors are not
logged until they reach the severity level indicated.  The
only level more verbose than BINARY is polling, which
logs cyclic activity inside the ifd handler, and should only
be required in extreme debugging, if ever.

The debug flags control the output as follow:

	FILEINFO:   Add filename and line #'s to prefix for every entry
                    to indicate from where it was logged	

	NOINDENT:   Don't indent multi-line text as a visual 
                    assist.

        NOWRAP:     Don't wrap lines at 80 characters

        ABSTIME:    Log timestamps as absolute time rather
                    than relative time since program start

        NOWHERE:    Don't display function name from where 
                    entry was logged (by default function name is shown).

