Skip to main content

Server configuration

Introduction​

All configuration attributes on the Encap server have reasonable default values. This page will show you how to adjust the defaults to the needs of your specific environment, if necessary.

Server Configuration​

Encap server configurations is split into two types of configurations.

  • Encap cluster wide configuration
    • Defined in the folder config/encap-cluster.properties
    • Cluster wide configuration, must be the same for all nodes
    • Server restart required to make changes go into effect.
  • Encap instance configuration
    • Defined in the folder config/encap-instance.properties
    • Instance specific
    • Server restart required to make changes go into effect.

Cluster configuration​

Encap server cluster configurations are specified in <ENCAP_HOME>/core/config/encap-cluster.properties within the Encap server distribution directory.

There are a vast amount of configuration properties that the Encap server and its device clients use. Most of these properties have reasonable default values which are left commented out in the provided configuration file. You only need the set the values that differs from the default value in the configuration file.

Cluster configurations are read from the encap-cluster.properties configuration file at the startup of the server and cannot be changed during runtime.

The following tables provide an overview of the core configuration parameters used by the Encap server and their default values:

DB cleanup configuration​

Instance configuration​

The instance configuration is controlled using a file called encap-instance.properties within the <ENCAP_HOME>/core/config directory in your Encap server distribution. The file defines parameters that are used by the startup script.

The properties and their function are described in the tables below. The properties have default values which are left commented out in the provided configuration file. You only need the set the values that differs from the default value in the configuration file.

Bind address and port​

Scaling​

Log and runtime mode​

Public location configuration​

TLS configuration​

The supported protocols, ciphers and security mechanisms used are chosen based on recommendations from ssllabs.com, owasp.org and nist.gov.

If TLS is used for communication with the Encap server update the following properties to configure your SSL setup.

Supported protocols and ciphers​

The Encap server has support for TLS 1.2 and TLS 1.3. The number of devices not supporting TLS 1.2+ is limited.

Example: Supported ciphers

TLS_AES_128_GCM_SHA256
TLS_AES_256_GCM_SHA384
TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
TLS_DHE_RSA_WITH_AES_128_CBC_SHA256
TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
TLS_DHE_RSA_WITH_AES_256_CBC_SHA256
HTTP Strict Transport Security​

HTTP Strict Transport Security (HSTS) is a web security policy mechanism which helps to protect websites against protocol downgrade attacks and cookie hijacking. At first connection with the server, the user agent is sent a HTTP response header Strict-Transport-Security and when enabled the user will be unable to connect to the website without a secure connection.

Encap concepts and configuration​

Generate API keys for REST authentication​

Encap server requires an API key for authenticating against the REST API. An API key consists of a key/secret pair.

The recommended way is to generate it through the REST API, but the first ADMIN-level API key has to be generated using the script.

REST API​

The REST API is the preferred way to manage API keys. There exists two APIs for managing API keys:

  • The standard REST API; can create and manage keys for the organisation the user belongs to.
  • The admin REST API; can create and manage keys for any organization. Requires an ADMIN user for accessing.

Manage API key script​

The script is only intended for creating the first ADMIN API key.

core/scripts/manageApiKey.sh manages API keys. Type ./manageApiKey.sh help to see flags and configuration.

Setting up End-to-End encryption between device client and Encap server​

The Encap server uses end-to-end encryption (E2EE) between smart device clients and the server. The Encap client encrypts communication using a public key of the Encap server belonging to an application configuration.

In a scenario where the private and public key of the Encap server needs replacement, the Encap server supports multiple private and public keys per application configuration for this purpose. The server can continue to support the old Encap client application even if new keys have been generated for the application configuration.

A default E2E key is configured on the Encap server during installation. The default key pair is intended for testing only as this is shared by all Encap customers.

You can find out how to generate a new key pair and configure the server with it the sections below.

Managing E2E keys using the REST API​

E2E keys can be created and managed using the REST API. Please see the End-to-End Key API documentation for details.

Configure the device client with the new key pair​

See iOS and Android client documentation.

Manage keys and certificates​

All keys and certificates are handled by the REST API.

Description of the various keys/certificates that exist:

  • The E2E key used on the Encap server for end-to-end encryption between the client and server.
  • The APNs push certificate and private key used for sending APNs push for an application configuration, a PKCS12 keystore containing both entities. You can find out how to create these on the APNs certificates and tokens page.
  • The APNs token used for sending APNs push, an authentication token signing key provided by Apple. You can find out how to create these on the APNs certificates and tokens page.

REST APIs​

Keys and certificates are managed using the REST API.

Manage application configurations​

Configuring APNS (Apple Push Notification Service)​

Encap supports both APNS certificates and APNS Tokens and are managed in the REST APIs.

The APNS certificate or token needs to be added before it can used in an application configuration. If push is enabled in the application configuration, then it is required to specify the APNS certificate or token when adding the application configuration.

It is also possible to update the APNS certificate or token for an application configuration.

Note

Changes to the application configuration, for example to APNs certificates, will be updated in runtime. This means that they do not require a server restart.

Known limitations for application configurations​

If an application configuration is created and then removed, it is not possible to add a new application configuration with the same application ID.

REST API​

Application configurations are managed using the REST API. See the App Config REST API docs for more details.

Manage organisations​

An organisation is a top level concept owning resources in Encap. There are two types of organisations, Standard and Admin.

A Standard organisation owns application configurations, API Keys, APNS certificates and E2E keys.

There can be multiple standard organisations, and a standard organisation only has access to resources that belongs to that organisation.

Example

When starting an authentication through the REST APIs using an API key, the server will only start an authentication if the API key and the specified AppConfig in the request belongs to the same organisation.

This adds a layer of authorisation on the REST APIs, only allowing API Keys to perform requests on resources that belong to the same organisation.

An Admin organisation owns resources that are shared server-wide. There can only be one admin organisation, and it is created when initialising or upgrading the database.

REST API​

The admin REST API is the preferred way of managing organisations. See the Organization REST API docs for more details.

Using script (deprecated)​

Managing organisations using script is deprecated.

core/scripts/manageOrganization.sh manages organisations. Type ./manageOrganization.sh help to see flags and configuration.

Diagram showing organisation management

Diagram showing organisation management

On this page