How to Install a Code Signing Certificate from a Developer in Niagara 4
Niagara 4 checks that every module is signed by a trusted certificate. To use a developer's self-signed modules, import their certificate into the trust store.
Third-party Niagara drivers and custom modules are everywhere in real projects. Since Niagara 4.8, the framework checks who signed each module and whether that signer is trusted, and the rules have tightened with each release. In Niagara 5 every module must carry a valid signature. This guide explains how module signing works, what the verification modes mean, how to install a developer's code signing certificate correctly, and how to diagnose signature warnings.
Why Niagara signs modules
A Niagara module is a JAR file containing code that runs inside your station with significant privileges. Signing proves two things:
- Origin: the module was produced by the holder of a particular certificate.
- Integrity: the module has not been altered since it was signed.
Without signing, a tampered or malicious module could be slipped into a station during an upgrade or by copying files. Module signing is one of the main defences against that.
Module signing timeline
| Niagara version | Default module verification | Behaviour |
|---|---|---|
| 4.8 | Low | Unsigned or invalidly signed modules produce warnings but still run |
| 4.9 | Medium | Modules must be signed by a valid, trusted certificate; self-signed certificates are accepted if trusted |
| 4.10 and later | High | Modules must be signed with a certificate issued by a recognised certificate authority (CA); self-signed certificates are rejected |
| Niagara 5 | Mandatory | Every module must have a valid digital signature; unsigned or legacy-signed modules do not load |
Verification modes explained
The mode is controlled by the niagara.moduleVerificationMode property in the host's system.properties file:
| Mode | Unsigned modules | Self-signed modules | CA-signed modules |
|---|---|---|---|
| low | Run, with warnings | Run | Run |
| medium | Rejected | Run, if the certificate is in the trust store | Run |
| high | Rejected | Rejected | Run |
High is the secure default on current Niagara 4 releases. Lowering the mode should be a temporary, documented exception, never a permanent fix.
Self-signed vs CA-signed certificates
- A CA-signed code signing certificate is issued by a commercial certificate authority after verifying the developer's identity. Niagara trusts it through the CA chain, so you usually do not need to import anything.
- A self-signed certificate is created by the developer. Niagara has no way to know whether to trust it, so you must import the developer's certificate into the trust store yourself, and the host must be in medium mode for it to be accepted.
Reputable driver vendors sign their modules with CA-issued certificates. Self-signed modules are more common for in-house custom code and small developers.
Installing a developer's code signing certificate
Step 1: Get the certificate from the developer securely
Ask the developer for their public certificate (usually a .pem or .cer file). Never accept or ask for a private key. Verify you received the genuine certificate, for example by confirming its fingerprint with the developer by phone.
Step 2: Import it into the trust store on your PC
- In Workbench, open Tools > Certificate Management.
- Select the User Trust Store tab.
- Click Import and choose the developer's certificate file.
- Check the certificate details (subject, issuer, validity dates, fingerprint) and confirm.
Workbench now trusts modules signed by that certificate on your PC.
Step 3: Import it on each host that will run the module
Each JACE, IONA or supervisor that installs the module must also trust the certificate:
- Open a platform connection to the host.
- Open the platform's Certificate Management view and its trust store.
- Import the developer's certificate.
Repeat for every host that will run the module.
Step 4: Check the verification mode
For a self-signed certificate, the host must be in medium mode; in high mode the module is rejected even if its certificate is in the trust store. If you must change the mode, edit niagara.moduleVerificationMode in system.properties:
- On a PC (Workbench or supervisor): in Workbench, open the Niagara system home's
defaultsfolder and editsystem.properties. Remove the#comment from the line and set the value. - On a JACE: use the platform File Transfer Client to copy
system.propertiesfrom the controller's Niagaradefaultsfolder to your PC, edit it, and copy it back, overwriting the original. Restart for the change to take effect.
Treat a mode change as a security decision: document why, who approved it, and when it will be reversed.
Step 5: Install the module
Install the module with the Software Manager. The Software Manager shows each module's signature status:
| Icon | Meaning |
|---|---|
| Green | Valid, trusted signature |
| Yellow | Warning, for example a trust issue in low mode |
| Red | Error; installation is blocked |
| Grey "?" | Status unknown |
Resolve red and yellow states before installing on a production controller.
Signing your own modules
If your team writes custom Niagara modules:
- obtain a CA-issued code signing certificate for production use, so modules work in high mode and in Niagara 5
- sign every build as part of your build process
- keep the private key secure, ideally in a hardware token or protected signing service
- for testing only, a self-signed certificate with medium mode on development hosts is acceptable
- plan for Niagara 5: modules must be ported to Java 21 and signed
Auditing modules on an existing site
Before upgrades, and as part of any Niagara 5 preparation, audit what is installed:
- Open a platform connection to each host and open the Software Manager.
- Sort or filter by vendor to separate Tridium modules from third-party ones.
- Note each third-party module's vendor, version, signature status and which station features depend on it.
- Check whether the station actually uses each module. Unused modules can often be removed, reducing risk.
- For each module that stays, confirm with the vendor that a signed build exists for your current Niagara version and for the version you plan to move to.
Record the results in a simple table:
| Host | Module | Vendor | Version | Signature status | Used by | Niagara 5 build available? |
|---|---|---|---|---|---|---|
| Supervisor | exampleDriver-rt | Vendor A | 4.13.2.18 | Green | Building A integration | Confirmed |
| JACE-03 | customLogic-rt | In-house | 4.10 | Yellow (self-signed) | Pump sequencing | Needs porting and CA signing |
This list becomes your action plan: rebuild, re-sign, replace or remove each problem module before it blocks an upgrade.
Certificates you will meet in Niagara
Code signing certificates are one of several certificate types in a Niagara system. Knowing which is which avoids confusion:
| Certificate | Purpose | Where it matters |
|---|---|---|
| Code signing certificate | Proves who built a module | Module verification in Software Manager and at station start |
| Server (TLS) certificate | Identifies a host for FoxS, HTTPS and platform TLS connections | Workbench and browser connections |
| Root / CA certificates | Establish trust in server and code signing certificates | Trust stores on PCs and controllers |
| Client certificates | Authenticate users or systems | Advanced authentication setups |
All of them are managed through Workbench Certificate Management, with key stores (a host's own certificates and private keys) and trust stores (certificates the host trusts). Keep track of expiry dates: an expired server certificate breaks connections, and an expired code signing certificate can stop newly signed modules from verifying.
Troubleshooting
Module shows a red signature status. It is unsigned or its signer is not trusted for the current mode. Get a properly signed build, or import the signer's certificate and check the mode.
Imported the certificate but the module is still rejected. The host is in high mode and the certificate is self-signed, or the certificate was imported on your PC but not on the controller.
Signature valid on PC, rejected on JACE. The JACE's trust store does not contain the certificate, or its verification mode differs.
Certificate has expired. Modules signed while the certificate was valid may still verify if timestamped; otherwise ask the developer for a re-signed build.
Warnings after a Niagara upgrade. Newer releases default to stricter modes. Update third-party modules to signed builds for the new version.
Reading a certificate's details
Before trusting any certificate, check its details in the import dialog or certificate viewer:
| Field | What to check |
|---|---|
| Subject | The developer's or company's name, as expected |
| Issuer | For CA-signed certificates, a recognised certificate authority; for self-signed, the same as the subject |
| Valid from / to | The certificate is within its validity period |
| Key usage | Includes code signing |
| Fingerprint (SHA-256) | Matches the value the developer gave you through a separate channel |
If anything does not match, do not import it. Contact the developer and resolve the discrepancy first.
Good practice for integrators
- Prefer drivers from vendors who publish CA-signed builds for every Niagara version you support.
- Keep a register of trusted developer certificates you have imported, with fingerprints and expiry dates.
- Never import a certificate you received by unverified email or download.
- Remove certificates for developers you no longer use.
- Keep hosts on the default high verification mode wherever possible.
- Include module signing status in your handover documentation and maintenance checks.
Code signing and Niagara 5
Niagara 5 removes the "warn and continue" option entirely. Before migrating, audit every non-Tridium module on every host and confirm a signed Niagara 5 build exists. See the Niagara 5 readiness checklist.
Frequently asked questions
What is module signing in Niagara 4?
A security mechanism where each module JAR is digitally signed, so Niagara can verify who produced it and that it has not been altered.
Where is the module verification mode set?
In the niagara.moduleVerificationMode property of the host's system.properties file, with values low, medium or high.
Can I use self-signed modules in Niagara 4.10 and later?
Only if the host's verification mode is set to medium and the signer's certificate is in the trust store. The default high mode rejects self-signed modules.
How do I import a code signing certificate in Workbench?
Open Tools > Certificate Management, go to the User Trust Store tab and click Import. Repeat on each host through its platform Certificate Management view.
Will unsigned modules work in Niagara 5?
No. Every module must have a valid digital signature to load in Niagara 5.
What is the difference between a trust store and a key store?
A key store holds a host's own certificates and private keys. A trust store holds other parties' certificates that the host trusts, such as a developer's code signing certificate or a certificate authority.
Should I lower the verification mode to get a module working?
Only as a temporary, documented exception. The better fix is a properly signed module from the developer, ideally with a CA-issued certificate.
Do I need to restart after changing the verification mode?
Yes. Changes to system.properties take effect when Niagara restarts on that host.
What if a Tyrrell Products driver shows a signature warning?
Our drivers are published as separate builds for each Niagara version. If the Software Manager shows a signature warning or error on one of them, contact our team with your Niagara version and we will supply the correct build.
What file types are code signing certificates?
Developers usually supply the public certificate as a .pem or .cer file. Workbench's certificate import accepts these.
Where do I find a module's signature status?
In the Software Manager on a platform connection. Each module shows a coloured status: green for valid, yellow for warnings, red for errors and grey for unknown.
Does module signing slow down the station?
Signatures are verified when modules load, typically at station start. There is no meaningful effect on normal running performance.
Can I sign modules written by a previous integrator?
Only with the source code and a code signing certificate of your own. Signing proves who built a module, so re-signing someone else's compiled module without understanding its contents is not recommended.
Need help from a Niagara engineer?
If this guide has not solved the problem, contact the Tyrrell Products technical team on 01942 732819 or [email protected]. Tell us the controller or host type, its Niagara version and what you have already tried, and we will help you get the system running.