Configure & Authenticate Agent

After installing the Agent, use the signum-util tool to configure the Agent with the connection information and credentials to authenticate a user.

Configuration Options

Use the help command to return information about the tool:

signum-util help

The command returns the following:

signum-util 4.60.3+c1d230508a5da192ecc28dc9e82147902e3c7a2d
Copyright (C) 2025 signum-util
  show, w                 Shows stored info.
  test, t                 Tests the connection to the configured instance.
  logout, l               Closes the session for the current user and deletes stored credentials.
  keychain, k             KeyChain specific actions. (macOS only)
  certificate-store, cs   Windows certificate store actions (Windows only)
  listcertificates, lc    List certificates from the server.
  setup, s                Setup Signum
  signserversetup, dss    Configures the Signum Agent for use with SignServer.
  selection, slc          Configure the list of selected certificates
  service, ser            Signum Service related operations, requires running with elevated permissions.
  help                    Display more information on a specific command.
  version                 Display version information.
Example to setup new config:
        signum-util setup -h [HOSTNAME] -u [USERNAME] -x [PROXY]
        signum-util setup -h [HOSTNAME] -c [CERTIFICATE PATH]
        signum-util setup -h [HOSTNAME] -n [CERTIFICATE NAME]
        signum-util setup -h [HOSTNAME] -t [CERTIFICATE THUMBPRINT]
        signum-util signserversetup -h [SIGNSERVER URL] -c [CERTIFICATE PATH]

As of Signum 4.60.2, the ClientID parameter is no longer required.

The following table describes the returned values:

Command	Flag	Usage
`show`	`w`	Returns the current setup information, including hostname, log level, certificate, and server used.
`test`	`t`	Tests the connection to the configured instance.
`logout`	`l`	Closes the session for the current user and deletes stored credentials.
`keychain`	`k`	Use to add and remove certificates provided by the Signum agent to the macOS keychain. This is required to be able to use keys with native tools like `codesign` and `productsign`. See macOS Keychain Setup. Only available for the macOS Agent. Private keys cannot be exported from the HSM.
`certificate-store`	`cs`	Use to make changes to the Windows certificate store. See Add Certificates to Store. Only available for the Windows Agent.
`listcertificates`	`ls`	Returns a list of certificates that the configured user has access to based on a policy configured in Signum or Worker property in SignServer.
`setup`	`s`	Use for configuring the connection to your Signum server and authenticate your user.
`signserversetup`	`dss`	Use for configuring the connection to SignServer. For more information about using the signum-util with SignServer, see Signum Agents in the SignServer documentation.
`selection`	`slc`	Configure the list of selected certificate.
`service`	`ser`	Use for configuring the Signum Service. The backend value can be edited later to change between working with Signum or SignServer. The service command options require elevated permissions to write to the service configuration file and to restart the service. `-p, --port Set the listening port for the service, default 51599 -t, --logtype Set the log type, accepted values [STDOUT, FILE] -l, --loglevel Set log level. [NONE, LOW, MEDIUM or HIGH] -b, --backend Set the backend to SIGNSERVER or SIGNUM. -r, --restart Restarts the service to apply configuration changes, this will remove all elements from cache. -o, --outputFormat (Default: Text) Output formats [Text, JSON, JSONFormatted]`
`help`	-	Display more information on a specific command.
`version`	-	Display version information.

Configure Authentication

Use the setup command to configure the connection to your Signum server and authenticate your user:

signum-util setup

The command returns the following:

signum-util 4.80.3
Copyright (C) 2026 signum-util
  -n, --certificate_name              Set certificate name
  -t, --certificate_thumbprint        Set certificate thumbprint
  -h, --hostname                      Required. Set agent server address
  -u, --username                      Set username to connect
  -x, --https_proxy                   Setup an http proxy to be used by signum,
                                      this configuration overrides de system
                                      configuration (usually
                                      /etc/systemd/system.conf) if not
                                      specified, blank or unable to connect to
                                      the signum instance through it, the agent
                                      will fall back to the system configuration
                                      (usually /etc/systemd/system.conf).
  -c, --certificate                   Specify the certificate file to use for
                                      certificate-based login.
  -w, --waf_port                      Provide the WAF port configured in the
                                      Administration Console. Required only when
                                      using certificate-based login behind a
                                      WAF.
  -p, --password                      Set the password for the user or
                                      certificate to connect. If not provided,
                                      you will be prompted to input it
                                      interactively.
  -l, --loglevel                      (Default: NONE) Set log level. [NONE, LOW,
                                      MEDIUM or HIGH]
  -s, --configuration_storage_type    Specify where to store the configurations.
                                      Either an encrypted file on the disk
                                      [File] or using the keyring database of
                                      the system [Keyring]
  -o, --outputFormat                  (Default: Text) Output formats [Text,
                                      JSON, JSONFormatted]
  --help                              Display this help screen.
  --version                           Display version information.

Authenticate with User & Password

To authenticate with a certificate, you need the Signum Server URL which can be found in the Signum Links. You also need a p12 file of the certificate used for login, located in a folder accessible with permissions from the terminal, such as /tmp.

Enter your username in the format of username@domain. For example, if your username is testuser and your Local User Domain Alias is testdomain, enter testuser@testdomain.
```
signum-util --hostname a_signum_url --username testuser@testdomain
```
Enter the users credentials when prompted. The credentials can also be passed in with --password argument. Remember to clear shell histories of sensitive credentials or use the interactive prompts.
```
password:
*****************
```
A connection status message is returned.

Authenticate with Certificate

You can authenticate using the certificate name (-n), thumbprint (-t), or .p12 file (-c).

When using client certificate authentication, you must specify WAF port 8443 using the -w flag.

For more information about logging in with certificates and administrative steps, see Set Up Certificate-based Authentication.

Certificate Identification	Command	Description	Supported OS
Name	`signum-util setup -h [HOSTNAME] -n [CERTIFICATE NAME]`	The `CERTIFICATE NAME` refers to the certificate Common Name (CN).	Windows, macOS
Thumbprint	`signum-util setup -h [HOSTNAME] -t [CERTIFICATE THUMBPRINT]`	The `CERTIFICATE THUMBPRINT` refers to the SHA-1 value. Where is the certificate thumbprint? The macOS Keychain displays the certificate SHA1, which may differ from the thumbprint shown in the Administration Console. To retrieve the SHA1 from the Keychain, run: `security find-certificate -c [CERTIFICATE PATH] -Z` The output includes the SHA1 value. Use the SHA1 fingerprint of the certificate, without spaces, for example, `CAB84110F455DB1BCFF2A0F5E7A8E983A907A5F6`, for login.	Windows, macOS
.p12 file	`signum-util setup -h [HOSTNAME] -c [CERTIFICATE PATH]`	The `-c` parameter needs to be an absolute path.	Windows, macOS, Linux

To use a .p12 file, run the following command:

signum-util setup -h signum.mydeployment.us.s.az.keyfactorsaas.com -c example.p12 -p "password" -w 8443

Enter the certificate password when prompted.
```
password:
*****************
```

The command returns the following:

Instance [URL] successfuly reached .
User [mac@keyfactor] successfuly logged in URL.
New configuration saved successfully, some changes to system settings might require restarting SignumService.

List Certificates

With a user logged into the Agent and with a membership to a policy that allows access, running signum-util lc returns the certificates that the user has access to:

signum-util lc

Subject CN     : Signum-RSA-3072
    Issuer CN      : DemoRoot-G2
    Valid Until    : 2029-04-23
    Valid From     : 2024-04-24
    Thumbprint     : 170570A1D56FBB5A4CC780B69ACAEF94010D5DAA
Subject CN     : Signum-RSA-4096
    Issuer CN      : DemoRoot-G2
    Valid Until    : 2029-04-23
    Valid From     : 2024-04-24
    Thumbprint     : 3AB5BFB91DFBB46CF765D5BEE51429618C4857DD
Subject CN     : Signum-RSA-2048
    Issuer CN      : DemoRoot-G2
    Valid Until    : 2030-02-05
    Valid From     : 2025-02-06
    Thumbprint     : F78AE7871FEF1D0CF3EFFB58E9CC85F261438D2B

For a detailed view, run:

signum-util lc -v Detailed

Subject CN     : Signum-RSA-3072
    Issuer CN      : BenDemoRoot-G2
    Valid Until    : 2029-04-23
    Valid From     : 2024-04-24
    Thumbprint     : 170570A1D56FBB5A4CC780B69ACAEF94010D5DAA
    Serial Number  : 6FBEC1D43B272A64763488491D7191335564D92C
    Key Algorithm  : RSA
    Key Size       : 3072 bits
    Signature Algo : sha256RSA
    Capability     : Code Signing (1.3.6.1.5.5.7.3.3)
Subject CN     : Signum-ECDSA-521
    Issuer CN      : ManagementCA
    Valid Until    : 2027-04-07
    Valid From     : 2026-04-07
    Thumbprint     : 36D0CB3C5765FF5D978BBA93228BE1945E77F3F5
    Serial Number  : 460CA3F6C4C90D0A9B9834CFDA6F80969F1025BA
    Key Algorithm  : ECC
    Key Size       : 521 bits
    Signature Algo : sha256RSA
    Capability     : Code Signing (1.3.6.1.5.5.7.3.3)
    SAN Email      : mail@test.com

Add Certificates to System Cryptographic Store

To add certificates to your cryptographic store for use by the Signum Agents:

Windows: Add to User Certificate store or Local Machine store
macOS: Add to Keychain
Linux: Install the certificate directly to your browser. For an example with Firefox, see Import Certificate to Mozilla Firefox.

Windows: Add Certificates to Store

Specify where your Signum login certificates are stored, either in the User Certificate Store or the Local Machine Certificate Store.

Go to the certificate store options:

signum-util cs

The following options are available:

At least one option from group 'certificate-store options' (a, add, c, clear) is required.

-a, --add        Add available certificates to the Windows certificate store(s), bound to the Signum KSP.

-c, --clear      Remove Signum certificates from the Windows certificate store(s).

-t, --target     Target store(s): 'My' (current user) and/or 'LocalMachine' (needs elevation). Repeatable, e.g. -t My -t LocalMachine. Default: My.

0, -outputFormat (Default: Text) Output formats [Text, JSON, JSONFormatted]

-help            Display this help screen.

-version         Display version information.

Example to setup new config:
signum-util setup -h [HOSTNAME] -u [USERNAME] -x [PROXY] 
signum-util setup -h [HOSTNAME] -c [CERTIFICATE PATH] 
signum-util signserversetup -h [SIGNSERVER URL] -c [CERTIFICATE PATH]

The target store, -t, flag places the certificates from Signum in the selected store. You can specify either the User Certificate Store My or the Local Machine Certificate Store LocalMachine.

Using the LocalMachine store requires administrator access.

Example of adding a certificate to the User Certificate Store:

signum-util cs -a -t My

Example of adding a certificate to the Local Machine Store:

signum-util cs -a -t LocalMachine

macOS: Import Certificate to Keychain

Import the login certificate into your macOS keychain to enable certificate authentication:

Open macOS Keychain Access.
Import your certificate.
Ensure the certificate appears under Login>Certificates.
Verify the certificate includes a private key:
- Expand the certificate entry.
- Confirm the private key icon appears below the certificate.
Authorize the Signum agent (SignumService) to access the key:
- Double-click the private key (not the certificate).
- Go to Access Control.
- Add SignumService to the list of authorized applications.
- Click Save. You will be prompted for your macOS admin username and password.
Restart Keychain Access and confirm that SignumService still appears in the Access Control list.

Preselect Certificates

You can designate preferred certificates. Preselecting certificates affects the commands signum-util cs and signum-util keychain, and impacts the certificates available through PKCS#11.

For example, when one or more certificates are marked [PreSelected], signum-util keychain --add adds only those certificates to the keychain. Any certificates without the [PreSelected] designation are skipped.

The preselection also affects what certificates are available though PKCS11.

To configure the [PreSelected] certificates:

By thumbprint:

signum-util selection --add <Thumbprint1>, <Thumbprint2>

By CN:

signum-util selection --add "TestKeyfactor"

By CN using a wildcard, which adds all the certificates containing the wildcard value:

signum-util selection --add "TestKey*"

The certificate is marked as [PreSelected] in the signum-util lc output:

❯ signum-util lc
Subject CN     : RSACert
    Issuer CN      : ManagementCA
    Valid Until    : 2028-05-19
    Valid From     : 2026-05-20
    Thumbprint     : BDF725AAD40FE408612D8A04813D2E707F91CE2F
Subject CN     : TestGPGCert [PreSelected]
    Issuer CN      : ManagementCA
    Valid Until    : 2028-06-02
    Valid From     : 2026-06-03
    Thumbprint     : 6944EC3D2A6AB6DE53775FB7D02CB8C7DC717490

To delete certificates from the [PreSelected] list:

To clear the entire list:

signum-util selection -c

To remove a specific certificate by thumbprint:

signum-util selection -r "BDF725AAD40FE408612D8A04813D2E707F91CE2F"

To remove an specific certificate by CN:

signum-util selection -r TestGPGCert

Log Out

Calling signum-util logout removes the users credentials and configured setup information:

signum-util logout

The command returns the following:

Logout process started.
A total of 1 sessions have been closed for the provided user.
Successfully removed stored credentials.

Additional Information

Test Connection

The Agent connection can be tested with:

signum-util test

Returns a similar connection status message:

Instance [URL] successfuly reached .
Login successfull into the instance [URL] with user [USER].
User [USER] successfuly logged in [URL].
New configuration saved successfully, some changes to system settings might require restarting SignumService.
Please run [signum-util service --restart], [systemctl restart SignumService] or equivalent with appropiate permissions.

Restart

To restart the service, run:

signum-util service --restart
SignumService restarted successfully.

Troubleshooting

If any errors are returned during setup of signum-util or during signing, check the logs for more information about the root cause of the error.

The output logs for signum-util can be found under /tmp.

Some examples of issues that could cause the errors:

Incorrect Certificate URL

The certificate provided needs to be in a location that signum-util has permissions for. If this is the cause of the error, the logs will state that signum-util does not have permission to the provided .p12.

The URL provided during configuration must be only the base URL. Do not include the scheme or the SignServer path.

Incorrect Certificate Type

The chosen certificate for signing must be a signing certificate otherwise the signing fails. The command signum-util listcertificates -v Detailed shows the capabilities attribute:

% signum-util listcertificates -v Detailed
Subject CN     : code00001
    Issuer CN      : DSS Root CA 10
    Valid Until    : 2036-02-27
    Valid From     : 2016-03-03
    Thumbprint     : 0A9861B55542C065E68DBA15AA106C6C02095A2B
    Serial Number  : 0DE0C0DA115F264C
    Key Algorithm  : RSA
    Key Size       : 2048 bits
    Signature Algo : sha256RSA
    Capability     : Client Authentication (1.3.6.1.5.5.7.3.2)
    Capability     : Code Signing (1.3.6.1.5.5.7.3.3)
    Capability     : Email Protection (1.3.6.1.5.5.7.3.4)