What a station checks before loading a module

A Niagara host decides how strict to be about module signatures with a single system property, niagara.moduleVerificationMode. It takes four values — three real settings and one that means "nobody chose" — and the distinction between the three is about the certificate, not about whether a signature exists.

There is a fourth value, noPreference, which is what the setting means when nobody has chosen: the host resolves it from its own version. Below 4.8 the mode is forced to low whatever the preference says, 4.8 resolves to low, and 4.9 and later resolve to medium. noPreference is not a way to opt out — it inherits whatever the running version's default happens to be.

The default moved in two steps, not one. Niagara 4.8 shipped with the verification mode at low; 4.9 raised the shipped default to medium. A host running 4.9 or later gets medium behaviour out of the box. A host still on 4.8 does not — which is why a jar that installed unsigned for years stops installing the moment the host is upgraded, with no change to the jar itself.

The mode is not the only gate. Before it looks at the setting at all, the host asks whether the module requests a Niagara permission that requires a signature — and if it does, the signature is checked even on a host set to low. Six permission groups carry that requirement: access class, HSM signing, MBean, protection domain, reflection and third-party permission. Five are rated severe risk; protection domain is rated mild.

Reflection and third-party permission are the two that ordinary driver code reaches for. A module that wraps a vendor SDK, or that reads a private field to get at something the public API does not expose, is in signature territory regardless of what the estate has set. Unsigned, it is refused with failed signature validation: Module not signed, naming the module part that failed — so an unsigned -ux jar can be rejected while the -rt jar beside it loads. The wording is worth reading closely when a log line is all you have: the not-signed and invalid-signature messages name the module, while a certificate-chain failure names the module part — the name attribute from module.xml, profile suffix included. Same check, two vocabularies, and only one of them tells you which jar to look at.

There is a quieter failure in the same area. The permission groups a module requests are parsed one by one, and when a group that requires a signature is found in an unsigned jar the parser raises Permission group … requires signature but the module … is not signed — which is then caught in the same loop, logged as a warning about XML that could not be parsed, and the element is skipped. The module still loads. It simply loads without that permission, and the first symptom is a security exception in whatever code needed it, at a point far away from the cause. On an unsigned development build, a missing permission and a broken feature look identical.

Everything above is load time, inside the station. Software Manager and the commissioning wizard run their own check first, and it resolves the mode from the target, not from the workstation doing the installing: the platform's own preferred mode, combined with the version of the baja module on that host. Engineer a 4.8 controller from a 4.15 Workbench and the install-time rule is the controller's, not yours.

The installer also grades a signature more finely than the station does. It classifies each jar into one of nine states — fine, unsigned, invalid signature, not timestamped, unknown, self-signed signer, self-signed timestamp, chain validation failure, chain validation warning — and then asks whether that state is acceptable in the resolved mode. Low rejects only an invalid signature. Medium adds unsigned, chain-validation failure and unknown. High adds the two self-signed cases. Two states are acceptable in every mode, including high: not timestamped, and a chain-validation warning. A signed module with no timestamp installs everywhere — which is convenient right up to the day the signing certificate expires, because without a timestamp there is nothing to prove the signature predated the expiry.

The most common surprise is a module that installs on one host and is refused by the next, with the same jar and the same signature. Nothing about the module changed; the second host does not have the signing certificate in its trust store.

This is why "is it signed?" is the wrong question when something will not install. The question is "is this certificate trusted by this host, and does this host demand a CA behind it?" The answer is per host, and on an estate assembled over several years the answer varies across the estate.

There is a matching denylist of properties that cannot be set as launch arguments, and the verification mode is the first entry in it, alongside the program-object signing property. The default list is compiled into the runtime, so it applies to a host whose configuration file says nothing about it.

The enforcement has one condition worth knowing. It applies to a user who cannot write the host's system.properties: their -D is discarded and a warning is logged. Someone who administers the host and can edit that file can still change the setting there — deliberately, in configuration, where it is visible and auditable — but a process cannot quietly lower it for itself on the way up.

Treat a plan that involves relaxing verification as a plan that will be rejected during commissioning.

Modules are not the only executable thing in a station. Program objects have their own signing requirement, with its own property, defaulting to permissive — unsigned program objects run. A site that has tightened module verification and left program objects alone has a gap it very likely does not know about, and closing it is a one-line configuration change plus the work of signing what is already there.

The modes, the signature states each one accepts, and the log lines quoted above are all read out of the shipped jars by module-sign-scan, which is free and MIT. Run it against the installation you are shipping to and the answer is that installation's rather than this page's.