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.
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
.
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 |
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:
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.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 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
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