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.

For signing examples with the macOS agent, see Sign Apple Binaries using Signum and Using Signum with OpenSSL.

Prerequisites

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

In your download area on download.primekey.com, go to latest Signum agent folder.

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.

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

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

The following table describes the returned values:

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`. See macOS Keychain Setup. 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, Signum

Log in with Username

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]

Log in with Certificate

You can log in with a certificate imported into your macOS keychain using the name or thumbprint.

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.

Use one of the following command options, depending on how you want to identify the certificate:

With certificate name, where CERTIFICATE NAME refers to the certificate Common Name (CN):
CODE
```
signum-util s -h [HOSTNAME] -n [CERTIFICATE NAME]
```
With certificate thumbprint, where CERTIFICATE THUMBPRINT refers to the SHA-1 value:
CODE
```
signum-util s -h [HOSTNAME] -t [CERTIFICATE THUMBPRINT]
```

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:

CODE

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.

Using a p12 certificate file:

CODE

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

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

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

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:

CODE

% 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)

Worker changes not reflected in the keychain: Changes on the workers in SignServer are not directly reflected in the keychain. For every server change, execute a listcertificates and a keychain --add in the signum-util.
TLS issues with private PKI: When running a private PKI with the Mac Agent and SignServer, TLS issues can occur, indicated by the following error:
CODE
```
The SSL connection could not be established, see inner exception.
The remote certificate is invalid because of errors in the certificate chain: UntrustedRoot
```
To resolve, run the following command to add the certificate to the system keychain and ensure SSL validation:
CODE
```
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychsudo security add-tr
```