Skip to main content

Configuration

The application.yaml file​

The Application.yaml file is the most important configuration file, the most common configuration options of which are described here.

app​

App specific settings

SettingTypeDefaultDescription
ui.showAdditionalInfoBooleanfalseSet to true to display additional info on start page. Should false on production system
date.formatStringyyyy-MM-dd'T'HH:mm:ssZDate / Time format. Sample: yyyy-MM-dd'T'HH:mm:ss.SSSXXX
date.time-zoneTimeZoneUTCTime zone. Sample: Europe/Berlin
api.max-file-sizeDataSize10MMax file size for encryption / decryption request in none streaming mode. Example: 1000=bytes, 1000KB=KBytes, 10MB=MBytes
warning

For security reasons, ui.showAdditionalInfo should be set to false on production systems.

server​

Server specific settings

SettingTypeDefaultDescription
portInteger8080HTTP port for the server
ssl.enabledBooleanfalseSet to true to enable HTTPS on the app server.
ssl.key-storeStringnullLocation of the keystore file where your certificates are stored.
ssl.key-store-passwordStringnullThe password which is used to secure the keystore file.
ssl.key-aliasStringnullThe alias to be used to select the certificate from the keystore.

http​

Settings for http redirects. Only important if https is activessl.enabled is true

SettingTypeDefaultDescription
redirect.enableBooleanfalseEnable if https should redirect to https
redirect.portInteger8080http port to use, if ssl.enabled is true

Enable HTTPS at the application​

info

This example is only relevant if the application is handle the https connection itself, i.e. if the application is not running behind a reverse proxy that performs the SSL termination.

This example shows the settings for active https connection.

application.yaml with activated https for the application
server:
  port: 443
  ssl:
    enabled: true
    key-store: keystore.p12
    key-store-password: myKeystorePassword
    key-alias: my-ssl-cert

http:
  redirect:
    enable: true
    port: 80
  • Line 2: we set the https port to 443
  • Line 4: this activates https (ssl)
  • Line 5: The keystore file with the ssl certificates stored in keystore.p12 in the application directory.
  • Line 6: The password for accessing the keystore file must be the same as that entered when the keystore file was created. See below.
  • Line 7: The alias for the certificate must be the same as that used to store the certificate in the keystore file. See below.
  • Line 11: Http to https redirect is enabled.
  • Line 12: The http port is set to port 80.

Provide ssl certificates with the keystore file​

Generate self signed ssl certificate​

warning

This is for test purposes only.

keytool -genkeypair -alias my-ssl-cert ^
    -keyalg RSA -keysize 2048 -storetype PKCS12 -validity 3650 ^
    -dname "CN=Test, OU=IT, O=My Company, L=Berlin, ST=Example, C=DE" ^
    -keystore keystore.p12

After executing the command you must entered a password. After this the keystore file with filename keystore.p12 is generated.

Import a certificate to the keystore​

With the following command we convert the certificate file myCertificate.pfx to the keystore file myCertificate.p12. The alias is transferred from the input file (myCertificate.pfx).

keytool -importkeystore -srckeystore myCertificate.pfx -srcstoretype PKCS12 ^
    -destkeystore myCertificate.p12 -deststoretype PKCS12

After executing the command, you must first enter a new password for the new keystore file twice and then the password for your certificate file. The keystore file with the file name myCertificate.p12 is then created.

Checking the keystore content​

keytool -list -v -keystore myCertificate.p12 -storetype PKCS12

After executing the command, you must enter the keystore password.

Find alias from keystore file​

With this command you can determine the alias from keyytore file which must

keytool -list -v -keystore myCertificate.p12 -storetype PKCS12 | findstr /i "alias"

Configuring the authorisations​

The functions of the application and the API provided are protected by various authorisation roles.

There are three different roles

  • ADMIN:
    Have access to all functions e.g. integrated swagger-ui API documentation and all API endpoints.

  • API:
    Have access to all API endpoints located at /api/* and the integrated swagger-ui API documentation. \

  • METRICS:
    Have access to all metrics endpoints located at /actuator/*.

All roles can log in via the login form of the web UI under /login or via basic authorisation. The API role can also authorise itself with an API key, which can be submitted with requests to the endpoints under /API/* via the HTTP header X-API-KEY.

authorizations.yml​

Example for authorizations.yml
app:
  security:
    users:
      - username: admin
        password: "{bcrypt}$2b$10$ThEmnL5BsGew4X/QIDwj0e1ZBzVkzY5HxE7uTjiqU4MyYfJj7uKUi"
        roles: ADMIN, API
      - username: metrics
        password: "{SHA-256}5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8"
        roles: METRICS
      - username: api
        password: "{bcrypt}$2b$10$DICfbYd2U5Y2AVCQgZmze.0TuChdvft09orxJMCyybULIqUMBtD.G"
        roles: API

    api-keys:
      - key: "27045b2c815cdd8b5c57523f4a36bb7b"
        description: "Api-Key for application 1"
      - key: "92aa13fec153affa9ff085bdca6f5db3"
        description: "Api-Key for application 2"
  • Line 4: Defines the user name admin.
  • Line 5: Defines the password for the admin user. The password here is pwd for the user admin.
  • Line 6: Assigns the desired roles to the user.
  • Line 7 - 9: Defines the user name, the password and the roles for the next user. (metrics). The password here is password for the user metrics.
  • Line 10 - 12: Defines the user name, the password and the roles for yet another user. (api). The password here is api for the user api.
  • Line 15: Defines the first API-Key.
  • Line 16: Defines the description for the first API-Key.
  • Line 17 - 18: Defines another API-Key and description.
info

The description of an API key is for information purposes only and has no technical function, but must be provided.

warning

Do not use passwords and keys from this example. Always create this data yourself. See the following section.

Generating password hashes​

The passwords in the authorisations.yml are stored hashed. The hash algorithms bcrypt or SHA-256 can be used here.

Bcrypt​

Create a bcrypt hash width nubexx-encryption-service.jar
java -jar nubexx-encryption-service.jar --bcrypt=myPassword
Example output
Bcrypt-Hash: "{bcrypt}$2a$10$GHpl/SQGm5T/2owtB22fPenAb0tKTSIPjTxU6rwTPKUcN.PEIQW46"

You can then insert the value in quotation marks directly as a hashed password in the corresponding section of authorizations.yml.

SHA256​

Create a SHA256 hash from password
echo myPassword > temp.txt && certutil -hashfile temp.txt SHA256 && del temp.txt
warning

Passwords hashed with SHA256 shasum are not salted. Therefore, passwords of such hashes can probably be easily determined by brute force attacks and with the help of rainbow tables. It is therefore better to hash passwords with bcrypt. See above.