Scripts for Apple signing using CryptoTokenKit (CTK) on GitHub

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.

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:

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:

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:

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.

To download the certificate from DigiCert​​®​​ Software Trust Manager:

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

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

To integrate environment variables as GitHub secrets:

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:

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

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

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

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

To install the DigiCert​​®​​ Software Trust Manager client tools:

To access the client tools from GitHub actions:

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

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

- 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 

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

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

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

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

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

- 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