Download and configure Jenkins and test the FXCL Jenkins plugin

this section covers the steps required to download, run, and configure jenkins to leverage {{ch}} for code signing set up jenkins download the jenkins war file from https //www jenkins io/download/ 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/ https //www jenkins io/doc/book/installing/war file/ install the plugin perform the following steps to install the fxcl jenkins plugin from the main jenkins dashboard page, select the manage jenkins icon in the left side 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, 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 {{ch}} 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 {{ch}} 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 side menu change the value in the kind drop down list to certificate 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 select \[ change password ] and enter the password of the pkcs #12 file 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 {{ch}} 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 side 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 identity name and password for the jenkins identity created on the {{ch}} select \[ ok ] to save the new credentials sign a file in a freestyle project by using the {{ch}} registration authority this section walks you through creating, configuring, and running a new freestyle project in jenkins if you want to use the {{ch}} 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 {{ch}} for code signing by using the fxcl jenkins plugin from the main jenkins dashboard, select the new item icon in the left side menu select freestyle project , enter a name for the project, and select \[ ok ] 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 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 in the kmes host field, enter the ip address or hostname of the {{ch}} the port number is optional it defaults to port 2001 , the system/host api port, which is the recommended port 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 time in seconds that you want the fxcl jenkins plugin to wait between code signing status requests that it sends to the {{ch}} in the tls pki field drop down list, 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, 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 select \[ save ] at the top of the page test {{ch}} 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 {{ch}} does not have any files to sign perform the following steps to test {{ch}} code signing by running the freestyle project from the freestyle project's main page, select \[ build now ] in the left hand menu 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 log in to the {{ch}} and go to the jenkins code signing service to approve the signing request return to the jenkins gui after the fxcl jenkins plugin has polled the {{ch}} 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 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 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 from the main jenkins dashboard, select an existing pipeline project on the pipeline project main page, go to pipeline syntax in the left side 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 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 copy and paste the generated code into an existing pipeline script to automate code signing within your project