Download and configure Jenkins and test the FXCL Jenkins plugin
This section covers the steps required to download, run, and configure Jenkins to leverage for code signing.
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/
From the main Jenkins dashboard page, click the Manage Jenkins icon in the left-hand menu.
Click the [ Manage Plugins ] button in the System Configuration section.
On the Plugin Manager page, click the Advanced tab.
Scroll down to the Upload Plugin section and click the [ Choose File ] button. In the file browser, find and select the FXCL Jenkins Plugin file, then click [ Upload ].
After clicking upload you will be redirected to the Update Center page shown above, where you can see the progress of the plugin installation. If the installation is successful the status of the FXCL Jenkins Plugin will change to "Success".
This section imports the PKCS #12 file exported from the 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.
On the Manage Jenkins page, click the [ Manage Credentials ] button in the Security section.
Select the Jenkins Store contained within the global domain.
Select the Global credentials (unrestricted) Domain.
Click the [ Add Credentials ] button in the left-hand menu.
Change the value in the Kind dropdown to Certificate.
Select the Upload PKCS#12 certificate radio button, then click [ Choose File ]. This will open the file browser. Find and select the .p12 file, then click [ Open ]. A message should appear that says, 'Could retrieve key "system tls ca root'. You may need to provide a password.
Click the [ Change Password ] button and enter the password of the PKCS #12 file.
Click the [ OK ] button to save the new credentials.
This section shows how to configure a username with password credentials in Jenkins for the Jenkins identity created on the .
On the Manage Jenkins page, click the [ Manage Credentials ] button in the Security section.
Select the Jenkins Store, contained within the global domain.
Select the Global credentials (unrestricted) Domain.
Click the [ Add Credentials ] button in the left-hand menu.
Leave the value in the Kind dropdown to the default value (i.e., Username with password).
In the Username and Password fields, specify the identity name and password for the Jenkins identity created on the .
Click the [ OK ] button to save the new credentials.
This section walks you through creating, configuring, and running a new Freestyle project in Jenkins. If you want to use the registration authority to sign code in an existing Freestyle project, skip to step 6 in the next section.
Create and configure a Freestyle project to leverage the for code signing by using the FXCL Jenkins plugin
From the main Jenkins dashboard, click the New Item icon in the left-hand menu.
Select Freestyle project, enter a name for the project, then click the [ OK ] button. This will bring up the configuration page for the Freestyle project.
Scroll down to the Build section, click the [ Add build step ] button, and select Sign file via Futurex Code Signing in the dropdown. This option is provided by the FXCL Jenkins Plugin.
In the Method of Signature field, leave the default value (i.e., Code Sign). Note: There are currently two types of signatures: Code Sign and External Signature. Code Sign will try to use knowledge of the file format to embed a signature. If it does not understand the file format, it will fail. An external signature does not need to know the file format, but it cannot embed signatures.
In the KMES Host field, enter the IP or hostname of the . The port number is optional. It will default to port 2001, the System/Host API port, which is the port that we want to connect to.
In the Issuance Policy field, enter the UUID of the issuance policy to handle the signing request.
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.
In the Poll Interval field, specify the amount of time in seconds that you want the FXCL Jenkins plugin to wait between code signing status requests that it sends to the .
In the TLS PKI field, click the dropdown and select the TLS PKI you imported as a PKCS #12 file in a previous section.
In the Credentials field, select the username with password credentials you configured.
In the Files to sign field, click the [ Add ] button. Then, in the File(s) field, enter "*.exe".
Multiple files can be added. The asterisk * regular expression is supported as well. For example, you could configure it as shown below if you want all .exe and .dll files in the project to be signed.
Click the [ Save ] button at the top of the page. This will take you back to the main page for the Freestyle project.
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 will fail because will not have any files to sign.
From the Freestyle project's main page, click [ Build Now ] in the left-hand menu.
From the main page for the build that was just initiated, click Console Output in the left-hand menu.
You should see something similar to below in the console output. The last line in the output says, "Waiting on sign request "646425A0D1E3CF1C". This means that there were no errors on the Jenkins side, and the signing request was submitted successfully.
Log in to the and navigate to the Jenkins Code Signing service to approve the signing request.
Return to the Jenkins GUI. After the FXCL Jenkins Plugin has polled the again for the status of the signing request, it should complete the code signing process and finish with a "SUCCESS" message.
The following example is in Windows 10. The process for confirming whether a file is signed varies depending on which operating system you are using.
Go to the main page for the Freestyle project and select the Workspace folder.
Select [ all files in zip ] in the center of the page to download a zip of all the files in the workspace.
In your file manager, go to the location of the zip file you downloaded and extract it.
Open the extracted folder, right-click the .exe file that was signed, and select Properties.
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.
Another type of project in Jenkins, a Pipeline project, is a scriptable version of a project. Jenkins describes a Pipeline project this way: Orchestrates long-running activities that can span multiple build agents. Suitable for building pipelines (formerly known as workflows) and/or organizing complex activities that do not easily fit in freestyle job type.
Another feature of the FXCL Jenkins plugin is a syntax generator. It is intended to be used within the context of Pipeline projects. It makes it simple and easy to generate a script for automating code signing, which can be added to existing Pipeline scripting code.
Perform the following steps to use the FXCL Jenkins plugin syntax generator:
From the main Jenkins dashboard, click on an existing Pipeline project.
On the Pipeline project's main page, click on Pipeline Syntax in the left-hand menu.
In the Steps section, select the Sample Step drop-down option and select kmesCodeSign: Sign file via registration authority.
The fields that need to be filled in are identical to the fields that were filled in for signing files via registration authority in the Freestyle project example. Once you've filled in every field, click the [ Generate Pipeline Script ] button. This will generate the syntax needed to script code signing within your Pipeline project, as shown below:
Then, simply copy and paste the syntax that was generated into an existing Pipeline script to automate code signing within your project.