Setup
This section provides information to use SignPath with any tool that supports macOS CryptoTokenKit.
Supported versions
macOS 12.0 or higher
Installation
Simply copy-deploy the SignPathCryptoTokenKit.app application to the target system.
Configuration
See SignPath Crypto Providers for general configuration options.
Usage
General usage
Enable the CryptoTokenKit extension
Start the SignPathCryptoTokenKit.app application to load certificates into the macOS keychain through a CryptoTokenKit extension. The application supports the following parameters (all optional):
| Parameter | Value | Default | Description |
|---|---|---|---|
--config |
path/to/configfile.json |
Path to SignPath configuration file | |
--api-url |
$ApiUrl |
https://app.signpath.io/Api |
Base URL of the SignPath API |
--project-slug |
$ProjectSlug |
Slug of the SignPath Project | |
--signing-policy-slug |
$SigningPolicySlug |
Slug of the SignPath Signing Policy | |
--organization-id |
$OrganizationId |
ID of the SignPath Organization | |
--api-token |
$ApiToken |
API token for a SignPath User |
Example call starting the application:
export SIGNPATH_API_TOKEN=...
open SignPathCryptoTokenKit.app --args \
--project-slug MyProject \
--signing-policy-slug release-signing \
--organization-id 0241f767-69c8-448d-ad5e-8bd453916068
Background
SignPath uses the CryptoTokenKit extension mechanism to provide keys and certificates can be provided. The application that registers the extension must be running. Therefore, before calling signing tools like
codesign, theSignPathCryptoTokenKit.appneeds to be started.
Project and signing policy
Identify a specific Signing Policy by specifying Project and Signing Policy slugs. The SignPath CryptoTokenKit provider will select that policy’s certificate.
Default values can be provided as configuration values.
Always specify Project and Signing Policy slugs
When you specify neither, SignPath will load all certificates available for the API Token’s user. When you specify only the Project, SignPath will load the certificates of all available Signing Policies for the specified project.
This works fine if a certificate clearly identifies a single Signing Policy. However, if a certificate is referenced by more than one available Signing Policy, using it will result in an ambiguous reference error.
codesign
codesign is a command line tool by Apple.
codesign requires the following parameter to find the correct certificate:
| Parameter | Value | Description |
|---|---|---|
-s |
$SigningIdentity |
A descriptor of the code signing identity that is stored in the keychain by the SignPath CryptoTokenKit. Provide the common name (or a substring) of the certificate. |
Sample: sign MyApp.app
codesign -s MyCertificateSubjectName MyApp.app
Info: Using the right certificate
codesignrequires an “Apple Developer Application” certificate.
productsign
productsign is a command line tool by Apple.
productsign requires the following parameter to find the correct certificate:
| Parameter | Value | Description |
|---|---|---|
--sign |
$SigningIdentity |
A descriptor of the code signing identity that is stored in the keychain by the SignPath CryptoTokenKit. Provide the common name (or a substring) of the certificate. |
Sample: sign MyInstaller.pkg
productsign --timestamp --sign "XX6NBJ3UUF" MyInstaller.pkg MyInstaller-signed.pkg
Info: Using the right certificate
productsignrequires an “Apple Developer Installer” certificate.
Troubleshooting
Loading the certificates and making them available in the macOS keychain can take up to 20 seconds.
Logs
Unless specified otherwise, the log files are stored in ~/Library/Logs/SignPathCryptoTokenKit/ and ~/Library/Containers/io.signpath.apps.CryptoTokenKit/Data/Library/Logs/ctk/ respectively.
Useful commands
The following commands are helpful to make sure the setup is correct:
Using the security command, the registered smart cards can be listed. This list should contain an entry io.signpath.apps.SignPathCryptoTokenKit.ctk:<identifier>
security list-smartcard
Using the pluginkit tool, the registration of the token driver can be verified. The command lists all registered tokens and should also list io.signpath.apps.CryptoTokenKit($Version).
pluginkit -m -v -p com.apple.ctk-tokens
The smartcard service on macOS sometimes has issues. If the certificates cannot be loaded, the service can be restarted by running the following command:
killall ctkd
Info: Updated intermediate certificate
When creating a certificate in the Apple Developer portal, the intermediate certificate can be selected. On some machines, the new intermediate certificate is still missing. You can download it here.
Warning: Produce correct timestamps
When using codesign (or any other signing tool) directly, you are responsible for correct time stamping. See Timestamps