Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.futurex.com/llms.txt

Use this file to discover all available pages before exploring further.

This section shows you how to configure TLS communication between the KMES Series 3 and the Jenkins instance and then covers general KMES configurations for the KMES to provide Jenkins code-signing functionality.

​
Configure TLS communication

Perform the following tasks to configure TLS communication between the KMES Series 3 and the Jenkins instance:
  1. Create a certificate authority (CA).
  2. Generate a CSR for the System/Host API connection pair.
  3. Sign the System/Host API CSR.
  4. Export the Root CA and signed System/Host API TLS certificate.
  5. Load the exported certificates into the System/Host API connection pair.
  6. Generate a signed client certificate for the Jenkins instance.
  7. Allow export of certificates by using passwords.
  8. Export the signed Jenkins certificate as a PKCS #12 file.
The following sections describe how to perform these tasks.

​
Create a CA

Perform the following steps to create a CA:
1
Log in to the KMES Series 3 application interface with the default Admin identities.
2
Go to PKI > Certificate Authorities, and select [ Add CA ] at the bottom of the page.
3
In the Certificate Authority window, enter a name for the certificate container, leave all other fields set to the default values, and select [ OK ].
The certificate container that you created now displays in the Certificate Authorities menu.
4
Right-click the certificate container and select Add Certificate > New Certificate.
5
On the Subject DN tab, set a Common Name for the certificate, such as System TLS CA Root.
6
On the Basic Info tab, leave the settings set to the default values.
7
On the V3 Extensions tab, select the Certificate Authority profile and select [ OK ].
The root CA certificate now displays under the previously created certificate container.

​
Generate a CSR

Perform the following steps to generate a CSR for the System/Host API connection pair:
1
Go to Administration > Configuration > Network Options.
2
In the Network Options window, go to the TLS/SSL Settings tab.
3
Under the System/Host API connection pair, uncheck the Use Futurex Certificates checkbox and select [ Edit ] next to PKI Keys in the User Certificates section.
4
In the Application Public Keys window, select [ Generate ].
5
When warned that SSL will not be functional until new certificates are imported, select [ Yes ] to continue.
6
In the PKI Parameters window, leave all fields set to the default values and select [ OK ].
You see that a PKI Key Pair is loaded in the Application Public Keys window.
7
Select [ Request ].
8
On the Subject DN tab, you can leave the default System/Host API value set in the Common Name field, or you can change it to a different value.
9
On the V3 Extensions tab, select the TLS Server Certificate profile.
10
On the PKCS #10 Info tab, select a save location for the CSR and select [ OK ].
11
When prompted that the certificate signing request was successfully written to the file location that was selected, select [ OK ].
12
Select [ OK ] again to save the Application Public Keys settings.
The main Network Options menu under the System/Host API connection pair now shows Loaded next to PKI Keys.

​
Sign the CSR

Perform the following steps to sign the System/Host API CSR:
1
Go to PKI > Certificate Authorities.
2
Right-click the root CA certificate you created and select Add Certificate > From Request.
3
In the file browser, find and select the CSR that you generated for the System/Host API connection pair.
4
After it loads, you don’t need to modify any settings for the certificate. Select [ OK ].
The signed System/Host API certificate now displays under the root CA certificate on the Certificate Authorities page.

​
Export the Root CA and certificates

Perform the following steps to export the Root CA and signed System/Host API certificates:
1
Right-click the root CA certificate and select Export > Certificate(s).
2
Change the encoding to PEM and select [ Browse ]. Specify a location and name for the export file.
3
When prompted that the file was successfully written to the location that was selected, select [ OK ].
4
Right-click the signed System/Host API certificate and select Export > Certificate(s).
5
Change the encoding to PEM and select [ Browse ]. Specify a location and name for the export file.
6
When prompted that the file was successfully written to the location that was selected, select [ OK ].

​
Load the certificates

Perform the following steps to load the exported certificates into the System/Host API connection pair:
1
Go to Administration > Configuration > Network Options.
2
In the Network Options window, go to the TLS/SSL Settings tab.
3
Under the System/Host API connection pair, select [ Edit ] next to Certificates in the User Certificates section.
4
Right-click the System/Host API SSL CA X.509 certificate container and select [ Import ].
5
Select [ Add ] at the bottom of the Import Certificates window.
6
In the file browser, select both the root CA certificate and the signed System/Host API certificate and select [ Open ].
The certificate chain appears in the window.
7
Select [ OK ] to save the changes.
In the Network Options window, the System/Host API connection pair shows Signed loaded next to Certificates in the User Certificates section.

​
Generate a certificate

Perform the following steps to generate a signed certificate for the Jenkins instance:
1
Go to PKI > Certificate Authorities.
2
Right-click the root CA certificate and select Add Certificate > New Certificate.
3
On the Subject DN tab, set a Common Name for the certificate, such as Jenkins.
4
Leave all fields on the Basic Info tab set to the default values.
5
On the V3 Extensions tab, select the TLS Client Certificate profile and select [ OK ].
The signed Jenkins certificate now displays under the root CA certificate.

​
Allow export of certificates

Perform the following steps to configure the allow export of certificates by using passwords function:
1
Go to Administration > Configuration > Options.
2
Select the checkbox next to the menu option Allow export of certificates using passwords.
3
Select [ Save ].

​
Export the certificate

Perform the following steps to export the signed Jenkins certificate as a PKCS #12 file:
1
Go to PKI > Certificate Authorities.
2
Right-click the signed Jenkins certificate and select Export > PKCS12.
3
Select [ Set Password ], enter a password for the PKCS #12 file, and select [ Save ].
4
In the Export Certificates window, select Export Selected Certificate with Parents under Export Options, and select [ Next ].
5
Specify a name for the PKCS #12 export file and select [ Open ].
A message box states that the PKCS #12 certificate export was successful.

​
Configure general KMES settings

Perform the following tasks to configure the KMES Series 3 for communication with Jenkins:
  1. Enable Host API commands.
  2. Create a Jenkins role with the required permissions.
  3. Create a Jenkins identity with the correct assigned roles.
  4. Create a signing approval group and give it appropriate permissions.
  5. Create a Jenkins code signing certificate.
  6. Apply an issuance policy to the Jenkins code signing certificate.
The following sections show you how to complete these tasks.

​
Enable the API commands

Perform the following steps to enable the required Host API commands:
1
Go to Administration > Configuration > Host API Options and enable the following commands:
CommandDescription
RAFAEnumerate issuance policies
RAGARetrieve issuance policy details
RAGZRetrieve Request (Authenticode)
RAUZUpload Request (Authenticode)
RAGJRetrieve Request (JAR)
RAUJUpload Request (JAR)
RKLOLogin User
RAGORetrieve Request (Hash Signing)
RAUOUpload Request (Hash Signing)
2
Select [ Save ].

​
Create a Jenkins role

Perform the following steps to create a Jenkins role with the required permissions:
1
Go to Identity Management > Roles, then select [ Add ] at the bottom of the page.
2
On the Info tab, specify a name for the role, such as Jenkins. Set the Type to Application, the Role Class to Principal, and Logins Required to 1.
3
On the Permissions tab, select the following permissions:
PermissionSubpermission
Certificate AuthorityExport Clear Key, Upload
4
On the Advanced tab, select only Host API for Allowed Ports.
5
Select [ OK ] to save and finish.

​
Create a Jenkins identity

Perform the following steps to create a Jenkins identity with the correct assigned roles:
1
Go to Identity Management > Identities, right-click the background, and select Add> Client Application.
2
On the Info tab, select Application for the storage type and specify a name for the identity.
3
On the Assigned Roles tab, select the role you created in the previous section.
4
On the Authentication tab, remove the API key mechanism, add the password mechanism, and set your password.
5
Select [ OK ] to finish creating the identity.

​
Create a signing approval group

Perform the following steps to create a signing approval group and give it appropriate permissions:
1
Go to PKI > Signing Workflow and select [ Add Approval Group ] at the bottom of the page.
2
Set a name for the approval group, such as Jenkins, and select [ OK ] to save.
3
Right-click the Jenkins approval group you just created and select [ Permission ].
4
Select the Show all roles and permissions checkbox, grant the Jenkins role the Use permission, and select [ OK ]*.

​
Create a Jenkins code signing certificate

Perform the following steps to create a Jenkins code signing certificate:
1
Go to PKI > Certificate Authorities and select [ Add CA ] at the bottom of the page.
2
In the Certificate Authority window, enter a name for the Certificate Container, such as Jenkins Code Signing CA. Set the owner of the CA to the Jenkins role and select [ OK ]*.
The certificate container you just created now displays in the Certificate Authorities menu.
3
Right-click the Jenkins certificate container and select Add Certificate > New Certificate.
4
On the Subject DN tab, set a Common Name for the certificate, such as Root.
5
On the Basic Info tab, leave all fields set to the default values.
6
On the V3 Extensions tab, select the Code Signing Certificate profile and select [ OK ].
The Root Jenkins code signing certificate displays under the Jenkins certificate container.

​
Apply an issuance policy

Perform the following steps to apply an issuance policy to the Jenkins code signing certificate:
1
Go to PKI > Certificate Authorities.
2
Right-click the root certificate within the Jenkins certificate container and select Issuance Policy > Add.
3
On the Basic Info tab, make the following changes:
  • (Optional) Specify an Alias.
  • Set Approvals to 1. Setting approvals to 0 allows anonymous signing.
  • Select any hashes that you want to allow.
4
On the X.509 tab, set the default approval group to Jenkins.
5
On the Object Signing tab, select the Allow object signing checkbox.
6
Select [ OK ] to apply the issuance policy to the Root Jenkins code signing certificate.