MSP security, certificate setup and recovery

All documentation · Support center

This guide describes the 4.1.6 candidate. The source package does not establish successful H1 Windows build, installer generation or runtime acceptance.

What Changed

PostgreSQL encryption is observed on the current authenticated session through pg_stat_ssl WHERE pid=pg_backend_pid(). The repository refuses secure-profile queries on a plaintext session. Startup now also fails closed if a secure profile cannot initialize over encrypted database transport. Configuring Require is not reported as proof of observed TLS. Status includes observation time/protocol/cipher for MSPAdmin; other roles retain the existing limited status contract. Test Server and Verify Current Secure Connection issue read-only diagnostics; neither saves settings nor provisions/restarts the service. Save Server Profile saves client credentials and checks connectivity without provisioning. Explicit ON/OFF controls apply the server profile. Failed secure provisioning does not retry the key over HTTP. OFF diagnostics intentionally skip API authentication over HTTP; they cannot establish full authenticated readiness. The normal OFF client remains supported, but plaintext transport is explicit. Server Admin now has Database TLS & Recovery: host, SSL mode, CA path, revocation, read-only test, save after live test, explicit previous-configuration restore and sanitized server report export. It guides ITAF's connection configuration; it does not automatically modify PostgreSQL configuration or issue database certificates. Security saves validate certificate SAN/validity/Server Authentication EKU, database TLS and profile requirements first. Writes atomically retain server-settings.json.previous. Unknown JSON fields survive server/Admin saves. Running listener policy remains unchanged until restart. Recovery never happens silently. Preflight cannot prove service-account private-key access or a remote client's trust; those remain post-restart checks. Admin preflight is bounded but can occupy the UI while its database probe runs. Trust import places intermediate CAs in Intermediate Certification Authorities and self-issued roots in Trusted Root. CA-issued leaf certificates are rejected as trust anchors; import their issuing chain. Import requires confirmation. Client certificates require Client Authentication EKU and a private key. Renew-before-expiry guidance appears in diagnostics.

Which Profile And Why

OFF: isolated temporary setup/troubleshooting only when plaintext API transport is intentionally accepted. No encryption claim; do not use for sensitive production traffic. Select OFF explicitly and use HTTP. No silent fallback from HTTPS. Standard: HTTPS TLS 1.2/1.3, API key and encrypted database transport. Suitable for a basic authenticated server connection. For maximum security within this setting use a CA-issued certificate, VerifyFull database TLS and restricted network reachability. Standard does not require signed requests or mTLS. Enhanced: adds certificate revocation checks and signed API requests. Suitable when replay/body-integrity controls and revocation checking are required. Use CA-issued certificates with reachable CRL/OCSP services; keep clocks synchronized and use signature v2. Disable legacy signatures after all clients support v2. High Assurance: adds mandatory mTLS and TLS 1.3. Suitable for managed assessor devices where possession of a device certificate is required. Use CA-chain trust, Client Authentication certificates, private-key access limited to the assessor and revocation infrastructure. Explicit thumbprint mode remains an intentional compatibility option; renewal needs allowlist updates. DoD-Aligned: technical profile requiring TLS 1.3, mTLS, request signing, revocation, CA-chain trust and the application's Windows FIPS policy gate. Use only when those requirements fit the environment and all gates pass. This label is not certification, authorization to operate, or proof of CMMC compliance. Profile colors identify verified modes; red/unknown/expired verification overrides profile colors. These modes add controls, not a claim that every higher profile uses a stronger cipher.

Api Server Certificate — Server Installation

Use the actual stable DNS name in ApiAdvertisedHost and in the certificate DNS SAN. If clients connect to an IP, the certificate must include that address as an IP SAN. ADVERTISED_HOST is never a deployable hostname. Request Server Authentication EKU and a usable private key from your enterprise/public CA. Import PFX/P12 using Server Admin Security & Communications > Import PFX/P12, into LocalMachine\My. Import root and intermediate public CA certificates through Import Trusted CA, verifying fingerprints out of band. Grant the service identity read access to the private key using certlm.msc > Personal > certificate > All Tasks > Manage Private Keys. The default service identity is LocalSystem; check sc.exe qc ITAuditFactoryMSPServer for the actual identity. Never copy the server private key to assessor clients. Select the certificate, confirm advertised DNS/IP and port, test preflight, save and restart. For a controlled lab, Regenerate Self-Signed TLS uses the real advertised name/IP; export only its public CER and explicitly trust it on clients. Self-signed certificates generally do not provide normal CA revocation infrastructure and are not the recommended Enhanced/High/DoD deployment.

Api Server Trust — Client Installation

Use Settings & Credentials > Central MSP Server > Import/Trust CA or Server Certificate. Verify subject/issuer/fingerprint independently before confirming. Install the root and intermediate CA public certificates in the proper CurrentUser trust stores. Windows Trust Store mode validates the chain and URL identity; filling a thumbprint box alone does not select explicit pinning. For an intentional self-signed deployment, select explicit self-signed trust and enroll the verified public certificate. Configure the HTTPS URL using the exact SAN hostname, then save the client profile/key and run the read-only verification. Do not disable certificate validation to work around a name mismatch.

mTLS CLIENT CERTIFICATE For High Assurance or DoD-Aligned, issue a separate Client Authentication certificate per device/user. Import its PFX using the client Import PFX control into the user's Personal store, protect the PFX password and remove temporary PFX copies after enrollment. Select the certificate thumbprint. On the server, trust its root/intermediate CA and select required client certificates. For ExplicitThumbprints, add that client's public thumbprint without discarding other clients; DoD-Aligned requires WindowsChain. A server TLS certificate and an mTLS client certificate are different roles. Revoke retired devices and API keys independently.

Postgresql Tls — Prepare First

The database certificate is separate from the API listener certificate. PostgreSQL uses PEM files, not a Windows certificate-store thumbprint. Obtain a Server Authentication certificate with a SAN matching DatabaseHost, its PEM private key and issuer chain. Keep the key readable only by PostgreSQL's service account and administrators. Find the actual service data/config directory; do not assume an installation path or change the existing port, database, user or password. Back up postgresql.conf and pg_hba.conf. Configure ssl=on, ssl_cert_file to the server certificate/chain PEM and ssl_key_file to its private-key PEM. Configure ssl_ca_file when your PostgreSQL deployment needs CA trust/client-certificate authentication; it is not a replacement for the CA trusted by ITAF. Add appropriately scoped hostssl rules for the ITAF database/user/address using scram-sha-256, and place a matching hostnossl reject rule before any permissive rules. Preserve existing administrative/local maintenance access and test it before removing older rules. Reload/restart PostgreSQL as its documented settings require. Managed PostgreSQL should remain local; do not expose 55432 to assessor clients. In Server Admin > Database TLS & Recovery, enter the database certificate hostname. Choose VerifyFull and select the trusted CA PEM, or use a correctly installed Windows trust chain. Enable revocation where CA infrastructure supports it. Test: require encrypted=true and the negotiated protocol/cipher. Save verified settings; then restart ITAF. Require encrypts without authenticating server identity; VerifyCA validates the chain but not the hostname; VerifyFull is the recommended production setting. Do not claim maximum security with Require. A certificate for DNS localhost does not cover 127.0.0.1 unless that IP SAN is present. If using localhost, confirm PostgreSQL is reachable on the address to which it resolves. Optional independent SQL check, entered into an authenticated psql session: SELECT ssl, version, cipher FROM pg_stat_ssl WHERE pid=pg_backend_pid(); Never put database passwords into diagnostic command lines.

Safe Change / Recovery

Finish PostgreSQL TLS and certificate trust first, then enable the intended API profile locally or with the explicit ON action. A 409 response means security preflight refused the change and retained current configuration. The API may return a staged profile while the old listener is still active; restart and reverify before claiming readiness. Downgrades from High Assurance/DoD-Aligned remain local-only; other API downgrades retain confirmation/reason/audit controls. A generated self-signed certificate is not silently pinned: verify its fingerprint when prompted. If a restart fails, use Server Admin > Export server troubleshooting report. Resolve the reported certificate/database/service issue. If needed, Restore previous configuration explicitly shows the profile and database SSL mode, saves the current file as the new recovery point and does not restart automatically. Review it, restart locally, then verify the client. Recovery is a single previous-file slot, not a full backup system. Preserve the recovery file before further saves. Database TLS setup never rewrites PostgreSQL or network configuration automatically.

Troubleshooting

Client Troubleshooting is one ON/OFF control per entry point. Stop saves the partial report; completion saves and opens the report and folder. Client reports are under %LOCALAPPDATA%\ITAuditFactory\MSP\Troubleshooting. Server Admin export is under the configured DataRoot\Troubleshooting and independently attempts to open the report and folder. It captures configured profile, service state, certificate metadata, live database TLS or a sanitized error type and allowlisted startup-failure fields. It excludes keys, passwords, raw settings, customer evidence and private-key bytes. It is not a complete Windows Event Log export. Review hostnames and certificate identity before sharing; reports are never uploaded automatically. Read the layers separately: API TLS; API authentication; database TLS; effective profile. TLS rejection is not proof of a bad API key. HTTP 401 can indicate a rejected key, signing mismatch or clock/nonce issue. HTTP 403 indicates authorization denial. Service Running alone does not establish a usable secure connection. Failed certificate generation/restart no longer prints unconditional success.

Windows Acceptance Matrix — Required Before Release

Run BUILD.cmd for both editions. The new SecurityReadiness behavior project exercises certificate hostname/IP SAN, missing private key, wrong hostname, placeholder rejection, trust import and atomic recovery. Existing security, vault, CMMC and diagnostics gates remain mandatory. The Professional guided-workflow parity gate remains a release blocker until its existing Windows evidence requirement is satisfied. For each OFF/Standard/Enhanced/High Assurance/DoD-Aligned: test fresh install, upgrade from 4.1.5, service restart, correct client profile, an older API-8 client, a non-admin role, and API/DB profile-layer display. Verify OFF works only with explicit HTTP and its troubleshooting report does not claim authenticated readiness. Verify Standard/Enhanced with CA-issued server certificates and VerifyFull database TLS. Verify mTLS profiles with valid, absent, expired, revoked and wrong-EKU client certificates. Verify DoD fails when its FIPS/CA/TLS gate is absent. Negative cases: wrong SAN; unknown CA; revoked certificate; unreachable revocation service; wrong database CA; plaintext database; unreachable database; expired API certificate; inaccessible private key for service account; missing EFS support; failed restart; unwritable diagnostic folder; missing report viewer. Confirm no silent downgrade, no API key sent in an HTTP retry, no stale green status and no secret-bearing export. Read-only test: hash server-settings.json and client settings before and after Test Server / Verify; files must not change and service PID must stay unchanged. Explicit ON/OFF is tested separately. Renewal: install a new certificate with the same SAN, update configured thumbprint and explicit pins where applicable, restart, retest all clients, then retire the old certificate. Test interrupted/failed settings write and explicit recovery. PowerShell commands (one line at a time, elevated on the server): sc.exe qc ITAuditFactoryMSPServer sc.exe queryex ITAuditFactoryMSPServer Get-FileHash 'C:\ProgramData\ITAF\MSP\server-settings.json' -Algorithm SHA256 Get-Item 'Cert:\LocalMachine\My\YOUR_THUMBPRINT' | Format-List Subject,Issuer,Thumbprint,NotBefore,NotAfter,HasPrivateKey curl.exe --fail --show-error https://YOUR_SAN_HOST:7443/api/health Do not use curl -k to establish acceptance. Enhanced/mTLS authenticated API tests should use the app, which supplies signing and client certificates. Record negotiated API TLS, current database observation, effective profile, build identity and report path for each test.

Public Contract / Compatibility

API version remains 8. Existing status fields and limited non-admin response remain. MSPAdmin status adds databaseTlsObserved, databaseTlsCheckedUtc, databaseTlsProtocol and databaseTlsCipher; capabilities adds databaseTlsObservation/securityPreflight. New configuration fields: DatabaseRootCertificate (PEM path or empty for Windows trust), DatabaseCheckCertificateRevocation (default true). Invalid security provisioning now returns 409 without saving its candidate; old clients must display the error instead of expecting automatic enablement. Signature/vault/file download contracts remain unchanged. Existing plaintext-DB secure-profile deployments must configure database TLS locally before this candidate starts successfully. Relying on .NET 8 APIs: X509Certificate2.MatchesHostname(string,bool,bool), certificate EKU/basic constraints extensions; File.Replace; Npgsql 8.0.9 NpgsqlConnectionStringBuilder.RootCertificate/CheckCertificateRevocation; ExecuteReaderAsync with CancellationToken. Shared SecurityReadiness.cs explicitly uses System.IO, System.Text.Json, System.Security.Cryptography.X509Certificates and Npgsql. Windows WPF/service/private-package compilation remains required.

Regression Token Changes

Current identity literals advance 4.1.5/C7 to 4.1.6/C8 in current metadata, launchers and contract predicates. Historical revision lookup entries remain. DatabaseTransportEncrypted method name remains but uses live observation rather than Require/VerifyCA/VerifyFull string comparisons. TestServer_Click remains; its PersistServerProfileAsync/AutoProvision calls and hardcoded All 6 success message are removed. Explicit apply retains AutoProvisionSecureCommunicationAsync. Removed automatic HTTP fallback and runtime cfg assignment before restart. Certificate/trust/success message text now reflects actual role and result. No vault/signing/throttle/nonce/CSV/zip/download tokens intentionally removed. Unified diffs are supplied for every changed source/build/test file.

Edition Scope

MSP owns server/API/PostgreSQL/mTLS controls. Professional remains local SQLite: no PostgreSQL controls or MSP listener are inserted. Its current release identity, shared diagnostics pipeline, documentation and existing parity gates are synchronized. Free delivery is the existing diagnostics adapter plus integration instructions; it is not a rebuilt Free app and does not establish Free UI/launcher parity. Current Free application source is needed for integration. No checks were removed merely because they were old. H7's removal of obsolete synthetic skipped rows is retained; active coverage remains required.

Primary Technical References

https://www.postgresql.org/docs/17/ssl-tcp.html https://www.postgresql.org/docs/17/monitoring-stats.html#PG-STAT-SSL-VIEW https://www.npgsql.org/doc/security.html https://www.npgsql.org/doc/connection-string-parameters.html https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.x509certificates.x509certificate2.matcheshostname?view=net-8.0

Upgrade Preflight Note

Setup now passes the configured DatabaseRootCertificate PEM to its libpq/psql check and restores PGSSLROOTCERT afterward. VerifyCA/VerifyFull upgrades should supply a CA PEM compatible with both Npgsql and libpq; Windows-only trust may not satisfy the libpq readiness check. For a legacy secure profile with DatabaseSslMode=Disable, complete database TLS configuration before running the upgrade. The C8 published Admin tool can be run locally against the existing DataRoot to configure and test it; do not change profiles or overwrite secrets merely to bypass preflight.

Email Support