Download and configure Jenkins and test the FXCL Jenkins plugin
This section covers how to download, run, and configure Jenkins so that you can leverage the KMES Series 3 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, select the Manage Jenkins icon in the left-hand menu.
Select [ Manage Plugins ] in the System Configuration section.
On the Plugin Manager page, go to the Advanced tab.
Scroll down to the Upload Plugin section and select [ Choose File ]. In the file browser, select the FXCL Jenkins Plugin file and select [ Upload ].
Selecting upload redirects you to the Update Center page where you can see the progress of the plugin installation. If the installation is successful the status of the FXCL Jenkins Plugin changes to Success.
This section shows you how to import the PKCS #12 file (previously exported from the KMES in the Configure KMES Series 3 section) into Jenkins for TLS communication. This PKCS #12 file contains the signed Jenkins certificate and the root certificate (and intermediate certificates if applicable) that signed it, protected by a password.
On the Manage Jenkins page, select [ Manage Credentials ] in the Security section.
Select the Jenkins Store, contained within the global domain.
Select the Global credentials (unrestricted) domain.
Select [ Add Credentials ] in the left-hand menu.
Change the value in the Kind drop-down list Certificate.
Select the [ Upload PKCS#12 Certificate ] radio button and select [ Choose File ]. In the file browser, select the .p12 file and select [ Open ].
A message box states: Could retrieve key "system tls ca root"
If prompted, provide a password.
Select [ Change Password ] and enter the password of the PKCS #12 file.
Select [ OK ] to save the new credentials.
The new credentials display on the Global credentials (unrestricted) page.
This section shows you how to configure username with password credentials in Jenkins for the Jenkins user you created on the KMES in the Configure KMES Series 3 Configuration section.
On the Manage Jenkins page, select [ Manage Credentials ] in the Security section.
Select the Jenkins store, contained within the global domain.
Select the Global credentials (unrestricted) domain.
Select [ Add Credentials ] in the left-hand menu.
Leave the value in the Kind drop-down list set to the default value (Username with password).
In the Username and Password fields, specify the username and password of the Jenkins user you created on the KMES in the Configure KMES Series 3 section.
Select [ OK ] to save the new credentials.
This section shows you how to create, configure, and run a new Freestyle project. If you want to use the KMES Series 3 registration authority to sign code in an existing Freestyle project, skip to step 6 in the following section.
Create and configure a Freestyle project to leverage the KMES for code signing by using the FXCL Jenkins plugin
From the main Jenkins dashboard page, select the New Item icon in the left-hand menu.
Select Freestyle project, enter a name for the project, and select [ OK ]. This will bring up t.
In the configuration page for the Freestyle project, scroll down to the Build section, select [ Add build step ], and select Sign file via Futurex Code Signing in the drop-down list.
Leave the Method of Signature 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.
In the KMES Host field, enter the KMES host to connect to. The port number is optional. It defaults to port 2001, the System/Host API port, which is the port you want to connect to.
In the Issuance Policy field, enter the UUID of the issuance policy to handle the signing request. To get this information, perform the following steps:
- Log in to the KMES application interface and go to the Certificate Authorities menu.
- Right-click the Root Jenkins code signing certificate that is under the Jenkins certificate container ans select Issuance Policy > Edit.
- Note down the UUID in the first field of the Basic Info tab.
- Go back to the Jenkins GUI, and enter the UUID in the Issuance Policy field.
In the Hash Algorithm field, select the hash algorithm to use when requesting signatures.
The hash algorithm that you select must be one of the allowed hashes that you configured for the issuance policy attached to the Root Jenkins code signing certificate under 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 KMES.
Right-click TLS PKI. In the drop-down list, select the TLS PKI that you imported as a PKCS #12 file in a previous section.
In the Credentials field, select the username with password credentials configured in the Register the username with password credentials section.
In the Files to sign field, select [ Add ]. Then, in the File(s) field, enter *.exe.
You can add multiple files, so we support the asterisk (*) regular expression.
Select [ Save ] at the bottom of the page.
You return to the main page for the Freestyle project.
Before proceeding with the steps in this section, copy one or more legitimate .exe files to the root directory of the Freestyle project. If you do not complete this step, the build fails because the KMES has no files to sign.
From the Freestyle project main page, select [ Build Now ] in the left-hand menu.
From the main page for the build you just initiated, select [ Console Output ] from the left-hand menu.
You should see console output, with the last line similar to this sample: 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 KMES to approve the signing request. After you log in, go to the Signing Approval menu.
Right-click the signable object under the approval group you created and select Approve.
When prompted that the signing request was approved, select [ OK ].
A green checkmark appears beside the signing request.
Return to the Jenkins GUI.
After the FXCL Jenkins Plugin polls the KMES again for the status of the signing request, it should complete the code signing process and finish with a SUCCESS message.
The following steps are for Windows 10, and the process for confirming whether a file is signed varies depending on which operating system you use.
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 files in the workspace.
In your file manager, go to the download location for the zip file and extract it.
Go to the extracted folder, right-click the .exe file you previously signed, and select Properties.
In the Properties window, 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 that was used, and so on.
Jenkins also Pipeline projects. Essentially, 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 organizing complex activities that do not easily fit in free-style job type.
The FXCL Jenkins plugin has a syntax generator feature that you use within the context of Pipeline projects. It makes it easy to generate a script for automating code signing, which you can add to existing Pipeline scripting code.
Perform the following steps to use the FXCL Jenkins plugin syntax generator:
From the main Jenkins dashboard, select an existing Pipeline project.
On the Pipeline project main page, select [ Pipeline Syntax ] in the left-hand menu.
In the Steps section, select the Sample Step drop-down list and select kmesCodeSign: Sign file via registration authority.
The fields that need to be filled in are the same as the fields you filled in for signing files by using 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.
Copy and paste the generated syntax into an existing Pipeline script to automate code signing within your project.