Documentation

If you have any questions that are beyond the scope of this help file, Please feel free to email via Support Page.

Administrative Guide

Copyright 2025 Encryption Consulting LLC. All rights reserved.

Copyright in this document is the property of Encryption Consulting LLC. It is not to be reproduced, modified, adapted, published, translated in any material form (including storage in any medium by electronic means whether or not transiently or incidentally) in whole or in part nor disclosed to any third party without the prior written permission of Encryption Consulting LLC neither shall it be used otherwise than for the purpose for which it is supplied.

Words and logos marked with ^® or ^™ are trademarks of Encryption Consulting LLC or its affiliates in the EU and other countries.

Mac and OS X are trademarks of Apple Inc., registered in the U.S. and other countries.

Microsoft and Windows are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

Linux® is the registered trademark of Linus Torvalds in the U.S. and other countries. Information in this document is subject to change without notice.

This software and all subsequent code are provided “as is”. Encryption Consulting LLC makes no warranty of any kind concerning this information, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. Encryption Consulting LLC shall not be liable for errors contained herein or for incidental or consequential damages concerned with the furnishing, performance, or use of this material.

Introduction

This document discusses the administrative responsibilities and how to manage the server, client, keys, and other resources corresponding to CodeSign Secure 3.02's application. Section 2 (Introduction) - Section 10 (System Setup) cover how to use our CodeSign Secure web application and explain all its features.
Section 11 (User Trust Integrity) - Section 12 (Signing Capabilities) explains how to install, configure, and use our signing tools. Section 13 (CI/CD Integration) deals with CI/CD pipeline and automation.
We provide compatibility with Entrust nShield HSM and Thales Luna HSM, and all the signing operations have been thoroughly tested to guarantee smooth integration and optimal performance with the firmware and software versions as listed below:

1. Entrust nShield HSM

   • Firmware: 13.4.4-316
   • Software: 12.72.3

2. Thales Luna HSM

   • Firmware: 10.7.1-125
   • Software: 7.3.0

User Login/Setup

Access to the Code Signing server is done through your Azure Active Directory account. Go to codesignsecure.encryptionconsulting.com and enter your Microsoft account credentials. Once login is successful, you can access the CodeSign Secure web platform.

NoteIf 2-Factor Authentication is enabled, the user will be asked for an authentication code.

Setting up Certificate based authentication using pfx files

Navigate to the system setup tab in the CodeSign secure dashboard. This is the last option in the navigation pane on the left-hand side of the UI. Then you can click on the User tab and create a new certificate from the drop down on the right side of the screen.

Create a new certificate

Click on the Generate Authentication Certificate button from the drop down. After generating the certificate using the dashboard, a .pfx file will be downloaded, and a password will be supplied. This password is not retrievable, so store it somewhere safe and secure.

Setting up your environment

Set the following three environment variables. To do this, open your control panel and search for environment variables.

Select “Edit the system environment variables.”

Create three new Environment variables using the “New” option one at a time.

EC_SSL_VERBOSE         <0/1>

0: no detailed logging output (including on tools like signtool)

1: detailed verbose debug output

EC_Client_Auth         <path to .pfx file>

EC_Client_Pass         <password for .pfx file>

CodeSign Secure dashboard and UI

When the administrator signs in to the management console, they get welcomed to a dashboard with several options available on the sidebar. The APIs used for the signing process can be accessed by clicking the API button at the top right side of the window, next to your account name. You can find the download page for all of our related tools on the Signing Tools tab on the left side of the window (more on Section 11). If you do not see signing tools, you can expand the pane on the left side of the window by clicking on the 3 bars on the left side of the screen under the “EC” and “CodeSign Secure” logo.

We will talk about each option in detail and how to manage them.

The CodeSign secure dashboard provides a variety of information on signing activity.

The top left corner of the white pane includes details on requests under the Quick Insight category. Next to this is the pane about the number of signing KSPs consumed out of the total KSPs bought. Below the requests and KSP pane, you can verify the integrated HSM's status and health.

The top right corner of the dashboard lets you view the number of signing operations done each month; using the drop-down, you can filter by application, environment, or certificate.

On the bottom left is a bar chart showing the expiration dates for various certificates used for signing. By clicking on the bars, you filter the table below by that time frame. The table below shows the certificate name and the exact date of expiry.

Keys and Certificates

On this page, you'll see a chart with all keys listed and their names in the Key Name column. The chart also lists each key's UID, corresponding Algorithm, key Size, Status, Expiration, and Key Usage. Clicking on a row will also show additional information about the key.

In the Action column all the way to the right side, clicking the ⋯ will open up an option panel for three actions, either to edit the status of a key, to set up an email trigger, or to set the key usage. As shown below, a key status can be changed to Active or Inactive.

The second option listed is to set up an email trigger. This option, when enabled, will send an email to the provided email address when the Certificate expires. This can be useful as a reminder to avoid using old keys that need to be rotated.

The third option is to update the key usage of the certificate. This is necessary while implementing Reproducible build with CodeSign Secure. Using this you can update your key for either pre hash validation (done before signing) or for post hash validation (done after signing).

Application Management

This section deals with the ongoing projects/applications that are being developed. Each application has a name alongside the administrator owners assigned to them. You can create a new application by clicking the button at the top right of the window, you will be guided through the application creation process.

Every application deals with specific file types that are saved as artifacts. Clicking the … in the actions pane will display details about the application.

The application can have multiple environments, but each environment has one certificate corresponding to it. Each environment can be separately configured to have Multi-Factor Authentication in place for signing. If one of the entities disapproves, then the document cannot be signed.

Editing and Creating Applications

The Application Management window allows admins to manage each application and their corresponding environments. They can also deactivate applications if the project is no longer active.

To change the active applications, you can click on edit. There are four sections available; this process is also the same for creating a new application:

Application Details

This portion deals with the basic information regarding the application. It contains information such as

• Application Name
• Status, which can be active or inactive
• Description
• URL of a source code repository for informational purposes
• Business Unit which is what organizational unit of your business this application applies to
• Application Owners, which lists the account that has control over the application settings.

You can also see the Artifact Types box, which depending on which types of files the application signs, will need to have different types listed.

The type of files that owners wish to be signed need to be present in the artifact types. If, for example, .exe files are not mentioned in artifact types, .exe files cannot be signed.

Create Certificate

On this page, the admin is able to add environments, and create and choose a certificate for each environment.

Environments can be added using the Add Environment button at the top right of the window. Clicking on the environment dropdown button will give you a list to select from and the option to create a New Environment by typing a name and then pressing save. It's also possible to delete an environment using the trash bin icon. Once you select which environment the application will use, you can specify which Certificate to use. You also have the option to create a new certificate as well. Clicking Create Certificate will allow you to specify the following information:

• Certificate type
• Name
• Description
• Common name
• Organization
• Organizational unit
• E-mail address to be stored in the certificate
• Which key algorithm to use
• Validity time periods
• Country code
• State/province
• Locality
• Scope

When a certificate is created, the environment also creates a corresponding key pair, which is saved on the HSM. When the certificate is chosen, the corresponding key pair is used for the server's sign/verify operation.

Team Management

This section allows to create, update, or assign Teams for a specific certificate.

When a certificate is assigned to a specific environment within the application, access to that certificate can be restricted by assigning a team to it. The team will consist of authorized users who can utilize that certificate to perform operations.

To create a new team, click the Create Team button located at the top right of the screen. From there, you can enter the team name and add authorized members.

To manage an existing team, click on the Manage Team button in the top right of the window. Update the Team name or the authorized members list for that team.

Policy Details

This section deals with users who can access each environment. By clicking on the Signing Users text box, type in the email address associated with the person's account to add their access. It's possible to give different users access to different environments, and whether or not multi-factor authentication (MFA) is required. Approval type can also be specified, with Owner, Quorum, or No Approval options, along with approval type and MFA.

For Quorum-based approval, approval from multiple users to sign is required. This can act as a secure way of signing and deploying code into production. Owner-based approval requires approval from the owner/creator of the application. Manager approval requires approval from the specified application manager.

Signing Request

This section shows the admin the signing requests made to the server. This includes the date of the submission as the status of the request. Click on the application name to get a pop-up of the details. The status can be any of the below options:

• Approved
• Rejected, and
• Pending

Each status is color-coded for easier and faster interpretation. You can select the ⋯ on the action column to Approve or Reject signing requests.

Signing Tools

Clicking on the Signing Tools tab on the far left side of the screen will take you to the download page for each of CodeSign Secure's signing tools. You can filter by Operating System by clicking on the dropdown tab on the left side of the window and also search by name on the right side of the window.

Reports

This section displays reports regarding the environment. Reports can include details such as which users logged into the environment and more. Each of these reports has a timestamp in the leftmost field. Four types of reports are generated:

• Signing request

  The requests submitted for signing, concerning who submitted the request, regarding which application, and the job id to the corresponding request.

• Approval Request

  This generates a report of who approved the job, the job id, and the date the job was approved.

• Audit Trail

  This contains a record of users who logged into the admin console, and a message output will show any actions taken.

• Certificate

  This includes a record of the certificate name, who created the certificate, creation date, and expiry date.

• Client

  This includes the record of the Client IP, username and the creation date.

At the top right of the table, there is an option to export the listed information in different formats including PDF, CSV, or Syslog. If you click on the date, you can expand the report.

Logging

This page is similar to the Reports page but has more detailed logging as far as what code is being executed. Several fields are listed on the page as shown below:

• Event Time
• Action
• Severity
• Log Details

This can be useful if the exact process of any specific action needs to be observed, for example, specific response codes that can be useful for resolving issues.

At the top right of the table, there is an option to export the listed information in different formats, including CSV, or Syslog. If you click on the date, you can expand the log.

System Setup

This section has multiple subsections, with each controlling and containing different parts of the environment.

Identity Store

This is where we can control the identities that can be used to log into the environment. There are two major ways to maintain identities:

• Active Directory (AD)
• Single Sign-On (SSO)

AD and SSO can be added into the identity store, where we can also disable them, if needed.

Active Directory

With active directory you can choose different types including Azure AD or Local AD.

Single Sign-On

Integrating your Single Sign on capabilities with CodeSign Secure.

Backup

The section ensures the safety and security of the data. It allows to create a complete backup of the application data at any time. These backups can then be downloaded with a backup name and event time. Additionally, this section keeps track of past backups, allowing to restore or download any previous version if needed.

Navigate to backup section in System setup and click on Take Backup. You also have the option to download and restore any previous backup.

User Management

This sections allows to administer all the user accounts and view the essential information, including their email address, username, the date their account was created, and their current account status (locked or unlocked). You can filter by User Role by selecting the dropdown button and searching for a specific user using the search bar.

Clicking on the … associated with each user allows to manage user accounts in more detail. It provides advanced user management options, allowing to update user details, modify account status (locked/unlocked), or even delete the user entirely.

By clicking on a user's email address, a detailed view of the user profile can be overseen including their assigned roles within the application. Additionally, all SSL certificates associated with the user can be viewed which are categorized by their validity status (valid, disabled, or expired). Each certificate entry displays information such as the creation date, expiration date, and the certificate thumbprint.

This section also allows more functionalities such as:

1. Register User

   This feature allows to register a new user who will be able to access the application

2. Generate API Key

   This generates an exclusive Authorization Token with an expiry date choice of 30, 60 or 90 days from the date of creation.

3. Generate Authorization Certificate

   Corresponds to the creation of a SSL Authentication Certificate for a user by providing details such as Username, Certificate Name and Expiry Date.

User Permissions

This section allows to manage user access within the CodeSignSecure application by defining roles and their corresponding permissions. There are 5 roles in the application:

1. System Admin

   Oversees and manages the entire Codesign Secure platform, ensuring system integrity, security, and accessibility.

2. Project Manager

   Coordinates application timelines, resources, and team collaboration to meet project objectives efficiently.

3. Security Officer

   Focuses on implementing and maintaining robust security measures to protect data and manage platform vulnerabilities.

4. Auditor

   Conducts thorough reviews and audits of platform processes and security to ensure compliance with standards and regulations.

5. Developer

   Maintains platform features, working on software development and technical problem-solving.

Clicking Edit will present a window with some changeable parameters, allowing you to edit the permissions associated with each role:

1. Download Syslog Report

   This allows you to download the Syslog report of the Audit Trail in your local system.

2. View audit report

   This allows you to view and investigate all the reports in the Reports Tab.

3. View log report

   This allows you to access and investigate the logs in the Logging tab.

4. Generate CSR

   This lets you create code-signing CSR and download it in your local system.

5. Import Certificates

   This allows you to upload your signed certificate from your PKI into our CodeSign Secure platform.

6. Create Self-Signed Certificates

   This lets you create a Self-Signed code-signing certificate from our platform and download it into your local system.

7. Sign tools

   This allows you access to the Signing Tools tab and download the required tools.

8. Download Syslog Logging

   This allows you to download a Syslog file for the Logs into your local system.

9. Application creation

   This allows you to create an Application in the Application Management tab.

10. Environment creation

    This allows you to create a new Environment or use an existing one while creating/editing an Application.

11. Policy Selection

    This lets you select the signing Policy for the Environment you created or assigned inside the Application.

12. Signing requests decision

    This allows you to either Approve or Reject the signing request for your specific application inside the Signing Requests tab.

13. Email Configuration

    This allows you to setup new configurations for email responses.

14. Email Template

    This allows you to create new template or edit existing templates.

15. SSL Authentication certificate creation

    This lets you generate a P12 SSL certificate for your client system.

16. API Key creation

    This lets you generate JWT Token/API Key for running the APIs in your client system.

17. Backup Dump

    This allows you to take a backup dump and restore this Backup on the server.

18. Register User

    This lets you add new user to the CodeSign Secure platform.

19. Origin verification configuration

    This allows you to configure the changes in your Certificates table to choose the type of hash verification.

20. User Role Assign

    This allows you to grant roles to a user present in the platform.

21. Activate License

    This lets you add your key inside the Activate License section to activate the license for specific days.

22. CodeSigning Operation

    This allows you to perform Sign and Verify operation via our platform.

23. Add Identity Store

    This allows you to add an Identity Store, which will be used in the Authentication and signing process.

24. API Access

    This allows you to access and use our APIs in your local client system separately.

25. Team Management

    This permission allows the Project Manager to create, update, or assign Teams for a specific certificate.

26. Upload SSL/TLS Certificate

    This allows you to upload your own SSL or TLS certificate in the CodeSign Secure server for the web portal.

Email

This section allows to create and manage email templates and SMTP configurations, within the organisation. It consists of two functionalities:

1. Email Template

   It allows to create an email template by providing fields like name, subject and status. An actions tab is provided with edit and archive option that allows to modify the details of the template and set the status of the template as Active or Inactive respectively.



2. SMTP config

   This allows you to setup new configurations for email responses by providing the host name, username, port number and password. It also has an actions tab to edit details and update the status of a particular SMTP config.

Signing Projects

This section manages the projects that utilise the reproducible build setup. It allows to create a new project by providing details:

1. Project Name

   Corresponds to descriptive name for the project.

2. Source Code Management

   Corresponds to the source code repository URL (git), access credentials and allowed branches.

3. Build Commands

   Corresponds to the environment variables, build command, build file location, and signer type (SignTool with KSP or JarSigner with KSP).

4. Build Server

   Corresponds to the details of the build server URL (Jenkins) and access credentials.

5. Email

   Corresponds to the email to receive signing status notifications.

SSL/TLS Management

This section allows you to manage the SSL/TLS certificate for the web portal. It displays the information for the certificate which is/was currently being used. The status of the current certificate will be set to Active and can be downloaded as well but can't be deleted. It also shows the certificates which were being used earlier with their status as Inactive. They can be both deleted and downloaded.

By clicking on a specific certificate's UID, you can also view the detailed information for that certificate,

This section provides the following features:

1. Generate CSR

   The CSR generation functionality to easily create a CSR which can used by a certificate authority (CA) to issue an SSL/TLS certificate the web portal.

   

2. Import Certificate

   This functionality can be used to import a SSL/TLS certificate generated from a Certificate Authority (CA).

   

3. Renew Certificate

   This feature allows you to renew your existing SSL/TLS certificate which is currently being used for the web portal.

   

SBOM

SBOM or Software Bill of Materials provides a clear view into the composition of software/code, enabling you to check your Code’s vulnerability and push the safe code onto GitHub.

To run a SBOM scan, perform the following steps:

1. Go to System Setup section on CodeSign Secure web portal.

2. Open the SBOM tab under it.

   

3. Click on Scan Code button.

   

4. Enter the following details:.

   

5. To get GitHub PAT follow the following steps:

   • Go to your GitHub settings section and open Developer Settings.

     

   • Under Personal access tokens, select Tokens (classic)

     

   • Then click on Generate new token (classic)

     

   • After that enter the Token Note and under scopes give permission for repo and workflow

     

6. Upload your code in a zip file and click on Submit button

   

7. If the code vulnerability is less than your input vulnerability percentage, you’ll get a success message.

   
   

8. If the code has more vulnerability percent, then you’ll get a warning message

   

User Trust Integrity

Reproducible Build

Reproducible build refers to the process of building software so that the result can be replicated bit-for-bit by anyone who follows the same steps using the same source code, build environment, and tools.

CodeSignSecure facilitates this feature, helping users trust the source of the software and avoid signing malicious code. It involves using automated tools to analyse the build process and verify the integrity of the final software code.

Automated Hash Validation

Automated hash validation is a security process that uses cryptographic hash functions to ensure the integrity and authenticity of data throughout an automated workflow.

1. Pre-Sign Hash Validation

   Pre-sign hash validation is a step in the automated hash validation process before the code is signed.

2. Post-Sign Hash Validation

   Post-sign hash validation is another step within the automated hash validation process, but it occurs after the code has been signed with cryptographic keys.

Reproducible Build Process Flow

Prerequisites for performing this task includes:

• A GitHub repository
• Signtool installed and configured
• ECSigning KSP installed and configured
• Jenkins Build Server and Project

To install and configure Signtool and the ECSigning KSP, please follow the steps mentioned here.

Before we get started, we will need to configure a Source Code Repository (i.e. GitHub). This version control system manages the commits for the builds pushed in the repository.

After configuring the source code repository, we will need to add a project on the Jenkins server to access the latest commit in the repository.

• Sign into Jenkins

  

• To create a new Pipeline, go to New Item from the sidebar

  

• Enter the item name and select Pipeline from the list of services provided

  

• Then the configuration tab will open to modify the settings of the project.

  

• Enter the required details and information for the Pipeline. Here we are adding the String Parameters to convey the branch name of source code repository from which the latest builds will be accessed.

  

• Then we need to provide the Pipeline Script for the Reproducible Build.

Pipeline Script Components

• Pipeline Definition: Defines the overall pipeline structure (e.g., pipeline { ... }).
• Stage: Groups related steps into logical phases (e.g., stage('Build') { ... }).
• Condition (Optional): Controls execution based on certain criteria (e.g., when { expression }).
• Error Handling (Optional): Manages unexpected situations during pipeline execution.

• Shared Resource (Optional): Reusable component (function/library) for multiple pipelines.

  

  A sample script for Jenkins project is provided below.

                                      
                                          pipeline {
                                              agent any
                                              parameters {
                                                  string(name: 'BRANCH_NAME', defaultValue: 'main', description: 'Branch to build')
                                              }
                                              stages {
                                                  stage('Checkout') {
                                                      steps {
                                                          script {
                                                              // Checks out the existence of the specified branch in the repository
                                                              checkout([$class: 'GitSCM', branches: [[name: params.BRANCH_NAME]], userRemoteConfigs: [[url: 'https://github.com/shivamSharmaMWP/reproducible_dotnet.git', credentialsId: 'shivamSharmaMWP']]])
                                                          }
                                                      }
                                                  }
                                           
                                                  stage('Build') {
                                                      steps {
                                                      // Provide the build command according to source code language
                                                          bat 'dotnet build'
                                                      // Archive the unique versions of the specified file
                                                          archiveArtifacts artifacts: 'bin/Debug/net7.0/reproducible_dotnet.exe', fingerprint: true
                                                      }
                                                  }
                                                  
                                                  stage('Sign') {
                                                      steps {
                                                      // Provide extra Signing Project Parameters – required for this setup
                                                          bat "echo {\"codesign_signing_project_id\": 2, \"codesign_build_job_id\": ${env.BUILD_NUMBER}} > signing_parameters.json"
                                                      // Provide Signing command 
                                                          bat 'set EC_SIGN_PARAMS=.\\signing_parameters.json && signtool sign /csp "Encryption Consulting Key Storage Provider" /kc onetech /fd SHA256 /f c:/websites/onetech.crt /tr http://timestamp.digicert.com /td SHA256 bin/Debug/net7.0/reproducible_dotnet.exe'
                                                   // Archive the unique versions of the specified file
                                                          archiveArtifacts artifacts: 'bin/Debug/net7.0/reproducible_dotnet.exe', fingerprint: true
                                                      }
                                                  }
                                              }
                                          }                                
                                      
                                  

• Save the configuration for the pipeline. This will create a build project on Jenkins server.

  

  Jenkins Project is configured in such a way that every build job must contain a commit that it uses to pull the specific version of source code.

  

  You can adjust your pipeline so that whenever a new commit is made to the source code in the repository, it should trigger a new build started on the Jenkins server for that specific commit, like above.

To access reproducible build functionality from the CodeSignSecure Server

• A signing project must be added with the source code repository details
• Provide the build commands
• Add the Build server (Jenkins) project details
• Add the email to receive signing status notifications

To add a Signing Project on CodeSignSecure server:

• Go to the System setup tab and click on Signing Projects

  

• Click on add Signing Project. An input form will open to take the required details of the project

  

• Project Name: Corresponds to the name of the Project that you want to use Hash verification for.
• Source Code Management: As per best industry standards, we're supporting GitHub for now.
• Git Reprository URL: Corresponds to the URL of your configured repository.
• Git Username & Password: Corresponds to the credentials for login into your git.
• Git Allowed Branches (Optional): Corresponds to specific branches from which the builds will be accessed.
• Environment Variables: Corresponds to any variables required for the project.
• Build Command: Corresponds to the command that will be used to create the build files from repository.
• Build File Path: Corresponds to the location to store the created build file.
• Build Server: As per best industry standards, we're supporting Jenkins for now.
• Build Signer Type: As per industry standards, we're supporting SignTool with KSP and JarSigner with KSP tools.
• Jenkins URL: Corresponds to the URL of the Jenkins project that you have created for the pipeline.
• Jenkins Username & Password: Corresponds to your credentials to access the Jenkins server and project.
• Email Recipient: Corresponds to your email to get notified regarding the status of Code Signing.

After providing the build settings, the project will be created, and details can be overviewed by selecting the specific project.

Now, use the Certificate or Key from CodeSignSecure keys list required for signing the code.

• To create a new Key and Certificate, go to the Keys and Certificates tab on CodeSignSecure and click on Add new Certificate

  

• Provide the details regarding the Key & Certificate creation in the input form.

  

• Reproducible Build Key Usage: This tells whether the key will be used for Pre-Sign Hash Validation or Post-Sign Hash Validation or none of these. This is required for the Hash validation of the latest build and verify the origin of the file.

  To see the details about a specific key & certificate, click on the respective certificate's UID.

  

  With this setup, whenever you submit the signing request via Signtool, it will automatically pass extra parameters of the Signing Project ID and Build Job ID within the signing request.

  It fetches commit revision and build job ID at code signing time. If parameters are not up to mark in this process, code signing will be declined

Hash Validation

The CodeSignSecure server will receive the incoming hash. If the validation is successful, it will proceed with the code signing.

For hash validation, the incoming hash from the client is matched with the hash generated from the Jenkins pipeline. Automated validation depends on the key usage, i.e., Pre-sign or Post-sign.

• If the hashes match, a success notification is sent to the email mentioned when creating the signing project on the CodeSign application. Now, the code is considered authentic and proceeds to the code signing stage.

  

• If the hashes differ, a failure/error notification is sent to the user on the email.

  

  

  On Successful validation, the build will be signed using the cryptographic key and certificate created on our CodeSignSecure platform.

Signing Tools

Through the CodeSign Secure web platform, we have made available several tools that can handle different types of signing operations. Each tool listed below has a detailed explanation of how they work, how they are installed, and what files they can sign. All of these can be downloaded from the CodeSign Secure Website.

Windows Signing

Our Windows Signing tool can sign all types of Windows files including .exe, .dll, .sys, and more.

Windows Configuration

To install the client tools:

• Sign in to CodeSign Secure

• Navigate to: Signing tools repository.

  

• Download "Encryption Consulting CNG-SigningKSP"

• Install the client tools using the .MSI installer. The .MSI installer automates much of the configuration. Navigate to where the downloaded file is saved and launch the installer

  

• Click next when the installation wizard appears.

  

• Click next

  

• In the Username field, type admin.

• In the Code field, copy the code that you've defined in your configuration file (conf.ini).

  

• Change the Identity Type to 1.
• Leave API BaseURL the same.
• Click next

• Click next

  

• You will then be notified that this program will make changes to your pc, click yes.

  

• Installation is now complete

  

• After installing the KSP, we need to update the Environment Variables

  1. Click on Start menu and search for Environment Variables

     

  2. Click on Environment Variables

     

  3. Add new system variables by clicking on New button. Provide the following variable name and there corresponding details.

     • EC_Client_Auth : Corresponds to the path of your SSL Authentication certificate which can be created from CodeSignSecure

       

     • EC_Client_Pass : Corresponds to the password of your certificate which is provided at the time of creation of the certificate.

     • EC_SSL_VERBOSE : Corresponds to the setting to either enable (1) or disable (0) the debugging output for EC KSP.

       

• We also need add the “ectoken” in the Registry Editor

  1. Click on Start menu and search for “Registry Editor”

     

  2. Go to HKEY_CURRENT_USER -> Software -> Encryption Consulting -> SigningKSP

     

  3. Get the ectoken from CodeSignSecure

     

  4. Update the field with the token generated from CodeSign Secure platform.

     

• Using the following download link, download the Windows Software Development Kit with the following tools selected: developer.microsoft.com/en-us/windows/downloads/windows-10-sdk/

  

• Open the installer once downloaded and select next on the first screen

  

• Select next

  

• Select Accept

  

• Deselect everything except "Windows SDK Signing Tools for Desktop Apps" and select install

  

Go to the following path where the tools should have downloaded to: C:\Program Files (x86)\Windows Kits\10\bin\10.0.19041.0\x64.

Ensure you are in the x64 directory, copy the directory path, and search environment variables in the bottom searchbar of your taskbar. The following window should appear when selecting environment variables:

Select Environment Variables at the bottom right. Scroll down through the system variables on the bottom table until you find PATH in the variable names.

Double click on PATH in system variables and select new on the left of the screen. Paste your copied directory path into the new selection.

Select OK at the bottom right of each page.

Apple Signing

Using CodeSign Secure and our Apple Signing CSP, you have the ability to quickly and efficiently set up your environment to sign any type of Apple file including .app, .dmg, .pkg, .ipa, and .mpkg files with ease. Configuration of your Mac to run our Apple CSP is a very quick and easy process.

Prerequisites: Ensure you have a username and access to the CodeSign Secure webpage.

• From the CodeSign Secure webpage, go to the Signing Tools section and download the EC Provider for Mac.

  

• Unzip the file and transfer the unzipped file to the Applications folder. From here, run the ECCssProvider application.

  

• Ensure you have your CodeSign Secure URL, Username, and code entered into the application and then select refresh. The Page should now show different certificates you have access to for signing.

  

• Now, we must set up the P12 certificate for access to signing on the server. First, go to the CodeSign Secure Webpage and select the settings section. From here, select “User”. Finally, on the drop-down menu on the right, select “Generate Authentication Certificate”.

  

• Enter the Certificate Name, UserName, and Expiration Date of the P12 certificate, then select the “Generate” option. A p12 certificate should be generated and downloaded to your machine. Save the password of the certificate as well as the certificate itself.

  

• Double-click your newly downloaded P12 certificate and open it with the application “Key Chain Access.” It should prompt you for the administrator password and the certificate password, which will put the certificate in your System key chain.

  

• After putting the authentication certificate into your key access chain, open the key itself. It should be in the drop-down of the authentication certificate. Right-click it and select get info. From there, select access control and allow access to the certificate using the ECCssProvider.app application. You will likely need to restart your machine to see that permission actually changes.

  
  

• Next, ensure you have the full certification path of the certificate you will be signing within your Keychain Access. Mac devices tend not to start with the known Certification chains like Windows machines do, so if you are using an OV/EV certificate for signing, you must upload that entire certification chain.

  

• Now, we need to run the following command:

                      
                        /Applications/ECCssProvider.app/Contents/MacOS/ECCssProvider –batch –tlsclient <Auth Cert Name>
                      
                    

  This command will set the authentication certificate we uploaded as the TLS authentication certificate when connecting to the CodeSign Secure server.

  

• Now, we need to run:

                      
                        security export-smartcard -I com.encryptionconsulting.ECCssProvider.CssToken:ECCSS
                      
                    

  This command pulls up all of the certificates listed in the ECCssProvider GUI and details about those certificates.

  The important detail we need is the SHA1 hash of that certificate. We will use that hash to determine which certificate we are signing with. The certificates are in the same number order as they appear in the GUI.

  

• Finally, we run our codesign command:

                      
                        codesign -f -s <Hash of the Certificate for signing> <Application or file to be signed>
                      
                    

  The -f flag is for overwriting old signatures on files, and the -s flag is to specify what we are signing. Then, we provide the hash of the certificate we are using and the path to the file to be signed. As you can see below, this is our expected output on the signing command.

  

SignTool (MS Authenticode)

Before continuing, ensure you have completed the prerequisite steps under Windows Configuration.

• Installing SignTool
• Signing
• Verifying a signature

Installing SignTool

SignTool is shipped as part of Visual Studio. It is also available as part of the Windows SDK. Download Windows SDK: developer.microsoft.com/en-us/windows/downloads/windows-10-sdk/

You can choose to install only the Windows SDK Signing Tools for Desktop Apps.

Open the winsdksetup.exe file. Remember the default path shown in the install path, as this will be helpful with running these commands from the command prompt.

On the Windows Kits Privacy page, either option for allowing Microsoft to collect insights is okay. Click next.

Accept the License agreement

Deselect every feature except for Windows SDK Signing Tools for Desktop Apps, then select install.

When prompted if you want to allow this app to make changes, select yes.

Click on windows search bar on task bar and type "Edit the system environment variables" and select the control panel option of the same name.

Click environment variables.

Before editing the variable list, navigate to where the Windows SDK is installed to using file explorer, you must copy the path of the folder which contains the signtool application, the default path is C:\Program Files (x86)\Windows Kits\10\bin\10.0.22621.0\x64, refer to the below screenshot. Make sure to right click and copy the path as shown. You can also see the signtool application at the bottom of the file list, this is the command you will run.

In the System Variables list, click new. Then type Path as the variable name, and copy and paste the aforementioned path. Then click OK on the environment variables window and system properties window.

To test the installation, open command prompt, and type signtool, and the output should be as shown below.

The default signtool installation location is, for example: C:\Program Files (x86)\Windows Kits\10\bin\10.0.22621.0\x64

Signing

There are multiple ways to sign a file with signtool using a certificate.

Signing a file with a certificate

You will need a copy of the public certificate. You can obtain the certificate from the CodeSign Secure portal.

Open an administrator command prompt.

The remainder of this guide assumes you are running all Windows commands from an elevated (Administrator) prompt.

Run the command cd <Path to your directory with the file to be signed> into the command line. The line after cd should be the path to the directory the file you want to sign is in. This would be necessary if you haven't setup the env variable.

Run the following command to sign your Windows file: signtool sign /csp "Encryption Consulting Key Storage Provider" /kc <key name of private key associated with the certificate> /fd <the desired signing algorithm to be used when signing> /f <The location of the certificate to be used for signing>.pem /tr <The URL of the time stamping server to be used> /td <The signing algorithm to be used with the time stamping server> <The path to the file to be signed>

signtool sign /csp "Encryption Consulting Key Storage Provider" /kc evcodesigning /fd SHA256 /f evcodesigning.pem /tr http://timestamp.digicert.com /td SHA256 setup.exe

The following are the flags and their meaning in the command:

• - /csp

  This specifies the Key Service Provider to be used. This should always be "Encryption Consulting Key Storage Provider"

• - /kc

  This should be the name of the private key associated with your certificate. This will likely be the same name as the certificate name.

• - /fd

  This is the signing algorithm to be used with the signing function. This can be SHA256, SHA384, or SHA512.

• -/f

  The name of the certificate to be used for signing. This should be the same name as the /kc flag, with a .pem appended to the end. This certificate must be in the same directory this command is run from.

• -/tr (optional)

  This is the URL of the timestamping authority to be used. If /tr is not in use, and timestamping is not required, then /td should also be left out of this command.

• -/td (optional)

  This is the signing algorithm to be used with the timestamping server. This can be SHA256, SHA384, or SHA512. This algorithm should be the same as the /fd field. If /tr is not in use, and timestamping is not required, then /td should also be left out of this command.

• - <file path>

  This is the name of the file to be signed. This file must be in the directory this command is being run in.

Below is an example of a successful output of the command

To check the signature on the file, right click the file and select properties.

Select Digital Signatures at the top tab.

You can see here that the file has been successfully signed by selecting the name of the signer (in this example ec.com) and clicking details.

Macro Signing

Signing Windows Excel Macro files is possible using the signtool command. In the above command sample, the file to be signed is AgentService.exe, replace this file with any .xlsm file and run the signing command.

signtool sign /csp "Encryption Consulting Key Storage Provider" /kc evcodesigning /f C:\Users\Administrator\Desktop\ForTesting\evcodesigning.pem /fd SHA256 /tr http://timestamp.digicert.com /td SHA256 "C:\Users\Administrator\Desktop\ForTesting\MacroTest.xlsm"

To verify the signed file, simply use the verify command:

signtool.exe verify /pa C:\Users\Administrator\Desktop\ForTesting\MacroTest.xlsm

Appx & Msix Signing

1. Signing Appx and Msix files can be done using the Windows Signtool which comes along the Windows SDK setup.

   Microsoft Windows SDK includes an executable named “makeappx.exe” located in the "C:\Program Files (x86)\Windows Kits\10\bin<build number><architecture>\makeappx.exe" directory.

   If you are not able to see the "makeappx.exe" file, you would need to re-configure your Windows SDK with the following settings.

   

2. Here we are using the example of an Appx File. Similar steps can be followed for Msix files as well. Use the command prompt to run the following command:

   "C:\Program Files (x86)\Windows Kits\10\bin\<build number>\<architecture>\makeappx.exe" unpack /p “<the path to your .appx file<” /d “<Your desired new target directory>”

   

3. Now locate the certificate you wish to use for signing. The certificate must have the .pem extension. You can change the extension by renaming the certificate.

   

4. Navigate to the target directory specified in the previous command and find the file AppxManifest.xml. Inside, two lines must be modified.

   

5. Replace the Publisher line in the AppxManifest.xml with the subject line from the .pem certificate.

   

   This is the subject line from the .pem certificate

   

   The subject line may be in reverse order depending on your settings and certificate. To check, see if the Publisher line in AppxManifest.xml file begins with CN as the first entry. If it does not, make sure the order is switched such that it does.

   Check that the Publisher line in the AppxManifest.xml file contains S instead of ST, if you see ST as a field, replace it with S.

6. Replace the PublisherDisplayName line with your organization's name if it is currently incorrect.

   

7. Repack the file using the following command:

   "C:\Program Files (x86)\Windows Kits\10\bin\<build number>\<architecture>\makeappx.exe" pack /d “<target directory>” /p “<target location with package name and extension(.appx)>”

   

8. View the file properties, and confirm “read only” is NOT checked or the signing will fail.

   

9. Proceed with Windows signing using the .pem certificate you used to modify the manifest and the following signtool command:

   signtool sign /csp "Encryption Consulting Key Storage Provider" /kc <key name of private key associated with the certificate> /fd <the desired signing algorithm to be used when signing> /f <The location of the certificate to be used for signing>.pem /tr <The URL of the time stamping server to be used> /td <The signing algorithm to be used with the time stamping server> <The path to the new .appx file>

   An example command is as below:

   signtool sign /csp "Encryption Consulting Key Storage provider" /kc "DemoCert1" /fd "SHA256" /f "C:\Users\riley\Desktop\demo files\Signing Certificates\DemoCert1.crt" /tr http://timestamp.digicert.com /td SHA256 "C:\Users\riley\Desktop\demo files\Test Files\HelloWorld-new.appx"

   

   A successful signing will show an output as below:

   

MVS ClickOnce

Sign ClickOnce manifests with Visual Studio

1. Install and Configure the tool (SigningKSP)

2. From the command prompt reach to the directory where ECGetCert.exe is located.

   

3. Run the command: ECGetCert.exe evcodesigning

   Here, evcodesigning is the certificate name which we are using for codesigning purpose

   This command will save evcodesigning.pem (certificatename.pem) file in the same directory.

   

4. Open certmgr.msc and navigate to Personal -> certificates. If there is no certificate folder, just right click on personal -> All Tasks -> Import

   

5. A Certificate import wizard Opens. Click on next, the store location here is by default current user.

   

6. In the next page browse for the certificate. It should be saved in the same directory where EGGetCert.exe is located. From there select evcodesigning.pem (certificatename.pem). If you’re unable to see the file select all files at the bottom, instead of X.509 certificate. Once the certificate is selected click next.

   

   

7. In the other page, ensure that, "Place all the certificates in the following store is selected" and under that, Certificate store is set to Personal. Click on next and then Click on Finish. You'll see a dialogue box saying the import was successful.

   

   

8. Once the certificate import is done, you need thumbprint value of your certificate. Click on Personal -> Certificates -> and then the imported certificate. Navigate to “Details” and scroll down to thumbprint. You can copy the value.

   

   Return to command prompt. Run the following command. Ensure that you place the Thumbprint of your certificate in your command.

   certutil -f -repairstore -csp "Encryption Consulting Key Storage Provider" -user "My" 79656a9ce126fd0d1bb33f4dc73dba308f58b3ac

   

   

9. Once the command runs, navigate to the project in Visual Studio, that you want to publish with ClickOnce.

10. In the Solution Explorer, Right Click on your project and navigate to Publish. Click on it.

    

11. A new window opens. Select ClickOnce and click on Next.

    

12. In the next page, you can choose a publish location or leave the default bin\publish and click on Next.

    

13. You can choose the Install Location as per your choice or leave the default. Click on Next.

    

14. You can select your settings in the next tab as you like and Click Next.

    

15. In Sign manifests, check the box “Sign the ClickOnce manifests” and click on select certificate from store.

    

    A dialogue box opens with certificate, which was initially imported. Click OK to proceed.

    

    You can now see the certificate details in Sign manifests.

    

16. Click on next to choose your configuration and click on Finish.

17. You’ll see Publish profile creation progress and a green tick when successful

    

18. You can see the Publish Profile created.

    

    We have successfully signed ClickOnce manifests with Visual Studio.

Jar Signing

This section details how to sign jar files using the JarSigner tool. Java must be installed for it to work. You can download and install Java from https://www.oracle.com/java/technologies/downloads.

We need to install the Signed certificate from CodeSignSecure platform in the Certificate Manager of your system.

1. Click on the certificate from CodeSignSecure and then click on Install Certificate.

   

2. Select “Current User” and click Next.

   

3. Select “Place all certificates in the following store”.

   

4. Click on Browse and select Personal. Then click Next.

   

5. Click Finish on “Completing the Certificate Wizard”.

   

6. The certificate will be successfully imported

   

After importing the certificate, we need to assign it a private key

1. From Start, search “certmgr.msc”

   

2. Click Personal and then click Certificates

   

3. You would be able to see your installed certificate. Click on the certificate and go to Details tab.

   

4. Copy the thumbprint of this certificate

   

5. Open CMD and run this command. Modify the command with the thumbprint of your certificate.

   certutil -f -repairstore -csp "Encryption Consulting Key Storage Provider" -user "My" <thumberprint>

   

After successfully running the above command, we can now use this certificate for signing the files.

• Navigate to Java's jdk installation and go inside the bin folder (usually located at C:\Program Files\Java\jdk-20\bin). There you will find JarSigner application “Jasigner.exe”.

• You can drag the application to command line to get its path or simply navigate to that folder using the cmd.

• In cmd, we will first specify our store type, we are doing so by using -storetype Windows-My. This is where our KSP comes into play.

• Specify signing algorithm with: sigalg SHA256withRSA. You can use whichever signing algorithm you choose.

• Specify Time Stamp Server: ‐tsa http://timestamp.digicert.com

• Specify the Jar File you wish to sign.

• Specify the "Issued to" name of the certificate.

  

Altogether the command somewhat looks like the following. This needs to be executed from the directory where JarSigner Application is located.

We can run Jar Signer verifier to check if the Jar files has been signed or not.

It is done in the same directory as that of signer and with the command below.

Open SSL Signing

To sign binary files (.txt, .so) with OpenSSL, make sure to have the CodeSignAgent.zip file extracted from the download tools tab on the codesign secure website. For this example, the path required on the Windows Command prompt to execute these commands is:

C:\Users\Administrator\Desktop\CodeSignAgent\CodeSignAgent\CodeSignAgent\bin.

Open an admin command prompt and input cd \CodeSignAgent\dist

Then input the following command, remember to replace the file in <brackets> with your file you wish to sign:

CodeSign.exe -S <C:\Users\Administrator\Desktop\ForTesting\><myFile.txt> -u <username> -k TestSelfCert1.0 -a SHA256

The output should be as follows:

To verify a file, input the following command:

CodeSign.exe -V <C:\Users\Administrator\Desktop\ForTesting\><lmyFile.txt> -s C:\Users\Administrator\Desktop\ForTesting\myFile.sig -u <username> -k TestSelfCert1.0 -a SHA256

The output should be as follows:

Sign HLK/HCK using CodeSign Secure

Prerequisites

• Encryption Conculting’s Utility Tool installed in the system.
• OpenSSL Configured in the system.
• Sample HLK/HCK file present in the system.

Encryption Consulting LLC's expertise in this domain ensures your code signing process is seamless, secure, and compliant with Microsoft's standards. Digitally signing your HLK package (.hlkx) involves a series of steps to create a secure and verifiable digital signature. These steps ensure that the code meets Microsoft's standards. We understand that flexibility is key, so we offer two methods for HLK signing. You can pick the one that best suits your requirements.

1. Using our custom Utility Tool

   This method involves leveraging our in-house utility tool designed to perform all kinds of Windows signing (even HLK signing). This tool streamlines the signing process, making it efficient and hassle-free.

   

   With this method, you can expect the following benefits:

   • Simplicity : Our utility tool is designed with user-friendliness in mind. It simplifies the HLK signing process, reducing complexities and saving time.

   • Customization : We understand that each hardware component and driver is unique. Our utility tool allows for customization to meet your specific requirements.

   • Efficiency : Time is of the essence, and our tool is optimized for efficiency. You can expect quicker results without compromising quality.

2. Using our KSP (Encryption Consulting Key Storage Provider) with Signtool

   This method involves using our KSP (Encryption Consulting Key Storage Provider) with Microsoft's signtool. This method offers a higher level of security and is ideal for clients who prioritize security and compatibility.

   

   The command is:

                                           
                                           signtool sign /csp "Encryption Consulting Key Storage Provider" /kc evcodesigning /fd SHA256 /f
                                           C:\Users\riley\Desktop\ForTesting\evcodesigning.pem /tr http://timestamp.digicert.com /td SHA256
                                           C:\Users\riley\Desktop\CodeSign_UtilityTool\f9-879-e0-d5eba97-fa5264.hlkx
                                           
                                       

   • /csp

     To enter our KSP (Encryption Consulting Key Storage Provider). [This will not vary and remain constant]

   • /kc

     A key container within the CSP that holds the private key. [Rename it to the private key alias you’re going to use]

   • /fd

     File digest algorithm to use for creating file signatures.

   • /f

     Indicates the location of the public key file or certificate. [Make sure to sign using a .pem file only]

   • /tr

     Specifies the URL of the RFC 3161 timestamp server. This helps provide a timestamp for when the file was signed.

   • /td

     Specifies the digest algorithm used by the RFC 3161 timestamp server

   With this method, you can expect the following benefits:

   • Enhanced Security : Our KSP adds a layer of security to the signing process, safeguarding your code and drivers from potential threats.

   • Integration with Microsoft Tools : By combining our KSP with Microsoft's signtool, you benefit from the best of both worlds – our expertise and Microsoft's trusted tools.

   • Compliance : We ensure your signing process aligns with Microsoft's standards, keeping your hardware and drivers fully compliant.

Overcoming Common Challenges with Encryption Consulting LLC

While HLK signing is essential, it can come with its challenges. Such as:

• Addressing Driver Compatibility Issues

  HLK signing can uncover compatibility issues that must be addressed. This might involve revising code, fixing bugs, or adjusting hardware components.

• Troubleshooting Code Signing Problems

  Code signing can sometimes be tricky, and errors can occur. Knowing how to troubleshoot and resolve these issues is crucial to achieving a successful HLK signing.

This is where Encryption Consulting LLC excels. Our team can swiftly address compatibility issues and troubleshoot code signing problems, ensuring your journey to HLK certification is smooth.

Why choose Encryption Consulting’s CodeSign Secure for HLK Signing?

We have three main benefits which support and help promote our CodeSign Secure as an ideal fit for HLK Signing. Those are:

• Fortified Security - FIPS 140-2 Level 3 HSM Compliance

  Encryption Consulting LLC has taken security to the next level in response to CA/Browser Forum's June 1, 2023, requirement. Our private keys for CodeSigning certificates are stored, generated, and used within a Hardware Security Module (HSM) that complies with FIPS 140-2 Level 3 standards and never leaves the HSM in any situation. This rigorous compliance ensures the highest level of security for your code signing process, meeting industry standards and safeguarding your digital signatures.

• Client-Side Hashing - Unveiling the Benefits with CodeSign Secure

  Our CodeSign Secure, utilised in both the utility tool and KSP methods, employs client-side hashing for your code signing needs, and it brings several benefits to the table:

  • Enhanced Efficiency : Client-side hashing reduces the load on your infrastructure, making the code-signing process more efficient. It minimises the need to transfer large files to a remote server for hashing, saving time and resources.
  • Privacy and Control : You maintain complete control over your data with client-side hashing. Your sensitive code and files remain within your network, reducing the risk of data exposure or interception during transmission.
  • Improved Compliance : Client-side hashing ensures that your code signing process complies with industry regulations and standards. It provides a transparent and auditable process, making demonstrating compliance to stakeholders, auditors, or regulatory authorities easier. This can be particularly crucial for industries with stringent compliance requirements.

• Proxy-Based Access to HSM for Enhanced Security

  Proxy-based access to the keys stored in a Hardware Security Module (HSM) is one of the essential security elements provided by Encryption Consulting LLC. This approach significantly enhances security by safeguarding your private keys from unauthorised access and potential breaches. Our CodeSign Secure utilises proxy-based access to interact with the private keys stored in the HSM, ensuring the integrity and security of your code-signing process. This approach is crucial in establishing trust, verifying digital signatures, and securing the communication between your components and the HSM.

By integrating these advanced security measures and technologies into our code-signing process, Encryption Consulting LLC ensures that your HLK certification is reliable and fortified against potential threats, meeting the highest industry standards.

NuGet Signing

Prerequisites

• Install NuGet in your system.
• Windows Operating System.
• Encryption Consulting’s utility tool is installed in the system.
• OpenSSL configured in the system.

Encryption Consulting is well-versed in compliance standards (FIPS 140-2 Level 3 HSM), and we also ensure that your package signing process meets industry regulations and standards. We use Proxy-Based access to HSM for enhanced security; this way, we ensure the safeguarding of your private key from unauthorised access and potential breaches. We understand that each organisation has unique needs, so we provide tailored solutions which will fit your requirements. Thus, we provide trust by providing a secure signing process.

Using Command-Line and Import Certificate (preferably EV)

This method involves leveraging the NuGet (Command Line Interface) that provides functionality to create, publish, sign, and manage packages without changing the project files. But before that, you need to generate a CSR from our web portal, get it signed using Publicly trusted CA (or MS PKI), and later import that certificate into our web portal.

• Download nuget.exe from here
• Set these executable files to the PATH environment variable.

Now, use nuget.exe to sign your package.

The command is :

                    
                    
                        nuget sign HelloWorld.1.3.0.15\* -Timestamper http://timestamp.digicert.com -outputdirectory ..\am-HelloWorld.1.3.0.15
                        -CertificateFingerprint 79656a9ce126fd0d1bb33f4dc73dba308f58b3ac -HashAlgorithm SHA256 -Verbosity detailed -Overwrite
                    
                    
                    

To verify whether the package has been signed or not:

The command is: nuget verify -All HelloWorld.1.3.0.15\*

Using Command-Line and Self-Signed certificate (from our web portal)

This method also involves leveraging the NuGet (Command Line Interface) that provides functionality to create, publish, sign, and manage packages without changing the project files. But first, the user needs to generate a Self-Signed certificate from our web portal. After that, convert the download certificate from .pem to .crt format for better operations. When these steps are performed successfully, perform the following steps:

• Download the Certificate Chain from our “Signing Tools” screen. And unzip it in your client machine.

• After that, install the Root Certificate into your system:

  Steps	Outputs
  Click on the INSTALL CERTIFICATE button.
  On the “Import Wizard” popup, select Current User and then hit NEXT.
  On the “Certificate Store” popup, choose Trusted Root Certification Authorities for the Root CA certificate and click on NEXT.
  After verifying all the details, click on FINISH.

• After installing Root CA, install the Issuing CA from the Certificate Chain folder (intermediate.crt). Follow the same procedure, except to install this certificate in Intermediate Certification Authorities.
• After successfully installing the Issuing CA, install the End Entity certificate (or the Self-Signed certificate from our portal) into your system. The process is the same, except this certificate will be installed in the Personal store.

• Run the repairstore command using the Thumbprint of this End Entity certificate. Like this:

                  
                      
                      certutil -f -repairstore -csp "Encryption Consulting Key Storage Provider" -user "My" <thumbprint of the certificate>
                      
                      
                  

  

• When all of these steps have been completed successfully, try running the NUGET command-line command using this certificate’s thumbprint. Here,

                  
                      
                      nuget sign HelloWorld.1.3.0.15\* -Timestamper http://timestamp.digicert.com -outputdirectory ..\am-HelloWorld.1.3.0.15
                      -CertificateStoreLocation CurrentUser -CertificateStoreName My -CertificateFingerprint <thumbprint of the certificate>
                      -HashAlgorithm SHA256 -Verbosity detailed -Overwrite
                      
                      
                  

  

Using our Utility Tool

This method involves leveraging our in-house utility tool designed to perform all kinds of Windows signing (even NuGet signing). This tool streamlines the signing process, making it efficient and hassle-free.

Enter the appropriate details when prompted to get a signed package. This method allows customisation and increases efficiency without compromising quality.

Mage Signing

"Mage.exe" is a command-line tool used in the Windows operating system for signing and verifying software manifests

Prerequisites

• Install mage in your system.
• .NET Framework 4 or above.
• Signing Certificate.

Mage.exe is a .NET Framework tool, so it will either get automatically installed while you install .NET Framework using Visual Studio or it is downloaded with Windows SDK, under Windows SDK signing tools for Desktop apps.

You can locate it in file path C:\Program Files (x86)\Microsoft SDKs\Windows\v10.0A\bin\NETFX 4.8.1 Tools

Once you’ve mage.exe in your system, you will need to set PATH environment variable to mage.exe

Mage commands and parameters

You can also see these by mage -help or mage -help verbose in your CMD

Using the command line and EV certificate

We will use Mage.exe to sign file

Syntax

                                
                                
                                    mage -sign <file_name> -CertHash <hash_or_cert_fingerprint>
                                        mage -verify <file_name>                                    
                                
                                
                                

For example:

                                
                                
                                    mage -sign CodeSignText.exe.manifest -CertHash f39dbe6bcfaa43ca39585aa40ab0a19bf29991cb                                    
                                
                                
                            

here

<file_name>: specify the name of the file you want to sign or the path of the file, if it is not in the same directory

<hash_or_cert_fingerprint>: specify the fingerprint or Hash of your certificate. This can be found in detail section of your certificate.

A sample of the executed command:

Using the command line and self sign certificate (from our web portal)

This method also involves leveraging the Mage (Command Line Interface) that provides functionality to create, publish, sign, and manage packages without changing the project files. But first, the user needs to generate a Self-Signed certificate from our web portal. After that, convert the download certificate from .pem to .crt format for better operations. When these steps are performed successfully, perform the following steps:

• Download the Certificate Chain from our “Signing Tools” screen. And unzip it in your client machine.
• After that, install the Root Certificate into your system

Steps:

• Click on the INSTALL CERTIFICATE button.

  

• On the “Import Wizard” popup, select Current User and then hit NEXT.

  

• On the “Certificate Store” popup, choose Trusted Root Certification Authorities for the Root CA certificate and click on NEXT.

  

• After verifying all the details, click on FINISH.

  

• After installing Root CA, install the Issuing CA from the Certificate Chain folder (intermediate.crt). Follow the same procedure, except to install this certificate in Intermediate Certification Authorities.
• After successfully installing the Issuing CA, install the End Entity certificate (or the Self-Signed certificate from our portal) into your system. The process is the same, except this certificate will be installed in the Personal store.

• Run the repairstore command using the Thumbprint of this End Entity certificate. Like this:

                                          certutil -f -repairstore -csp "Encryption Consulting Key Storage Provider" -user "My" <thumbprint of the certificate>
                                      

When all of these steps have been completed successfully, try running the Mage command-line command using this certificate’s thumbprint.

Syntax

                                mage -sign <file_name> -CertHash <hash_or_cert_fingerprint>
    mage -verify <file_name>
                            

For example:

                                    mage -sign CodeSignText.exe.manifest -CertHash f39dbe6bcfaa43ca39585aa40ab0a19bf29991cb
                                

Here,

<file_name>: specify the name of the file you want to sign or the path of the file, if it is not in the same directory

<hash_or_cert_fingerprint>: specify the name of the file you want to sign or the path of the file, if it is not in the same directory

A sample of executed command

Sign OVA/OVF using Encryption Consulting’s Utility Tool

Encryption Consulting(EC) understands the need for security in the modern world and strives to solve these problems through CodeSign Secure. To that end, we have developed an easily operated command-line Utility that provides users with seamless and hassle-free OVA/OVF signing.

CodeSign Secure’s Utility tool is designed for high performance, accuracy and user-friendliness in mind, making signing of OVA/OVF files simplified for the users.

Prerequisites

• Encryption Consulting’s Utility Tool installed in the system.
• OpenSSL Configured in the system.
• Sample OVA/OVF present in the system.

The Actual process is:

1. Necessary input

   The user needs to give all the input data, mentioned below, to the utility tool for the signing process.

   • Username : The primary email of the user to proceed with the signing process.

   • Certificate path : The path to the certificate being used for signing the desired file.

   • Input file path : The path to the OVA/OVF file that needs to be signed.

   • Output file path : The path to the signed OVA/OVF output file.

   • Application name : Application name is the application associated with the certificate used for signing in our web portal.

   • Environment : The environment name, whether it’s production, non-production, Lab, or any specific environment created by the user in our web portal.

2. Acquiring an End-Entity Certificate

   To sign the OVA or OVF file, the user needs an end-entity certificate. This certificate can be generated from our web application, or can be imported into the utility tool. We prefer importing EV certificate(Extended Validation) certificate as it is the highest form of SSL Certificate on the market.

3. Generating a Hash

   Client-side Hashing is used to calculate the hash of the file that is to be signed. This hash is sent to the server along with the private key alias to generate signature.

4. Generating and attaching the Signature

   Signature is generated in the HSM by using the hash and the private key and this digital signature is sent back to the client. Once client receives the signature it is attached to the OVA or OVF package.

   

Mechanism

1. Define the domain variable, which represents the base URL of the API.
2. Implementing the get_token function to retrieve the authentication token from the API. It takes the domain and certificate_path as parameters and returns the token.
3. Implement the sign_ova function to sign the OVA file with the certificate and hash. It takes the certificate, hash, and token as parameters and returns the signature.
4. Implementing the store_signature function to store the signature in a file. It takes the signature as a parameter and does not return any value.
5. Implementing the attach_signature function to attach the signature and certificate to the OVA file. It takes certificate_path, ova_file_path, and output_file_path as parameters and does not return any value.
6. Implementing the generate_hash function to generate the hash value of the OVA file using OpenSSL. It takes ova_file_path as a parameter and returns the hash value.
7. Implementing the verify_sig function to verify whether the OVA file with the provided certificate has been signed. It takes the certificate, hash, token, and signature as parameters and returns the True or False, depending on the verification status

Benefit of choosing EC’s Utility Tool

Encryption Consulting’s Utility tool keeps strict compliance with latest security guidelines. Utility tool showcases some security features that ensure we are a step ahead in securing the files.

The following features make CodeSign Secure’s Utility tool a trustworthy vector for your code signing endeavours.

• We strictly adhere to the CA/B Forum guidelines, ensuring that we maintain the highest standards in the industry.
• We go the extra mile by utilizing FIPS 140/2 level 3 compliant Hardware Security Modules (HSMs). With us, your private key is generated and securely stored within the HSM, ensuring that it never leaves the module. This guarantees the impossibility of a private key compromise.
• Client-Side hashing is an extra step that is implemented from our end to ensure more secure transfer of data between client and server. Client-side hashing ensure even if the packet is intercepted the attacker get just the hash which is useless of the attacker. Client-Side hashing provides a significant advantage in terms of remote digital signature generation, reducing the overall bandwidth requirement due to only hash value upload, and avoiding the attacks of malicious code signed due to no code file movement within the environment.

Utility Tool for code signing

The following tool will help you perform code signing through the command line. The tool will allow to the feature of single signing or bulk signing. Incase of signle siging, it will take the path of your file as an input, and when performing bulk signing, it will take the path of the folder which contains all the files that need to be signed. It will then automatically scan it for virus, and if malware is detected, the process exits and does not allow signing to continue when single signing. In bulk signing, it will skip that file. Once the file has been scanned for malware, as per the file type, an appropriate code signing method will be selected for you. For example, files with the .so and .txt extension will be signed with OpenSSL, files with the .jar extension will be signed with Jar signing, and files with the .exe, .dll, .sys, .cat, .cab will be signed with windows signing.

Installation of Utility Tool

For installation, you would need to download and run a MSI file from the portal which will install this tool into your machine. Along with the tool, it will also prompt you to install various signing softwares such as Windows SDK, Java SDK and Encryption Consulting KSP. These signing softwares will be used by the Utility Tool to perform signing operation on different file types.

You can cancel the installation of signing softwares if updated versions are already configured in your system environment.

Single Signing

Follow the steps below to use the tool for single file signing:

1. To Access the tool, click on the executable file- Utility Tool.exe

   

2. It will prompt you to provide your username, Application Name and Environment Name that will perform user authentication on the portal and verify the user's team details.

   

3. It will then ask you whether you want to bulk sign or not, Y for Yes and N for No. Enter N in this case.

   

4. Then enter the path of the file that needed to be signed.

   

5. Once you provide the file path, malware check is done if ClamAV antivirus software is present in your system. Provide the inputs as asked. An example of doing .exe file with Windows signing is provided below.

   

6. A message will be displayed when Codesigning is done.

   

All possible inputs that users may have to provide for code signing are listed below with an example of each.

• Enter the path of the file

  This is where you provide the path of file that you want to sign. Example C:\<Folder_name>\<File_name>. Make sure you have provided a file name with the proper extension.

• Enter the key name

  This refers to the cryptographic key used to sign the code. Example: evcodesigning

• Enter the certificate location

  An example of what can be put in this field is C:\testing.pem. The certificate.pem file MUST be included in this input.

• Enter Hashing Algorithm

  You need provide the name of hashing algorithm such as SHA256, SHA384, or SHA512. It must be one of these three values.

Bulk Signing

Follow the steps below to use the tool for bulk file signing:

1. To Access the tool, click on the executable file- UtilityTool.exe. This file will be located at

   C:\Program Files (x86)\Encryption Consulting\Utility Tool\UtilityTool.exe

   

2. It will prompt you to provide your username, Application Name and Environment Name that will perform user authentication on the portal and verify the user's team details.

   

3. It will then ask you whether you want to bulk sign or not, Y for Yes and N for No. Enter Y in this case.

   

4. Then enter the path of the folder which contains all the files that needed to be signed.

   

5. Now, provide the key name of the certificate which you want to use for signing. Key name or key alias can be seen from the portal.

   

6. Now, provide the path of this certificate that will be used for signing the file.

   

7. Then enter the url of the timestamping server. Press enter to select the default server i.e. http://timestamp.digicert.com

   

8. Then enter the hashing algorithm (Accepted algorithm: SHA256, SHA384, SHA512)

   

9. It will then generate a Signing Report for all files. It will provide details about successful signings, failed signing and skipped files.

   

RPM Signer

WSL Installation

Kindly follow instruction in the below link for the windows server 2019 https://learn.microsoft.com/en-us/windows/wsl/install-on-server

Version: WSL
WSL2 will not support in windows server 2019

Steps

1. Enable WSL

   Open PowerShell as Administrator and run:

                                           
                                               Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux
                                           
                                       

2. Download ubuntu distribution [From here]

3. Extract downloaded file

   1. Rename the downloaded file to Ubuntu_.zip, then extract this archive. Inside there are different appx files for different platforms. Choose Ubuntu_2004.2021.825.0_x64.appx.
   2. Rename the appx file for your platform to Ubuntu.zip and extract this archive.
   3. Extract the files in Ubuntu.zip to the target location where you would like your linux distro to reside.
   4. Open the target location folder with the files of Ubuntu.zip and run the file ubuntu.exe, which is located inside the folder. This will install the distribution. It is important that you don't move the folder any more after the installation as this will result in an error when starting Ubuntu later.
   5. Add the folder containing the ubuntu.exe file to the path variable. Ubuntu can then be started via ubuntu on the command line.

Generate key pair

Follow the below steps on WSL to generate key pairs.

First make sure that the nfast server is running on the WSL.
To check, execute below commands in the WSL terminal.

                                    
                                        $ cd /opt/nfast/bin
                                        $ ./enquiry
                                    
                                    

if it’s not running execute the below restart command

                                    
                                        $ /opt/nfast/sbin/init.d-ncipher restart
                                    
                                    

Note

To add the generated key to the HSM, admin have to manually import the certificate into the CodeSigner platform

Steps

1. Change directory to /opt/nfast/bin

                                           
                                               $ cd /opt/nfast/bin
                                           
                                           

2. Execute command and enter appropriate details

                                           
                                               $ ./generatekey pkcs11 selfcert=yes
                                           
                                           

   Note: Remember Key Name and Email address. Those will be used in further steps

   Output not exact but similar

                                           
                                               type: Key type? (DES3, DH, DHEx, DSA, HMACSHA1, HMACSHA256, HMACSHA384,
                                               HMACSHA512, RSA, DES2, AES, Rijndael, ECDSA, ECDH, Ed25519,
                                               X25519) [RSA] >
                                               size: Key size? (bits, minimum 1024) [2048] >
                                               OPTIONAL: pubexp: Public exponent for RSA key (hex)? []
                                               >
                                               plainname: Key name? [] > gpg2
                                               x509country: Country code? [] > us
                                               x509province: State or province? [] > ca
                                               x509locality: City or locality? [] > cupertino
                                               x509org: Organisation? [] > entrust
                                           
                                           

                                           
                                               x509orgunit: Organisation unit? [] > team gpg
                                               x509dnscommon: Domain name? [] > entrust.com
                                               x509email: Email address? [] > test@entrust.com
                                               digest: Digest to sign cert req with? (md5, sha1, sha256, sha384, sha512)
                                               [default sha256] >
                                               key generation parameters:
                                               operation Operation to perform generate
                                               application Application pkcs11
                                               verify Verify security of key yes
                                               type Key type RSA
                                               size Key size 2048
                                               pubexp Public exponent for RSA key (hex)
                                               plainname Key name gpg2
                                               x509country Country code us
                                               x509province State or province ca
                                               x509locality City or locality cupertino
                                               x509org Organisation entrust
                                               x509orgunit Organisation unit team gpg
                                               x509dnscommon Domain name entrust.com
                                               x509email Email address test@entrust.com
                                               digest Digest to sign cert req with sha256
                                               Key successfully generated.
                       
                                               Path to key: /opt/nfast/kmdata/local/key_pkcs11_ua44dd63fe496285397e87922a23d57deefd7f7682
                                               Path to self-cert: /opt/nfast/bin/pkcs11_ua44dd63fe496285397e87922a23d57deefd7f7682_selfcert
                                           
                                           

3. Execute command

                                           
                                               $ ./ckcerttool -n -f pkcs11_ua44dd63fe496285397e87922a23d57deefd7f7682_selfcert -k
                                               ua44dd63fe496285397e87922a23d57deefd7f7682 -L gpg2
                                           
                                       

   Here, for -f and -k option self-cert and key will be used from the 2nd step. For the -L will be the same as Key name entered in the 2nd step

4. Install the gnupg-pkcs11-scd

                                           
                                               $ sudo apt-get install gnupg-pkcs11-scd
                                           
                                           

   Note: if sudo apt-get install is not working, execute below command first.

                                           
                                               $ sudo apt-get update && sudo apt-get upgrade -y
                                           
                                           

5. Configure gnupg agent

   • Edit the following lines in the gpg-agent.conf

                                                 
                                                     $ nano ~/.gnupg/gpg-agent.conf
                             
                                                     - Enter below lines and save file
                             
                                                     scdaemon-program /usr/bin/gnupg-pkcs11-scd
                                                     pinentry-program /usr/bin/pinentry
                                                 
                                                 

   • Edit the following lines in the gnupg-pkcs11-scd.conf

                                                 
                                                     $ nano ~/.gnupg/gnupg-pkcs11-scd.conf
                             
                                                     - Enter below lines and save file
                             
                                                     providers p1
                                                     provider-p1-library /opt/nfast/toolkits/pkcs11/libcknfast.so
                                                 
                                                 

6. Reload the agent

                                           
                                               $ gpg-agent --server gpg-connect-agent <<EOF
                                               > RELOADAGENT
                                               > EOF
                                           
                                           

7. Get the GPG KEY-FRIENDLY string (of newly generated key)

   • Retrieve card details

                                                 
                                                     $ gpg --card-status
                                                 
                                                 

   • Retrieve key friendly names and certificates

                                                 
                                                     $ gpg-agent --server gpg-connect-agent << EOF
                                                     > SCD LEARN 
                                                     > EOF
                                                 
                                                 

     Output: Here we need to find Key-Friendly for the generated key based on the provided email address in the 2nd step. Here for example test@entrust.com

                                                 
                                                     OK Pleased to meet you
                                                     gnupg-pkcs11-scd[1757.1766750016]: Listening to socket '/tmp/gnupg-pkcs11-scd.Wk3Gst/agent.S'
                                                     gnupg-pkcs11-scd[1757.1766750016]: accepting connection
                                                     gnupg-pkcs11-scd[1757]: chan_0 -> OK PKCS#11 smart-card server for GnuPG ready
                                                     gnupg-pkcs11-scd[1757.1766750016]: processing connection
                                                     gnupg-pkcs11-scd[1757]: chan_0 <- GETINFO socket_name gnupg-pkcs11-scd[1757]: chan_0 -> D
                                                     /tmp/gnupg-pkcs11-scd.Wk3Gst/agent.S
                                                     gnupg-pkcs11-scd[1757]: chan_0 -> OK
                                                     gnupg-pkcs11-scd[1757]: chan_0 <- LEARN gnupg-pkcs11-scd[1757]: chan_0 -> S SERIALNO D27600012401115031317CEF11601111
                                                     S SERIALNO D27600012401115031317CEF11601111
                                                     gnupg-pkcs11-scd[1757]: chan_0 -> S APPTYPE PKCS11
                                                     S APPTYPE PKCS11
                                                     gnupg-pkcs11-scd[1757]: chan_0 -> S KEY-FRIEDNLY 7CCB46206A0EAC0ECE303307932A90DB8245C1CE
                                                     /C=us/ST=ca/L=cupertino/O=entrust inc/OU=test gpg/CN=entrust.com/emailAddress=test@entrust.com on accelerator
                                                     S KEY-FRIEDNLY 7CCB46206A0EAC0ECE303307932A90DB8245C1CE /C=us/ST=ca/L=cupertino/O=entrust inc/OU=test
                                                     gpg/CN=entrust.com/emailAddress=test@entrust.com on accelerator
                                                     gnupg-pkcs11-scd[1757]: chan_0 -> S CERTINFO 101
                                                     nCipher\x20Corp\x2E\x20Ltd//350C\x2D03E0\x2DD947/accelerator/7CCB46206A0EAC0ECE303307932A90DB8245C1CE
                                                     S CERTINFO 101 nCipher\x20Corp\x2E\x20Ltd//350C\x2D03E0\x2DD947/accelerator/7CCB46206A0EAC0ECE303307932A90DB8245C1CE
                                                     gnupg-pkcs11-scd[1757]: chan_0 -> S KEYPAIRINFO 7CCB46206A0EAC0ECE303307932A90DB8245C1CE
                                                     nCipher\x20Corp\x2E\x20Ltd//350C\x2D03E0\x2DD947/accelerator/7CCB46206A0EAC0ECE303307932A90DB8245C1CE
                                                 
                                                 

                                                 
                                                     S KEYPAIRINFO 7CCB46206A0EAC0ECE303307932A90DB8245C1CE
                                                     nCipher\x20Corp\x2E\x20Ltd//350C\x2D03E0\x2DD947/accelerator/7CCB46206A0EAC0ECE303307932A90DB8245C1CE
                                                     gnupg-pkcs11-scd[1757]: chan_0 -> OK
                                                     OK
                                                     gnupg-pkcs11-scd[1757]: chan_0 <- RESTART gnupg-pkcs11-scd[1757]: chan_0 > OK
                                                     gnupg-pkcs11-scd[1757]: chan_0 <- [eof] gnupg-pkcs11-scd[1757.1766750016]: post-processing connection
                                                     gnupg-pkcs11-scd[1757.1766750016]: accepting connection gnupg-pkcs11-scd[1757.1766750016]: cleanup connection
                                                     gnupg-pkcs11-scd[1757.1766750016]: Terminating root@ubuntu19:~# gnupg-pkcs11-scd[1757.1761310464]: Thread command
                                                     terminate gnupg-pkcs11-scd[1757.1761310464]: Cleaning up threads
                                                 
                                                 

     (press enter or Ctrl + c to exit)

   • Import key into GPG 2 keyring

     Note: Use same details as add in the 2nd step

     User Key-Friendly as get above step for the Enter the keygrip:

                                                 
                                                     $gpg --expert --full-generate-key
                                                     gpg (GnuPG) 2.2.12; Copyright (C) 2018 Free Software Foundation, Inc.
                                                     This is free software: you are free to change and redistribute it.
                                                     There is NO WARRANTY, to the extent permitted by law.
                             
                                                     Please select what kind of key you want:
                                                     (1) RSA and RSA (default)
                                                     (2) DSA and Elgamal
                                                     (3) DSA (sign only)
                                                     (4) RSA (sign only)
                                                     (7) DSA (set your own capabilities)
                                                     (8) RSA (set your own capabilities)
                                                     (9) ECC and ECC
                                                     (10) ECC (sign only)
                                                     (11) ECC (set your own capabilities)
                                                     (13) Existing key
                                                     Your selection? 13
                                                 
                                                 

                                                 
                                                     Enter the keygrip: 7CCB46206A0EAC0ECE303307932A90DB8245C1CE
                             
                                                     Possible actions for a RSA key: Sign Certify Encrypt Authenticate
                                                     Current allowed actions: Sign Certify Encrypt
                             
                                                     (S) Toggle the sign capability
                                                     (E) Toggle the encrypt capability
                                                     (A) Toggle the authenticate capability
                                                     (Q) Finished
                             
                                                     Your selection? Q
                                                     Please specify how long the key should be valid.
                                                     0 = key does not expire
                                                     <n> = key expires in n days
                                                     <n>w = key expires in n weeks
                                                     <n>m = key expires in n months
                                                     <n>y = key expires in n years
                                                     Key is valid for? (0)
                                                     Key does not expire at all
                                                     Is this correct? (y/N) y
                             
                                                     GnuPG needs to construct a user ID to identify your key.
                             
                                                     Real name: walt dreksler
                                                     Email address: test@entrust.com
                                                     Comment:
                                                     You selected this USER-ID:
                                                     "walt dreksler <test@entrust.com>"
                             
                                                     Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O
                                                     gpg: key 5C6FE3F2217C672E marked as ultimately trusted
                                                     gpg: revocation certificate stored as '/root/.gnupg/openpgp-revocs.d/2F954E8021148748D54618195C6FE3F2217C672E.rev'
                                                     public and secret key created and signed.
                             
                                                     pub rsa2048 2022-04-07 [SCE] 2F954E8021148748D54618195C6FE3F2217C672E
                                                     uid Test Entrust <test@entrust.com>
                                                 
                                                 

     • To check key in gpg key ring

                                                       
                                                           $ gpg --list-keys
                                                       
                                                       

     • Steps performed in the Dev server for the reference only.

       

       

       

RPM Signer Utility

Prerequisite

In order to use XML Signer, First needs to set environment variables for the SSL Client Authentication Certificate path and certificate password. Ask the Encryption Consulting team if you don’t already have it.

NOTE: SSL Client Authentication Certificate should be in the PKCS12 format(.p12 or .pfx)

Execute bellow command to set environment variables

Mac or Linux

                                    
                                        $ export SIGNER_SSL_CERT_PFX=path_to_ssl_certificate
                                        $ export SIGNER_SSL_CERT_PFX_PASS=your_client_certificate_password
                                    
                                    

Windows

                                    
                                        $ set SIGNER_SSL_CERT_PFX=path_to_ssl_certificate
                                        $ set SIGNER_SSL_CERT_PFX_PASS=your_client_certificate_password
                                    
                                    

How to use the RPM Signer utility?

Sign and verify functionality is OS independent and can be used in any system that supports python language.

Get the version of the RPM Signer Utility

Execute the below command

                                    
                                        $ python3 rpmsigner.py -v or $ python3 rpmsigner.py --version
                                    
                                    

Sign a RPM Package

Use sign subcommand to sign a RPM package

                                    
                                        rpmsigner.py sign
                                        <file_to_be_signed> -u
                                        <user_name> -k
                                        <key_name> -i
                                        <issuer_email> -f
                                        <key_fingerprint> -a
                                        <algorithm> [-o <output_sig_file_name>]
                                    
                                    

sign: RPM Package to be signed.

-u: User name. A user name on Encryption Consulting server. Ask the Encryption Consulting team if you don't already have it.

-k: Key/certificate name for signing/verification provided by Encryption Consulting server. Ask the Encryption Consulting team if you don't already have it.

-i: User email address which is used to generate key pair. Ask the Encryption Consulting team if you don't already have it.

-f: GPG key fingerprint in hex format. Ask the Encryption Consulting team if you don't already have it.

-a: Algorithm to be used for signing. One of the following options should be used:

• SHA224
• SHA256 (Default)
• SHA384
• SHA512

If the algorithm is not provided, it will default to SHA256.

-o: Output file to store the signature. This is an optional parameter. If this option is provided, the signature file will be generated with the name <file_to_be_signed>.sig.

-h: Display help.

-v: Display verbose logs.

Examples

                                    
                                        : rpmsign.py -h
                                        : rpmsign.py sign myFile.rpm -u admin -k RPMSignCertificate -i
                                        example@ex.com -f C4F1F7FEC262FD3545FFE29E4519CD8D20C3154C -a SHA256
                                        : rpmsign.py sign myFile.rpm -u admin -k RPMSignCertificate
                                        -a SHA256 -o myFile.sig
                                    
                                    

Verify the signature

Use verify subcommand to sign a RPM package

                                    
                                        rpmsigner.py verify
                                        <file_to_be_verified> -u
                                        <user_name> -k
                                        <key_name> -i
                                        <issuer_email> -f
                                        <key_fingerprint> -a
                                        <algorithm>
                                    
                                    

verify: File to be verified. It can be a binary or text file.

-u: User name. A user name on Encryption Consulting server. Ask the Encryption Consulting team if you don’t already have it.

-k: Key/certificate name for signing/verification provided by Encryption Consulting server. Ask the Encryption Consulting team if you don’t already have it.

-i: User email address which is used to generate key pair. Ask Encryption Consulting team if you don’t already have it.

-f: gpg key fingerprint in hex format. Ask Encryption Consulting team if you don’t already have it.

-a: Algorithm to be used for verification. One of the below options to be used:

• SHA224
• SHA256 (Default)
• SHA384
• SHA512

If the algorithm is not provided, it will use SHA256 as the default.

-h: Display help.

-v: Display verbose logs.

Examples

                                    
                                        : rpmsign.py -h
                                        : rpmsign.py verify myFile.rpm -u admin -k RPMSignCertificate -i example@ex.com -f C4F1F7FEC262FD3545FFE29E4519CD8D20C3154C -a SHA256
                                    
                                    

Notes

1. Same algorithm name must be used for signing and verification of a file.
2. At present only the SHA256 algorithm is supported at the server end. We need to tweak the utility once other

How to build a RPM Signer utility?

Python version: 3.8
IDE used: PyCharm
Requirements: modules given in the requirement.txt file

• Run either of below commands

                                          
                                              $ python3 rpmsigner.py sign myFile.rpm -u admin -k RPMSignCertificate -i example@ex.com -f C4F1F7FEC262FD3545FFE29E4519CD8D20C3154C -o myFile.sig
                                          
                                          

                                          
                                              $ python3 rpmsigner.py verify myFile.rpm -u admin -k RPMSignCertificate -i example@ex.com -f C4F1F7FEC262FD3545FFE29E4519CD8D20C3154C
                                          
                                          

Troubleshooting

• apt-get

  If apt-get is not working and “the package not found” error shows every time. Execute below command

                                          
                                              $ sudo apt-get update && sudo apt-get upgrade -y
                                          
                                          

• gpg-agent : Cannot add PKCS#11 provider 'p1': 6-'CKR_FUNCTION_FAILED'

                                          
                                              rpmsigner@Signing-Server:/opt/nfast/bin$ gpg-agent --server gpg-connect-server << EOF
                                              > SCD LEARN
                                              > EOF
                                          
                                          

                                          
                                              OK Pleased to meet you
                                              gnupg-pkcs11-scd[28.2611480384]: Cannot add PKCS#11 provider 'p1': 6-'CKR_FUNCTION_FAILED'
                                              gnupg-pkcs11-scd[28.2611480384]: Could not load any provider
                                              ERR 67108983 No SmartCard daemon <GPG Agent>
                                          
                                          

  Solution: Check with the enquiry command that server is running or not

  if it’s not running execute the below restart command

  • /opt/nfast/sbin/init.d-ncipher restart

• GPG Key Generation: No key with this Key grip

  Try to kill gpg-agent with command below

                                          
                                              $ pkill gpg-agent
                                          
                                          

RPM Signer Utility

RPM Signer Utility can be used in any platform that supports python language.

Signing Container Image

Before proceeding with image signing , docker & cosign needs to be installed on that machine

Please follow the steps mentioned below for installing cosign

Installing Cosign

                                    
                                        # binary
                                        wget "https://github.com/sigstore/cosign/releases/download/v2.0.0/cosign-linux-amd64"
                                        mv cosign-linux-amd64 /usr/local/bin/cosign
                                        chmod +x /usr/local/bin/cosign
                
                                        # rpm
                                        wget "https://github.com/sigstore/cosign/releases/download/v2.0.0/cosign-2.0.0.x86_64.rpm"
                                        rpm -ivh cosign-2.0.0.x86_64.rpm
                
                                        # dkpg
                                        wget "https://github.com/sigstore/cosign/releases/download/v2.0.0/cosign_2.0.0_amd64.deb"
                                        dpkg -i cosign_2.0.0_amd64.deb
                                    
                                    

Installing and setting up python and docker

• sudo apt-get install docker.io
• sudo apt-get install python-is-python3
• sudo apt install python3-pip
• sudo apt-get install python3-docker
• sudo apt-get -y install python3-openssl
• sudo apt-get install -y dbus-user-session
• sudo apt-get install -y docker-ce-rootless-extras

If docker-ce-rootless-extras gives error, follow the below steps:

• sudo apt-get update
• sudo apt-get install ca-certificates curl gnupg lsb-release
• sudo mkdir -p /etc/apt/keyrings
• curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
• sudo apt-get update
• sudo apt-get install docker-ce-rootless-extras

Now you would need to login into to you docker hub account by running the below command

• sudo docker login

Setting up Container Signing

• Download the Container Signing Tools from CodeSignSecure portal.
• Go to folder SignImage

• Open “ec-signer.conf” file and update the codesigning url, path of your SSL Authentication certificate, and the password of the certificate.

  

  NOTE: The SSL Authentication Certificate and password can be generated from CodeSignSecure portal.

  

• Open terminal

• Execute

                      
            ./ec-signer --project_name=<certificate name> --image_name=<target container> --docker_username=<your docker username>
                      
                    

• You will be prompted to provide the docker hub password and the root privileges to the current user

  

• You will be able to see a new signature image on your docker hub account.

Verifying Container Image

Verification of Container Images will allow you to deploy to only deploy signed docker images and reject unsigned ones. To verify container image signing, Kubernetes needs to be deployed.

Installing Kubernetes

Please follow the following command to install Kubernetes

                      
                        curl -sfL https://get.k3s.io | sh -
                      
                    

Creating Kubernetes Services

Before we can verify an image in Kubernetes environment, following services needs to deployed in the Kubernetes cluster

• Verify Image Service
• Image Validation Webhook Service

To create the Verify Image Service, follow the below steps:

• Go to the ../VerifyImage/image-verifier directory.

• Create a docker image with name "verifyImage" using the Dockerfile present in the folder

  For example: sudo docker build -t aryan34/demo:verifyImage .

  where "aryan34" is the docker username and "demo" is the docker hub repository name.

• Now push this image to your docker hub account

  For example: sudo docker image push aryan34/demo:verifyImage

  where "aryan34" is the docker username and "demo" is the docker hub repository name.

• Now open the validator-deploy.yaml file and update the following settings
  • cert_name
  • server_url
  • pfx_file_path
  • pfx_file_passwd
  • DOCKER_USERNAME
  • DOCKER_PASSWORD
  • image (NOTE: Keep the image name as "verifyImage". Only change the docker username and repository name.)

  

• Deploy the Image Verifier Service

                      
                          sudo kubectl apply -f validator-deploy.yaml
                      
                    

To create the Image Validation Service, follow the below steps:

• Go to the ../VerifyImage/validating-webhook directory.

• Create a docker image with name "image-validation-webhook" using the Dockerfile present in the folder

  For example: sudo docker build -t aryan34/demo:image-validation-webhook .

  where "aryan34" is the docker username and "demo" is the docker hub repository name.

• Now push this image to your docker hub account

  For example: sudo docker image push aryan34/demo:image-validation-webhook

  where "aryan34" is the docker username and "demo" is the docker hub repository name.

• Now deploy the webhook secrets and configuration yaml files.

                      
                          sudo kubectl apply -f webhook-secret.yaml
                      
                    

                      
                          sudo kubectl apply -f webhook-config.yaml
                      
                    

• Now open the webhook-deploy.yaml file and update the following settings
  • image (NOTE: Keep the image name as "image-validation-webhook". Only change the docker username and repository name.)

  

• Deploy the Image Validation Webhook

                      
                          sudo kubectl apply -f webhook-deploy.yaml
                      
                    

• If the services are successfully deployed, when we execute the following command –

                      
                          sudo kubectl get pods --all-namespaces
                      
                    

  We should get the following output -

  

Testing

If we try to deploy any container image which is not signed, deployment will fail. We will be only able to deploy a signed image due to our verifier and validation kubernetes services.

Deploying an Unsigned Image

We need to create a yaml file for the unsigned image

We have created a demo-deployment-unsigned.yaml file to deploy the unsigned aryan34/demo:notSigned image.

Here is a sample yaml file. Remember to change the Deployed service name (demo-deployment-unsigned), image name, and the port number.

                
                  apiVersion: apps/v1
                  kind: Deployment
                  metadata:
                    name: demo-deployment-unsigned
                    labels:
                      app: demo
                  spec:
                    replicas: 1  # Number of desired replicas
                    selector:
                      matchLabels:
                        app: demo
                    template:
                      metadata:
                        labels:
                          app: demo
                      spec:
                        containers:
                          - name: demo
                            image: aryan34/demo:notSigned  # unsigned demo image
                            ports:
                              - containerPort: 8997  # Port to expose
                
              

To deploy the unsigned image using kubernetes, run the below command

                
                  sudo kubectl apply -f demo-deployment-unsigned.yaml
                
              

Deploying a Signed Image

Here is a sample yaml file. Remember to change the Deployed service name (deployed-demo), image name, and the port number.

                
                  apiVersion: apps/v1
                  kind: Deployment
                  metadata:
                    name: demo-deployment
                    labels:
                      app: demo
                  spec:
                    replicas: 1  # Number of desired replicas
                    selector:
                      matchLabels:
                        app: demo
                    template:
                      metadata:
                        labels:
                          app: demo
                      spec:
                        containers:
                          - name: demo
                            image: aryan34/demo:new3  # signed demo image
                            ports:
                              - containerPort: 8999  # Port to expose
                
              

To deploy the signed image using kubernetes, run the below command

                
                  sudo kubectl apply -f demo-deployment.yaml
                
              

Now if you check all the pods, you will see a demo-deployment service successfully running.

PKCS11 Wrapper

The PKCS11 Wrapper tool provides a medium to perform cryptographic operations with the HSM. This PKCS11 Wrapper is available in all operating systems: Windows, MacOS, and Linux. You can download this wrapper from our CodeSign Secure Portal in the "Signing Tools" section, which will be required for signings such as APK Signing, XMLSecTool Signing, and many more.

APK Signing

For APK signing, we use APKSigner which is command-line utility included in the Android SDK Build Tools that allows you to sign Android application package (APK) files and verify their signatures. It's an essential tool for Android developers to ensure the integrity and authenticity of their apps.

For Linux - Ubuntu

To sign your APK using APKSigner and our PKCS#11 wrapper in Ubuntu, please follow the below steps:

• Go to EC CodeSign Secure’s v3.02’s Signing Tools section and download the PKCS11 Wrapper for Ubuntu.

  

• After that, generate a P12 Authentication certificate from the System Setup > User > Generate Authentication Certificate dropdown.

  

• Go to your Ubuntu client system and edit the configuration files (ec_pkcs11client.ini and pkcs11properties.cfg) downloaded in the PKCS11 Wrapper.

  

  NOTE: When using Luna HSM, add the slot number in the pkcs11properties.cfg file as shown below:

  

• Now, let’s install some prerequisites in your client system to run the PKCS11 Wrapper.

  • Install Java 8: sudo apt install openjdk-8-jdk

    

  • Set Java 8 as the active version: sudo update-alternatives --config java

    

  • Install the Android SDK command-line tools: sudo apt install google-android-cmdline-tools-13.0-installer

    

  • Ensure that the SDK Manager for Android Studio has been properly installed: sdkmanager –-version

    

  • Install Build tools using SDKManager, which contains the APKSigner: sdkmanager "build-tools;34.0.0"

    

  • Ensure that APKSigner is present: apksigner --version

    

  • Two packages are required to run the PKCS11 Wrapper on your system. First, install liblog4cxx-dev using: sudo apt-get install liblog4cxx-dev

    

  • The last prerequisite is to install the curl package: sudo apt-get install curl

    

Signing

Now that all the configurations and prerequisites have been installed. Let’s perform the signing operation first.

The signing command will look something like this (ensure you run this command only inside the folder where your PKCS11 Wrapper is installed):

                  
                    apksigner sign --provider-class sun.security.pkcs11.SunPKCS11 --provider-arg  <path of the pkcs11properties.cfg file in your system> --ks NONE --ks-type PKCS11 --ks-pass pass:abcd1234 --ks-key-alias <private key alias> --in <path of the APK file you want to sign> --out <path of the Signed APK file>
                  
                

A sample command is provided below:

                  
                    apksigner sign --provider-class sun.security.pkcs11.SunPKCS11 --provider-arg  /home/administrator/PKCS11_Wrapper-Ubuntu/pkcs11properties.cfg --ks NONE --ks-type PKCS11 --ks-pass pass:abcd1234 --ks-key-alias gpg2 --in Sample.apk --out signed.apk
                  
                



NOTE: When working with Luna HSM, use the following signing command structure:

                  
                    apksigner sign --provider-class sun.security.pkcs11.SunPKCS11 --provider-arg  <path of the pkcs11properties.cfg file in your system> --ks NONE --ks-type PKCS11 --ks-pass pass:abcd1234 --ks-key-alias <private key alias> --in <path of the APK file you want to sign> --out <path of the Signed APK file> --min-sdk-version 28
                  
                

Verification

After successfully signing the APK, let’s verify it using this command:

                  
                    apksigner verify -verbose <path of the signed APK file>
                  
                

A sample command is provided below:

                  
                    apksigner verify -verbose signed.apk
                  
                



NOTE: When working with Luna HSM, use the following verifying command structure:

                  
                    apksigner verify -verbose --min-sdk-version 28 <path of the signed APK file>
                  
                

For MacOS

To perform APK Signing using APKSigner Tool and our PKCS11 Wrapper in MacOS machine, you would need to follow the below steps:

• Go to EC CodeSign Secure’s v3.02’s Signing Tools section and download the PKCS11 Wrapper for MacOS.

  

• After that, generate a P12 Authentication certificate from the System Setup > User > Generate Authentication Certificate dropdown.

  

• Go to your MacOS client system and edit the configuration files (ec_pkcs11client.ini and pkcs11properties.cfg) downloaded in the PKCS11 Wrapper.

  

  NOTE: When using Luna HSM, add the slot number in the pkcs11properties.cfg file as shown below:

  

• Now, let’s install some prerequisites in your client system to run the PKCS11 Wrapper.

  • Install Java 17: brew install openjdk@17

    

  • Set Java 17 as the active version

    For Zsh: nano ~/.zshrc

    

    For Bash: nano ~/.bash_profile

    

    Add these lines:
    export JAVA_HOME=$(/usr/libexec/java_home -v 17)
    export PATH=$JAVA_HOME/bin:$PATH

    And then run:
    source ~/.zshrc
    or
    source ~/.bash_profile

  • Install the Android SDK command-line tools from this site

    
    

  • Ensure that the SDK Manager for Android Studio has been properly installed: sdkmanager --sdk_root=/Users/subhayuroy/PKCS11_Wrapper-Mac --version

    

  • Install Build tools using SDKManager, which contains the APKSigner: sdkmanager --sdk_root=/Users/subhayuroy/PKCS11_Wrapper-Mac "build-tools;34.0.0"

    

  • Ensure that APKSigner is present: ls /Users/subhayuroy/PKCS11_Wrapper-Mac/build-tools/34.0.0/apksigner

    

  • Two packages are required to run the PKCS11 Wrapper on your system. First, install liblog4cxx-dev using: brew install log4cxx

    

  • The last prerequisite is to install the curl package: brew install curl

    

  • You need to ensure all the relative paths are added to your PATH variable (~/.zshrc file):
    export PATH=/Users/subhayuroy/PKCS11_Wrapper-Mac/cmdline-tools/bin:$PATH
    export JAVA_HOME=$(/usr/libexec/java_home -v 17)
    export PATH=$JAVA_HOME/bin:$PATH
    export ANDROID_SDK_ROOT=/Users/subhayuroy/PKCS11_Wrapper-Mac
    export PATH=$PATH:/Users/subhayuroy/PKCS11_Wrapper-Mac/build-tools/34.0.0

    

Signing

Now that all the configurations and prerequisites have been installed. Let’s perform the signing operation first.

The signing command will look something like this (ensure you run this command only inside the folder where your PKCS11 Wrapper is installed):

                  
                    java --add-exports=jdk.crypto.cryptoki/sun.security.pkcs11=ALL-UNNAMED -jar <path of the apksigner.jar in your system> sign --provider-class sun.security.pkcs11.SunPKCS11 --provider-arg <path of the pkcs11properties.cfg file in your system> --ks NONE --ks-type PKCS11 --ks-pass pass:abcd1234 --ks-key-alias <private key alias>  --in <path of the APK file you want to sign> --out <path of the Signed APK file>
                  
                

A sample command is provided below:

                  
                    java --add-exports=jdk.crypto.cryptoki/sun.security.pkcs11=ALL-UNNAMED \
                    -jar /Users/subhayuroy/PKCS11_Wrapper-Mac/build-tools/34.0.0/lib/apksigner.jar \
                    sign \
                    --provider-class sun.security.pkcs11.SunPKCS11 \
                    --provider-arg /Users/subhayuroy/PKCS11_Wrapper-Mac/pkcs11properties.cfg \
                    --ks NONE \
                    --ks-type PKCS11 \
                    --ks-pass pass:abcd1234 \
                    --ks-key-alias gpg2 \
                    --in Sample.apk \
                    --out signed.apk

                  
                



Verification

After successfully signing the APK, let’s verify it using this command:

                  
                    apksigner verify -verbose <path of the signed APK file>
                  
                

A sample command is provided below:

                  
                    apksigner verify -verbose signed.apk
                  
                

For Windows

To perform APK Signing using APKSigner Tool and our PKCS11 Wrapper in Windows machine, you would need to follow the below steps:

• Go to EC CodeSign Secure’s v3.02’s Signing Tools section and download the PKCS11 Wrapper for Windows.

  

• After that, generate a P12 Authentication certificate from the System Setup > User > Generate Authentication Certificate dropdown.

  

• Go to your Windows client system and edit the configuration files (ec_pkcs11client.ini and pkcs11properties.cfg) downloaded in the PKCS11 Wrapper.

  
  
  

  NOTE: When using Luna HSM, add the slot number in the pkcs11properties.cfg file as shown below:

  

• Now, let’s install some prerequisites in your client system to run the PKCS11 Wrapper.

  • Install Java 22 from Oracle’s official site, and follow the instructions in the msi file.

    
    
    

  • Set Java 22 as the active version by storing the bin path in the PATH variable.

    

  • Install the Android SDK command-line tools from this link here.

    

  • Extract the files into a “cmdline-tools” folder and create a subfolder named latest. Now, move the bin and lib folders into the latest folder.

    

  • Set an environment variable called ANDROID_HOME and set it to the path where you extracted the command line tools.

    

  • Install Build tools using SDKManager, which contains the APKSigner: .\bin\sdkmanager --channel=0 --install "build-tools;34.0.0"

    

  • Ensure that APKSigner is present: Apksigner.bat --version

    

Signing

Now that all the configurations and prerequisites have been installed. Let’s perform the signing operation first.

The signing command will look something like this (ensure you run this command only inside the folder where your PKCS11 Wrapper installed):

                  
                    apksigner sign --provider-class sun.security.pkcs11.SunPKCS11 --provider-arg  <path of the pkcs11properties.cfg file in your system> --ks NONE --ks-type PKCS11 --ks-pass pass:abcd1234 --ks-key-alias <private key alias> --in <path of the APK file you want to sign> --out <path of the Signed APK file>
                  
                

A sample command is provided below:

                  
                    apksigner sign --provider-class sun.security.pkcs11.SunPKCS11 --provider-arg C:\Users\riley\Downloads\PKCS11_Wrapper-Windows\pkcs11properties.cfg --ks NONE --ks-type PKCS11 --ks-pass pass:secretpassword --ks-key-alias gpg2 --in Sample.apk --out signed.apk
                  
                



Verification

After successfully signing the APK, let’s verify it using this command:

                  
                    apksigner verify -verbose <path of the signed APK file>
                  
                

A sample command is provided below:

                  
                    apksigner verify -verbose signed.apk
                  
                

XML Signing

For XML signing, we use XMLSecTool which is a powerful command-line tool that provides a range of functionalities for securing XML documents. Combining with out PKCS11 Wrapper Tool, you will be easily able to digitally sign XML files and ensure their integrity and authenticity.

For Linux - Ubuntu

To perform XML Signing using XMLSec Tool and our PKCS11 Wrapper in Linux (Ubuntu) machine, you would need to follow the below steps:

• Download our PKCS11 Wrapper Tool from CodeSign Secure portal in the Signing Tools section in your Ubuntu machine.



• Next we will need to download the latest version of XMLSec Tool (xmlsectool-3.0.0-bin.zip) using this link. You will need to extract the zip file into a directory of your choice.





• Go to your PKCS11 Wrapper directory (../PKCS11_Wrapper_Ubuntu).





• Open the "pkcs11properties.cfg" file in a text editor and update it with the correct library path. (ec_pkcs11client.so)






NOTE: When using Luna HSM, add the slot number in the pkcs11properties.cfg file as shown below:



• Open the "ec_pkcs11client.ini" file in a text editor and update the following fields:
1. name - provide the path location of the Log xml file you downloaded with the PKCS11 Wrapper tool. (EC_PKCS11_CLIENT-LogConfig.xml)
2. url - verify the server url of your CodeSign Secure portal.
3. username - provide the username of CodeSign Secure account
4. passcode - provide the secret passcode which was used to setup CodeSign Secure portal
5. path - Provide the path location of your SSL Authentication certificate.
6. passwd - Provide the password of your SSL Authentication certificate.
• NOTE: To create the SSL Auth Certificate, go to the CodeSign Secure Portal -> System Setup -> User. From the right drop down, select the "Generate Authorization Certificate" option.







• The initialization file should look like this with all the correct file paths and settings.





• Now, you would need to download and install Java in your Ubuntu machine.

  Open Terminal from interface or press (Ctrl+Alt+T). Run the below commands to install the Amazon corretto 17 java version on your machine.

  You can check other supported Java versions with XMLSec Tool here.

                  
                    wget -O - https://apt.corretto.aws/corretto.key | sudo gpg --dearmor -o /usr/share/keyrings/corretto-keyring.gpg && \
echo "deb [signed-by=/usr/share/keyrings/corretto-keyring.gpg] https://apt.corretto.aws stable main" | sudo tee /etc/apt/sources.list.d/corretto.list
                  
                

• Now install the package using the below command

                  
                    sudo apt-get update; sudo apt-get install -y java-17-amazon-corretto-jdk
                  
                

• To check whether Java has installed properly or not, run the below command:

                  
                    java -version
                  
                

• Now, you would need to add a "JAVA_HOME" environment variable in you system. Run the below command to find the correct path of Java in your system.

                    
                      update-alternatives --config java
                    
                  

  It might ask you to choose between paths if you have multiple Java versions installed. Enter the number which corressponds to your Java version.

  The path will look something similar to this: /usr/lib/jvm/java-17-amazon-corretto/bin/java

• Before you set the JAVA_HOME variable system wide in the environment file, you should take a backup of the environment file.

                  
                      cp ~/.bashrc ~/.bashrc.bak
                  
                

NOTE: If you make an error while setting the environment variables, you can always use this backup file to reset.

Run the command: cp /etc/skel/.bashrc ~/

• Replace the path of Java file before running the below command to set the JAVA_HOME variable.

                      
                        echo "export JAVA_HOME=/usr/lib/jvm/java-17-amazon-corretto" >> ~/.bashrc
                      
                    

  NOTE: Only add the path till the main directory i.e. java-17-amazon-corretto

• Check the last 3 lines of the file to verify the change by running the below command

                      
                        tail -3 ~/.bashrc
                      
                    

• Run the below command to reload the environment variable

                  
                      source ~/.bashrc
                  
                

• You would also need to install some other pre-requisite packages to perform XML signing.
• sudo apt-get install curl
• sudo apt-get install liblog4cxx12



NOTE: If "sudo apt-get install liblog4cxx12" command gives error, run the following steps to install this package

For amd architecture:

• wget http://archive.ubuntu.com/ubuntu/pool/universe/l/log4cxx/liblog4cxx12_0.12.1-4_amd64.deb
• sudo dpkg -i liblog4cxx12_0.12.1-4_amd64.deb



For arm architecture:

• wget http://ports.ubuntu.com/pool/universe/l/log4cxx/liblog4cxx12_0.12.1-4_arm64.deb
• sudo dpkg -i liblog4cxx12_0.12.1-4_arm64.deb

We are now ready with our environment to perform the XML signing using XMLSec tool and PKCS11 Wrapper

Signing

For Signing, change the working directory of the terminal to that folder which contains your "ec_pkcs11client.ini" file.



Now, run the signing command from this directory.

                  
                    <Path of xmlsectool.sh file> --sign --pkcs11Config <Path of pkcs11properties.cfg> --keyAlias <Key alias of the signing certificate> --keyPassword NONE --inFile <Path of XML file> --outFile <Path of the signed XML file>
                  
                

A sample command is provided below:

                  
                    ../xmlsectool-3.0.0-bin/xmlsectool-3.0.0/xmlsectool.sh --sign --pkcs11Config pkcs11properties.cfg --keyAlias DemoCertificate --keyPassword NONE --inFile ../xmlSample.xml --outFile ../out-xmlSample.xml
                  
                

Verification

For Verification, run the following command:

                  
                    <Path of xmlsectool.sh file> --verifySignature --pkcs11Config <Path of pkcs11properties.cfg> --keyAlias <Key alias of the signing certificate> --keyPassword NONE --inFile <Path of the signed XML file>
                  
                

A sample command is provided below:

                  
                    ../xmlsectool-3.0.0-bin/xmlsectool-3.0.0/xmlsectool.sh --verifySignature --pkcs11Config pkcs11properties.cfg --keyAlias gpg2 --keyPassword NONE --inFile ../out-sample.xml
                  
                

For MacOS

To perform XML Signing using XMLSec Tool and our PKCS11 Wrapper in MacOS machine, you would need to follow the below steps:

• Download our PKCS11 Wrapper Tool from CodeSign Secure portal in the Signing Tools section in your MacOS.



• Go to your PKCS11 Wrapper directory (../PKCS11_Wrapper-Mac) and update the "pkcs11properties.cfg" and "ec_pkcs11client.ini" with the required details.



For "pkcs11properties.cfg", update the library path.

NOTE: When using Luna HSM, add the slot number in the pkcs11properties.cfg file as shown below:



For "ec_pkcs11client.ini" file, update the following fields:

1. name - provide the path location of the Log xml file you downloaded with the PKCS11 Wrapper tool. (EC_PKCS11_CLIENT-LogConfig.xml)
2. url - verify the server url of your CodeSign Secure portal.
3. username - provide the username of CodeSign Secure account
4. passcode - provide the secret passcode which was used to setup CodeSign Secure portal
5. path - Provide the path location of your SSL Authentication certificate.
6. passwd - Provide the password of your SSL Authentication certificate.
• NOTE: To create the SSL Auth Certificate, go to the CodeSign Secure Portal -> System Setup -> User. From the right drop down, select the "Generate Authorization Certificate" option.







• The initialization and configuration files should look like this with all the correct file paths and settings.





• Next we will need to download the latest version of XMLSec Tool (xmlsectool-3.0.0-bin.zip) using this link. You will need to extract the zip file into a directory of your choice.





You will need this shell file to perform the XML signing



• Now, you would need to download and install Java in your MacOS machine. Download .pkg file of Amazon corretto 17 java version on your MacOS machine using this link.

  You can check other supported Java versions with XMLSec Tool here.

• Double-click the downloaded file to begin the installation wizard and follow the steps in the wizard.



• To check whether Java has installed properly or not, run the below command:

                  
                    java -version
                  
                

• Now, you would need to add a "JAVA_HOME" environment variable in you system. Run the below command to find the correct path of Java in your system.
• First you will need to get the complete installation path using the below command

                  
                    /usr/libexec/java_home --verbose
                  
                



• Replace the path of Java file before running the below command to set the JAVA_HOME variable.

                    
                      echo 'export JAVA_HOME="/Library/Java/JavaVirtualMachines/amazon-corretto-17.jdk/Contents/Home"' >> ~/.zshrc
                    
                  

• Run the below command to reload the environment variable

                  
                      source ~/.zshrc
                  
                

• You would also need to install some other pre-requisite packages to perform XML signing.
• brew install log4cxx
• brew install curl



We are now ready with our MacOS environment to perform the XML signing using XMLSec tool and PKCS11 Wrapper

Signing

For Signing, change the working directory of the terminal to that folder which contains your "ec_pkcs11client.ini" file.

Now, run the signing command from this directory.

                  
                    <Path of xmlsectool.sh file> --sign --pkcs11Config <Path of pkcs11properties.cfg> --keyAlias <Key alias of the signing certificate> --keyPassword NONE --inFile <Path of XML file> --outFile <Path of the signed XML file>
                  
                

A sample command is provided below:

                  
                    ../xmlsectool-3.0.0/xmlsectool.sh --sign --pkcs11Config pkcs11properties.cfg --keyAlias gpg2 --keyPassword NONE --inFile ../sample.xml --outFile  SignedSample.xml
                  
                

Verification

For Verification, run the following command:

                  
                    <Path of xmlsectool.sh file> --verifySignature --pkcs11Config <Path of pkcs11properties.cfg> --keyAlias <Key alias of the signing certificate> --keyPassword NONE --inFile <Path of the signed XML file>
                  
                

A sample command is provided below:

                  
                    ../xmlsectool-3.0.0/xmlsectool.sh --verifySignature --pkcs11Config pkcs11properties.cfg --keyAlias gpg2 --keyPassword NONE --inFile ../SignedSample.xml
                  
                

JSign Tool Signing

JSign is a versatile, platform-independent tool used for code signing of Windows executable files, installers, and scripts.

For Linux - Ubuntu

To perform Signing using JSign Tool and our PKCS11 Wrapper in Linux (Ubuntu) machine, you would need to follow the below steps:

• Go to EC CodeSign Secure’s v3.02’s Signing Tools section and download the PKCS11 Wrapper for Ubuntu.

  

• After that, generate a P12 Authentication certificate from the System Setup > User > Generate Authentication Certificate dropdown.

  

• Go to your Ubuntu client system and edit the configuration files (ec_pkcs11client.ini and pkcs11properties.cfg) downloaded in the PKCS11 Wrapper.

  

  NOTE: When using Luna HSM, add the slot number in the pkcs11properties.cfg file as shown below:

  

• Now, you will need to download the latest version of JSign tool (DEB package) in your ubuntu machine using this link.

  
  

• Install the debian package using the below command:

                      
                        sudo dpkg --install jsign_7.0_all.deb
                      
                    

  

• To check whether JSign has been properly installed or not, run the following command:

                      
                        jsign
                      
                    

  

• You will also need to install Java (Java 17 or lower) on your Ubuntu machine for JSign to work with our PKCS11 Wrapper.

  Run the following command to install Java 17 on your Ubuntu machine

                      
                        sudo apt install openjdk-17-jdk
                      
                    

  

• To use Java 17, you will need to set it as the active version.

                      
                        sudo update-alternatives --config java
                      
                    

  

• Now to check whether Java has been installed properly or not, run:

                      
                        java -version
                      
                    

  

• You would also need to install some other pre-requisite packages to perform signing usign JSign.
• sudo apt-get install curl
• sudo apt-get install liblog4cxx12



NOTE: If "sudo apt-get install liblog4cxx12" command gives error, run the following steps to install this package

For amd architecture:

• wget http://archive.ubuntu.com/ubuntu/pool/universe/l/log4cxx/liblog4cxx12_0.12.1-4_amd64.deb
• sudo dpkg -i liblog4cxx12_0.12.1-4_amd64.deb



For arm architecture:

• wget http://ports.ubuntu.com/pool/universe/l/log4cxx/liblog4cxx12_0.12.1-4_arm64.deb
• sudo dpkg -i liblog4cxx12_0.12.1-4_arm64.deb



We are now ready with our Ubuntu environment to perform the signing using JSign tool and PKCS11 Wrapper

Signing

For Signing, change the working directory of the terminal to that folder which contains your "ec_pkcs11client.ini" file.




Now, run the signing command from this directory.

                  
                    <Path of JSign tool> --keystore <Path of pkcs11properties.cfg> --storepass NONE --storetype PKCS11 --alias <Key alias of the signing certificate> <Path of the file to be signed>
                  
                

A sample command is provided below:

                  
                    jsign --keystore pkcs11properties.cfg --storepass NONE --storetype PKCS11 --alias gpg2 build_project.ps1
                  
                




NOTE: There is no verification command for JSign tool.

For MacOS

To perform Signing using JSign Tool and our PKCS11 Wrapper in MacOS machine, you would need to follow the below steps:

• Download our PKCS11 Wrapper Tool from CodeSign Secure portal in the Signing Tools section in your MacOS.



• Go to your PKCS11 Wrapper directory (../PKCS11_Wrapper-Mac) and update the "pkcs11properties.cfg" and "ec_pkcs11client.ini" with the required details.



For "pkcs11properties.cfg", update the library path.

NOTE: When using Luna HSM, add the slot number in the pkcs11properties.cfg file as shown below:



For "ec_pkcs11client.ini" file, update the following fields:

1. name - provide the path location of the Log xml file you downloaded with the PKCS11 Wrapper tool. (EC_PKCS11_CLIENT-LogConfig.xml)
2. url - verify the server url of your CodeSign Secure portal.
3. username - provide the username of CodeSign Secure account
4. passcode - provide the secret passcode which was used to setup CodeSign Secure portal
5. path - Provide the path location of your SSL Authentication certificate.
6. passwd - Provide the password of your SSL Authentication certificate.
• NOTE: To create the SSL Auth Certificate, go to the CodeSign Secure Portal -> System Setup -> User. From the right drop down, select the "Generate Authorization Certificate" option.







• The initialization and configuration files should look like this with all the correct file paths and settings.





• You will also need to install Java (Java 17 or lower) on your MacOS machine for JSign to work with our PKCS11 Wrapper.

  To install Java 17 on your MacOS machine, run the following command:

                      
                        brew install openjdk@17
                      
                    

• Find the location where Java 17 is installed on your machine:

                      
                        brew info to openjdk@17
                      
                    

• Now set Java 17 as the active version.

  For Zsh: nano ~/.zshrc

  For Bash: nano ~/.bash_profile

  After running the above command, add these lines:

  1. export PATH=<Path of Java 17 bin folder>:$PATH
  2. export JAVA_HOME=<Path of Java 17 bin folder>
  
  

  

• Reload the environment variables using the below commands:

  For Zsh: source ~/.zshrc

  For Bash: source ~/.bash_profile

• You would also need to install some other pre-requisite packages to perform signing using JSign.
• brew install log4cxx
• brew install curl



• Now, you will need to download the latest version of JSign tool (JAR package) in your ubuntu machine using this link.

  

• To check whether JSign has been properly installed or not, run the following command:

                      
                        java -jar <Path of JSign Jar Package>
                      
                    

We are now ready with our MacOS environment to perform the signing using JSign tool and PKCS11 Wrapper

Signing

For Signing, change the working directory of the terminal to that folder which contains your "ec_pkcs11client.ini" file.

Now, run the signing command from this directory.

                  
                    java -jar <Path of JSign tool> --keystore <Path of pkcs11properties.cfg> --storepass NONE --storetype PKCS11 --alias <Key alias of the signing certificate> <Path of the file to be signed>
                  
                

A sample command is provided below:

                  
                    java -jar jsign-7.0.jar --keystore pkcs11properties.cfg --storepass NONE --storetype PKCS11 --alias gpg2 build_project.ps1
                  
                




NOTE: There is no verification command for JSign tool.

For Windows

To perform signing using JSign Tool and our PKCS11 Wrapper in Windows machine, you would need to follow the below steps:

• Go to EC CodeSign Secure’s v3.02’s Signing Tools section and download the PKCS11 Wrapper for Windows.

  

• After that, generate a P12 Authentication certificate from the System Setup > User > Generate Authentication Certificate dropdown.

  

• Go to your Windows client system and edit the configuration files (ec_pkcs11client.ini and pkcs11properties.cfg) downloaded in the PKCS11 Wrapper.

  
  
  

  NOTE: When using Luna HSM, add the slot number in the pkcs11properties.cfg file as shown below:

  

• Now, let’s install some prerequisites in your client system to run the PKCS11 Wrapper.

  • Install Java 22 from Oracle’s official site, and follow the instructions in the msi file.

    
    
    

  • Set Java 22 as the active version by storing the bin path in the PATH variable.

    

• Now, you will need to download the latest version of JSign tool (JAR package) in your ubuntu machine using this link.

  

• To check whether JSign has been properly installed or not, run the following command:

                      
                        java -jar <Path of JSign Jar Package>
                      
                    

We are now ready with our Windows environment to perform the signing using JSign tool and PKCS11 Wrapper

Signing

For Signing, change the working directory of the terminal to that folder which contains your "ec_pkcs11client.ini" file.





Now, run the signing command from this directory.

                  
                    java -jar <Path of JSign tool> --keystore <Path of pkcs11properties.cfg> --storepass NONE --storetype PKCS11 --alias <Key alias of the signing certificate> <Path of the file to be signed>
                  
                

A sample command is provided below:

                  
                    java -jar jsign-7.0.jar --keystore pkcs11properties.cfg --storepass NONE --storetype PKCS11 --alias gpg2 build_project.ps1
                  
                




NOTE: There is no verification command for JSign tool.

Jarsigner Signing

Jarsigner is a command-line tool within the Java Development Kit (JDK) used for digitally signing Java Archive (JAR) files.

For Linux - Ubuntu

To perform Signing using Jarsigner Tool and our PKCS11 Wrapper in Linux (Ubuntu) machine, you would need to follow the below steps:

• Go to EC CodeSign Secure’s v3.02’s Signing Tools section and download the PKCS11 Wrapper for Ubuntu.

  

• After that, generate a P12 Authentication certificate from the System Setup > User > Generate Authentication Certificate dropdown.

  

• Go to your Ubuntu client system and edit the configuration files (ec_pkcs11client.ini and pkcs11properties.cfg) downloaded in the PKCS11 Wrapper.

  

  NOTE: When using Luna HSM, add the slot number in the pkcs11properties.cfg file as shown below:

  

• You will also need to install Java (Java 21 or lower) on your Ubuntu machine for Jarsigner to work with our PKCS11 Wrapper.

  Run the following command to install Java 21 on your Ubuntu machine

                      
                        sudo apt install openjdk-21-jdk
                      
                    

  

• To use Java 21, you will need to set it as the active version.

                      
                        sudo update-alternatives --config java
                      
                    

  

• Now to check whether Java has been installed properly or not, run:

                      
                        java -version
                      
                    

  

• You would also need to install some other pre-requisite packages to perform signing using Jarsigner.
• sudo apt-get install curl
• sudo apt-get install liblog4cxx12



NOTE: If "sudo apt-get install liblog4cxx12" command gives error, run the following steps to install this package

For amd architecture:

• wget http://archive.ubuntu.com/ubuntu/pool/universe/l/log4cxx/liblog4cxx12_0.12.1-4_amd64.deb
• sudo dpkg -i liblog4cxx12_0.12.1-4_amd64.deb



For arm architecture:

• wget http://ports.ubuntu.com/pool/universe/l/log4cxx/liblog4cxx12_0.12.1-4_arm64.deb
• sudo dpkg -i liblog4cxx12_0.12.1-4_arm64.deb



We are now ready with our Ubuntu environment to perform the signing using Jarsigner tool and PKCS11 Wrapper

Signing

For Signing, change the working directory of the terminal to that folder which contains your "ec_pkcs11client.ini" file.




Now, run the signing command from this directory.

                  
                    <Path of Jarsigner tool> -keystore NONE -storepass NONE -storetype PKCS11 -sigalg SHA256withRSA -providerClass sun.security.pkcs11.SunPKCS11 -providerArg <Path of pkcs11properties.cfg> -signedjar <Path of the file after signing> <Path of the file to be signed> <Key alias of the signing certificate> -tsa http://timestamp.digicert.com
                  
                

A sample command is provided below:

                  
                    jarsigner -keystore NONE -storepass NONE -storetype PKCS11 -sigalg SHA256withRSA -providerClass sun.security.pkcs11.SunPKCS11 -providerArg pkcs11properties.cfg -signedjar helloworld_signed.jar helloworld.jar gpg2 -tsa http://timestamp.digicert.com
                  
                




Verification

For Verification, run the following command:

                  
                    <Path of Jarsigner tool> -verify <Path of the file after signing> -certs -verbose
                  
                

A sample command is provided below:

                  
                    jarsigner -verify helloworld_signed.jar -certs -verbose
                  
                

For MacOS

To perform signing using Jarsigner and our PKCS11 Wrapper in MacOS machine, you would need to follow the below steps:

• Download our PKCS11 Wrapper Tool from CodeSign Secure portal in the Signing Tools section in your MacOS.



• Go to your PKCS11 Wrapper directory (../PKCS11_Wrapper-Mac) and update the "pkcs11properties.cfg" and "ec_pkcs11client.ini" with the required details.



For "pkcs11properties.cfg", update the library path.

NOTE: When using Luna HSM, add the slot number in the pkcs11properties.cfg file as shown below:



For "ec_pkcs11client.ini" file, update the following fields:

1. name - provide the path location of the Log xml file you downloaded with the PKCS11 Wrapper tool. (EC_PKCS11_CLIENT-LogConfig.xml)
2. url - verify the server url of your CodeSign Secure portal.
3. username - provide the username of CodeSign Secure account
4. passcode - provide the secret passcode which was used to setup CodeSign Secure portal
5. path - Provide the path location of your SSL Authentication certificate.
6. passwd - Provide the password of your SSL Authentication certificate.
• NOTE: To create the SSL Auth Certificate, go to the CodeSign Secure Portal -> System Setup -> User. From the right drop down, select the "Generate Authorization Certificate" option.







• The initialization and configuration files should look like this with all the correct file paths and settings.





• You will also need to install Java (Java 21 or lower) on your MacOS machine for Jarsigner to work with our PKCS11 Wrapper.

  To install Java 21 on your MacOS machine, run the following command:

                      
                        brew install openjdk@21
                      
                    

• Find the location where Java 21 is installed on your machine:

                      
                        brew info to openjdk@21
                      
                    

• Now set Java 21 as the active version.

  For Zsh: nano ~/.zshrc

  For Bash: nano ~/.bash_profile

  After running the above command, add these lines:

  1. export PATH=<Path of Java 21 bin folder>:$PATH
  2. export JAVA_HOME=<Path of Java 21 bin folder>

• Reload the environment variables using the below commands:

  For Zsh: source ~/.zshrc

  For Bash: source ~/.bash_profile

• You would also need to install some other pre-requisite packages to perform signing using Jarsigner.
• brew install log4cxx
• brew install curl



We are now ready with our MacOS environment to perform the signing using Jarsigner tool and PKCS11 Wrapper

Signing

For Signing, change the working directory of the terminal to that folder which contains your "ec_pkcs11client.ini" file.

Now, run the signing command from this directory.

                  
                    <Path of Jarsigner tool> -keystore NONE -storepass NONE -storetype PKCS11 -sigalg SHA256withRSA -providerClass sun.security.pkcs11.SunPKCS11 -providerArg <Path of pkcs11properties.cfg> -signedjar <Path of the file after signing> <Path of the file to be signed> <Key alias of the signing certificate> -tsa http://timestamp.digicert.com
                  
                

A sample command is provided below:

                  
                    jarsigner -keystore NONE -storepass NONE -storetype PKCS11 -sigalg SHA256withRSA -providerClass sun.security.pkcs11.SunPKCS11 -providerArg pkcs11properties.cfg -signedjar helloworld_signed.jar helloworld.jar gpg2 -tsa http://timestamp.digicert.com
                  
                




Verification

For Verification, run the following command:

                  
                    <Path of Jarsigner tool> -verify <Path of the file after signing> -certs -verbose
                  
                

A sample command is provided below:

                  
                    jarsigner -verify helloworld_signed.jar -certs -verbose
                  
                

For Windows

To perform signing using JSign Tool and our PKCS11 Wrapper in Windows machine, you would need to follow the below steps:

• Go to EC CodeSign Secure’s v3.02’s Signing Tools section and download the PKCS11 Wrapper for Windows.

  

• After that, generate a P12 Authentication certificate from the System Setup > User > Generate Authentication Certificate dropdown.

  

• Go to your Windows client system and edit the configuration files (ec_pkcs11client.ini and pkcs11properties.cfg) downloaded in the PKCS11 Wrapper.

  
  
  

  NOTE: When using Luna HSM, add the slot number in the pkcs11properties.cfg file as shown below:

  

• Now, let’s install some prerequisites in your client system to run the PKCS11 Wrapper.

  • Install Java 22 from Oracle’s official site, and follow the instructions in the msi file.

    
    
    

  • Set Java 22 as the active version by storing the bin path in the PATH variable.

    

We are now ready with our Windows environment to perform the signing using JSign tool and PKCS11 Wrapper

Signing

For Signing, change the working directory of the terminal to that folder which contains your "ec_pkcs11client.ini" file.




Now, run the signing command from this directory.

                  
                    <Path of Jarsigner tool> -keystore NONE -storepass NONE -storetype PKCS11 -sigalg SHA256withRSA -providerClass sun.security.pkcs11.SunPKCS11 -providerArg <Path of pkcs11properties.cfg> -signedjar <Path of the file after signing> <Path of the file to be signed> <Key alias of the signing certificate> -tsa http://timestamp.digicert.com
                  
                

A sample command is provided below:

                  
                    jarsigner -keystore NONE -storepass NONE -storetype PKCS11 -sigalg SHA256withRSA -providerClass sun.security.pkcs11.SunPKCS11 -providerArg pkcs11properties.cfg -signedjar helloworld_signed.jar helloworld.jar gpg2 -tsa http://timestamp.digicert.com
                  
                




Verification

For Verification, run the following command:

                  
                    <Path of Jarsigner tool> -verify <Path of the file after signing> -certs -verbose
                  
                

A sample command is provided below:

                  
                    jarsigner -verify helloworld_signed.jar -certs -verbose
                  
                

CI/CD integration

Github Actions

You can also perform codesigning using GitHub actions. For this we create a workflow in our desired repository in GitHub and perform codesigning with using the script.

Prerequisites for performing this task includes:

1. A GitHub repository (You'll require admin account)
2. Signtool installed and configured
3. ECSigning KSP installed and configured.

To install and configure Signtool and the ECSigning KSP, please follow the steps mentioned here.

Before we get started, we will need to configure a runner. Runner will be setup in the device where you have SIgntool and ECSigning KSP installed and configured.

To set up the runner, follow the steps below:

Navigate to your Github Repository. You'll need to have an admin account for this.

• Navigate to Settings of Repository.
• Scroll down to Actions and select Runner from dropdown menu.
• Click on New Self Hosted Runner.

After doing so, you can click on the runner image (macOS/Linux/Windows) of your choice. The instructions below are for windows. You’ll see a number of commands to be followed on the screen.

Run the commands that was shown in the configuration of runner. The commands are also given below

• mkdir actions-runner; cd actions-runner

• Invoke-WebRequest -Uri
  https://github.com/actions/runner/releases/download/v2.303.0/actions-runner-win-x64-2.303.0.zip -OutFile actions-runner-win-x64-2.303.0.zip

• Add-Type -AssemblyName System.IO.Compression.FileSystem ; [System.IO.Compression.ZipFile]::ExtractToDirectory("$PWD/actions-runner-win-x64-2.303.0.zip", "$PWD")

• ./config.cmd --url https://github.com/Encryption-Consulting-LLC/CodeSignSecure-Desktop --token <token_number>

Once you'll see Github Actions written on your screen, you'll be asked for runner registration.

• Enter the name of the runner group to add this runner to: [press Enter for Default] (You can leave this to default).
• Enter the name of the runner: [press Enter for CLIENT] (You can enter the desired name for your runner).

• This runner will have the following labels: 'self-hosted', 'Windows', 'X64'

  Enter any additional labels (ex., label-1,label-2): [press Enter to skip] (Please enter a label here, it can be anything, do not leave/skip this step. The same name will be used later to call runner in the script).

• The following will be prompted on your screen once it’s done

  • Runner successfully added
  • Runner connection is good

#Runner settings

• Enter name of work folder: [press Enter for _work] (You can leave this to default or you can specify a folder of your choice)

  Settings Saved

• Would you like to run the runner as service? (Y/N) [press Enter for N] (Enter Y)

• User account to use for the service [press Enter for NT AUTHORITY\NETWORK SERVICE] (Make sure you enter Administrator here)

  (Administrator privilege is required to run the command. Hence it is MUST to set the user as an administrator)

• Password for the account CLIENT\Administrator (Provide password of your Administrator account)

• Once done, you’ll see the following prompt on your screen.

  It will be prompted as Service actions.runner.<repository name>.<runner_name>

  Granting file permissions to 'CLIENT\Administrator'.

  Service actions.runner.Encryption-Consulting-LLC-CodeSignSecure-Desktop.TryThree successfully installed

  Service actions.runner.Encryption-Consulting-LLC-CodeSignSecure-Desktop.TryThree successfully set recovery option

  Service actions.runner.Encryption-Consulting-LLC-CodeSignSecure-Desktop.TryThree successfully set to delayed auto start

  Service actions.runner.Encryption-Consulting-LLC-CodeSignSecure-Desktop.TryThree successfully configured

  Waiting for service to start...

  Service actions.runner.Encryption-Consulting-LLC-CodeSignSecure-Desktop.TryThree started successfully

Once the runner is setup on your device, navigate to your repository in GitHub.

Go to Actions.

Click on New Workflow

Click on set up a workflow yourself

This is how your editor will look like. You can rename your .yaml file or leave the name to default.

Add the script below to your editor after making some changes or updating the variables.

                                    
                                    name: Code Signing
            
                                    on:
                                    push:
                                        branches: <[ Your Branch Name ]>
            
                                    jobs:
                                    build:
                                        runs-on: <Your runner name>
                                        steps:
                                        - name: Checkout code
                                            uses: actions/checkout@v2
                    
                                        - name: Sign code
                                            run: |
                                            signtool sign /csp "Encryption Consulting Key Storage provider" /kc <Key Name> /fd <hashing algorithm> /f "<Certificate Location>" /tr <timestampserver> /td SHA256 "<file path>"
                                    
                                    

Please replace the variables specified under <variable name>. A short description of expected variable is given below.

<file path>: This is where you provide the path of file that you want to sign. Example C:\<Folder_name>\<File_name>. Make sure you have provided a file name with the proper extension.

<key name>This refers to the cryptographic key used to sign the code. Example: evcodesigning

<certificate location>: An example of what can be put in this field is C:\testing.pem. The certificate.pem file MUST be included in this input. You can generate a pem file of the certificate for codesigning, if you have the key name using, ECSigningKSP. For doing so follow the commands below:

In your device where you have ECSigningKSP installed and configured, navigate to the folder of ECSigningKSP, which is usually present in “C:\Program Files\Encryption Consulting\SigningKSP”

In your command prompt reach to this directory.

Then use following command to get pem file of the certificate.

ECGetCert.exe <Key_Name>  (example: ECGetCert.exe evcodesigning)

Provide the location of the certificate saved.

<hashing algorithm>: You need provide the name of hashing algorithm such as SHA256, SHA384, or SHA512. It must be one of these three values.

<time stamp server>: A timestamp server provides proof that a digital signature was performed at a specific time, allowing verification in the future that a file was signed at a particular time. The one we generally use is http://timestamp.digicert.com

The Command I used for signing was

signtool sign /csp "Encryption Consulting Key Storage provider" /kc evcodesigning /fd SHA256 /f "C:\Users\Administrator\Desktop\ForTesting\evcodesigning.pem" /tr http://timestamp.digicert.com /td SHA256 "C:\Users\Administrator\Desktop\ForTesting\AgentService.exe"

The Script I used was:

                                        
                                        name: Code Signing

                                        on:
                                        push:
                                            branches: [ Github_Actions ]
                
                                        jobs:
                                        build:
                                            runs-on: runner
                                            steps:
                                            - name: Checkout code
                                                uses: actions/checkout@v2
                
                                            - name: Sign code
                                                run: |
                                                    signtool sign /csp "Encryption Consulting Key Storage provider" /kc evcodesigning /fd SHA256 /f "C:\Users\Administrator\Desktop\ForTesting\evcodesigning.pem" /tr http://timestamp.digicert.com /td SHA256 "C:\Users\Administrator\Desktop\ForTesting\AgentService.exe"
                                        
                                    

Once you’ve edited your script, click on commit. You can commit directly to your default branch or commit to a new branch. Make sure you update the name of your branch inside the code. After committing the job will run.

Jenkins

To perform codesigning using Jenkins the following steps are necessary:

Prerequisites:

1. Jenkins must be setup and configured on your device.
2. Signtool must be installed and configured.
3. The ECSigning KSP must be installed and configured.

To install and configure Signtool and the ECSigning KSP, please follow the steps mentioned here.

To Setup and Configure Jenkins go through the link

Once Jenkins is setup, we will require administrative privilege to run the command for signtool. To set up administrative privilege for Jenkins using these steps:

• Go to services on your system (You can just search for it)
• Scroll down to Jenkins. There in the “Log on As” column you can see the user account set up for Jenkins. If it’s set to anything (Local Service/System, Network Service/System) other than “.\Administrator”, then we have to set it for Administrator.

• Double Click on Jenkins or Right Click > Properties to open Properties. Go to Log On. Select “This Account”

  Set it as “.\Administrator”. Give a password, preferably admininstrator password. Click on Apply once done.

  

Once we have set this we’ll now head to Jenkins. Whichever URL/hostname you specified earlier while setting up, navigating to that from your browser will lead you to Jenkins. In my system I have set it up as http://localhost:8080/ (It is also default).

In you Dashboard follow the steps below:

• Click on Manage Jenkins (NOTE: Manage Jenkins doesn’t come up unless you have a job created)

  

• Scroll down to Plugins, Under System Configuration

  

• In Manage Plugins, in “Available Plugins” section, search for powershell plugin. It won’t show in search result in this section if it has already been installed. You can see under “Installed Plugins” to see the plugins you have installed.

  Click the Checkbox of the plugin (if not already installed), and click on Install without restart. You can refresh the page once installed.

• After doing so go to Global Tool Configuration. Dasboard > Manage Jenkins > Under System Configuration (as shown in the picture above) – Global Tool Configuration

• Scroll down to Powershell. Click on Add Powershell. You’ll see configuration window like the picture below. Name you powershell. Provide the path (where it is located in your machine) to your powershell. The default path is

  C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe

  Click on Apply and Save.

  

After we’ve configured powershell. We’ll mov

• From Dashboard click on New Item

• Enter any item name and click on pipleline and click ok.

  

• In configuration page, under General put up a description as your wish

  

• Scroll down to the bottom to find Pipeline.

  

• Write the script in the script box and click on save. You’ll need to edit your environment variable as per your setup

                                          pipeline {
                                              agent any
                                              environment {
                                                  SM_KEY_NAME='evcodesigning'
                                                  SM_CLIENT_CERT_FILE='C:\\Users\\Administrator\\Desktop\\ForTesting\\evcodesigning.pem'
                                                  SM_HASHING_ALGORITHM='SHA256'
                                                  SM_TIME_STAMP_SERVER="http://timestamp.digicert.com"
                                                  SM_FILEPATH="C:\\Users\\Administrator\\Desktop\\ForTesting\\AgentService.exe"
                                              }
                                              stages {
                                                  stage('Code Signing') {
                                                      steps {
                                                          dir('C:\\Users\\Administrator\\Desktop\\ForTesting'){
                                                              bat 'signtool sign /csp "Encryption Consulting Key Storage provider" /kc %SM_KEY_NAME% /fd %SM_HASHING_ALGORITHM% /f %SM_CLIENT_CERT_FILE% /tr %SM_TIME_STAMP_SERVER% /td SHA256 %SM_FILEPATH%'
                                                          }
                                                      }
                                                  }
                                              }
                                          }
                                          

• Click on build now and you’ll see a build number running on the screen

  

• If you click on the build number and go for console output you’ll see that your file has been signed.

  

GitLab

Using Gitlab for code signing process require you to set up a runner which has Signtool, ECSigningKSP and a GitLab Account. Listing down the pre-requisites:

1. Self Hosted Runner which has ECSigning KSP, Signtool installed and configured. This runner should be provided with Administrative privileges.
2. A GitLab Account.

To set up the ECSigningKSP and Signtool please navigate to section 11.2. After doing so, please follow the steps below:

• Set Up a GitLab Account. Navigate to creating a New Blank Project.

• Scroll down to settings -> CI/CD and navigate to runner. Expand it.

  

• Install GitLab runner in your device using the link. This link is for Windows. You can look this link to see steps to Install it in your specific device.
• You can follow the documentation to set up your runner and register it as per your device.

To register a runner under Windows:

1. Run the following command:

   .\gitlab-runner.exe register

2. Enter your GitLab instance URL (also known as the gitlab-ci coordinator URL). Example: https://gitlab.com
3. Enter the token you obtained to register the runner. You can access this from settings -> CI/CD -> Expand -> Project runners. Under project runners you can find token.
4. Enter a description for the runner. You can change this value later in the GitLab user interface. Example: Device
5. Enter the tags associated with the runner, separated by commas. You can change this value later in the GitLab user interface. Example: WindowsRunner
6. Enter any optional maintenance note for the runner.
7. Provide the runner executor. We’re operating this in Shell.

Once the runner is installed and configured, navigate to services in your device, scroll down to GitLab Runner and set log on as Administrator. Provide Admin Password here.

Once this is done, go to your project. You might have to rename the .ym file name. Rename it as .gitlab-ci.yml.

There are three sections in this pipeline.

1. Tags

   The tags you provided while setting up the runner

2. Variables

   EC_Client_Auth : Corresponds to the path of your SSL Authentication certificate which can be created from CodeSignSecure.

   EC_Client_Pass : Corresponds to the password of your certificate which is provided at the time of creation of the certificate.

3. Script

   Provide the signtool command to sign a file.

A sample script is given below to perform codesigning.

                                    job1:
                                            tags:
                                                    - shell
                               
                                            variables:
                                                    EC_Client_Auth: C:\Users\riley\Documents\EncryptionConsulting\Test_demo.pfx
                                                    EC_Client_Pass: c74c5b7db312
                               
                                            script:
                                                    - signtool sign /csp "Encryption Consulting Key Storage provider" /kc Test_aryan90 /fd SHA256 /f "C:\Users\riley\Desktop\gitlab\Test_aryan90.pem" /tr http://timestamp.digicert.com /td SHA256 "C:\Users\riley\Desktop\agent.exe"                           
                                

If you click on Build -> Jobs, you'll see it being successfully signed.

You'll need to modify the command as per your variables

• kc <certificate name>: replace evcodesiging with your key name
• f <certificate location>: replace location with location of your .pem file to perform codesiging. You can get this by using signing KSP. From command prompt reach to the directory having SigningKSP. Use command ECGetCert.ece to get pem file of your certificate.
• tr http://timestamp.digicert.com: time stamping server
• td SHA256 <file location>: location of file you want to get signed.

Azure DevOps

1. Navigate to dev.azure.com and sign in with your Microsoft account or you can start free with your GitHub Account too

2. Give the details as prompted

   

3. You’ll be asked to create an organization if you haven’t already. Create a organization and get started with the project.

4. If you already have a project where you want to build the pipeline, navigate to pipelines. If not create a simple project first. Provide the necessary details to continue.

   

5. After a project is made, navigate to user setting at the top left corner of your screen and click on personal Access token. On the next page click on “New Token”. On the dialogue box prompted, provide necessary details such as name of the token, organization name (the organization you created/accessed earlier. Set Expiration and Scopes. I have set the Scope to full access.

   

   

   Click on create and copy the token somewhere as you won’t be able to see the token again.

6. After we are done getting a token, we need to set up a self-hosted runner. This is a machine where Signtool and ECSigningKSP is installed and configured. To do so return to the Code Summary page and on the bottom left of the screen you’ll see Project settings, click on that.

   

   Under Pipelines, you’ll see Agent Pools. Click on that and then click on default.

   

   Click on new agent at the top left.

   

   Get the agent as per your operating system. I am proceeding with windows. Download the agent, extract it to a folder “C:\agents”.

   You can also follow this documentation for more help about this

   

7. After you extract the files, navigate to the folder where you extracted it to from cmd and run .\config.cmd.

   

   Now, Server url will be https://dev.azure.com/<your_organzation_name
   Just press enter for PAT on the authentication type and on the next question provide the token copied earlier.

   Once the Agent is registered, For Agent Pool, since we’ve it as default, press enter If you want to name your agent something you can name them but press enter for it to be named as CLIENT.

   Once the agent it added, You can leave the work folder as default or change as per your choice For Running Agent as a Service enter Y as in yes For User account to use for service make sure you set this as Administrator, this is important because you’ll require Administrative Privilege to perform code signing. Provide password for your administrative account of your machine

   Since we have set this as a service, the agent will run automatically if we hadn’t set this as service, we would have to manually run the agent.

   Navigate to services.msc and scroll down to Azure Pipeline Agent to see you’ve se Log on as Administrator. If you didn’t do so, you can change it from itself. Just click on log on and a dialogue box will appear; navigate to log on, set it to Administrator and provide the password for the same and restart the service. Once this is done, go back to Azure DevOps to build the pipeline.

8. Click on pipelines to get started.

   

   Click on Create Pipeline in the following page.

9. In the next page, in the Connect section, choose where your code is. In this my code is in GitHub and I am proceeding with so. You will require Administrative Privilege of your repository to grant access.

   

10. Select the repository where you’ve your code.

    

11. Now in the Configure Section, if you don’t already have .yml file in your repository click on Starter Pipeline, if you do click on Existing Azure Pipeline. For starter pipeline, you may need to create a new branch or commit on the main branch itself it’s your choice.

    

12. In the editor write the following script

                                    
                                    
                                        trigger:
                                        - <your_branch_name>
                                    
                                        
                                        pool:
                                          name: <your_pool_name> #In this documentation it’s set as Default
                                        
                                        
                                        variables:
                                          varible_name: variable_value
                                        
                                        
                                        steps:
                                        - script: |
                                          signtool sign /csp "Encryption Consulting Key Storage provider" /kc <Key_name> /fd
                                        <hashing algorithm> /f <certificate location> /tr <time
                                        stamping server> /td SHA256 <file path>
                                        
                                    
                                    

Please replace the variables specified under <variable name>. A short description of expected variable is given below.

<key name>: This refers to the cryptographic key used to sign the code. Example: evcodesigning

<hashing algorithm>: You need provide the name of hashing algorithm such as SHA256, SHA384, or SHA512. It must be one of these three values.

<certificate location>: An example of what can be put in this field is C:\testing.pem. The certificate.pem file MUST be included in this input. You can generate a pem file of the certificate for codesigning, if you have the key name using, ECSigningKSP. For doing so follow the commands below:

In your device where you have ECSigningKSP installed and configured, navigate to the folder of ECSigningKSP, which is usually present in “C:\Program Files\Encryption Consulting\SigningKSP”

In your command prompt reach to this directory.

Then use following command to get pem file of the certificate

ECGetCert.exe <Key_Name> (example: ECGetCert.exe evcodesigning)

Provide the location of the certificate saved.

<time stamp server>: A timestamp server provides proof that a digital signature was performed at a specific time, allowing verification in the future that a file was signed at a particular time. The one we generally use is http://timestamp.digicert.com

<file path>: This is where you provide the path of file that you want to sign. Example C:\<Folder_name>\<File_name>. Make sure you have provided a file name with the proper extension.

My script was

                            
                                
                                trigger:
                                - azure-pipelines1
                                
                                
                                pool:
                                  name: Default
                                
                                
                                variables:
                                  EC_Client_Auth: C:\Users\riley\Documents\EncryptionConsulting\testClient.pfx
                                
                                
                                steps:
                                - script: |
                                  signtool sign /csp "Encryption Consulting Key Storage provider" /kc evcodesigning 
                                /fd SHA256 /f C:\\Users\\Administrator\\Desktop\\ForTesting\\evcodesigning.pem 
                                /tr http://timestamp.digicert.com /td SHA256 C:\\Users\\Administrator\\Desktop\\ForTesting\\AgentService.exe
                                
                                
                            

When you click save and run, you’ll prompted with branch tag, make sure the name provided here and under trigger in script is same before running the script.

Once the build is successful, you’ll see that your file has been successfully signed.

TeamCity

TeamCity is a powerful CI/CD tool that automates the software development process, helping teams deliver high-quality applications faster. It provides a comprehensive platform for managing build configurations, running tests, and deploying applications to various environments.

To perform codesigning using TeamCity, go through the steps below.

1. You can either download the free TeamCity application or a paid Enterprise version using the link. There are three OS choices for the application - Linux, Windows, and MacOS. We'll be working on the Windows executable file.

   

2. Run the application to install the TeamCity server in your environment.

   

3. Accept the terms and conditions and click "I Agree".

   

4. Keep the default settings for easier integration and management of the server.

   

   

   

   Click Save and then OK to proceed to the next step of account creation.

   

5. Select the option to run the TeamCity Server and TeamCity Agent under the user account and click Next. It will ask you to login as the current user of your system.

   

   

6. Select both the options to start the build agent service and the TeamCity server service. Click Next.

   

7. Click Finish. This will take you the Web UI of the TeamCity where you can create your projects and set the configurations policies.

   

8. The Web UI runs on localhost on port 8111 (default). Click Proceed to set the location of data directory for TeamCity server. Access TeamCity from a browser by going to http://localhost:8111

   

9. Select the appropriate database which will store the build history and your account related information. We will be choosing HSQLDB database for this project.

   

10. Accept the license agreement and click Continue.

    

11. Now create a login account for your CI/CD pipeline and projects.

    

12. After successful login, it will take you to the TeamCity Dashboard. Now you can begin with creating your first project. Click on "Create project".

    

13. There are two choices when you create a project on TeamCity. It can be done either using a repository account or manually.

    Let's first see the Manual process. Enter the required details for you project.

    

    Once successfully created, it will then prompt you to create a build configuration.

    

14. Here as well, you have two options - repository or manual process. We will again proceed with the manual process. Enter the required details and click Create.

    

15. It will then ask you to enter the details for Version Control Settings. It is an optional step. We will be skipping it for this project.

    

16. After setting up the general project and configuration settings, we can now add build steps to our pipeline. These are the processes that will actually execute and perform code signing operations.

    

    Click on the "Add Build Step" button and choose "Command Line" from the dropdown.

    

17. It will then ask you to enter the details for Version Control Settings. It is an optional step. We will be skipping it for this project.

    

18. Provide the basic details such as Step name and Step ID.

    Select the Custom script code option from the dropbox of Script field and enter the cmd script to perform the signing operation using the required details.

    A sample Command Line script is provided below for your reference:

                          # Execute the signtool command
                          "C:\Program Files (x86)\Windows Kits\10\bin\10.0.26100.0\x86\signtool.exe" sign /csp "Encryption Consulting Key Storage provider" /kc DemoCertificate /fd SHA256 /f "C:\demo files\Signing Certificates\DemoCertificate.crt" /tr http://timestamp.digicert.com /td SHA256 "C:\demo files\Test Files\TestFile1.exe"
                        

    The entire step should look something similar to the image below:

    

19. Now repeat the above process to create another build step for Verification of the signed file.

    A sample Command Line script is provided below for your reference:

                          # Execute the signtool verify command
                          "C:\Program Files (x86)\Windows Kits\10\bin\10.0.26100.0\x86\signtool.exe" verify /pa "C:\demo files\Test Files\TestFile1.exe"
                        

    The entire step should look something similar to the image below:

    

20. Now to run the pipepline, click on "Run" which is on the top-right of the project view.

    After clicking "Run", you can see the live action of the pipeline by clicking "Agents"(top-left)->Select the agent name->Build History.

    

21. A successfull execution of a pipeline will look like this. Here you can see that both the build steps - signing and verification - have been completed.

    

Bamboo – Atlassian CI/CD Pipeline

1. Download Bamboo

• Go to the Atlassian Bamboo download page to download the version that is suitable for your Windows system.

• Check the compatibility for your supported platform here.

2. Install Bamboo for your Windows 11

   • Once the Bamboo zip file is downloaded, extract it to your desired directory, for example, C:\Atlassian\

   • Bamboo requires Java to run. Make sure your system has JDK 17 installed.

   • After installing JDK 17, set the JAVA_HOME environment variable to the path of your JDK 17.

3. Configure Bamboo

   • Open the extracted folder and navigate to this path: <Bamboo installation folder>/Atlassian-bamboo/WEB-INF/classes/ and open the bamboo-init.properties file.

   • In this file, insert the property “bamboo.home”, with an absolute path to your Bamboo home directory (for example, C:\Atlassian\Bamboo). Your file should look like this: bamboo.home=C:\Atlassian\Bamboo

   • Open a command prompt as an Administrator in the Bamboo installation directory (C:\Atlassian)

   • Start Bamboo using the following command: bin\start-bamboo.bat

   • Access Bamboo from a browser by going to http://localhost:8085

4. Setup Bamboo on the web portal now

   • You will be asked for a license.

     

   • You have to copy your Server ID.

   • Go to the license evaluation site and select your product as Bamboo. After that, enter the necessary details, and then the Server ID is copied above.

     This will generate your License.

     

   • Paste this license on the Bamboo Dashboard and click on “Continue.”

     

   • Configure the Instance with the necessary details.

     

   • Bamboo requires a database to store build data. You can use PostgreSQL, MySQL, or any supported database. By default, Bamboo will offer to use an embedded HSQL database, but for production use, it’s better to configure an external one (like PostgreSQL or MySQL). In our case, we are using an H2-embedded database; you can follow this guide.

   • After configuring the Database, complete the setup in the Web UI, by configuring an Administrator Account (admin username, password, and email).

5. Install Bamboo agents

   • Download the Remote Agent Jar from the Agents section inside Build Resources.

   • In the Agents tab, you’ll see a list of both local and remote agents that are connected to Bamboo. If you don’t see any agent, click on the “Install Remote Agent” button.

     

   • After that, you’ll be prompted to approve the agent.

     

   • Check the agent’s status and capabilities after clicking on the Agent.

     

6. Create and configure a new Bamboo Plan

   • Navigate to the Dashboard and click on Create > Create Plan.

     

   • Configure the plan by selecting its Project name, Plan name, and Plan key (Bamboo will auto-generate this key based on the Plan name).

     

   • You will be required to provide a Repository Host. (we’re going to sign an already compiled file, so we chose “None”).

     

   • Choose the environment you want to run this Job (Agent Environment) and then click on “Add Task.”

     

   • Search and select “Script” for this job.

     

   • For the script location, select “Inline” and the Interpreter as “Shell” for this job.

     

   • In the script body, paste the signtool command you want to run ("C:\Program Files (x86)\Windows Kits\10\bin\10.0.26100.0\x86\signtool.exe" sign /csp "Encryption Consulting Key Storage provider" /kc DemoCertificate /fd SHA256 /f "C:\demo files\Signing Certificates\DemoCertificate.crt" /tr http://timestamp.digicert.com /td SHA256 "C:\demo files\Test Files\TestFile1.exe") and click on “Save”.

     

   • After the task has been created successfully, click on “Create”.

     

   • You can see the Plan details now.

     

   • Then click on “Run Plan” in the Run dropdown.

     

   • You can see that your job has been successful.

     

   • Check the signature details in the executable file’s properties.