A newer version of this documentation is available.

View Latest

Watch

The Watch component is an executable which will do actions either when smart card is inserted or removed.

Arguments

The following arguments are available:

  • -w

  • -match <criteria>

  • -wait "<insert>|<remove>"

  • -message "<insert>"|"<remove>"

  • -hide insert|remove

  • -sync

  • -logon

  • -term

  • -recognized

  • config | <insert command>

The argument order is important for historical reasons. Last in the argument list is either the static value config or one single insert command. The value config will activate the Watch Insert and Watch Remove configuration sections in configuration which allow several different commands.

Watch configurations are only read from global configuration, not from local configuration file, due to security reasons.

-w

Argument -w is used to wait with the execution of the command until a smart card is loaded, meaning all certificates are read. This value only has meaning for insert commands.

-match

Argument -match is used to select a specific certificate which should be used when generating an event. The match criteria consist of an issuer field and an optional key usage.

Example 1. -match with issuer field and optional key usage
-match "2.5.4.3=SecMaker CA v2|A0"
This argument is only available when used with <insert command> as last argument not with config.

-wait

Argument -wait is used to specify the number of seconds to wait for a command to finish, may use separate values for insert and remove.

Example 2. -wait with values for insert and remove.
-wait "60|30"

-message

Argument -message is used to specify a message to be shown when command is executed, may use different messages for insert and remove.

Example 3. -message with values for insert and remove.
-message "Card inserted"|"Card removed"

-hide

Argument -hide is used to specify that the command should be executed hidden, may separate with different messages for insert and remove.

Example 4. -hide.

-hide

-hide insert

-hide remove

-sync

Argument -sync is used by remove event. When specified remove events will not be generated until after a smart card is inserted.

-logon

Argument -logon is used only to generate a remove event for the currently logged on user.

-term

Argument -term is used by remove event. Will require the process started at insert event to be terminated, currently only a single process may be terminated.

-recognized

Argument -recognized is used to require that the smart card is recognized, unknown cards will not generate any events.

Commands

The configuration sections [Watch Insert] and [Watch Remove] will specify a list of commands executed when a smart card is inserted or removed.

The following commands are available for execution when a smart card is inserted or removed:

  • application <binary> <argument>

  • close <window name>

  • extern <library>,<argument>

  • kill <application>

  • load <library>,<argument>

  • open <file>

  • set –config <file>

  • set –registry <key>

All commands in the list may be prefixed with "parallel" to only start the execution, it will immediately continue with the next command and ignore the result. Not in parallel will require successful execution before it continues with the next command, on failure no more commands will be executed.

application

Command "application" is used to start any application <binary> with any argument <argument>.

$ application c:\windows\notepad.exe c:\iid.txt

Successful execution will always require the process to start, but may also depend on "-wait" argument if present.

close

Command "close" is used to close a Microsoft Windows application. Specify the <windows name> that should be closed.

$ close "iid - Notepad"

The execution will always be considered as successful.

extern

Command "extern" may be used for insert command to read user information from an external library. The smart card is not supported internally, but instead the reader name is sent with the specified command arguments. The library must export a function with the following syntax:

int CALLBACK
ReadCommand(
    const char* pszReader,
    const char* pszCmd,
    char* pszData,
    unsigned long nData)

Return non-zero for success and the data buffer should return username and domain information, separated with ‘;’.

$ extern c:\iid.dll,-iclassid –config c:\iid.txt

After a successful command execution the set command below will be executed with the collected user information.

This execution will be considered as successful if the user information is collected successfully.

kill

Command "kill" is used to terminate or kill an application. Will search for a process with the specified binary and try to kill that process.

$ kill c:\windows\notepad.exe

This execution will always be considered as successful.

load

Command "load" will load a library and call the specified function. The function syntax must follow the parameter syntax used by rundll32.exe:

$ load c:\iid.dll,EntryAdmin -argument

This execution will be considered to be successful if the function is found in the specified library, but will have no requirements for the function to return value.

open

Command "open" may be used on Windows platform to open a file type defined in Registry.

$ open c:\temp\iid.txt

This execution will always be considered as successful.

set

Command "set" either specifies a configuration file or a Registry key which will be updated with user information found on the inserted smart card. Argument "-match" may be used to specify search criteria for the user information.

$ set –config c:\temp\iid.txt
$ set –registry HKLM\Software\SecMaker\Info

This execution will be considered to be successful if user information found.

script

A command "script" may be used on Windows platforms in the same manner as "open", the difference is that it will be executed hidden.

$ script c:\temp\iid.vb

This execution will be considered to always be successful.