Scripts for Apple signing using CryptoTokenKit (CTK) on GitHub

Download and set up the DigiCert® Software Trust Manager CryptoTokenKit on the GitHub hosted Apple virtual machine (VM) for signing.

Prerequisites

DigiCert® Software Trust Manager CryptoTokenKit
DigiCert® Software Trust Manager credentials
DigiCert® Software Trust Manager client tools
An Apple certificate
A GitHub repository

Software Trust Manager account

You must have access to DigiCert ONE to use the client tools and connect to DigiCert® Software Trust Manager for operations. If you do not have access to DigiCert® Software Trust Manager (STM), contact an administrator for DigiCert ONE and request access.

User authentication

DigiCert® Software Trust Manager requires multifactor authentication. You will need to set up two credential types, namely an API token and an authentication certificate before you can access keypairs, certificates, and to sign code.

Create an API token

The API token is an authentication method used to verify the user and their permissions as set in DigiCert ONE. The client authentication provides the first factor authentication.

To generate an API token:

Sign in to DigiCert ONE.
Select the profile icon.
Select Admin Profile.
Scroll down to API Tokens.
Select Create API token.
Nota
The information shown after creating an API token cannot be accessed again, securely store all the information specified on the screen to use it later.

Create an authentication certificate

The client authentication certificate is an authentication method used to verify the user and their permissions as set in DigiCert ONE. The client authentication certificate provides the second factor authentication.

To create a client authentication certificate:

Sign in to DigiCert ONE.
Navigate to Profile icon > Admin Profile.
Scroll down to Authentication certificates.
Select Create authentication certificate.
Nota
The information shown after creating an client authentication certificate cannot be accessed again, securely store all the information specified on the screen to use it later.

Authorization

Permissions

Select the required permissions for the user to use the client tools and perform operations with DigiCert® Software Trust Manager. To remain compliant, the administrator must enable multifactor authentication for the user.

The following permissions are required:

Generate keypair
View keypair
Import keypair
Sign
View certificate
Generate certificate
Manage certificate
Manage certificate hierarchy
Import certificate

Best practices for secure GitHub use

Use secrets and secure files to ensure security and accountability among your GitHub users when they use DigiCert® Software Trust Manager to sign code. The code examples later assume that you are using secrets and secure files.

GitHub Secrets

Secrets are variables in GitHub encrypted so users can input information without knowing what the value of that information is. For example, with API keys, you do not want all of your GitHub collaborators knowing what your unique API key is, but they may need to use it to use signing tools through DigiCert® Software Trust Manager . You can set up a variable where "(api_key)" is the name and the value is the API key itself.

Set certificate file in environment variables

To download the certificate from DigiCert® Software Trust Manager:

Sign in to DigiCert ONE.
Navigate to DigiCert® Software Trust Manager > Certificates.
Click on the certificate alias that you want to download.
Select the download icon next to the Certificate field.

To add a certificate to GitHub secrets, you need to encode the certificate to a base64 string.

To encode the certificate file to base 64, run:

base64 file_name

Configure GitHub Secrets

The client tools need these environment variables to connect with DigiCert® Software Trust Manager.

To integrate environment variables as GitHub secrets:

Access GitHub repository.
Navigate to: Settings > Secrets > Actions.
Select New repository secret.

Enter the following environment variables:

Environment variables	Description
SM_CLIENT_CERT_PASSWORD	The password from client authentication certificate setup.
SM_CLIENT_CERT_FILE_B64	The base64 encoded text of certificate downloaded from client authentication certificate setup.
SM_HOST	The path to the DigiCert ONE portal with client authorization.  Nota In most cases, this path stays as it is unless you are connecting to a self-hosted instance of the DigiCert ONE product.
SM_API_KEY	The API token generated during API token setup.
SM_CODE_SIGNING_CERT_SHA1_HASH	The certificate fingerprint.

Nota

The SM_HOST value you use for the commands below will depend on whether you are using demo or prod.

tabla 1. SM_HOST values

Country	Host type	SM_HOST value
United States of America (USA)	Demo	https://clientauth.demo.one.digicert.com
United States of America (USA)	Production	https://clientauth.one.digicert.com
Switzerland (CH)	Demo	https://clientauth.demo.one.ch.digicert.com
Switzerland (CH)	Production	https://clientauth.one.ch.digicert.com
Japan (JP)	Demo	https://clientauth.demo.one.digicert.co.jp
Japan (JP)	Production	https://clientauth.one.digicert.co.jp
Netherlands (NL)	Demo	https://clientauth.demo.one.nl.digicert.com
Netherlands (NL)	Production	https://clientauth.one.nl.digicert.com

Commands to set environment variables

Once you save the variable, it is fully encrypted. Not even the creator of the value (you) can see the value. Make sure you save it elsewhere if it is something you will need in the future.

To set the API token as a new repository secret:

Name	SM_ SM_API_KEY
Value	Insert the API token you created.

To set the client authentication certificate as a new repository secret:

Name	SM_CLIENT_CERT_FILE_B64
Value	Insert the base 64 encoded string you generating when creating the client authentication certificate.

To set the client authentication certificate as a new repository secret:

Name	SM_CLIENT_CERT_PASSWORD
Value	Insert the password you were shown when creating the client certificate password.

YAML command to set up the certificate file for signing:

- name: Setup Certificate
  run: |
    echo "${{ secrets.SM_CLIENT_CERT_FILE_B64 }}" | base64 -D > Certificate_pkcs12.p12
    mv Certificate_pkcs12.p12 /Users/runner/Downloads/Certificate_pkcs12.p12
    chmod 777 /Users/runner/Downloads/Certificate_pkcs12.p12

Set up CryptoTokenKit

To properly understand how to set up the CryptoTokenKit, refer to the CryptoTokenKit CLI tool documentation.

Client tool setup

To install the DigiCert® Software Trust Manager client tools:

Sign in to DigiCert ONE.
Navigate to DigiCert® Software Trust Manager > Resources > Client tool repository.
Download DigiCert® Software Trust Manager CryptoTokenKit (portable zip).
Add the zip file in the GitHub repository.

To access the client tools from GitHub actions:

Unzip the DigiCert® Software Trust Manager CryptoTokenKit.
Move the DigiCert SSM Signing Clients.app to /Applications folder.

YAML command to install the Apple Client tools:

- name: Apple ClientTools Installation
  run: |
    unzip "DigiCert SSM Signing Clients.zip"
    sudo mv "DigiCert SSM Signing Clients/DigiCert SSM Signing Clients.app"  "/Applications/DigiCert SSM Signing Clients.app"
    chmod 777 "/Applications/DigiCert SSM Signing Clients.app"
    mkdir dist

Set up CryptoTokenKit in GitHub Actions

The DigiCert® Software Trust Manager CryptoTokenKit is an implementation of the Apple CryptoTokenKit extension used to sign Apple binaries.

YAML command to register a new token driver:

- name: Register a new token driver
  run: |
    open "/Applications/DigiCert SSM Signing Clients.app"
    pluginkit -a "/Applications/DigiCert SSM Signing Clients.app/Contents/PlugIns/TokenExtension.appex"

YAML command to verify the token driver:

- name: Verify the token driver
  run: |
    pluginkit -m -v -p com.apple.ctk-tokens

YAML command to create a symlink to run the tool:

- name: Create a symlink
  run: |
    ln -s "/Applications/DigiCert SSM Signing Clients.app/Contents/MacOS/DigiCert SSM Signing Clients" DigicertSmctl
    ./DigicertSmctl smctl

Add environment variables

You can add different DigiCert® Software Trust Manager credentials to your macOS keychain by using the environment command.

YAML command to add the environment variables:

- name: Add an environment variables
  run: |
    ./DigicertSmctl smctl environment add --host ${{ secrets.SM_HOST }} --api-key ${{ secrets.SM_API_KEY }} --client-certificate-file /Users/runner/Downloads/Certificate_pkcs12.p12 --client-certificate-password ${{ secrets.SM_CLIENT_CERT_PASSWORD }}
    ./DigicertSmctl smctl environment show

Token management

You must add a token so that you can add keys which is used for codesign and productsign.

YAML command for adding the token:

- name: Add a token
  run: |
    ./DigicertSmctl smctl token add-token

Keypair management

To create a keypair for codesign and product sign:

Sign in to DigiCert ONE®.
Navigate to DigiCert® Software Trust Manager > Keypairs > Create keypair.

YAML command to fetch the keypair from DigiCert® Software Trust Manager and add them to the token present on the MacOS:

- name: Add keypairs
  run: |
    ./DigicertSmctl smctl keypair add-keys Apple_CodeSign Apple_ProductSign

Keypair verification

YAML command to verify the keypair added to token:

- name: Verify keys added to the token
  run: |
    security export-smartcard

Codesign signing and verification

The following command requires:

The Apple developer identity.
The path to the file to be signed.

YAML command for codesign signing and verifying:

- name : Codesign Signing
  run: |
    /usr/bin/codesign --deep --force --verify --verbose --sign "<Apple Developer ID>" --options runtime “<Path to app bundle>”
    /usr/bin/codesign -dv --verbose <path to signed file>

Product signing and verification

The following command requires:

The Apple developer identity.
The path to the file to be signed.
Path where signed file should be stored

- name: Productsign Signing
  run: |
    /usr/bin/productsign --sign "<Apple Developer ID>" <Unsigned file path> <Signed output file path>    
    pkgutil --check-signature <path to signed file>

Apple code signing sample

YAML script for signing apple files using codesign and productsign:

- name: 'build and release electron installer'
on:
  push:
    tags:
      - 'v*'
      
jobs:
  release:
    runs-on: ${{ matrix.os }}
    
    strategy:
      matrix:
        os: [macOS-latest]
        
    steps:
      - name: Check out Git repository
        uses: actions/checkout@v2

      - name: Install Node.js, NPM and Yarn
        uses: actions/setup-node@v2
        with: 
          node-version: 14
  
      - name: Setup Certificate
        run: |
          echo "${{ secrets.SM_CLIENT_CERT_FILE_B64 }}" | base64 -D > Certificate_pkcs12.p12
          mv Certificate_pkcs12.p12 /Users/runner/Downloads/Certificate_pkcs12.p12
          chmod 777 /Users/runner/Downloads/Certificate_pkcs12.p12

      - name: Apple ClientTools Installation
        run: |
          unzip "DigiCert SSM Signing Clients.zip"
          sudo mv "DigiCert SSM Signing Clients/DigiCert SSM Signing Clients.app"  "/Applications/DigiCert SSM Signing Clients.app"
          chmod 777 "/Applications/DigiCert SSM Signing Clients.app"
          mkdir dist

      - name: Setup CryptoTokenKit
        run: |
          open "/Applications/DigiCert SSM Signing Clients.app"
          pluginkit -a "/Applications/DigiCert SSM Signing Clients.app/Contents/PlugIns/TokenExtension.appex"
          pluginkit -m -v -p com.apple.ctk-tokens
          ln -s "/Applications/DigiCert SSM Signing Clients.app/Contents/MacOS/DigiCert SSM Signing Clients" DigicertSmctl
          ./DigicertSmctl smctl
          ./DigicertSmctl smctl environment add --host ${{ secrets.SM_HOST }} --api-key ${{ secrets.SM_API_KEY }} --client-certificate-file /Users/runner/Downloads/Certificate_pkcs12.p12 --client-certificate-password ${{ secrets.SM_CLIENT_CERT_PASSWORD }}
          ./DigicertSmctl smctl environment show
          ./DigicertSmctl smctl token add-token
          ./DigicertSmctl smctl keypair add-keys Apple_CodeSign Apple_ProductSign
          security export-smartcard

      - name : Codesign Signing
        run: |
          mv UNSIGNED.app dist/UNSIGNED.app
          /usr/bin/codesign --deep --force --verify --verbose --sign "Apple Development: Rosemary Thomas (85W9468PYV)" --options runtime dist/UNSIGNED.app
          /usr/bin/codesign -dv --verbose dist/UNSIGNED.app

      - name: Productsign Signing
        run: |
          /usr/bin/productsign --sign "Developer ID Installer: Rosemary Thomas (DHPK4B64QS)" UNSIGNED_PKG.pkg dist/Signed.pkg
          pkgutil --check-signature dist/Signed.pkg

      - name: Upload artifacts
        uses: actions/upload-artifact@v2
        with:
          name: ${{ matrix.os }}
          path: |
            dist

En esta sección:

Scripts for Apple signing using CryptoTokenKit (CTK) on GitHub

Prerequisites

Software Trust Manager account

User authentication

Nota

Nota

Authorization

Permissions

Best practices for secure GitHub use

Set certificate file in environment variables

Configure GitHub Secrets

Nota

Nota

Set up CryptoTokenKit

Client tool setup

Set up CryptoTokenKit in GitHub Actions

Add environment variables

Token management

Keypair management

Keypair verification

Codesign signing and verification

Product signing and verification

Apple code signing sample

Related articles

Resultados de la búsqueda