How to Integrate eSigner CKA with CI/CD Tools for Automated Code Signing

.NET Code DLL Signing Example Workflow

Prepare the components of the workflow

1. Create a .circleci folder on your editor. Include workflows with the folder and create a yml file as config.yml under the folder.
2. Set the CircleCI version. The version field is intended to be used in order to issue warnings for deprecation or breaking changes.

   version: 2.1

3. Orbs are reusable packages of CircleCI configuration that you may share across projects, enabling you to create encapsulated, parameterized commands, jobs, and executors that can be used across multiple projects. To use the signtool tool this needs to be windows.

   orbs:

      win: circleci/windows@5.0.0

4. Invoke jobs via workflows. Workflows orchestrate a set of jobs to be run. 

   workflows:

      # The name of the workflow.

      sign-file:

         # Inside the workflow, you define the jobs you want to run.

            jobs:

               – sign-file

5. Define a job to be invoked later in a workflow.

   jobs:

      sign-file:

6. Specify the execution environment. We must use the windows executer because signtool is needed.

   executor:

      name: win/server-2019

      size: medium

      variant: vs 2019

7. Place the working directory for the job 

   working_directory: /home/circleci/project

8. Add steps to the job See: https://circleci.com/docs/2.0/configuration-reference/#steps  

   steps:

9. Check out the source code so that the workflow can access it.

   – checkout

10. Download and Unzip eSignerCKA Setup

    – run:

          name: Download and Unzip eSignerCKA Setup

          command: |

             Invoke-WebRequest -OutFile eSigner_CKA_1.0.3.zip “https://www.ssl.com/download/ssl-com-esigner-cka-1-0-3”

             Expand-Archive -Force eSigner_CKA_1.0.3.zip

             Remove-Item eSigner_CKA_1.0.3.zip

             Move-Item -Destination “eSigner_CKA_1.0.3.exe” -Path “eSigner_CKA_1.0.3SSL.COM eSigner CKA_1.0.3.exe”

11. Install eSignerCKA

    – run:

          name: Setup eSignerCKA in Silent Mode

          command: |

                mkdir -p “/home/circleci/project/eSignerCKA”

                ./eSigner_CKA_1.0.3.exe /CURRENTUSER /VERYSILENT /SUPPRESSMSGBOXES /DIR=”/home/circleci/project/eSignerCKA” | Out-Null

12. Set SSLcom account information on eSignerCKA

    – run:

          name: Config Account Information on eSignerCKA

          command: |

                /home/circleci/project/eSignerCKA/eSignerCKATool.exe config -mode $env:MODE -user “$env:USERNAME” -pass “$env:PASSWORD” -totp “$env:TOTP_SECRET” -key “/home/circleci/project/eSignerCKA/master.key” -r

13. Unload and Load certificate to windows certificate store

    – run:

          name: Load Certificate into Windows Store

          command: |

                /home/circleci/project/eSignerCKA/eSignerCKATool.exe unload

                /home/circleci/project/eSignerCKA/eSignerCKATool.exe load

14. Select code signing certificate and get thumbprint for signing and Sign artifact with signtool

    – run:

          name: Select Certificate From Windows Store and Sign Sample File with SignTool

          command: |

                $CodeSigningCert = Get-ChildItem Cert:CurrentUserMy -CodeSigningCert | Select-Object -First 1

                & ‘C:\Program Files (x86)\Windows Kits\10\App Certification Kit\signtool.exe’ sign /debug /fd sha256 /tr http://ts.ssl.com /td sha256 /sha1 “$($CodeSigningCert.Thumbprint)” “HelloWorld.dll”

.NET Code DLL Signing Example Workflow

Prepare the components of the workflow

1. Create a .github/workflows folder on your editor. Include workflows with the folder and create a sign.yml file under the folder.
2. Name your project and the type of workflow involved 

   Name: Sign Artifact

3. Trigger this workflow on a push 

   on: push

4. Create an environment variable

   env:

    MASTER_KEY: master.key

    SIGNABLE_FILE_PATH: HelloWorld.dll

    INSTALL_DIR: C:UsersrunneradmineSignerCKA

    MASTER_KEY_FILE: C:UsersrunneradmineSignerCKAmaster.key

5. Define the jobs on your editor

   jobs:

    sign-file:

6. Run job on Windows Runner
   runs-on: windows-latest

7. Create a name. When the workflow runs, this is the name that is logged.

   name: Sign DLL File with eSignerCKA

Outline the steps for the Sign job

1. Check out the source code so that the workflow can access it.

   – name: Checkout Repository

      uses: actions/checkout@v3

2. Download and Unzip eSignerCKA Setup

   – name: Download and Unzip eSignerCKA Setup

     run: |

         Invoke-WebRequest -OutFile eSigner_CKA_1.0.3.zip “https://www.ssl.com/download/ssl-com-esigner-cka-1-0-3”

         Expand-Archive -Force eSigner_CKA_1.0.3.zip

         Remove-Item eSigner_CKA_1.0.3.zip

         Move-Item -Destination “eSigner_CKA_1.0.3.exe” -Path “eSigner_CKA_1.0.3SSL.COM eSigner CKA_1.0.3.exe”
3. Install eSignerCKA

   – name: Setup eSignerCKA in Silent Mode

     run: |

         New-Item -ItemType Directory -Force -Path ${{ env.INSTALL_DIR }}

         ./eSigner_CKA_1.0.3.exe /CURRENTUSER /VERYSILENT /SUPPRESSMSGBOXES /DIR=”${{ env.INSTALL_DIR }}” | Out-Null

4. Set SSL.com account information on eSignerCKA

   – name: Config Account Information on eSignerCKA

     run: |

         ${{ env.INSTALL_DIR }}/eSignerCKATool.exe config -mode “${{ secrets.MODE }}” -user “${{ secrets.USERNAME }}”

        -pass “${{ secrets.PASSWORD }}” -totp “${{ secrets.TOTP_SECRET }}” -key “${{ env.MASTER_KEY_FILE }}” -r

5. Unload and Load certificate to windows certificate store

   – name: Load Certificate into Windows Store

     run: |

         ${{ env.INSTALL_DIR }}/eSignerCKATool.exe unload

         ${{ env.INSTALL_DIR }}/eSignerCKATool.exe load
6. Select code signing certificate and get thumbprint for signing

   – name: Select Certificate From Windows Store

     run: |

         $CodeSigningCert = Get-ChildItem Cert:CurrentUserMy -CodeSigningCert | Select-Object -First 1

         echo “THUMBPRINT=$($CodeSigningCert.Thumbprint)” >> $env:GITHUB_ENV
7. Sign artifact with signtool

   – name: Sign Sample File with SignTool

     run: |

         & ‘C:\Program Files (x86)\Windows Kits\10\App Certification Kit\signtool.exe’ sign /debug /fd sha256 /tr http://ts.ssl.com /td sha256 /sha1 ${{ env.THUMBPRINT }} ${{ env.SIGNABLE_FILE_PATH }}
   
   
   Note: If error occurs when using the x64 version of SignTool, use the x86 version. For example: C:\Program Files (x86)\Windows Kits\10\bin\10.0.22621.0\x86\signtool.exe
   
   You can also refer to this sample workflow for signing: https://github.com/SSLcom/esigner-sample/blob/main/.github/workflows/sign.yml#L37
   

.NET Code DLL Signing Example Workflow

Define the components of the workflow

1. Create a yml file as .gitlab-ci.yml under the folder.
2. Used to select runners from the list of available runners. A runner must have all tags listed here to run the job.

   .windows_runners:

         tags:

               – shared-windows

               – windows

               – windows-1809

3. Groups jobs into stages. All jobs in one stage must complete before next stage is executed.

   stages:

         – sign

4. Below is the definition of your job to sign file. Define what stage the job will run in.

   sign-file:

        stage: sign

5. The name of one or more jobs to inherit configuration from.

   extends:

        – .windows_runners
6. Write the script to sign the file.

   script:

   # Download and Unzip eSignerCKA Setup

      – powershell.exe -ExecutionPolicy Bypass -Command ‘Invoke-WebRequest -OutFile eSigner_CKA_1.0.3.zip “https://www.ssl.com/download/ssl-com-esigner-cka-1-0-3″‘

      – powershell.exe -ExecutionPolicy Bypass -Command ‘Expand-Archive -Force eSigner_CKA_1.0.3.zip’

      – powershell.exe -ExecutionPolicy Bypass -Command ‘Remove-Item eSigner_CKA_1.0.3.zip’

      – powershell.exe -ExecutionPolicy Bypass -Command ‘Move-Item -Destination “eSigner_CKA_1.0.3.exe” -Path “eSigner_CKA_1.0.3SSL.COM eSigner CKA_1.0.3.exe”‘

   
   

   # Setup eSignerCKA in Silent Mode

   – powershell.exe -ExecutionPolicy Bypass -Command ‘./eSigner_CKA_1.0.3.exe /CURRENTUSER /VERYSILENT /SUPPRESSMSGBOXES /DIR=”C:Usersgitlab_runnerDesktopeSignerCKA”‘

   
   

   # Check installation directory

   – powershell.exe -ExecutionPolicy Bypass -Command ‘dir C:Usersgitlab_runnerDesktopeSignerCKA’

   
   

   # Config Account Information on eSignerCKA

   – powershell.exe -ExecutionPolicy Bypass -Command ‘C:Usersgitlab_runnerDesktopeSignerCKAeSignerCKATool.exe config -mode ${MODE}

        -user “${USERNAME}” -pass “${PASSWORD}” -totp “${TOTP_SECRET}” -key “C:Usersgitlab_runnerAppDataRoamingeSignerCKAmaster.key” -r’

   
   

   # Unload Certificate into Windows Store

   – powershell.exe -ExecutionPolicy Bypass -Command ‘C:Usersgitlab_runnerDesktopeSignerCKAeSignerCKATool.exe unload’

   
   

   # Load Certificate into Windows Store

   – powershell.exe -ExecutionPolicy Bypass -Command ‘C:Usersgitlab_runnerDesktopeSignerCKAeSignerCKATool.exe load’

   
   

      # Check data directory

      – powershell.exe -ExecutionPolicy Bypass -Command ‘dir C:Usersgitlab_runnerAppDataRoamingeSignerCKA’

   
   

      # Check config data directory

      – powershell.exe -ExecutionPolicy Bypass -Command ‘dir C:Usersgitlab_runnerAppDataRoamingeSignerCKAConfig’

   
   

   # Select Certificate From Windows Store

   – powershell.exe -ExecutionPolicy Bypass -Command ‘$CodeSigningCert = Get-ChildItem Cert:CurrentUserMy -CodeSigningCert | Select-Object -First 1; echo $CodeSigningCert.Thumbprint > .Thumbprint’

   # Debug Certificate Thumbprint

   – powershell.exe -ExecutionPolicy Bypass -Command ‘Set-Variable -Name Thumbprint -Value (Get-Content .Thumbprint); echo $Thumbprint’

   
   

   # Sign Sample File with SignTool

   – powershell.exe -ExecutionPolicy Bypass -Command “Set-Variable -Name Thumbprint -Value (Get-Content .Thumbprint);

        ‘C:Program Files (x86)Windows Kits10bin10.0.17763.0x86signtool.exe sign /debug /fd sha256 /tr http://ts.ssl.com /td sha256 /sha1 $Thumbprint HelloWorld.dll'”

.NET Code DLL Signing Example Workflow

Define the components of the workflow

1. Create a yml file as .travis.yml under the root folder.
2. Place the CPU Architecture to run the job on.

   arch: amd64

3. Default language to run jobs on Travis CI
   

   language: csharp

4. The Operating System to run the job on
   

   os: windows

5. Specify the order of stages. All jobs in one stage must be completed before the next stage is executed.
   

   stages:

     – sign

6. Define the build stage
   

   jobs:

     include:

        – stage: sign

7. The job name

   name: sign-file

8. The operating system to run the job on

   os: windows

9. Current language to run jobs on Travis CI

   language: c

10. Write the Before script to run before building the project

    before_script:

        – powershell.exe -ExecutionPolicy Bypass -Command ‘New-Item -ItemType Directory -Force -Path C:Userstravisbuildesigner-sampleeSignerCKASSLcom’

11. Write the script to build the project.

    script:

    # Download and Unzip eSignerCKA Setup

    – powershell.exe -ExecutionPolicy Bypass -Command ‘Invoke-WebRequest -OutFile eSigner_CKA_1.0.3.zip “https://www.ssl.com/download/ssl-com-esigner-cka-1-0-3″‘

    – powershell.exe -ExecutionPolicy Bypass -Command ‘Expand-Archive -Force eSigner_CKA_1.0.3.zip’

    – powershell.exe -ExecutionPolicy Bypass -Command ‘Remove-Item eSigner_CKA_1.0.3.zip’

    – powershell.exe -ExecutionPolicy Bypass -Command ‘Move-Item -Destination “eSigner_CKA_1.0.3.exe” -Path “eSigner_CKA_1.0.3SSL.COM eSigner CKA_1.0.3.exe”‘

    
    

    # Setup eSignerCKA in Silent Mode

    – powershell.exe -ExecutionPolicy Bypass -Command ‘./eSigner_CKA_1.0.3.exe /CURRENTUSER /VERYSILENT /SUPPRESSMSGBOXES /DIR=”C:Userstravisbuildesigner-sampleeSignerCKASSLcom” | Out-Null’

    
    

    # Check installation directory

    – powershell.exe -ExecutionPolicy Bypass -Command ‘dir C:Userstravisbuildesigner-sampleeSignerCKASSLcom’

    
    

    # Config Account Information on eSignerCKA

    – powershell.exe -ExecutionPolicy Bypass -Command ‘C:Userstravisbuildesigner-sampleeSignerCKASSLcomeSignerCKATool.exe config -mode ${MODE} -user “${USERNAME}”

       -pass “${PASSWORD}” -totp “${TOTP_SECRET}” -key “C:Userstravisbuildesigner-sampleeSignerCKASSLcommaster.key” -r’

    
    

    # Unload Certificate into Windows Store

    – powershell.exe -ExecutionPolicy Bypass -Command ‘C:Userstravisbuildesigner-sampleeSignerCKASSLcomeSignerCKATool.exe unload’

    
    

    # Load Certificate into Windows Store

    – powershell.exe -ExecutionPolicy Bypass -Command ‘C:Userstravisbuildesigner-sampleeSignerCKASSLcomeSignerCKATool.exe load’

    
    

    # Select Certificate From Windows Store

    – powershell.exe -ExecutionPolicy Bypass -Command ‘$CodeSigningCert = Get-ChildItem Cert:CurrentUserMy -CodeSigningCert | Select-Object -First 1; echo $CodeSigningCert.Thumbprint > .Thumbprint’

    
    

    # Debug Certificate Thumbprint

    – powershell.exe -ExecutionPolicy Bypass -Command ‘Set-Variable -Name Thumbprint -Value (Get-Content .Thumbprint); echo $Thumbprint’

    
    

    # Sign Sample File with SignTool

    – powershell.exe -ExecutionPolicy Bypass -Command “Set-Variable -Name Thumbprint -Value (Get-Content .Thumbprint); ‘C:Program Files (x86)Windows Kits10binx64signtool.exe sign /debug /fd sha256 /tr http://ts.ssl.com /td sha256 /sha1 $Thumbprint HelloWorld.dll'”