ILM Core

This repository is part of the open source project ILM. You can find more information about the project at the ILM repository, including the contribution guide.

Core provides the basic functionality for the ILM platform. It implements the logic for the certificate lifecycle management and handles all related tasks. You can think about it as a brain of the ILM platform.

There are two types of communication that the Core is responsible for:

• client requesting management operations on top of certificates and related objects
• Connector that provides the functionality for specific technologies

The management of certificates and cryptographic keys is abstracted through ILM objects called Profiles, such as:

• RA Profile - configuration of the service for certificate lifecycle management
• Token Profile - configuration of the cryptographic service and management of the keys
• Compliance Profile - compliance requirements for the certificates and related objects

For more information, refer to the ILM documentation.

Access Control

Core access control requires the following to run:

• auth service to manage users, roles, permission. The URL of the Auth service can be configured using AUTH_SERVICE_BASE_URL environment variable.
• OPA (Open Policy Agent) evaluating policies and providing decisions about authorization. The OPA service URL can be confgiured using OPA_BASE_URL environment variable.
• OPA policies bundles that are loaded into OPA service and define the rules to be evaluated. The policies are defined in auth-opa-policies

Warning The Core will fail to run when Auth or OPA is missing.

Note OPA can run on the same system with the Core or it can be hosted externally. To improve the performance of the permissions evaluation, it is typically running on the same host as Core (e.g., as a sidecar).

Certificate inventory

Certificate inventory contains all Certificates that were discovered or were imported to the platform. Each Certificate provides comprehensive and consistent information which can be managed.

Lifecycle operations

The following basic lifecycle operations are supported for each Certificate:

• create (request)
• issue
• renew
• rekey
• revoke

Operations can be automated by the Core, but also can be performed manually by the user.

Cryptographic key inventory

Key inventory contains all Keys that are available for usage. Each Key provides comprehensive and consistent information which can be managed through the Token Profile.

Support for PQC algorithms

Core supports the following PQC algorithms: ML-DSA, SLH-DSA, ML-KEM and FALCON (FN-DSA).

CBOM inventory events

CBOM uploads validate custom attributes before sending the document to the repository. After repository acceptance, Core commits the CBOM record before applying attributes in a separate transaction. A late attribute failure preserves the record and returns an explicit partial-failure error containing its UUID: 422 for permission or validation failures, 500 for unexpected failures. Update attributes on that record to retry.

CBOM_SYNCED is raised after the first successful asset ingest of each CBOM UUID. A new document version has its own UUID and event. Skipped or superseded documents emit no sync event; retries and recovery of an already completed CBOM do not emit it again.

CRYPTO_ASSET_PQC_NOT_READY is raised when an asset is first decided NOT_READY or changes from READY or NOT_APPLICABLE to NOT_READY. UNKNOWN preserves the last decided verdict, so NOT_READY → UNKNOWN → NOT_READY emits no second event. The payload carries the asset's properties, rule, reason and previous decided verdict at the write. An asset deleted before consumption is skipped.

A committed verdict batch can emit asset events even if later CBOM ingest fails or is superseded. There is no guaranteed delivery order between asset verdict and CBOM sync events. A deleted asset that later re-enters inventory has a new UUID and verdict history.

Inventory attribute actions verify and lock their parent in a short, independent transaction after permissions are loaded. Deletion before the write prevents new attribute content. A successful attribute action remains committed if saving event history later fails.

Configure document-summary notifications on CBOM_SYNCED: the first ingest of a mostly classical inventory can emit one not-ready event per asset. Use the asset event for selective rules and actions. Neither event sends a notification without a configured action.

The nullable verdict-history column requires no backfill and emits nothing during migration. Normal sweeps after upgrade apply the same transition rule. Both events use the existing after-commit sender and its best-effort delivery behavior.

Protocol support

Core support the following protocols for certificate management:

• ACME
• SCEP (with optional Intune support)
• CMP

Message brokers support

Application supports two types of message brokers:

• RabbitMQ – uses JmsPoolConnectionFactory with configurable connection pool settings
• Azure Service Bus - uses JmsConnectionFactory with two authentication options:
  • SAS (Shared Access Signature) - uses connection string with policy name and key
  • AAD (Azure Active Directory / Entra ID) - uses OAuth2 with Service Principal credentials

Authentication configuration

Broker	Authentication	Required variables
RabbitMQ	Username/Password	BROKER_USERNAME, BROKER_PASSWORD
Azure Service Bus	SAS	BROKER_USERNAME, BROKER_PASSWORD
Azure Service Bus	AAD	BROKER_AZURE_TENANT_ID, BROKER_AZURE_CLIENT_ID, BROKER_AZURE_CLIENT_SECRET

Docker container

Core is provided as a Docker container. Use the hub.omnitrustregistry.com/ilm/core:tagname to pull the required image from the repository. It can be configured using the following environment variables:

Variable	Description	Required	Default value
JDBC_URL	JDBC URL for database access		N/A
JDBC_USERNAME	Username to access the database		N/A
JDBC_PASSWORD	Password to access the database		N/A
DB_SCHEMA	Database schema to use		core
PORT	Port where the service is exposed		8080
HEADER_NAME	Name of the header where the certificate of the client can be found		ssl-client-cert
HEADER_ENABLED	True if the certificate should be get from the header		N/A
TS_PASSWORD	Password for the trusted certificate store		N/A
OPA_BASE_URL	Base URL of the Open Policy Agent		N/A
AUTH_SERVICE_BASE_URL	Base URL of the authentication service		N/A
AUTH_TOKEN_HEADER_NAME	Name of the header for the JSON ID content		X-USERINFO
SCHEDULED_TASKS_ENABLED	Scheduled certificate status update enable / disable		true
JAVA_OPTS	Customize Java system properties for running application		N/A
TRUSTED_CERTIFICATES	List of PEM encoded additional trusted certificates		N/A
SCHEDULER_BASE_URL	Base URL of the scheduler service		N/A
BROKER_TYPE	Message broker type - supported values are SERVICEBUS or RABBITMQ		RABBITMQ
BROKER_URL	Message broker url (include protocol, e.g. amqp://localhost:5672 for RabbitMQ, amqps://namespace.servicebus.windows.net:5671 for ServiceBus)		N/A
BROKER_USERNAME	Message broker username (required for RabbitMQ and ServiceBus+SAS)		N/A
BROKER_PASSWORD	Message broker password (required for RabbitMQ and ServiceBus+SAS)		N/A
BROKER_AZURE_TENANT_ID	Azure AD tenant ID (required for ServiceBus+AAD authentication)		N/A
BROKER_AZURE_CLIENT_ID	Azure AD application (client) ID (required for ServiceBus+AAD)		N/A
BROKER_AZURE_CLIENT_SECRET	Azure AD client secret (required for ServiceBus+AAD authentication)		N/A
BROKER_AZURE_TOKEN_REFRESH_INTERVAL	Azure AD token refresh interval in seconds (required for ServiceBus+AAD authentication)		300
BROKER_AZURE_TOKEN_GETTING_TIMEOUT	Azure AD token getting timeout in seconds (required for ServiceBus+AAD authentication)		30
BROKER_EXCHANGE	Message broker exchange/topic name		ilm
BROKER_VHOST	Message broker vhost (for RabbitMQ only)		N/A
BROKER_SESSION_CACHE_SIZE	ConnectionCachingFactory session cache size (only for RabbitMQ)		25
BROKER_QUEUE_AUDIT_LOGS	Queue name for audit logs (for RabbitMQ only)		core.audit-logs
BROKER_QUEUE_EVENT	Queue name for events (for RabbitMQ only)		core.event
BROKER_QUEUE_NOTIFICATION	Queue name for notifications (for RabbitMQ only)		core.notification
BROKER_QUEUE_SCHEDULER	Queue name for scheduler (for RabbitMQ only)		core.scheduler
BROKER_QUEUE_VALIDATION	Queue name for validation (for RabbitMQ only)		core.validation
BROKER_ROUTINGKEY_ACTIONS	Routing key for actions		actions
BROKER_ROUTINGKEY_AUDIT_LOGS	Routing key for audit logs		auditlogs
BROKER_ROUTINGKEY_EVENT	Routing key for events		event
BROKER_ROUTINGKEY_NOTIFICATION	Routing key for notifications		notification
BROKER_ROUTINGKEY_SCHEDULER	Routing key for scheduler		scheduler
BROKER_ROUTINGKEY_VALIDATION	Routing key for validation		validation
SETTINGS_CACHE_REFRESH_INTERVAL	Interval of scheduled settings cache refresh from DB (in seconds)		30
PLATFORM_LOG_FORMAT	Console log format: text for the pattern, ecs or logstash for one JSON object per line		text

Client certificate authentication

See Client certificate authentication for setup with a gateway or reverse proxy.

OpenTelemetry settings

Core supports OpenTelemetry for producing signals (metrics, traces, logs) to the observability system. The following environment variables can be used to configure OpenTelemetry:

Variable	Description	Required	Default value
OTEL_SDK_DISABLED	Disables the OpenTelemetry SDK. Supported values: true, false. OpenTelemetry SDK is disabled by default		true
OTEL_LOGS_EXPORTER	The logs exporter to use. Supported values: none, otlp, logging.		none
OTEL_METRICS_EXPORTER	The metrics exporter to use. Supported values: none, otlp, logging.		none
OTEL_TRACES_EXPORTER	The traces exporter to use. Supported values: none, otlp, logging.		none
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	Endpoint URL for log data only, with an optionally-specified port number. Typically ends with v1/logs when using OTLP/HTTP.		http://localhost:4317
OTEL_EXPORTER_OTLP_LOGS_PROTOCOL	Protocol to use for the logs exporter. Supported values: grpc, http/protobuf, http/json.		grpc
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT	Endpoint URL for metric data only, with an optionally-specified port number. Typically ends with v1/metrics when using OTLP/HTTP.		http://localhost:4317
OTEL_EXPORTER_OTLP_METRICS_PROTOCOL	Protocol to use for the metrics exporter. Supported values: grpc, http/protobuf, http/json.		grpc
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT	Endpoint URL for trace data only, with an optionally-specified port number. Typically ends with v1/traces when using OTLP/HTTP.		http://localhost:4317
OTEL_EXPORTER_OTLP_TRACES_PROTOCOL	Protocol to use for the traces exporter. Supported values: grpc, http/protobuf, http/json.		grpc

Proxy settings

You may need to configure proxy to allow Core to communicate with external systems. To enable proxy, use the following environment variables for docker container:

Variable	Description	Required	Default value
HTTP_PROXY	The proxy URL to use for http connections. Format: <protocol>://<proxy_host>:<proxy_port> or <protocol>://<user>:<password>@<proxy_host>:<proxy_port>		N/A
HTTPS_PROXY	The proxy URL to use for https connections. Format: <protocol>://<proxy_host>:<proxy_port> or <protocol>://<user>:<password>@<proxy_host>:<proxy_port>		N/A
NO_PROXY	A comma-separated list of host names that shouldn't go through any proxy		N/A

Example values:

• HTTP_PROXY=http://user:password@proxy.example.com:3128
• HTTPS_PROXY=http://user:password@proxy.example.com:3128
• NO_PROXY=localhost,127.0.0.1,0.0.0.0,10.0.0.0/8,cattle-system.svc,.svc,.cluster.local,my-domain.local

Building against an unmerged interfaces change

A change that needs a not-yet-merged interfaces API cannot compile against the mainline snapshot. Put one marker in the pull request body to redirect the build; the pom is never edited.

Depends-On: OmniTrustILM/interfaces#940

CI then builds against that pull request's own snapshot, which it publishes only while it carries the publish-snapshot label, and never from a fork.

Use Interfaces-Version instead to pin one already-published build — useful when somebody else's merge reddens an unrelated pull request:

Interfaces-Version: 2.20.0-M907-1299756b

Three rules decide whether a marker is read at all. It must start at column 0 — no bullet, no indent, no >, no bold — nothing may follow the value, and the repository must be spelled in full as OmniTrustILM/interfaces. Break either of the first two and the build fails with a message naming the accepted form; a shortened repository name is not recognised as a marker at all, so it is ignored in silence. Markers inside fenced code blocks or HTML comments are skipped too, so quoting the syntax is safe.

Interfaces pin stays red for as long as a marker is active, and it feeds the required Build check, so neither form can reach main. Depends-On clears itself once the interfaces pull request merges and all jobs are re-run — re-running only the failed job replays the cached resolution. Interfaces-Version clears only when you delete the line.

The rest of the flow — merge order, which workflows to re-run and why, building locally — is in docs/coupled-interfaces-changes.md.