macOS Agent

ENTERPRISE

The Signum macOS Agent uses Apple’s native code signing tools to access certificates stored in SignServer.

The current version of Signum-util supports only configuring one backend at a time. You can set up either SignServer or Signum as the backend, but not both simultaneously. For more information, see Signum macOS Agent documentation.

Prerequisites

SignServer Enterprise 7.4.0 or later is required for the Mac Agent.

Step 1 - Install Mac Agent (ServiceUtilAgent)

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

Follow the next steps to set up your SignServer workers for this new integration and to set up SignumUtil to use your SignServer as the backend for signing.

Step 2 - Set up SignServer

To use your SignServer instance with the Mac Agent, you need to have already set up a CryptoWorker. For more information, see CryptoTokens.

Worker Configuration

The Mac Agent needs a PlainSigner configured in SignServer to process the request made through SignumUtil.

The Mac Agent supports signing operations only with a PlainSigner configured in SignServer. Use of any other worker type is not supported in this workflow.

For the configuration to work with the SignumUtil:

Set CLIENT_VISIBLE=true to let the agent access only the workers set up for use with SignumUtil.
Set CLIENTSIDEHASHING=true to sign with the agent.

In the example, the CryptoWorker is configured from our PlainSigner template using a P12 CryptoToken and NOAUTH:

CODE

WORKERGENID1.CLIENT_VISIBLE=true
WORKERGENID1.CRYPTOTOKEN=CryptoTokenP12
WORKERGENID1.ACCEPTED_HASH_DIGEST_ALGORITHMS=SHA-256,SHA-384,SHA-512
WORKERGENID1.TYPE=PROCESSABLE
WORKERGENID1.DISABLEKEYUSAGECOUNTER=true
WORKERGENID1.AUTHTYPE=NOAUTH
WORKERGENID1.CLIENTSIDEHASHING=true
WORKERGENID1.DEFAULTKEY=code00001
WORKERGENID1.IMPLEMENTATION_CLASS=org.signserver.module.cmssigner.PlainSigner
WORKERGENID1.NAME=PlainSigner

The preferred configuration for authentication for production environments is to use ClientCert as AuthType in your worker. See Configure Client Certificate Authentication and Authorization.

Multiple PlainSigners can be configured for signing with different certificates or keys. However, setting up several PlainSigners with different configurations but pointing to same certificate can result in unexpected behavior and is not recommended.

Step 3 - Set up Signum

To use the Mac Agent, the SignumUtil needs to be configured to connect to your SignServer deployment. For more information, see Signum macOS Agent documentation.

SignumUtil Configuration

The setup for SignServer configuration is done with the following command:

CODE

signum-util signserversetup --certificate /home/path/to/my/cert --instance_url localhost:443

SignumUtil needs to have permissions to the path where your certificate is stored.

Example of a successful setup:

CODE

% signum-util signserversetup -c /tmp/dss10_client1.p12 -u localhost:443 

SignServer Test completed, able to connect to instance [localhost:443] with certificate [/tmp/dss10_client1.p12].
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.

The setup can be checked by running the show command:

CODE

% signum-util show                                                      
Signum SignServer stored configuration.
   certificate=/tmp/dss10_client1.p12
   instance_url=localhost:443
   loglevel=NONE

Or you can also retest the configuration:

CODE

% signum-util test
SignServer Test completed, able to connect to instance [localhost:443] with certificate [/tmp/dss10_client1.p12].

Step 4 - Using Signum

The listcertificates command returns the certificates that the user is authorized to access and that are configured in SignServer for use with the Signum Agent. For more information, see the CLIENT_VISIBLE setting in the SignServer Worker Configuration.

CODE

signum-util listcertificates
Subject CN     : code00001
    Issuer CN      : DSS Root CA 10
    Valid Until    : 2036-02-27
    Valid From     : 2016-03-03
    Thumbprint     : 0A9861B55542C065E68DBA15AA106C6C02095A2B

In the example, the response includes only one certificate, reflecting the SignServer configuration above that grants the user access to a single signing certificate with SignumUtil:

CODE

% signum-util keychain --add                                         
Existing Signum certificates where successfully removed from the KeyChain
Certificate with alias [code00001] and ID [1] was added successfully to the KeyChain

After running the --add command, check that the certificate was added successfully by running the following:

CODE

% sc_auth identities
SmartCard: com.keyfactor.signum.token:1
Unpaired identities:
9DB1491F4933493C083F3CFE5E25AC3D10C0EB1E	code00001

Codesign Example

This example shows how to sign a file using Codesign.

Create a sample file to sign:

CODE

echo "Something cool to sign" > file.sh

The created file is then provided to Codesign together with the Thumbprint returned by the listcertificates command above. The output should return file.sh: signed generic, as seen in the following output:

CODE

% codesign -s 0A9861B55542C065E68DBA15AA106C6C02095A2B -v file.sh                                   
file.sh: signed generic [file]

If an error is returned, check the output logs from Codesign for more information about where the error occurred.

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

CODE

% codesign -dv --verbose file.sh
Executable=/Users/hhansson/Library/CloudStorage/OneDrive-Keyfactor/Desktop/Projects/PreBuild/signserver-ee-7.3.2/bin/file.sh
Identifier=file
Format=generic
CodeDirectory v=20100 size=149 flags=0x0(none) hashes=1+2 location=embedded
Signature size=3608
Authority=code00001
Authority=DSS Root CA 10
Signed Time=15 Oct 2025 at 08:04:00
Info.plist=not bound
TeamIdentifier=not set
Sealed Resources=none
Internal requirements count=1 size=80

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.