Code signing
Jenkins Code Signing
Download and configure Jenkins and test the FXCL Jenkins plugin
10min
this section covers how to download, run, and configure jenkins so that you can leverage the {{k3}} for code signing download, run, and 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 fxcl jenkins 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 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 register certificate credentials this section shows you how to import the pkcs #12 file (previously exported from the {{k}} in the configure {{k3}} 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 perform the following steps to register certificate credentials for tls communication between jenkins and the {{k3}} 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 ] 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 register the username this section shows you how to configure a username with password credentials in jenkins for the jenkins user you created on the {{k}} in the configure kmes series 3 configuration section perform the following steps to register the username with password credentials 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 username and password of the jenkins user you created on the {{k}} in the configure kmes series 3 section select \[ ok ] to save the new credentials work with a freestyle project this section shows you how to create, configure, and run a new freestyle project if you want to use the {{k3}} registration authority to sign code in an existing freestyle project, skip to step 6 in the following section create a freestyle project perform the following steps to create and configure a freestyle project to leverage the {{k}} for code signing by using the fxcl jenkins plugin from the main jenkins dashboard page, select the new item icon in the left side menu select freestyle project , enter a name for the project, and select \[ ok ] 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 uses 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 {{k}} 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 {{k}} application interface and go to the certificate authorities menu right click the root jenkins code signing certificate that is under the jenkins certificate container and 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 {{k}} 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 test a {{k}} code signing 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 {{k}} has no files to sign perform the following steps to test a {{k}} code signing by running the freestyle project 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 {{k}} 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 {{k}} again for the status of the signing request, it should complete the code signing process and finish with a success message confirm the exe file signature the following steps are for windows 10 the process for confirming whether a file is signed varies depending on the operating system you use perform the following steps to confirm the exe file signature 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 used, and more use the plugin syntax generator jenkins also has pipeline projects essentially, a pipeline project is a scriptable version of a project jenkins describes a pipeline project this way it 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 a 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