Skip to main content
This section covers the steps required to download, run, and configure Jenkins to leverage CryptoHub for code signing.

​
Set up Jenkins

Download the jenkins.war file from https://www.jenkins.io/download/. Then follow the instructions for running the WAR file and completing the post-installation setup at the following URL: https://www.jenkins.io/doc/book/installing/war-file/

​
Install the plugin

Perform the following steps to install the FXCL Jenkins plugin:
1
From the main Jenkins dashboard page, select the Manage Jenkins icon in the left-side menu.
2
Select [ Manage Plugins ] in the System Configuration section.
3
On the Plugin Manager page, go to the Advanced tab.
4
Scroll down to the Upload Plugin section and select [ Choose File ]. In the file browser, find and select the FXCL Jenkins Plugin file, and select [ Upload ].
On the Update Center page, you can see the progress of the plugin installation. If the installation succeeds, the status of the FXCL Jenkins Plugin changes to Success.

​
Register certificate credentials

This section imports the PKCS #12 file exported from the CryptoHub for Jenkins TLS communication. The PKCS #12 file contains the signed Jenkins certificate and root CA certificate (and intermediate CA certs if applicable) that issued it, protected by a password. Perform the following steps to register certificate credentials for TLS communication between Jenkins and the CryptoHub:
1
On the Manage Jenkins page, select [ Manage Credentials ] in the Security section.
2
Select the Jenkins Store contained within the global domain.
3
Select the Global credentials (unrestricted) Domain.
4
Select [ Add Credentials ] in the left-side menu.
5
Change the value in the Kind drop-down list to Certificate.
6
Select the Upload PKCS#12 certificate radio button, and select [ Choose File ]. This opens the file browser. Find and select the .p12 file, and select [ Open ]. A message should appear that says, Could retrieve key system tls ca root. You may need to provide a password.
7
Select [ Change Password ] and enter the password of the PKCS #12 file.
8
Select [ OK ] to save the new credentials.

​
Register username

This section shows how to configure and register a username with password credentials in Jenkins for the Jenkins identity created on the CryptoHub.
1
On the Manage Jenkins page, select [ Manage Credentials ] in the Security section.
2
Select the Jenkins Store, contained within the global domain.
3
Select the Global credentials (unrestricted) domain.
4
Select [ Add Credentials ] in the left-side menu.
5
Leave the value in the Kind drop-down list set to the default value (Username with password).
6
In the Username and Password fields, specify the identity name and password for the Jenkins identity created on the CryptoHub.
7
Select [ OK ] to save the new credentials.

​
Sign a file in a Freestyle project by using the CryptoHub registration authority

This section walks you through creating, configuring, and running a new Freestyle project in Jenkins. If you want to use the CryptoHub registration authority to sign code in an existing Freestyle project, skip to step 6 in the next section.

​
Create a Freestyle project

Perform the following steps to create and configure a Freestyle project to leverage the CryptoHub for code signing by using the FXCL Jenkins plugin:
1
From the main Jenkins dashboard, select the New Item icon in the left-side menu.
2
Select Freestyle project, enter a name for the project, and select [ OK ].
3
On the project configuration page, scroll down to the Build section, select [ Add build step ], and select Sign file via Futurex Code Signing in the drop-down menu. The FXCL Jenkins Plugin provides this option.
4
In the Method of Signature field, leave the field set to the default value (Code Sign).
There are currently two types of signatures: Code Sign and External Signature. Code Sign tries to use knowledge of the file format to embed a signature. If it does not understand the file format, it fails. An external signature does not need to know the file format, but it cannot embed signatures.
5
In the KMES Host field, enter the IP address or hostname of the CryptoHub. The port number is optional. It defaults to port 2001, the System/Host API port, which is the recommended port.
6
In the Issuance Policy field, enter the UUID of the issuance policy to handle the signing request.
7
In the Hash Algorithm field, select the hash algorithm to use when requesting signatures.
The hash algorithm you select must be one of the allowed hashes configured for the Issuance Policy attached to the issuing Jenkins code signing certificate inside the Jenkins Certificate Container.
8
In the Poll Interval field, specify the time in seconds that you want the FXCL Jenkins plugin to wait between code signing status requests that it sends to the CryptoHub.
9
In the TLS PKI field drop-down list, select the TLS PKI you imported as a PKCS #12 file in a previous section.
10
In the Credentials field, select the username with password credentials you configured.
11
In the Files to sign field, select [ Add ]. Then, in the File(s) field, enter *.exe.
You can add multiple files, and the field supports the asterisk (*) regular expression. For example, you could configure it to sign all .exe and .dll files in the project.
12
Select [ Save ] at the top of the page.

​
Test CryptoHub code signing

Before proceeding with the steps in this section, copy any .exe file to the root directory of the Freestyle project (it can be any legitimate .exe file). If you do not complete this step, the build fails because CryptoHub does not have any files to sign.
Perform the following steps to test CryptoHub code signing by running the Freestyle project:
1
From the Freestyle project’s main page, select [ Build Now ] in the left-hand menu.
2
From the main page for the build that was just initiated, go to Console Output in the left-side menu.
The last line in the console output should display a message similar to: Waiting on sign request “646425A0D1E3CF1C”.This means that there were no errors on the Jenkins side, and the signing request was submitted successfully.
3
Log in to the CryptoHub and go to the Jenkins Code Signing service to approve the signing request.
4
Return to the Jenkins GUI.
After the FXCL Jenkins Plugin has polled the CryptoHub again for the status of the signing request, it should complete the code signing process and finish with a SUCCESS message.

​
Confirm the signature

The following example is in Windows 10. The process to confirm whether a file is signed varies depending on your operating system.
Perform the following steps to confirm that the .exe file is signed:
1
Go to the main page for the Freestyle project and select the Workspace folder.
2
Select [ all files in zip ] in the center of the page to download a zip of all the files in the workspace.
3
In your file manager, go to the location of the zip file you downloaded and extract it.
4
Open the extracted folder, right-click the .exe file that was signed, and select Properties.
5
In the Properties dialog, go to the Digital Signatures tab. There you can see the name of the certificate that signed the file. To retrieve more details, select the signature and select [ Details ].
You can view information such as the validity dates of the certificate that signed the file, the signature hash algorithm used, and so on.

​
Use the syntax generator

Another type of project in Jenkins, a Pipeline project, is a scriptable version of a project. Jenkins says a Pipeline project orchestrates long-running activities that can span multiple build agents. Suitable for building pipelines (formerly known as workflows) and organizing complex activities that do not easily fit in freestyle job type. Another feature of the FXCL Jenkins plugin is a syntax generator to be used within the context of Pipeline projects. It simplifies generating a script to automate code signing, which you can add to existing Pipeline scripting code. Perform the following steps to use the FXCL Jenkins plugin syntax generator:
1
From the main Jenkins dashboard, select an existing Pipeline project.
2
On the Pipeline project main page, go to Pipeline Syntax in the left-side menu.
3
In the Steps section, select the Sample Step drop-down option and select kmesCodeSign: Sign file via registration authority.
4
The fields that need to be filled in are identical to those filled in for signing files through the registration authority in the Freestyle project example. After you fill in every field, select [ Generate Pipeline Script ].
This generates the syntax needed to script code signing within your Pipeline project.
5
Copy and paste the generated code into an existing Pipeline script to automate code signing within your project.