Windows Agent
The Signum Windows Agent provides an authenticated user access to signing certificates from the Signum Server and a connected HSM for use with signing tools that support working with Microsoft’s API for Key Storage Providers (KSP) and also the older Microsoft’s older Cryptographic Service Provider (CSP). Some examples would be Signtool, Jarsigner, Nuget Signer, VSIX signer, and more.
Installation Requirements
Microsoft Windows 10 & 11 (64 bits)
Windows Server 2019 and later (64 bits)
Microsoft Visual C++ 14.29.30133 (The installer will prompt and download this automatically unless configured for a silent/quiet
SQL Compact - The installer will prompt and download this automatically where possible unless configured not to.)
.NET 4.8
Administrator privileges during install
Installation
To install the Windows Agent, a.bat file setup with initial configuration parameters needs to be run targeting or in the same directory as the Signum Agent .msi installer. With the basic format being:
configuration_parameter_key="some_value" for example AuthMode="LocalUsers"
Below is an example .bat file that installs a particular version of the Signum Windows Agent .msi in USER mode with an interactive UI configured to use a SAML provider.
msiexec /i kf-agent-x64-4.20.0-499d76fd-MS-WO_Trust.msi ^
RTPRIMARY="Deployment URL" RTSECONDARY="Deployment URL" ^
CLIENTID="The ClientID from the SaaS Portal" ^
AuthMode="SAML2" AGENTMODE="USER" DefaultDomain="somedomain.com" ^
Language="en-US" ^
NO_FIREFOX="1" NO_EDGE="1" NO_CHROME="1" NO_IEXPLORER="1" ^
/l* log.txt ^
echo Exit Code is %errorlevel%
Installation Parameters
Below are the available parameters to pass during installation. Note that some of these parameters are for other use cases with prior versions of Signum.
Most Frequently Used Parameters
Parameter | Optional | Default Value | Description |
---|---|---|---|
PrimaryServer | No | Primary Signum Server URL (without https://) | |
SecondaryServer | No | For Signum, copy the information used in the PrimaryServer argument. This feature is for a legacy model of backup server and will be removed as a required argument from future versions of the agent. | |
ClientID | No | Unique value for the Signum Instance. This can be obtained from Keyfactor during deployment. | |
DefaultDomain | Optional for LocalUsers Required for SAML and OAuth | If connecting users coming from SAML or Oauth domains this needs to be set to the name of the domain. Note: If AgentMode is set to SERVER only LocalUsers is supported. | |
AuthMode | No | The Agent Authentication Mode. What type of Domain will customers be authenticating from. Valid options for Signum are:
| |
ONLY_KSP | Yes | 0 | Optional setting to only use Microsoft’s KSP instead of both the KSP and CSP. This setting can be useful if you want the most performance out of the agent and are not trying to use older applications. To change this needs to be set at install time. |
Language | Yes | Agent’s language. Valid options are:
| |
AGENTMODE | Yes | USER | If the Agent will run in User-Interface mode (i.e. with a GUI) or in Server mode with no user interface. Valid options are:
|
NO_FIREFOX | Yes | 0 | This is a legacy feature that is being deprecated for Signum. For Signum, this value should be set to 1. 0 - Installs the add-on for Firefox 1- Does not install the add-on for Firefox |
NO_CHROME | Yes | 0 | This is a legacy feature that is being deprecated for Signum. For Signum, this value should be set to 1. 0 - Installs the add-on for Chrome 1- Does not install the add-on for Chrome |
NO_IEXPLORER | Yes | 0 | This is a legacy feature that is being deprecated for Signum. For Signum, this value should be set to 1. 0 - Installs the add-on for IExplorer 1- Does not install the add-on for IExplorer |
NO_EDGE | Yes | 0 | This is a legacy feature that is being deprecated for Signum. For Signum, this value should be set to 1. 0 - Installs the add-on for MS Edge 1- Does not install the add-on for MS Edge |
Additional Parameters
Parameter | Optional | Default Value | Description |
Timeout seconds | Yes | 31 | Seconds of timeout after which the agent considers that the server is not available. |
START_DELAYED | Yes | 0 | Specifies the operating mode of the installed service. If set to delayed start, the agent will attempt to be the last process to start on boot. 0 - Automatic start 1- Delayed start |
PIN_EXPIRATION | Yes | 0 | Number of seconds before the user must re-enter a PIN. This only applies to a single Cryptographic session. |
NO_SQLCOMPACT | Yes | 0 | Some signing tools are able to use both KSP and PKCS11 in Windows. SQL Compact needs to be installed to enable this PKCS11 functionality. 0 - Installs the SQL Server Compact 1- Does not install SQL Server Compact |
NO_REDIST | Yes | 0 | 0 - Installs the C++ redistributables 1- Does not install C++ redistributables |
WEBPROXY_URI | Yes | Can be used to optionally configure a proxy. The proxy must be transparent with no authentication in the format of a URL. | |
HIDE_TRAYICON | No | 0 | 0 - Tray Icon is visible 1 - Tray Icon is not visible |
DISABLE_NOTIFICATIONS | No | 0 | 0 - Notifications are shown 1 - No notifications are shown ( if HIDE_TRAYICON is set to 1, then this parameter is also set to 1. |
Optional Additional Registry Settings
These properties cannot be passed at installation but can be set directly in the registry at HKEY_LOCAL_MACHINE\SOFTWARE\Evolium\Redtrust.
Parameter | Optional | Description | Description |
TCP_PORT | Yes | CSP module and RTTrayApp use this port to communicate to the local service. If the default port is unavailable another one can be configured. | Default service is on 51598 |
KSP_WEBAPI_PORT | Yes | KSP module uses this port to communicate to the local service. If the default port is unavailable another one can be configured. | Default service is on 51600 |
Windows Agent in USER mode (With a UI)
With the agent installed in USER mode i.e. with the user interface, there should be a “RTTrayApp” process running which is the Signum Windows Agent. Looking in the System tray, there should be an icon showing the Keyfactor Signum Agent.
Right clicking on the tray Icon will bring up several options.
About
Information about the Agent.
Settings
Note, this option is only present if the AuthMode is LocalUsers. The Settings section allows a user assigned to a LocalUsers Domain an option to update their credentials to the service.
Certificates
The Certificates part of the Agent only shows what certificates are available to the authenticated user based on the policies that have been defined. If multiple certificates are listed, making no selections in this window will make all of those certificates available and is the default behavior. Making a specific selection here will make only the selected certificates available on the machine.
Login
Selecting login on the Agent will bring up a login window where a LocalUser can enter their credentials. The option to remember user credentials is disabled by default, if enabled the user would automatically be logged in after restarting the machine. Logging out of the Agent would again prompt for the credentials. Reach out to Keyfactor about enabling this feature.
A user logging in to a Saml or Oauth Domain after clicking login would be taken to the IDP login page based on the DefaultDomain property configured as part of the Agent Parameter.
Logout
Logging out will terminate the Signum session and requires the user to re-authenticate to connect.
Windows Agent in SERVER Mode (CLI Only)
Additional information about the Agent in Server mode.
Certificates are stored in the machine certificate store instead of the user store.
Credentials are configured using the rtsetup tool
Only LocalUsers is supported as a Domain type for Signum
Using the Setup Tool
With the Agent msi installed (see Installation above), navigate to the installation folder (default location C:\Program Files\KeyFactor) and open the “rtsetup.exe” using command prompt or powershell. The tool will provide information about usage seen below. Running the rtsetup.exe tool with the parameters described will authenticate the LocalUser’s credentials, if the server information was set during the install there is no need to re-enter using the tool.
PS C:\Program Files\KeyFactor> .\rtsetup.exe
Tool to configure the Redtrust Server Agent.
Usage:
rtsetup.exe -authMode=[LocalUsers|Ldap] -username=[username] -password=[password]
or
#Recommended if your password contains special characters:
rtsetup.exe -authMode=[LocalUsers|Ldap] -username=[username]
or
rtsetup.exe -authMode=ActivationCode -code=[activation code]
Optional parameters:
-primaryServer=[IP or hostname]
-secondaryServer=[IP or hostname]
-servicePort=[Port] (default value: 443)
Note: Both need to be set at once. Port is only updated when servers are set.
Login Example
PS C:\Users\Demo> & "C:\Program Files\KeyFactor\rtsetup.exe" -authMode=LocalUsers -username=test@domain
password:
RTService currently has status Running, stopping...
Starting RTService
RTService currently has status Running
RTService restarted.
Logout Example
PS C:\Users\Demo> & "C:\Program Files\KeyFactor\rtsetup.exe" logout
Editing Settings
Once the Agent has been installed many of the parameter settings can be changed by editing the registry at:
Computer\HKEY_LOCAL_MACHINE\SOFTWARE\Evolium\Redtrust
After making changes, restart the System service that is running “RTService”. It may also be necessary to quiet and relaunch the Tray Application, this can be done by ending the “RTTrayApp” process in Task Manager and then relaunching by running the “RTTrayApp” found in C:\Program Files\KeyFactor.
Settings for the KSP and between USER/SERVER modes need to be set at installation time and cannot be updated later to new values.