Configure KMES Series 3
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.
Perform the following tasks to configure TLS communication between the KMES Series 3 and the Jenkins instance:
- Create a certificate authority.
- Generate a CSR for the System/Host API connection pair.
- Sign the System/Host API CSR.
- Export the Root CA and signed System/Host API TLS certificate.
- Load the exported certificates into the System/Host API connection pair.
- Generate a signed client certificate for the Jenkins instance.
- Allow export of certificates by using passwords.
- Export the signed Jenkins certificate as a PKCS #12 file.
The following sections describe how to perform these tasks.
Log in to the KMES Series 3 application interface with the default Admin identities.
Go to PKI > Certificate Authorities, and select [ Add CA ] at the bottom of the page.
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.
Right-click the certificate container and select Add Certificate > New Certificate.
On the Subject DN tab, set a Common Name for the certificate, such as System TLS CA Root.
On the Basic Info tab, leave the settings set to the default values.
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.
Go to Administration > Configuration > Network Options.
In the Network Options window, go to the TLS/SSL Settings tab.
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.
In the Application Public Keys window, select [ Generate ].
When warned that SSL will not be functional until new certificates are imported, select [ Yes ] to continue.
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.
Select [ Request ].
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.
On the V3 Extensions tab, select the TLS Server Certificate profile.
On the PKCS #10 Info tab, select a save location for the CSR and select [ OK ].
When prompted that the certificate signing request was successfully written to the file location that was selected, select [ OK ].
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.
Go to PKI > Certificate Authorities.
Right-click the root CA certificate you created, and select Add Certificate > From Request.
In the file browser, find and select the CSR that you generated for the System/Host API connection pair.
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.
Right-click the root CA certificate and select Export > Certificate(s).
Change the encoding to PEM and select [ Browse ]. Specify a location and name for the export file.
When prompted that the file was successfully written to the location that was selected, select [ OK ].
Right-click the signed System/Host API certificate and select Export > Certificate(s).
Change the encoding to PEM and select [ Browse ]. Specify a location and name for the export file.
When prompted that the file was successfully written to the location that was selected, select [ OK ].
Go to Administration > Configuration > Network Options.
In the Network Options window, go to the TLS/SSL Settings tab.
Under the System/Host API connection pair, select [ Edit ] next to Certificates in the User Certificates section.
Right-click the System/Host API SSL CA X.509 Certificate Container and select [ Import ].
Select [ Add ] at the bottom of the Import Certificates window.
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.
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.
Go to PKI > Certificate Authorities.
Right-click the root CA certificate and select Add Certificate > New Certificate.
On the Subject DN tab, set a Common Name for the certificate, such as Jenkins.
Leave all fields on the Basic Info tab set to the default values.
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.
Go to Administration > Configuration > Options.
Select the checkbox next to the menu option Allow export of certificates using passwords.
Select [ Save ].
Go to PKI > Certificate Authorities.
Right-click the signed Jenkins certificate and select Export > PKCS12.
Select [ Set Password ], enter a password for the PKCS #12 file, and select [ Save ].
In the Export Certificates window, select Export Selected Certificate with Parents under Export Options, and select [ Next ].
Specify a name for the PKCS #12 export file and select [ Open ].
A message box states that the PKCS #12 certificate export was successful.
Perform the following tasks to configure the KMES Series 3 for communication with Jenkins:
- Enable Host API commands.
- Create a Jenkins role with the required permissions.
- Create a Jenkins identity with the correct assigned roles.
- Create a signing approval group and give it appropriate permissions.
- Create a Jenkins code signing certificate.
- Apply an issuance policy to the Jenkins code signing certificate.
The following sections show you how to complete these tasks.
Go to Administration > Configuration > Host API Options and enable the following commands:
Command
Description
RAFA
Enumerate issuance policies
RAGA
Retrieve issuance policy details
RAGZ
Retrieve Request (Authenticode)
RAUZ
Upload Request (Authenticode)
RAGJ
Retrieve Request (JAR)
RAUJ
Upload Request (JAR)
RKLO
Login User
RAGO
Retrieve Request (Hash Signing)
RAUO
Upload Request (Hash Signing)
Select [ Save ].
Go to Identity Management > Roles, then select [ Add ] at the bottom of the page.
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.
On the Permissions tab, select the following permissions:
Permission
Subpermission
Certificate Authority
Export Clear Key, Upload
On the Advanced tab, select only Host API for Allowed Ports.
Select [ OK ] to save and finish.
Go to Identity Management > Identities, right-click the background and select Add > Client Application.
On the Info tab, select Application for the storage type and specify a name for the identity.
On the Assigned Roles tab, select the role you created in the previous section.
On the Authentication tab, remove the API key mechanism, add the password mechanism, and set your password.
Select [ OK ] to finish creating the identity.
Go to PKI > Signing Workflow and select [ Add Approval Group ] at the bottom of the page.
Set a name for the approval group, such as Jenkins, and select [ OK ] to save.
Right-click the Jenkins approval group you just created and select [ Permission ].
Select the Show all roles and permissions checkbox, grant the Jenkins role the Use permission, and select [ OK ].
Go to PKI > Certificate Authorities and select [ Add CA ] at the bottom of the page.
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.
Right-click the Jenkins certificate container and select Add Certificate > New Certificate.
On the Subject DN tab, set a Common Name for the certificate, such as Root.
On the Basic Info tab, leave all fields set to the default values.
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.
Go to PKI > Certificate Authorities.
Right-click the root certificate within the Jenkins certificate container and select Issuance Policy > Add.
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.
On the X.509 tab, set the default approval group to Jenkins.
On the Object Signing tab, select the Allow object signing checkbox.
Select [ OK ] to apply the issuance policy to the Root Jenkins code signing certificate.