General Configuration and HTTPS

This page applies equally to all of our Enterprise Server server-side apps.

How to set properties

Each property can be set either in a properties file, as a sysarg, or as an environment variable. The property definition format and order from the lowest to highest precedence are:

The properties file chosen with the --config <path> sysarg with the property in it, e.g. org.id=my.org.
Environment variables (use capitals and underscores), e.g. ORG_ID=my.org java -jar app.jar.
Command-line arguments e.g. java -jar app.jar --property org.id=my.org.

General properties

These relate to the basic configuration and how the app REST API and/or web app is accessed:

Property	Description
`org.id`	An identifier for your business that comes with your license. We’ll assign this to you. Example: `evaluation.org`
`api.hostname`	The IP address or hostname that the service will listen to. The `0.0.0.0` address means binding to all available IP interfaces. Example: `0.0.0.0`
`api.port`	The listening port of the service. You may choose any port if the service is behind a Reverse Proxy or Load Balancer if the service is ultimately exposed on the `443` port to the client. If you run the node stand-alone without any layer in front of it, use the `443` port. Example: `443`
`api.accept.hosts`	The allowed hosts the browser/client can send requests to. This corresponds to the HTTP request Host header. You can set more than one comma-separated allowed hosts: `api.accept.hosts=[host as seen from the load balancer]:[port],[host as seen from the client]:[port]`. Example: `evaluation.org,localhost:8080`
`api.https.enabled`	`true` to listen on HTTPS, and `false` to listen on HTTP. Either enable HTTPS in configs or put it behind the HTTPS reverse proxy on the same machine. Example: `true`
`api.https.key.file`	(for `api.https.enabled=true`) The keystore file containing the certificate to present to HTTPS requests. Example: `keystore.p12`
`api.https.key.password` optional	(for `api.https.enabled=true`) The password to access the keystore file. Empty means the keystore file isn’t encrypted. Example: ` ` (empty)
`api.context.path` optional	Sets a context path which will act as a base for matching URI paths. No property means no context path is accepted, and will be the default value of `` (empty string). It should start with a slash and end with no slash. Example: `/my-context-path` will return status 200 for `GET https://host:port/my-context-path/` and 404 for `GET https://host:port/`
`api.cors.origins` optional	A comma-separated CORS valid origins. Use `` for greedy matching. No property means all origins are accepted. Example:* `https://*.example.com`
`api.error.format` optional	The level of detail to show in error messages. The `detailed` option returns the full stack trace, `short` offers a simple message that exposes fewer system details, and `id_only` returns an ID for the message so that full details can be found in the logs. Default value: `detailed` Example: `detailed`
`api.openapi.enabled`	Set to `true` to allow Swagger API definitions to run at `/openapi` and `/openapi/json`. Example: `false`
`api.outbound.timeout.seconds` optional	The number of seconds before timing out with an outbound network request. Examples are EAP to EKM, FES & WKD or Oauth 2 JWKS retrieval. Default value: `30` Example: `30`
`truststore.file` optional	Java trust store which holds public certificates/keys used to validate other users and issuing authorities. Comment out this line to use the default JRE trust store, or uncomment to set a truststore to verify KMIP connections. Example: `truststore.p12`
`truststore.password` optional	The password for the truststore file. Empty means the truststore file isn’t encrypted. Example: `password`
`truststore.include.default` optional	When the value is set to `false`, it means that only the provided truststore file is used; `true` means that the JVM default and the provided truststore are both used. Default value: `false` Example: `true`

Don’t run me as a root

We don’t recommend running the service as root. Instead, you can use the following command:

sudo setcap CAP_NET_BIND_SERVICE=+eip $(readlink -f `which java`)

By executing this command, the java binary will be able to bind on low ports without running it as a root. Alternatively, you could run the above-mentioned command for a specific startup script, like so:

sudo setcap CAP_NET_BIND_SERVICE=+eip /full/path/to/start-ekm-service.sh

How to create SSL/HTTPS certs and truststore

To create/edit a Java keystore file, we’d recommend one of the following options:

openssl: If you already have a PEM file, you can convert it to PKCS#12 as follows: openssl pkcs12 -export -out cert.p12 -in cert.pem -inkey key.pem.
KeyStore Explorer: Use PKCS#12 format when exporting the keystore file.

How to configure Java keystore & truststore files

A Java keystore stores private key entries or TLS certificates. You can configure this EKM with two keystore files: api.https.key.file for HTTPS and store.kmip.key.file for KMIP connection TLS.

A truststore is the opposite. While a keystore holds onto keys/certificates that identify us, a truststore holds onto certificates that identify others. This is particularly important if you use your own CA, as this will be required for communication between two deployed services, as well as between the service and external KMIP store if such an integration can be configured for that particular service. Java comes with a default truststore only containing public CAs. To use self-signed certificates, point to a custom truststore with a truststore.file property.

Troubleshooting

Below are common startup problems and how to resolve them:

Message	How to fix
`java.io.FileNotFoundException: flowcrypt-\[service].properties`	The application can’t find the properties file. Please rename or create the file.
`\[xxx] is not a valid option for property \[yyy]`	There is a typo or invalid option for the specified property. Please select a valid value from the displayed options.
`Property '\[xxx]' not found`	The service is expecting a property to be defined in the properties file but it’s not found. Please create, or uncomment the line.
`UnrecoverableKeyException: failed to decrypt safe contents entry`	This means the password for your Java keystore or truststore file is incorrect.
`ConnectException: Connection refused: connect`	This message during startup means that one of the URLs in your properties file is down. Please check the provided JWKS URLs.

You can debug more complex issues by running with the logger.default.level=DEBUG property.

For help or to report issues, please email us at human@flowcrypt.com.