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 following table describes the returned values:

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

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:

security find-certificate -c [CERTIFICATE PATH] -Z

Authenticate with User & Password

Set up a new configuration using the username:

signum-util setup -h [HOSTNAME] -u [USERNAME]

1. Provide the URL of your Signum instance as [HOSTNAME] and 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 signum.mydeployment.us.s.az.keyfactorsaas.com --username testuser@testdomain
   

2. 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:
*****************

3. A connection status message is returned.

Authenticate with Certificate

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

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.

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

signum-util setup -h [HOSTNAME] -n [CERTIFICATE NAME] -w 8443

signum-util setup -h [HOSTNAME] -t [CERTIFICATE THUMBPRINT] -w 8443

signum-util setup -h [HOSTNAME] -c [CERTIFICATE PATH] -w 8443

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

2. Enter the certificate password when prompted:

   password:
   *****************
   

3. 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 listcertificates returns the certificates that the user has access to:

signum-util listcertificates

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 listcertificates -v Detailed

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

To store your Signum login certificates, you need to specify either the User Certificate Store or the Local Machine Certificate Store.

Go to the certificate store options:

signum-util certificate-store

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.

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.

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:

1. Open macOS Keychain Access.

2. Import your certificate.

3. Ensure the certificate appears under Login > Certificates.

4. Verify the certificate includes a private key:

   • Expand the certificate entry.

   • Confirm the private key icon appears below the certificate.

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

6. 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 PKCS#11.

To configure the [PreSelected] certificates:

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

signum-util selection --add "TestKeyfactor"

signum-util selection --add "TestKey*"

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

❯ signum-util listcertificates
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:

signum-util selection -c

signum-util selection -r "BDF725AAD40FE408612D8A04813D2E707F91CE2F"

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.

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.

TLS Validation Modes

When the Signum Agent connects to its backend over HTTPS, it validates the server’s TLS certificate. You can opt in to the tlsvalidationmode setting, which chooses how the trust anchor (the CA) is established. The certificate's hostname must match the configured server, and the chain must be cryptographically valid and within its validity dates.

The TLS validation mode only changes which CA is trusted and which engine builds the chain, never whether the server's identity is checked. This is useful for private/internal CAs, or on macOS where Apple applies stricter rules.

Why Default Validation Can Fail

1. Private CA not in the OS trust store: A cert issued by your own CA that is not installed or trusted at the machine level.

2. macOS SSL-policy rules (macOS only): macOS validates via Apple's SecTrust TLS policy, which adds requirements beyond standard validation. A certificate can fail on macOS due to Certificate Transparency (missing SCTs), the 398-day max lifetime, the serverAuth EKU requirement, revocation (OCSP/CRL), or weak algorithms and keys.

Description of Modes

Choosing the Mode

See the following decision tree to help you choose your mode:

Backend rejected by default (System)?
├─ No ─────────────────────────────────────────────► keep System
└─ Yes
   ├─ Private CA you CAN install in the OS store ───► install CA, keep System
   └─ Private CA you can't/won't install, OR a
      macOS SSL-policy rejection (CT, 398-day,
      serverAuth EKU) on an otherwise-valid cert ──► PinnedCa, pointing -c
                                                       at that CA's cert

Configure

With the signum-util service command, change the mode and use the -r flag to restart to apply.

To use the default with full OS trust:

sudo signum-util service -m System -r

To trust only the provided CA bundle (root + intermediate):

sudo signum-util service -m PinnedCa -c /etc/keyfactor/backend-ca-bundle.pem -r

Verify

signum-util test

Success prints a connection confirmation. On failure, the Agent prints the reason and writes the full presented certificate chain to the SignumService log. Report issues to Keyfactor support with the SignumService log attached.

Reverting

sudo signum-util service -m System -r

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 and SignumService have 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)

Wrong WAF Port

The following error indicates that no TLS handshake took place, so this is a network/port issue rather than a certificate problem.

Unable to reach [mtls01.trustear.io] on waf_port [8444]: the connection was refused or timed out.

To resolve, check that waf_port [8444] is the correct listener port for [mtls01.trustear.io] and that it is reachable from this host.

Changes to system settings might require restarting SignumService:

signum-util service --restart

systemctl --user restart SignumService

Wrong Password

The following error appears when the wrong password is used:

The login certificate at [test.p12] could not be loaded: The certificate data cannot be read with the provided password, the password may be incorrect..

Invalid Certificate Name or Thumbprint

Could not find the configured certificate [randomCert] in this process's certificate store/keychain. This is expected if it is scoped to SignumService only; run [signum-util test] after restarting the service to confirm access.
Unable to authenticate to [mtls01.trustear.io] with the login certificate [randomCert].
[mtls01.trustear.io] is reachable and its own certificate was accepted, so the problem is the certificate this agent presents.

To resolve, check that the certificate exists, that its private key is accessible, that it has not expired, and that this host can build its issuing chain. The certificate that was used is logged in the SignumService log.

After restarting the service, run the following to confirm access:

signum-util test