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

Step 1 - Install macOS Agent (ServiceUtilAgent)

For access to the Agent download, contact Keyfactor.

  1. Download the .pkg package.

  2. Click on the package to install.

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

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 macOS Agent, you need to have already set up a Crypto Worker. For more information, see Crypto Tokens.

Worker Configuration

The macOS Agent needs a Plain Signer configured in SignServer to process the request made through SignumUtil.

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

For the configuration to work with the SignumUtil:

  1. Set CLIENT_VISIBLE=true to let the Agent access only the workers set up for use with SignumUtil.

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

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 Plain Signers can be configured for signing with different certificates or keys. However, setting up several Plain Signers 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 macOS 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:

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

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

Example of a successful setup:

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

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

Or you can also retest the configuration:

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

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:

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

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

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:

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

% codesign -dv --verbose file.sh
/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:

    % 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 macOS Agent and SignServer, TLS issues can occur, indicated by the following error:

    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:

    sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychsudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain PrivatePKIManagementCA.cacert.pem