Skip to main content
Skip table of contents

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:

CODE
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.

CODE
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:

  • LocalUsers

  • SAML2

  • OAuth2

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:

  • en-US (english)

  • en-ES (spanish)

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:

  • USER

  • SERVER

NO_FIREFOX 

Yes 

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 

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 

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 

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 

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 

Number of seconds before the user must re-enter a PIN. This only applies to a single Cryptographic session.

NO_SQLCOMPACT 

Yes 

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 - 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.

CODE
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

CODE
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

CODE
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:

CODE
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.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.