macOS Agent

The Signum macOS Agent can be installed on macOS machines to provide users with access to remote keys from Signum that can be used with Apple’s native code signing tools.

This agent also supports working with SignServer 7.4 and later. For more information about configuring this agent with SignServer, see SignServer macOS Agent documentation.

Installation Requirements

macOS Sonoma 14.0 or later.
Supports ARM architecture.
Signum user needs to be a member of a policy configured to support macOS signatures. For more information on policy configuration, see Policies.

For signing macOS and iOS type binaries, Apple uses developer.apple.com to manage certificates. Specific types of certificates need to be used depending on the type of file that is being signed. For more information, consult the Apple documentation.

Install the Agent

On the Keyfactor Customer Portal, navigate to your Signum deployment and select Signum Links > Signum Agents.

Download the .pkg package.
Click on the package to install.
Follow the installer guide to complete the macOS Agent installation.

After completing the installation, three new tools are available:

SignumUtil
SignumService
SignumAgent App

The Signum macOS Agent is set up and configured using the signum-util tool. The tool is added to /usr/local/bin/signum-util by the installer and added to the users path.

Signum Agent App only displays version information about the Agent. In a future release, this App will also provide an GUI option for configuring the Agent.

Set up the Agent

The signum-util tool supports authenticating a user to either a Signum or SignServer backend to be able to sign binaries using keys remotely stored in Signum or SignServer.

Run the following command to return information about the tool:

CODE

signum-util help

The command returns the following:

CODE

signum-util 4.60.1+1ec280d8928cea3e631cf935eacde6b97b890895
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.

  listcertificates, lc    List certificates from the server.

  setup, s                Setup Signum

  signserversetup, dss    Configures the Signum Agent for use with SignServer.

  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 signserversetup -c [CERTIFICATE PATH] -u [SIGNSERVER URL]

Command	Usage
show	Returns the current setup information if present including the server being used.
test	Tests the connection to the configured instance.
logout	Closes the session for the current user and deletes stored credentials.
keychain	This command is used 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`. Private keys cannot be exported from the HSM.
listcertificates	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	Use this command to configure the connection to your Signum server and authenticate your user.
signserversetup	Use this command to configure the connection to SignServer. For more information about using the signum-util with SignServer, see SignServer documentation.
service	Use for configuring the Signum Service. The backend value can be edited later if needed 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. CODE `-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]`

Authentication

The signum-util tool supports different authentication options based on the backend.

Authentication Option	Backend
Local Users	Signum
Certificate	SignServer

You are prompted to enter credentials after running the setup or, if required, can pass with ‘-p’.

CODE

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

The command returns the following:

CODE

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

Log Out

To log out, run the following command:

CODE

signum-util logout

The command returns the following:

CODE

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

List Certificates

Run the following command to list certificates:

CODE

signum-util listcertificates

CODE

Subject CN     : Signum-RSA-4096
    Issuer CN      : BenDemoRoot-G2
    Valid Until    : 2029-04-22
    Valid From     : 2024-04-23
    Thumbprint     : 3AB5BFB91DFBB46CF765D5BEE51429618C4857DD

Keychain

Adding to Keychain

The signum-util keychain --add command adds all certificates to the keychain:

CODE

signum-util keychain --add

CODE

Certificate with alias [Signum-RSA-4096] and ID [21] was added successfully to the KeyChain

After adding to the keychain, the certificate(s) should be listed:

CODE

sc_auth identities

CODE

SmartCard: com.keyfactor.signum.token:21
Unpaired identities:
C08811A3E3E1CA52F4629433E700FA44B42EA701	Signum-RSA-4096

Removing from Keychain

To remove certificates from the keychain, run the following command:

CODE

signum-util keychain --clear

CODE

Signum certificates where successfully removed from the KeyChain

After removing from the keychain, the certificate(s) will be removed and will not be available to the keychain.

Logging

Logs for the agent can be found in /tmp.

CODE

ls /tmp/*[Ss]ignum*

Logs for the UI and token driver-specific can be found in ~/Library/Group Containers/group.com.keyfactor.signum.shared.

The log for the UI interface: keyfactoragent.log
The log for the token being invoked by the applications using the keychain's certificates: keyfactoragenttoken.log

Signing Example using Signum Backend

The following example shows how to configure the Agent with a key in Signum. To see an example of connecting the Agent to SignServer, see SignServer macOS Agent documentation.

Run the following command to configure and connect to the Signum Server:

CODE

signum-util setup -h URL -c 12345= -u mac@keyfactore

CODE

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

Run the signum-util lc command to list certificates:

CODE

Subject CN     : Signum-RSA-4096
    Issuer CN      : BenDemoRoot-G2
    Valid Until    : 2029-04-22
    Valid From     : 2024-04-23
    Thumbprint     : 3AB5BFB91DFBB46CF765D5BEE51429618C4857DD

Run signum-util keychain --add command to add the certificate to the keychain:

CODE

Certificate with alias [Signum-RSA-4096] and ID [21] was added successfully to the KeyChain

Create a sample file to sign:

CODE

echo "something to sign" >> test.sh

Use a certificate with codesign.

The certificate must have code signing capability. To verify the certificate capabilities, run the following command:

CODE

signum-util lc -v Detailed

In this example, only the second certificate is valid for use with codesign:

CODE

➜  installer git:(poc/InitializeServiceForUserOnSign) ✗ signum-util lc -v Detailed
Subject CN     : MyCertificate1
    Issuer CN      : ManagementCA
    Valid Until    : 2026-02-06
    Valid From     : 2025-02-06
    Thumbprint     : ADB6818E772A8A747C4C1B592216DC3255533D05
    Serial Number  : 5409C71053E4C637E193CD569150D4D53C9967C8
    Key Algorithm  : RSA
    Key Size       : 2048 bits
    Signature Algo : sha256RSA
    Capability     : Client Authentication (1.3.6.1.5.5.7.3.2)
    Capability     : Email Protection (1.3.6.1.5.5.7.3.4)
Subject CN     : MyCertificate2
    Issuer CN      : ManagementCA
    Valid Until    : 2027-02-17
    Valid From     : 2025-02-17
    Thumbprint     : 5EDC77B129DEC8617DB950590D739C6BBF0BA95E
    Serial Number  : 4292EC377E6A0FD414C354FD8952B9687ABE0E08
    Key Algorithm  : RSA
    Key Size       : 2048 bits
    Signature Algo : sha256RSA
    Capability     : Code Signing (1.3.6.1.5.5.7.3.3)

Use the certificate CN value or Thumbprint to identify the key.

CODE

codesign -s "Signum-RSA-4096" test.sh

CODE

codesign -s 3AB5BFB91DFBB46CF765D5BEE51429618C4857DD test.sh

After signing the file, use the following command to check the signed file:

CODE

codesign -dv --verbose test.sh

The command returns the following:

CODE

Executable=/Users/demo/signum-mac-demo/test.sh
Identifier=test
Format=generic
CodeDirectory v=20100 size=149 flags=0x0(none) hashes=1+2 location=embedded
Signature size=4173
Authority=Signum-RSA-4096
Authority=BenDemoRoot-G2
Signed Time=Aug 14, 2025 at 2:55:52 PM
Info.plist=not bound
TeamIdentifier=not set
Sealed Resources=none
Internal requirements count=1 size=80

Log out by running the signum-util logout command.

Installation Requirements

Install the Agent

Set up the Agent

Authentication

Log In

Log Out

List Certificates

Keychain

Adding to Keychain

Removing from Keychain

Logging

Signing Example using Signum Backend