Current Version 1.3

Overview

Signing Manager is comprised of two components: Signing Manager App and Signing Manager Service.

Signing Manager App is a macOS application for code signing and package signing using remote identities. It includes a CryptoTokenKit extension for presenting X.509 certificates to the macOS keychain for use in cryptographic signing operations, using built in commands such as codesign and productsign. Signing Manager Service is a web application to store and limit access to sensitive signing identities. It can be used as a cloud service hosted in AWS or installed locally in your macOS or Linux environment. 

Together, Signing Manager App and Signing Manager Service allow users to code sign and package sign without the need for having identities on their own machines. Using these two in tandem, an administrator can provide distributed access to certificate content within their organization while keeping identities centrally managed. Administrators can easily allow or restrict certain identities to the appropriate users and quickly push new identities. At the same time, users can enjoy a simple and intuitive interface, tools that make existing workflows more efficient, and the autonomy of a reduced dependency on specific machines or administrators.

Requirements

Signing Manager App: macOS 10.15 Catalina or later

Signing Manager Service (locally installed): macOS or Linux system capable of running Ruby on Rails

Signing Manager Service (cloud service): Internet Access

Certificate and private keys for signing macOS, iOS, watchOS, and iPadOS code and packages. These are generally provided by Apple for code and package signing.


Signing Manager Service

To use the cloud-hosted version of Signing Manager Service, please use signing-server.twocanoes.com 

You are able to use this on your own AWS server on your premises; see future updates to this guide for more information

Signing In

When first using Signing Manager Service, whether you are an administrator or user, you must sign in. The administrator’s login details will be provided via their Signing Manager Service purchase confirmation email. Administrators create Signing Manager Service accounts for all non-admin users; non-administrator users, contact your administrator for login information.

At the login page, enter in the credentials provided in your confirmation email (or by your administrator if a non-admin user). You may be prompted to change your password after login, then taken to the Main Page.

Main Page

At the bottom of the Main Page is your Signing Manager Service Domain and API Key. To show your API Key, click “click to show” in the API key field (most of the API Keys in this guide are greyed out). The API Key will appear in a pop-up:

Be sure to reference the Main Page when setting up Signing Manager App to match the Signing Manager Service Domain and API Key in Preferences. You will also see links for the identities page, the users page, and for downloading Signing Manager App. Users that are not designated as an organization admin will see a slightly different screen:

Note: the users tab is replaced with an “account” tab, as users who are not designated as organization admin cannot create new users. The “user accounts” link is also removed

Both administrators and non-administrator users sign out of Signing Manager App in the same way: by clicking the “sign out [username]” tab in the menu bar:

For ease of use, this guide will provide further instructions for use by both Organization Administrators and non-Administrator Users. To jump to non-Administrator users, click here.

Using Signing Manager Service as an Organization Administrator

Identities Page

To access the Identities Page, either click the “identities” tab in the menu bar or the “identities” link in “View identities for signing” on the Main Page itself.

Initially, your identities will be empty:

In this case, as there are no identities to view, none appear. Note that non-admin users are unable to import identities, only able view them with the “Import identity” button missing. To import identities, click the “Import identity” button:

After clicking the “Import identity” button, you will be redirected to the Import Identity page:

For this example, we will be using the sample identities found here. The password for the p12 files is included in the download. Begin by clicking “Choose File” (may appear different based on your operating system and/or browser) and navigating to the downloaded TestP12 folder:

As only one certificate can be imported at a time, we’ll choose to upload “CodeSigning.p12”: 

The P12 password is entered below the uploaded file. After clicking the “Import” button or pressing enter, the page is redirected to the Identity information page:

At the top, a banner confirms that the Identity was successfully created. The Identity is assigned a number (in this case, Identity 26) and will show the Common Name, Fingerprint, and Certificate below the number. 

To the right of the Identity number are five buttons:

  • “Back” returns you to the identity page, which now includes the newly imported identity:
  • “Sign” allows you to sign using the identity. This is normally only used for debugging.
  • “Authorize” allows you to modify the users authorized to access the identity
  • “Edit” allows you to edit the identity by re-uploading a .p12 file
  • “Delete” allows you to delete the identity

Sign

If you click the “Sign” button, either on the main Identities Page or when examining the identity itself, you are taken to the Sign with Identity Page. Beneath the common name, enter in your Blob and either click the “Sign” button or press enter:

When signing goes correctly, the common name, Signature, and Blob are listed. You may return to the main Identities Page using “Back” or sign the identity again using “Sign new”.

Authorize

If you click the “Authorize” button when viewing the details of an identity, you are redirected to the authorization screen for the identity. Underneath the number identifier for the identity are the Common Name and Fingerprint of the identity, also viewable from when viewing the details of an identity. 

By default, all users that you manage are able to view and sign with identities that you import. As an administrator, you do not need to authorize yourself. However, you can manage access to identities with specific users by clicking the “Choose authorized users” button:

Here, administrator fhernandez is managing authorization of the identity with their two non-administrator users: fhernandez2 and fhernandez3. Manage “Authorized” users at the top of the list, by clicking “select all” to authorize all users or “clear all” to clear authorization of all users under your management.  Individually manage the user authorizations by selecting the checkboxes next  to the users’ usernames. When finished, click the “Update authorization” button.

Edit

Delete

You can also delete an identity, either when viewing the identities details or on the main Identities Page. Before doing so, a prompt appears to verify that you want this identity deleted:

Prompts may appear different based on your operating system and/or browser. After clicking OK, you’re redirected to the main Identities Page:

A banner at the top confirms that the identity was successfully destroyed. The identity will no longer be listed under identities.

Users Page

To access the Users Page, click the “users” tab in the menu bar:

Let’s walk through an example of user management: user fhernandez is the organization admin of F. Hernandez, Inc. with two additional users:

From the Users page, an administrator can view Total users; search for particular users (either by user name, email, or organization name); create new users; and view, edit, or delete existing users. 

Searching for Users

To search for a user, use the search bar. In this case, fhernandez wants to find user fhernandez3. They’ll search for that user via their username:

The “Total users” count at the top will update with the total number of users contained within the search results. To view a user’s information, click on the user’s Name.

In the user’s information page, next to the username itself, we see three buttons:

  • “Back” returns you to the Users Page
  • “Edit” allows you to edit the user’s information via the Edit User page
  • “Delete” allows you to delete a user

Underneath the users information (User name, Email, Organization, and Organization admin status), the user’s Signing Manager Credentials are shown. To view the API Key, select “click to show”. Note: While the Signing Server Domain may be the same, API Keys will vary from user to user.

Editing a User

In this example, user fhernandez3 (pictured above) has the incorrect email: their account is tied to fhernandez30@fhernandez.edu instead of fhernandez3@fhernandez.edu. From the image above, administrator fhernandez clicks the Edit button (though they could also click the “Edit” button next to a user’s Name on the Users Page):

An organization administrator can easily change the User name, email, password, and/or Organization name of their users. In the above example, the email is corrected in the email field. As an added security measure, the administrator can also check the “Generate new password” box, which generates a new password for the you to share with the user. The password will not be shown again once the page has refreshed. To complete the edit of fhernandez3’s information, administrator fhernandez can either click the “Update User” button or hit enter on their keyboard.

A banner at the top confirms that fhernandez3’s information has been successfully updated. If generating a new password, this confirmation screen will look slightly different:

A username and password are now separately listed below the buttons alongside a new banner. Note: the password will no longer appear if the page is refreshed. Make sure to complete all necessary actions with the password before leaving the page.

Creating a New User

The process for making a new user begins at the Users Page. When viewing a user’s information, you can use the “Back” button to return to the Users Page. Otherwise, click the “users” tab in the menu bar to return to the Users Page.

Above, administrator fhernandez would like to create a new user with username fhernandez4. To go to the New User page, fhernandez clicks the “New user” button:

The process for creating a new user is similar to the process of editing an existing user: after providing the new user’s User name, email, and password, click the “Create User” button. After successfully creating a new user, the administrator is redirected to the user’s informational page, where a banner indicates that a user was successfully created:

As with editing a user, this screen looks slightly different if the “Generate new password” box is checked while editing:

The username and password are again listed separately below the buttons alongside the reminder banner. Note: for your user’s privacy, the password will no longer appear if the page is refreshed. Make sure to complete all necessary actions with the password before leaving the page.

Deleting a User

From the information screen of a user, as well as from the Users Page, an administrator can delete an existing user. Before doing so, a prompt appears to verify that the administrator wants this user deleted:

Prompts may appear different based on your operating system and/or browser. After confirming that the user is to be deleted, you will be redirected to the Main Page: 

After being redirected back to the Users Page, a banner appears at the top confirming that the User was successfully deleted. 

Note: if a user deletes their own account in error, you may create a new account with their same credentials. However, they should still be treated as a new user: identities have to be reassigned to them and their API Key will change.

Audit Page

To view an audit of all Signing Events, click the “audit” tab in the menu bar:

The Audit Page will have a complete list of all completed Signing Events.

API Reference Page

To access the API Reference Page, click the “api” tab in the menu bar:

Contained within the API Reference Page are three reference categories: Status, Signing Certificates, and Sign Blob.

Using Signing Manager Service as an non-Administrator user

Identities Page

To access the Identities Page, either click the “identities” tab in the menu bar or the “identities” link in “View identities for signing”. If your administrator has not imported identities, your identities will be empty:

After your administrator has imported identities, those identities for which you have access will appear. Below, administrator fhernandez has given non-administrator fhernandez2 access to “Twocanoes Test Code Signing 2”:

Contact your administrator for access to new identities. 

Let’s examine the identity listed:

Each Identity is assigned a number (in this case, Identity 26). When seeing the details of an identity, the page will show the Common Name, Fingerprint, and Certificate.

Next to the identifying number at the top are two buttons:

  • “Back” returns you to the main identities page, which can also be accomplished by clicking the identities tab in the menu bar
  • “Sign” allows you to sign using the identity you’re seeing the details of. As previously mentioned, this can also be done from the Identities Page

Let’s walk through the signing process with this identity:

If you click the “Sign” button, either on the main Identities Page or when examining the identity itself, you are taken to the Sign with Identity Page. Beneath the common name, enter in your Blob and either click the “Sign” button or press enter:

Below is a successful screen for signing an identity with the Common Name, Signature, and Blob listed:

You may return to the main Identities Page using “Back” or sign the identity again using “Sign new”.

Edit Account Page

To access the Edit Account Page, click the “account” tab in the menu bar:

You will be redirected to the Edit Account Page:

There are two buttons at the top of the page:

  • “Back” returns you to the Main Page
  • “Cancel my account” allows you to cancel your account.

Within the Edit Account page, you can:

  • Change your username
  • Change the email associated with your account
  • Create a new password

Editing an Account 

To demonstrate, let’s change the username for this account from test_user to test_user_1:

After inputting the current password (which is required to make changes, even if not password-related), the field “User name” is changed from “test_user” to “test_user_1”. To complete the process, press enter or click the “Update” button at the bottom:

You will be redirected back to the main page, where a banner at the top confirms that your account has been updated.

Canceling your Account

To cancel your account, return to the Edit Account Page, then click the “Cancel my account” button:

Prompts may appear different based on your operating system and/or browser. After confirming you would like your account cancelled, you will be logged out and redirected to the homepage of Signing Manager Service: 

A banner at the top confirms that your account has been cancelled. With this confirmation message, you will no longer have access to your account. Contact your administrator to create a new account.

API Reference Page

To access the API Reference Page, click the “api” tab in the menu bar:

Contained within the API Reference Page are three reference categories: Status, Signing Certificates, and Sign Blob.


Signing Manager App

Signing Manager App Installation

As mentioned in the Main Page section of the Signing Manager Service portion of this guide, a link to download the latest version of Signing Manager App is provided on the main page at https://signing-server.twocanoes.com. Signing Manager App is distributed as a disk image (.dmg) that contains a standard macOS installer package. 

To install the package in Finder:

  1. Double-click on the disk image to mount it in Finder.
  2. Double-click on the package in the mounted disk image to start installing the package.

Follow the prompts in the installer package to complete installation.

To install the package via the command line, use the installer command.

Installed Components

The macOS installer consists of two major components:

  1. macOS app (“Signing Manager.app”) installed in the /Applications folder
  2. CryptoTokenKit extension installed in the Signing Manager.app bundle

Installing your License

Included in your confirmation email is a license link. Click the link to download the Configuration Profile that serves as a license.

In order to install your license, double click on the provided file to install the Configuration Profile.

The above message will appear. Note: in some versions of macOS, you can complete installation from the notification.

After the message appears, open System Preferences:

In the bottom right of System Preferences, click on the “Profiles” button.

Within the Profile window, click “Install…” on the identity you’ve recently double clicked. You’ll get a prompt confirming the install:

After clicking “Install”, your license is activated:

The “Install…” and “Ignore” buttons will disappear.

Uninstalling

To uninstall Signing Manager App, use the Uninstaller .dmg included in the installation package and follow the instructions within.

If you’d like to uninstall your license, return to the “Profiles” window in System Preferences, then either click delete on the downloaded license or click the “-” button at the bottom of the list of downloaded profiles:

A prompt will confirm that you would like the profile removed. Click “Remove” to complete the process.

Signing Manager App Configuration

Now that the Signing Manager Service is running and accepting network connections, you can configure the macOS clients for signing operations. Configuration can be done in the Preferences (⌘ ,) of the Signing Manager app or on the command line.

App Preferences

Launch the Signing Manager App in /Applications. If there are no preferences specified, the Preference window will automatically open. If it does not open, select Preferences from the Signing Manager App menu. In the Preferences window, provide the URL to the Signing Server and API key provided by the Signing Manager Service. If the Signing Manager Service is using a self-signed certificate, select the Trust Self Signed Certificates checkbox.

Command Line

Preferences can also be set using the command line. The command line tool is located in the application bundle. Run it with the -h option to see the available options. Note that you must include the quotes due to the spaces in the application name.

"/Applications/Signing Manager.app/Contents/MacOS/Signing Manager" -h

-s                  Save settings.  Requires -i and -a. Optionally use -d.

-i <api host url>   Specify host for API signing operations.

-a <api_key>        Specify api key for accessing signing manager service.

-u                  trust self-signed certificates.

-d                  debug logging

-r                  refresh and display available certificates.

-p                  print configuation.

-h                  this message.

Using the -i, -a and -u options, set the preferences. For example, with a host URL of https://signingserver.local:3000, an API key of XYZ123, and trusting self-signed certificates:

"/Applications/Signing Manager.app/Contents/MacOS/Signing Manager" -s -i https://signingserver.local:3000 -a XYZ123 -u

To verify the settings, use the -p option:

"/Applications/Signing Manager.app/Contents/MacOS/Signing Manager" -p

api_host: https://signingserver.local:3000

trust self signed: true

debug: false

API key: Set

Note that the API key is not shown, but can be found in the macOS keychain under com.twocanoes.signing-manager.

Once the settings have been entered, click OK.

Using Signing Manager App

Now that Signing Manager Service has been set up and the client is configured, applications and packages can now be signed. If no certificates are showing in the main interface of Signing Manager App, click Refresh on the toolbar.

To refresh available certificates on the command line, run:

"/Applications/Signing Manager.app/Contents/MacOS/Signing Manager" -r

A list of available certificates and the SHA-1 fingerprints will be shown.

Menu Bar Operations

Note: These operations may also be accessed using the Keyboard Shortcuts located at the end of this User Guide.

  1. Refresh: After entering a new Signing Server and API Key in Preferences, clicking Refresh in Signing Manager will show the identities stored within Signing Manager Service; use Refresh after adding or removing identities in Signing Manager Service for Signing Manager App to reflect those changes.
  2. Show Log: The Signing Manager App Log opens in Console (SigningManager.log).
  1. Copy CN: Copy the Common Name of a highlighted certificate. You may also right-click the highlighted certificate and select “Copy Common Name”.
  1. Copy Fingerprint: Copy the SHA-1 Hash of the highlighted certificate. You may also right-click the highlighted certificate and select “Copy SHA-1 Hash”.
  1. Copy codesign command: Copy the codesign command for the highlighted certificate to use in Terminal. You may also right-click the highlighted certificate and select “Copy ‘codesign’ command”:
  1. Copy productsign command: Copy the productsign command for the highlighted certificate to use in Terminal. You may also right-click the highlighted certificate and select “Copy ‘productsign’ command”.
  1. Show Certificate: View the highlighted certificate

Signing Applications

To sign an application, select a certificate in the main interface and use Copy codesign command, then paste it into Terminal. Append the path to the application you want to sign and press return. For example:

codesign -fs "74FD9E670CFB7C906630B49FD26591CD66C66D79" ~/Documents/Projects/MyApp.app

Verify the signature by running codesign with the -dvvv options:

codesign -dvvv ~/Documents/Projects/MyApp.app

Signing Packages

To sign an installer package, select a certificate in the main interface and use Copy productsign command, then paste it into Terminal. Replace source.pkg and destination.pkg with a package to sign and a destination. For example:

productsign --sign "125F19515E25FA23CC1BA82E3E7A09D0A2097980" source.pkg destination.pkg

Verify the signature by double clicking on the signed package, then clicking on the certificate icon in the upper right corner of the first window of the installer.

Using with Xcode

In order to use Signing Manager App with Xcode, the certificate (and not the private key of the certificate) must be imported to the local keychain. This allows Xcode to find the remote identity and use it for signing. The certificate does not need to be trusted and made available to Xcode. This is not required when using codesign directly.

Signing Manager App Keyboard Shortcuts

  • ⌥⌘C: Copy Common Name
  • ⌥⌘S: Copy Fingerprint (SHA1 Hash)
  • ⌥⌘O: Copy codesign command
  • ⌥⌘P: Copy productsign command
  • ⌘R: Refresh
  • ⌥⌘E: Show Certificate
  • ⌘1: Show Certificates Window
  • ⌘L: Show Log