PKIMetal linting in Certificate Manager

Overview of PKIMetal linting

Certificate linting is the process of automatically checking a certificate against standards and profile
rules.

By integrating PKIMetal, Smart ID Certificate Manager can evaluate the to-be-signed (TBS) certificate content before a CA signature is applied, serving three primary purposes:

Compliance Auditing: Logging findings for review without interrupting issuance.
Issuance Enforcement: Blocking certificates that violate rules above a defined severity threshold.
Quality Assurance: Detecting configuration drift between procedures and intended profiles.

Linting is enabled at the certificate format level by adding two pre-signer modules (NexusX509CertEncoder and PKIMetalLinting) to the format definition.

Using PKIMetal, an open-source, multi-linter engine that aggregates multiple X.509 certificate linting libraries into a single HTTP service. It evaluates certificates against a wide range of standards and profiles, including RFC 5280, the CA/Browser Forum Baseline Requirements, ETSI EN 319 412, and various end-entity profiles such as TLS server, S/MIME, and code signing.

How the PKIMetal linting integration works

The linting flow is seamlessly integrated into the certificate production pipeline:

Preparation: Modifiers build the certificate content in the context as usual.
Encoding: The NexusX509CertEncoder pre-signer encodes the TBS structure and stores it in the pipeline context.
Submission: The PkiMetalLinting module sends the encoded TBS and selected profile to the PKIMetal HTTP endpoint.
Evaluation: PKIMetal returns a list of findings, each with a severity level: meta, debug, info, notice, warning, error, bug, or fatal.
Decision: If denial is enabled and a finding meets the threshold, issuance is blocked; otherwise, it proceeds to the signer.
Finalization: The Id2Signer1 module signs and issues the certificate.

Denial behavior and errors

When a certificate is denied (blocked), issuance is aborted immediately. The error context is populated with the findings in compact format and returned to the requestor via the RA client, REST API, or enrollment protocols (CMP, SCEP, EST).

If the PKIMetal service is unreachable at the time of issuance, the certificate request will fail with a connection error.

Configuration steps

Step 1: Configure PKIMetal linting module

The pkimetal.conf file in <configuration_root>/config/linter/ provides configuration parameters for the connection to the PKIMetal service and the policies for the module.

Replace the example URL in pkimetal.conf with your PKIMetal service URL:

pkimetal.url = http://pkimetal-proxy.internal.ingroupe.com <replace with your URL>

Configuration parameter details

Parameter	Default	Description
pkimetal.url	Required	The HTTP endpoint for the PKIMetal service.
pkimetal.connect-timeout-ms	5 seconds	Connection to PKIMetal server timeout.
pkimetal.read-timeout-ms	30 seconds	HTTP read timeout.
pkimetal.startup-profile-check	`true`	Verify connectivity to the PKIMetal service and retrieve the list of available linting profiles at CF startup.
pkimetal.log.findings.level	info	Logging level.
pkimetal.log.findings.format	compact	Format used when rendering in log messages.
pkimetal.profile	`autodetect`	The default linting profile to use.
pkimetal.minimum-fetch-severity	`meta`	Minimum finding severity to retrieve from the service.
pkimetal.denial.enable	`true`	Set to `false` for audit-only mode (issuance is never blocked).
pkimetal.denial.severity	`error`	Findings at or above this level trigger an issuance block.
pkimetal.denial.ignore-codes	Empty	Comma-separated list of codes that will never block issuance.

You can override the global pkimetal.conf settings for a specific certificate procedure format using the format definition fields.

Step 2: Register the module

The PKIMetalLinting module needs to be enabled in <configuration_root>/config/modules.conf. Add or uncomment the following:

[PKIMetalLinting]
FileName=com.id2tech.cm.cf.modifiers.PKIMetalLinting
InitData=linter/pkimetal.conf

Step 3: Certificate formats

Add the pre-signer modules NexusX509CertEncoder and PKIMetalLinting right before (lower index) the Id2Signer1 module to the format of the targeted certificate procedure through the Advanced button (Edit Format Definition) as described here. The NexusX509CertEncoder must precede PKIMetalLinting. If needed, also add format definition fields for the PKIMetal configuration parameters.

Alternatively, a custom format file can be created for re-use in multiple certificate procedures.

Last updated: July 09, 2026