Certificates and keys

tutorial

In order to secure the client-server and inter-service communication, Mender leverages public key cryptography. Several key pairs are used and each key pair comprises of a public key, which in some cases has a certificate that is shared with other services, and a private key, which is kept secret by the service. All keys are encoded in the PEM format. The public keys are shared in the standard X.509 certificate format, cert.crt below, while private keys are seen as private.key below.

See the service overview for schematics of the service communication flow. An overview of the components that use keys and for which purpose can be seen below.

Component Purpose of keys Shares certificate or key with
API Gateway Listens to a public port for https requests only (plain http is disabled). These requests can come from Mender Clients that check for- or report status about updates through the Device APIs, or from users and tools that manage deployments through the Management APIs. Mender Clients and users of the Management APIs, including web browsers accessing the Mender UI.
Storage Proxy Listens to a public port for https requests only (plain http is disabled). The Deployment Service manages Artifacts through the Storage Proxy and Mender Clients make Artifact download requests. The API Gateway can act as Storage Proxy in standard installations. Mender Clients and Deployment Service.
User Administration Signs and verifies JSON Web Tokens that users of the Management APIs, including end users of the Mender UI, include in their requests to authenticate themselves. Nothing. The service gets signature verification requests from the API Gateway, so all keys are kept private to the service and not shared.
Device Authentication Signs and verifies JSON Web Tokens that Mender Clients include in their requests to authenticate themselves when accessing the Device APIs. Nothing. The service gets signature verification requests from the API Gateway, so all keys are kept private to the service and not shared.
Mender Client Signs requests for JSON Web Tokens sent to the Device Authentication service. A Mender Client will request a new token when it connects to the Mender Server for the first time, and when a token expires. The Mender Client includes a token in all its communication to authenticate itself when accessing the Device APIs. The Device Authentication service stores the public keys of Mender Clients.
Mender Artifact Signs and verifies Mender Artifacts. The Signing system stores the private key used for signing Mender artifacts. After an artifact is signed using the private key it is verified by the Mender Clients.

Mender Client

The client does not need any special configuration regarding certificates as long as the server certificate is signed by a Certificate Authority. The client will verify trust using its system root certificates, which are typically provided by the ca-certificates package.

If the certificate is self-signed, then clients that are to connect to the server need to have the file with the concatenated certificates (keys-generated/certs/server.crt) stored locally in order to verify the server's authenticity. Please see the client section on building for production for a description on how to provision new device disk images with the new certificates. In this case, it is advisable to ensure there is a overlap between the issuance of new certificates and expiration of old ones so all clients are able to receive an update containing the new cert before the old one expires. You can have two valid certificates for the Mender server concatenated in the server.crt file. When all clients have received the updated server.crt, the server configuration can be updated to use the new certificate. In a subsequent update, the old certificate can be removed from the client's server.crt file.

The key of the Mender Client itself is automatically generated and stored at /var/lib/mender/mender-agent.pem the first time the Mender Client runs. We do not yet cover rotation of Mender Client keys in live installations in this document.

Mender Server

You can either generate new certificates by following the tutorial for generating certificates, or obtain the certificates in a different way - for example from your existing Certificate Authority. In either case the certificates on the client and server must be the same.

Mutual TLS

Mender Enterprise supports setting up a reverse proxy at the edge of the network, which can authenticate devices using TLS client certificates. Each client is equipped with a certificate signed by a CA certificate (Certificate Authority), and the edge proxy authenticates devices by verifying this signature. Authenticated devices are automatically authorized in the Mender backend, and do not need manual approval.

Please refer to the Mutual TLS section to find further details on the configuration of this feature.

Found errors? Think you can improve this documentation? Simply click the Edit link at the top of the page, and then the icon on Github to submit changes.