Configuration

The configuration of the Core Container follows Spring Configuration Properties to setup all of the initial parameters. The Core Container project contains type-safe properties that can be autowired into components. There is only one way to configure the Core Container, meaning there is only one mode of operation.

Not just the specific Core Container properties can be configured in this way, but also more generic Spring or Camel configuration can be provided. For instance, when you’d want to alter the logging settings.

Overview

The configuration properties are usually set by providing an application.yaml in the current working directory of the Java process, when using the Helm charts for deployment the locations of the configuration are pre-configured and everything under the ids key will be placed in the application.yaml file. Apart from setting the configuration properties by providing a file, Spring also allows you to provide environment variables to set configuration properties. For instance, the environment variable KEYSTORE_PEM_CERT will overwrite the keystore.pem.cert property. Environment variables will override properties set in the application.yaml configuration.

Spring uses relaxed binding to allow for non-exact matches, the most used relaxed rules are: kebab case vs. camel case, case-insensitive, dot vs. underscore delimiters. So all of the following notations will match the same property: broker.autoRegister, broker.auto-register, BROKER_AUTOREGISTER, broker.auto_register.

Spring Configuration properties

The table below shows all of the configuration properties that are defined by the Core Container. At the bottom of this page a minimal example is shown of the YAML structure following this.

Configuration Key Type (* required) Default Description
artifacts      
   .enabled Boolean true Whether automatic artifact handling should be enabled
   .location String /resources File location where artifacts will be stored
   .dapsValidation Boolean true Whether DAPS should be enabled for artifacts
   .policyEnforcement Boolean true Whether policy enforcement should be enabled for artifacts
   .encryptAtRest Boolean true Whether encryption at rest should be anabled for artifacts
   .aesEncryptionKey String - AES encryption key for encryption at rest in Base64 encoding
broker      
   .id URI* - Broker IDS Identifier
   .address URL* - Broker Access URL
   .autoRegister Boolean true Automatic registration at the Broker
   .profile MINIMAL, FULL MINIMAL Self-Description Profile to share with the Broker
   .reRegisterInterval Float 1 Interval (in hours) for automatic re-registration
   .brokerInitialDelay Long 10000 Initial delay (in milliseconds) for initial Broker registration
   .registrationMaxRetries Int 30 Maximum of retries for initial Broker registration
   .registrationBackoffPeriod Long 10000 Backoff period (in milliseconds) for initial Broker registration
   .brokerHealthCheckInterval Long 3600000 Broker health check interval (in milliseconds)
info      
   .idsid URI* - Connector IDS identifier
   .titles String[]* - Connector titles
   .descriptions String[]* - Connector descriptions
   .accessUrl URL[]* - Connector Access URL for external connectors
   .curator URI* - Curator of the contents of this connector, an IDS participant identifier
   .maintainer URI* - Technical administrator of this connector, an IDS participant identifier
   .securityProfile TRUST_SECURITY_PROFILE - Security Profile as set as self-declaration in the metadata of this connector
daps      
   .url String* - URL of the DAPS
   .issuerUrl String - Issuer URL of the DAPS, only required if DAPS URL structure is different
   .tokenUrl String - Token URL of the DAPS, only required if DAPS URL structure is different
   .jwksUrl String - JWKS URL of the DAPS, only required if DAPS URL structure is different
   .additionalDaps[]      
      .url String* - URL of the additional DAPS
      .issuerUrl String - Issuer URL of the additional DAPS, only required if DAPS URL structure is different
      .jwksUrl String - JWKS URL of the additional DAPS, only required if DAPS URL structure is different
   .requiredSecurityProfile BASE, TRUST, TRUST_PLUS BASE Minimal required security profile
   .dynamicClaims      
      .transportCertsSha256      
         .certLocation String - Location of certificate used for transport
httpMode MULTIPART_FORM_DATA, MULTIPART_MIXED, REST MULTIPART_MIXED IDS HTTP mode
keystore      
   .type PEM PEM Type of supplied keystore
   .pem.cert String* - IDS Certificate PEM-based certificate, either starting with file: to point to a file resource or direct certificate (plain or Base64 encoded)
   .pem.key String* - IDS Certificate PKCS#8-based key, either starting with file: to point to a file resource or direct key (plain or Base64 encoded)
resourceDatabase      
   .hostname String* - MongoDB hostname
   .port Integer 27017 MongoDB port
   .username String - MongoDB username
   .password String - MongoDB password
   .authenticationDatabase String - Authentication Database that contains the user to use
   .database String* - MongoDB database containing the relevant collection
   .collection String - MongoDB collection
   .isSslEnabled Boolean false Connect to MongoDB via SSL
   .isWatchable Boolean false Configuration on whether the MongoDB is watchable, i.e. is a replica set
namespaces Map<String, String> - Additionally supported namespaces in IDS Infomodel classes (in the properties field)
remoteAttestation      
   .tpm      
   .simulator Boolean false Deploy a simulator instead of using a physical TPM
   .host String - TPM Server host
   .port Integer - TPM Server port
   .ttp      
   .hostname String* - Hostname of the Trusted Third Party
   .port Integer 443 Port of the Trusted Third Party
routes      
   .https Boolean false Enable TLS for Camel routes, based on IDS certificate
   .ingress      
      .http[]      
         .id String - Identifier of the route (locally unique)
         .preProcessing String[] - Pre processing steps to be executed
         .postProcessing String[] - Post processing steps to be executed
         .port Integer 8080 Exposed port for incoming traffic
         .endpoint String `` Endpoint prefix for incoming traffic
         .parameters String `` Additional Camel HTTP parameters
         .dataApp String* - Data App Endpoint
         .clearing Boolean false Clearing House flag for automatic clearing of message
         .dapsVerify Boolean true DAPS Verification flag for automatic verification of incoming requests
         .policyEnforcement Boolean false Policy Enforcement flag
         .delegatedPolicyNegotiation Boolean false Delegate policy negotiation to the data app
      .idscp[]      
         .id String - Identifier of the route (locally unique)
         .preProcessing String[] - Pre processing steps to be executed
         .postProcessing String[] - Post processing steps to be executed
         .port Integer 9292 Exposed port for incoming traffic
         .dataApp String* - Data App Endpoint
         .clearing Boolean false Clearing House flag for automatic clearing of message
         .tlsClientHostnameVerification Boolean true Flag for enabling hostname verification on TLS level
   .egress      
      .http[]      
         .id String - Identifier of the route (locally unique)
         .preProcessing String[] - Pre processing steps to be executed
         .postProcessing String[] - Post processing steps to be executed
         .listenPort Integer 8080 Exposed port for internal traffic
         .endpoint String https_out Endpoint prefix for internal traffic
         .allowHTTP Boolean true Allow plain HTTP requests
         .clearing Boolean false Clearing House flag for automatic clearing of message
         .dapsInject Boolean true DAPS Injection flag for automatic injection of Dynamic Attribute Tokens to outgoing requests
         .forwardHeader String Forward-To Header used for indicating the intended recipient of the request
      .idscp[]      
         .id String - Identifier of the route (locally unique)
         .preProcessing String[] - Pre processing steps to be executed
         .postProcessing String[] - Post processing steps to be executed
         .listenPort Integer 8080 Exposed port for internal traffic
         .endpoint String idscp_out Endpoint prefix for internal traffic
         .clearing Boolean false Clearing House flag for automatic clearing of message
         .dapsInject Boolean true DAPS Injection flag for automatic injection of Dynamic Attribute Tokens to outgoing requests
         .forwardHeader String Forward-To Header used for indicating the intended recipient of the request
         .restOverIDSCP Boolean false Flag that indicates that REST over IDSCP is used
truststore      
   .type PEM, SYSTEM, ACCEPT_ALL PEM Type of supplied truststore
   .pem      
      .chain String* - Concatenated PEM CA certificates to be loaded in the Truststore, either starting with file: to point to a file resource or direct certificate chain (plain or Base64 encoded)
orchestrationManagerConfig      
   .enableKubernetes Boolean false Enable Kubernetes Orchestration Manager
   .masterUrl String - Kubernetes cluster master URL
   .clientCertificate String - Client certificate file
   .clientKey String - Client key file
   .certificateAuthorityData String - Certificate Authority data
   .pullSecretName String - Global pull-secret, used when no explicit pull-secret is given for a container
   .pullPolicy String IfNotPresent Kubernetes Image Pull Policy
   .namespace String - Kubernetes Namespace to use for resources, defaults to the current namespace (if in a Pod) or to “default”
   .timeout Long 900 Timeout (in seconds) for Kubernetes Completable Futures
pef      
   .negotiation      
      .enabled Boolean true Enable automatic Policy Negotiation
   .pdp      
      .enabled Boolean true Boolean on whether Policy Decision is enabled
      .defaultPolicy DENY_UNLESS, ALLOW_UNLESS DENY_UNLESS Default Policy in case no matching policy can be found
      .allowEmptyContract Boolean false Allow incoming messages without transfer contract
      .allowUnmappableMessage Boolean false Allow incoming message that are not supported for automatic mapping to a Policy Decision Request context
security      
   .enabled Boolean false Enable Spring Security
   .users[]      
      .id String* - User ID
      .password String* - Password in BCrypt format
      .roles String[] - User Role list
   .apiKeys[]      
      .id String* - API key ID
      .key String* - API key
      .roles String[] - User Role list
   .maxFailedAttempts Integer 10 Maximum of failed login attempts before temporarily locking account
   .failedAttemptDelay Long 900000 Time window in which the maximum of maxFailedAttempts is allowed in ms
   .accountLockDuration Long 900000 Time period an account is locked in ms
   .httpsOnly Boolean false Enable runtime check that stops the container if one of its endpoints is reachable via non encrypted HTTP
   .tlsVersions String[] ['TLSv1.3'] List of accepted TLS protocols for both ingress and egress
   .cipherSuites String[] [] List of Cipher suites, empty list indicates default Apache ciphers
   .passwordRotation Boolean false Whether you want to enable password rotation.
   .rotationPeriod Long 90*24*60*60*1000L The period of password rotation. I.e. after how many days users should change their password/api keys. Defaults to 90 days.
   .ntpInMilliseconds Long 100 The maximum amount of milliseconds allowed as a difference between NTP time and system time. Defaults to 100ms.
   .ntpCheckInterval Long 60*1000 The interval in which the NTP time is checked with the system time. Defaults to 60000 milliseconds.
   .ntpLogging Boolean false Boolean for whether you want to display NTP logs or not. Defaults to false.
selfdescription      
   .localEndpoint Boolean true Enable local multipart description endpoint
   .localPlainEndpoint Boolean true Enable local plain description endpoint
workflow      
   .incrementalIds Boolean false Use incremental identifiers rather than random UUIDs
   .useOrchestration Boolean false Boolean that indicates whether or not Data App Orchestration should be used by the workflow manager
   .internalHostname String - The internal hostname of this core container that can be reached by Data Apps
   .saveIntermediateResults Boolean false Debug flag for following intermediate results
Configuration properties

Security evaluation

On the healthcheck url /healthcheck, a JSON object is returned with an assesment of how secure the deployment is. All booleans should be set to true to have the most secure deployment. The table below lists the JSON property and the corresponding config parameter.

JSON Parameter Configuration parameter Description
routeConfiguration    
   .routesUsingTLS routeConfig.https Checks if all routes are using communication via HTTPS.
   .noCustomRoutes routeConfig.allRoutes Checks if no custom routes are used, because these cannot be verified.
   .camelRoutesViaDapsVerify routeConfig.ingress.http Checks if all ingress routes use DAPS verification.
   .CamelRoutesIDSCPIngress
WithHostnameVerification
routeConfig.ingress.idscp Checks if hostname verification is enabled for the TLS Client.
artifacts    
   .encryptionAtRest artifactConfiguration.encryptAtRest Checks if encryption at rest is enabled.
   .secureAesKey artifactConfiguration.aesEncryptionKey Checks if the default AES encryption key has been changed.
   .allExternalAccessUrlHttps connectorInfo.accessUrl Checks if the protocol of the access urls are using HTTPS.
   .securityEnabled securityConfig.enabled Checks if the security configuration is enabled, so users and API keys can be setup.
   .LimitedTrustStore trustStoreConfig.type Checks if the truststore is setup to not accept all certificates.
   .OCSP Environment variable ENABLE_OCSP (defaults to true) Checks if OCSP is enabled
   .APIKeysHaveMinimumOf32Chars securityConfig.apiKeys Checks if API keys have a minimal length of 32 characters.
   .TLSVersion1.3Only securityConfig.tlsVersions Checks if the TLS versions that are accepted are TLS 1.3 only.
Optional    
policyEnforcementOnCamelRoutes routeConfig.ingress.http Checks if the policyEnforcement is enabled for Camel routes.

On top of the dynamic security evaluation, some checks are executed on startup of the connector. If these checks fail, the connector will terminate. These checks are:

  • NTP Clock skew: On startup the system clock is evaluated against a server in the pool.ntp.org. If the clock skew is larger than 100 milliseconds, it is most likely the case that the server clock is configured incorrectly. This will give problems during runtime of the connector, especially around setting up TLS connections. Therefore the connector won’t start with a clock skew larger then 100 milliseconds (both towards the past as the future). Next to the check on startup, the connector will also check every minute if the clock skew is present. If it is, the connector will shutdown.
  • HTTPS Only: If in the security config the httpsOnly property is set to true, the connector will check on startup whether all communication, both internal as external, is encrypted. If that’s not the case, the connector won’t start. Configuration of the connector is only possible via editing yaml files and deploying the connector. We assume that everyone who has access to either the docker-compose- or kubernetes environment of the core container also has administrator rights within the core container, because it is inherit to the position that the cluster/vm adminstrator has. When the connector is offline, it is ensured that non adminstrators cannot tamper with the configuration, because it would require access to the environment where the connector is running. Therefore, only administrators can make changes to the configuration of the core container.

Next to the security aspects of the configuration, the connector also validates the given input for configuration and in case fields contain unexpected or unparseable contents (e.g. wrong serializations of key material) and will automatically stop the container in case this happens.

The truststores used throughout the connector are a combination of the default JVM truststore and the truststore configured via truststore.pem.chain. Which allows the connector to connect to dataspaces that fully use their proprietary PKI, including for TLS encryption. But also allows a proprietary PKI that only is used for interaction with the DAPS and a public PKI that is used for TLS termination. The latter requires the transportCertsSha256 to be configured to strictly pin the proprietary certificate to a public certificate. This transport certificate uses SHA256 for its hashing and for signing it should use an RSA key of 2048 bits.

The configured certificates might expire or be revoked during the runtime of the connector. A new certificate signing request might be necessary to be sent to the Certificate Authority. The processes of the Certificate Authority to handle renewal of revoked certificates might differ, so please contact your Certificate Authority to follow the right procedures. The core container accesses the certificates on a read-only basis. Therefore, to apply a new certificate a new instance of the core container should be deployed. In configurations using Kubernetes, this redeployment can be handled through rolling upgrades. For Docker-Compose configurations, scaling the connector to 2 instances and after successful deployment scaling back to 1 instance yields the same result.

Additional properties

Additional Spring or Camel properties can be provided next to the Core Container properties. This can be used to configure the logging properties of the Core Container.

For example, the following snippet can be added to the application.yaml to set the global logging level to INFO and the Core Container logging to debug:

logging:
  level:
    root: INFO
    nl.tno.ids: DEBUG

Example

broker:
  address: https://broker
  autoRegister: false
  id: urn:ids:broker

daps:
  url: https://daps.aisec.fraunhofer.de/v2

info:
  accessUrl:
    - http://localhost:8080
  curator: urn:ids:localhost
  descriptions:
    - IDSA Plugfest Localhost Connector
  idsid: http://plugfest2021.08.localhost.demo
  maintainer: urn:ids:localhost
  titles:
    - IDSA Plugfest Localhost Connector

keystore:
  type: PEM
  pem:
    # Truncated certificate and key
    cert: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t...
    key: LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0t...

orchestrationManagerConfig:
  enableKubernetes: true
  pullSecretName: 'pull-secret'

routes:
  egress:
    http:
      - clearing: false
        dapsInject: true
        id: HttpsOut

truststore:
  type: ACCEPT_ALL

workflow:
  incrementalIds: true
  internalHostname: 'host.docker.internal'
  type: IDS
  useOrchestration: true

Didn't find what you were looking for?