Getting started

This is a guide on how to setup your existing code signing operation to use the Cryptera Key Management Service.

When you order your first key on the Cryptera KeyServer, you will be contacted to by Cryptera to align the information discussed in this instuction. Cryptera will setup your dedicated server and you will receive access URL and credentials to get access to the administration website.

The administration website are used by persons that has been assigned roles in the software release procedures.

Access to use your keys are provided through a REST API. This is used by your build server that creates the signed software packages.

Some considerations of the following elements must be done, before setting up the code signing operation.

• Secure signing procedures
• Authorisation Server
• Build server

Details will be provided in the following.

Secure signing procedure

If you have existing procedures for securing your code signing, you have to consider how these can be optimized when using KeyServer. This will typically be procedures related to release of software packages.

It is assumed that the software package is created on a build server. In the next paragraph we will cover how the build can be linked to perform signing with keys on KeyServer.

If your procedures require a signoff by a release manager, it will be appropriate to setup an approval process that requires the release manager to review and approve the release as part of the signing process. This way you have an auditable process that enforces the approval task.

KeyServer can be configured with an approver for each key used in the signing process. When you order the key, you may decide that keys for certain software layers doesn't require approval, while others are more sensitive and requires approval.

Apart from the approver role, you need to assign the administrative role to one or more individuals in the organisation. The administrative role can access KeyServer setup the roles for approvers etc.

The following roles are offered by KeyServer:

When you order keys on the KeyServer, an ORDERER_ role and APPROVER_ role for keys where you want approvers will will be provided.

Through the administration website you will be able to setup the link between the authorized subjects (see next paragraph) and the roles on the KeyServer. You are assigning the roles to your build server and the key approvers involved in your release processes.

Authorisation Server

To setup your system with the Cryptera KeyServer, your company must utilize an Authorisation Server to handle identification and authentication of employees and automated processes. As an example, many companies use Microsoft Entry ID (formly Azure AD) or similar, to authorize access to enterprise infrastructure. You may operate a local server for this purpose or delegate this to a service provided by a third party.

Often two Authorisation Servers are used, one for employees/persons (users) and one for automated processes (clients). KeyServer can be configured to handle two Authorization Servers. It will provide extra security if the build server and approvers are authorised from separate servers.

The Authorization Servers must support OAuth2 authentication flows and it must be configured to issue JSON Web Tokens (JWT) for these flows. These tokens will be validated by KeyServer to allow access to use keys or perform administrative tasks.

When you sign up to use the Cryptera Key Management Service, you will be contacted with information and queries required to setup the authorisation link between your authorisation server and KeyServer.

Build server

Typically the tasks for software building, testing and releasing is done by a build server. In many software development setups, this is an automated process in which the build server continuously check out source code from a repository, builds the code and runs a number of tests to ensure the integrity of the software.

This is described as a Continuous Integration/Continuous Delivery (CI/CD) setup. The CI/CD process could be managed on GitLab, Jenkins or similar.

If all tests and validations succeed, the build server will package all the required files in a software package. This may include software on multiple layers of the software stack for the device. Multiple signatures of the various elements can be included as proof of integrity and origin.

The scripts in the build server that handles the signing process, must be adapted to access KeyServer to perform the required signings. The script will create hash values on the code and forward these hashes to KeyServer with a reference to the key to be used for the signing. KeyServer will return signatures to be included in the software package.

KeyServer may be accessed directly through a RESTful API (http), for example through curl-commands in scripts. Link: Tutorial un how to use the REST API

Link: Specification of the KeyServer REST API

Some signing tools utilize a PKCS#11 interface to access cryptographic keys in key-store files etc. In that case, the integration may be simplified by using a PKCS#11 library offered by Cryptera. Link: Tutorial on how to use our PKCS#11 library

No matter which specific interface is used, there is a need to authorise the build server to access the keys as described in the privious paragraph.

This instruction should give you an overview of the solution. Naturally our support will assist with any missing details of the setup.