Service

[Service]
ActionMonitor=Background-Start|!\{TS}||-|*
ActionStart=Background-Start|\{TS}||-|*
:ActiveClient=
ActiveSystem=none|{SANDBOX}||trace,cache,watch|\{LOCAL-PCSC}||trace,cache,pkcs11,watch|\{NO-CSP-SSO}||trace,cache,pkcs11,csp,watch|*
ActiveUser=none|\{SANDBOX}||watch,event,taskbar,token,certificate,netcontrol,ts-register|*
:ChannelMaxTransmit=16384
:ChannelMemoryCount=16
:ChannelName=netid
:ChannelOptions=0x34200000
:CheckLocation=1
:CommunicationDelay=
:CommunicationSecure=
:CommunicationTransmitHeader=
:CommunicationTransmitSize=
:Debug=0
IdleCheck=600
IdleTimeout=3600
:IdleTimeoutApp=
:LockMode=1
MaxContexts=32
:MaxContextsApp=
:MaxTransmitFail=0
:MaxTransmitSize=131072
:MaxTransmitTime=3000
:MutexTimeout=0
PredictableUniqueID=0
:ProtectAlgorithm=none
ProxyConnect=wts name:\{name}
ProxyListen=mem PROXY-\{name}
:RunAsProcess=0
:SharedPrefix=Global\
:WaitRunning=999

ActionMonitor

The ActionMonitor parameter is a list of actions that tells the internal actions that may be monitored. The monitoring automatically restarts processes that are stopped for any reason.

[Service]
ActionMonitor=Background-Start

The only supported monitoring is of the user service, which is the one configured above.

ActionStart

The ActionMonitor always started the requested action automatically. ActionStart is used to start in the same manner as the monitoring but without the monitoring. This is used to start the user service from the setup program to allow to switch from administrator privilege to normal user privilege.

[Service]
ActionStart=Background-Start

ActiveClient, ActiveSystem, ActiveUser

These parameters contain a list of colon-separated names that should run for each respective service (system and user):

#define SRV_TRACE         "trace"
#define SRV_SSO_CACHE     "cache"
#define SRV_SSO_PKCS11    "pkcs11"
#define SRV_SSO_CSP       "csp"
#define SRV_SSO_KSP       "ksp"
#define SRV_SSO_PLUGIN    "plugin"
#define SRV_WATCH         "watch"
#define SRV_TS_VC         "ts-register" (will require normal user)
#define SRV_EVENT         "event"
#define SRV_TOKEN         "token"
#define SRV_CERTIFICATE   "certificate"
#define SRV_SCS           "scs"
#define SRV_NETCONTROL    "netcontrol"
#define SRV_TASKBAR       "taskbar"
#define SRV_CRYPT         "crypt"

The ActiveSystem and ActiveUser tell that they should be started on this computer. But this computer can need to connect somewhere else, so the ActiveClient tells when this computer should connect. The default value for ActiveClient is the combination of ActiveSystem and ActiveUser.

[Service]
:ActiveClient=
ActiveSystem=trace,cache,pkcs11,watch
ActiveUser=watch,event,taskbar,token,certificate,netcontrol,ts-register

The order of names in the list is ignored since each component is started in the required order.

ChannelMemoryCount

The ChannelMemoryCount parameter is used when communicating with the virtual channel/driver. The number of available memory buffers is limited. Thus, this parameter should correspond to the value suggested in the documentation of the virtual channel/driver from Microsoft/Citrix.

[Service]
ChannelMemoryCount=16

ChannelName

The ChannelName parameter is used when communicating with the virtual channel/driver. The name is used to identify the Net iD Client’s channel and must be the same on both the Terminal Server system and the connecting computer.

[Service]
ChannelName=netid

ChannelOptions

The ChannelOptions parameter is used when communicating with the virtual channel/driver. The value is a bitmask with the following options:

#define CHANNEL_OPTION_INITIALIZED            0x80000000
#define CHANNEL_OPTION_ENCRYPT_RDP            0x40000000
#define CHANNEL_OPTION_ENCRYPT_SC             0x20000000
#define CHANNEL_OPTION_ENCRYPT_CS             0x10000000
#define CHANNEL_OPTION_PRI_HIGH               0x08000000
#define CHANNEL_OPTION_PRI_MED                0x04000000
#define CHANNEL_OPTION_PRI_LOW                0x02000000
#define CHANNEL_OPTION_COMPRESS_RDP           0x00800000
#define CHANNEL_OPTION_COMPRESS               0x00400000
#define CHANNEL_OPTION_SHOW_PROTOCOL          0x00200000

See the documentation of virtual channel/driver from Microsoft/Citrix for meaning and usage. Search in the respective developer forum for more information.

[Service]
ChannelOptions=0x34200000

CheckLocation

This parameter can be used to turn off the location checking. Do not use.

The CheckLocation parameter is used to validate the calling application. Only trusted locations are allowed when location check is active.

Trusted locations

Trusted locations depend on the platform.

Windows

  • %ProgramFiles%, that is C:\Program Files\

  • %WinDir%, that is C:\Windows\

Linux or macOS

  • /usr/bin/

  • /usr/lib/

  • /usr/local/bin/

  • /usr/local/lib/

[Service]
CheckLocation=1

All service calls are blocked if the location is considered untrusted. That is, single sign-on not available.

CommunicationDelay

The CommunicationDelay parameter is used by the developer to simulate communication delay and should never be used. The format is <protocol>:<delay> … <protocol><delay>. The delay value is a DWORD. The lower WORD tells the number of milliseconds that the process sleeps before starting a data transmit. The upper WORD tells the number of milliseconds that the process sleeps before processing the data.

[Service]
CommunicationDelay=net:0x00640064 ica:0x00640064

CommunicationSecure

This parameter is only used for debugging.

The CommunicationSecure parameter is used to send additional options for setting up SSL/TLS protocol:

  • protocol version

  • cipher suite

  • key exchange parameters

  • signature algorithm.

Values

The default value is any any any any. That is, use anything that is implemented.

Current implementation support

  • Protocol version: 1.2

  • Cipher suite:

    • rsa-aes128cbc-sha1

    • rsa-aes256cbc-sha1

    • rsa-aes128cbc-sha256

    • rsa-aes256cbc-sha256

    • ecdhe-rsa-aes128cbc-sha1

    • ecdhe-rsa-aes256cbc-sha1

  • Key exchange:

    • secp256r1

    • secp384r1

    • secp521r1

  • Signature:

    • rsa-sha1

    • rsa-sha256

    • rsa-sha384

    • rsa-sha512

[Service]
CommunicationSecure=1.2 rsa-aes128cbc-sha256,rsa-aes256cbc-sha256 secp256r1 rsa-sha256

CommunicationTransmitHeader

This parameter is only used for debugging.

The CommunicationTransmitHeader parameter tells the number of bytes needed for the protocol header. This value should never be updated but is included to handle possible future changes in protocols. The format is <protocol>:<size> … <protocol><size>.

[Service]
CommunicationTransmitHeader=mem:4 net:4 ica:8

CommunicationTransmitSize

This parameter is only used for debugging.

The CommunicationTransmitSize parameter tells the maximum number of bytes that can be transmitted for each protocol. The value must be between 1 kB and 128 MB, but is specified in bytes. Default value is 128 kB. The format is <protocol>:<size> … <protocol><size>.

[Service]
CommunicationTransmitSize=mem:131072 net:16383

Values

The value must be between 1 kB and 128 MB and is specified in bytes. Default value is 128 kB.

The format is <protocol>:<size> … <protocol><size>.

Debug

The Debug parameter enables the recording of more information to the trace. This information includes the actual data sent in the communication channel. Thus, it can be sensitive, and therefore a development license is required to enable this parameter.

[Service]
Debug=0

IdleCheck, IdleTimeout, IdleTimeoutApp

The listening service is running in a non-connected mode when used with the virtual channel or driver. Thus, the service may not discover that the connecting part is closed if disconnected without a proper close message. These parameters include an idle checking mechanism to detect when a connecting part is gone.

The normal conditions do not work since the application reading the configuration is the system service, and the parameter is specified for the connecting application. The application name is sent when setting up the communication.
[Service]
IdleCheck=600
IdleTimeout=3600
IdleTimeoutApp=60,netid.exe;180,iexplore.exe;30,*

LockMode

The communication must run without interference from other processes. Because some of the communication protocols are non-connected, it is necessary that only one part is communicating at the same time. The lock mode tells how the service locks the communication from other parties:

#define SERIALIZE_LOCK_THREAD 0x01
#define SERIALIZE_LOCK_PROCESS 0x02
#define SERIALIZE_LOCK_GLOBAL 0x03
#define SERIALIZE_LOCK_TYPE 0x04

[Service]
LockMode=1

MaxContexts, MaxContextsApp

The total amount of simultaneous connections is limited. Thus, it must be controlled what is allowed for each connection.

The normal conditions do not work since the application reading the configuration is the system service, and the parameter is specified for the connecting application. The application name is sent when setting up the communication.
[Service]
MaxContexts=32
MaxContextsApp=3,netid.exe;10,*

MaxTransmitFail

The MaxTransmitFail parameter resets the communication channel when the data transmission fails. The default value is 0, no resetting.

[Service]
MaxTransmitFail=0

MaxTransmitSize

The maximum data transmit buffer tells the maximum number of bytes that can be sent in the communication channel.

[Service]
MaxTransmitSize=131072

MaxTransmitTime

The MaxTransmitTime parameter is the maximum number of milliseconds that a transmit can take. But this is not entirely true. The initial connect may only take milliseconds, and some actions will get milliseconds. Usually, operations that result in smart card updates. Smart card key generation gets more time, so this parameter should be considered to be the maximum time for a normal operation.

Example 1. MaxTransmitTime effects

If you set MaxTransmitTime to 3000 (3 seconds):

[Service]
MaxTransmitTime=3000
  • normal operations can take a maximum time of 3 seconds, MaxTransmitTime=3000.

  • the first call can only take 300 ms, .

  • smart card updates can take up to 30 seconds, .

  • key generation is allowed to take up to 900 seconds.

MutexTimeout

The MutexTimeout parameter adds a timeout to the communication lock. Normally this is never needed. But it can be useful while diagnosing some failures. The value tells the number of milliseconds.

[Service]
MutexTimeout=0

PredictableUniqueID

ProtectAlgorithm

The ProtectAlgorithm parameter is the algorithm used when adding encryption to the communication channel. Default is no protection at all.

The remote communication using virtual channel/driver relies on the established protection used in each channel. Thus, no encryption is needed.

The shared memory protocol is only used at the local computer. Thus, no encryption is needed.

The network protocol, when used with localhost, does not require protection since the communication never leaves the computer. The network protocol, when used remotely, requires protection. Using network protocol remotely is not recommended at this time because there is a potential man-in-the-middle attack.

[Service]
ProtectAlgorithm=1.2.840.10045.3.1.7,2.16.840.1.101.3.4.1.2
ProtectAlgorithm=secp256r1,aes-128-cbc

ProxyConnect, ProxyListen

The virtual channel/driver communication requires a single communication channel. A proxy synchronizes all communication.

[Service]
ProxyConnect=wts name:{name}
ProxyListen=mem PROXY-{name}

RunAsProcess

The RunAsProcess parameter allows the system service to run as a process instead of service.

[Service]
RunAsProcess=0

SharedPrefix

Communicating with shared memory requires a special naming convention. See Windows documentation for more information.

[Service]
SharedPrefix=Global\

WaitRunning

The WaitRunning parameter tells the number of milliseconds a process must wait for the system/user service to run when not responding.

[Service]
WaitRunning=999