Let's Encrypt for Pohoda mServer (Stormware)
How to secure HTTPS communication with the Stormware Pohoda mServer using a Let's Encrypt certificate β including automatic renewal, with no manual re-selecting every three months.
How mServer handles HTTPS
Pohoda mServer is an HTTP server built into pohoda.exe. There are two ways to give it HTTPS:
- Windows http.sys (the same stack as IIS) β the certificate is not referenced by a file path but by its thumbprint in the
LocalMachine\Mystore; the port binding is done withnetsh http add sslcert. In the Pohoda GUI (DatabΓ‘ze β POHODA mServer β HTTPS tab) you then pick from the certificates already present in the store. - PEM files β some mServer versions want the certificate and private key as
.pemfiles (the HTTPS dialog takes paths to the certificate and the key).
That is why the wizard offers two modes for mServer in step 3 (Server).
Two modes: store vs pem
| store (recommended) | pem | |
|---|---|---|
| Where the certificate lives | only in the Windows Certificate Store (LocalMachine\My) |
in the store and as files in C:\admin\pohoda-cert |
| Private key on disk | no β stays in the store, non-exportable | yes (mserver-key.pem, mserver.pem) |
| Port binding | netsh http add sslcert by thumbprint (deploy-mserver.ps1) |
you enter the PEM file paths in Pohoda |
| After renewal | the hook rebinds the port to the new thumbprint | the hook re-exports the PEM files |
PrivateKeyExportable in win-acme settings.json |
off | on (only in this mode) |
| When to choose | whenever your mServer version can pick a certificate from the store | only when mServer must read files |
Rule of thumb: start with store. Use pem only when mServer really requires files β every private key on disk is one more thing to guard.
When Let's Encrypt helps (and when it does not)
| Your situation | What to do |
|---|---|
mServer has a public domain (e.g. pohoda.company.com) and port 80 reachable from the internet |
β HTTP-01 standalone works |
| Public domain, but port 80 closed (firewall/NAT) | β DNS-01 (Cloudflare or manual) |
mServer is only on LAN/VPN, you use pohoda.company.local or an IP address |
β Let's Encrypt will not sign it. Either: a) assign a public domain and use DNS-01, b) run your own internal CA (mkcert, step-ca) |
The domain pohoda.company.com points to an internal IP (split-horizon DNS) |
β DNS-01 works β Let's Encrypt validates via a DNS TXT record and never needs to reach the server |
Note: If you only use an internal IP/name, the recommended path is split-horizon DNS β register pohoda.company.com as a public A record pointing to the private IP. That is enough for DNS-01 validation and nobody can physically reach mServer from outside.
Steps (DNS-01 via Cloudflare β the recommended path)
A public domain (e.g.
pohoda.company.com) in Cloudflare DNS (split-horizon is fine).A Cloudflare API token with
Zone:DNS:Edit+Zone:Zone:Readfor this zone only. It is not entered into the wizard βissue.ps1asks for it on the server.In the wizard: step 3 β OS Windows Server, web server Pohoda mServer, mServer port, mode
store/pem; step 4 β DNS-01 Cloudflare (optionally enable "Dry run first" β the first run goes against the staging server with--test); step 6 β download the ZIP.On the server, PowerShell as Administrator, in the folder with the extracted scripts:
Unblock-File .\*.ps1 # files downloaded from the internet are blocked .\install.ps1 # downloads win-acme + the Cloudflare plugin from the same release, # verifies the Authenticode signature of wacs.exe, adjusts settings.json .\issue.ps1 # asks for the CF token, issues the cert into LocalMachine\My, # copies and registers the renewal hook .\deploy-mserver.ps1 # store mode: netsh binding of the port to the thumbprint .\export-pem.ps1 # pem mode: PEM files into C:\admin\pohoda-cert .\verify.ps1 # checks the certificate on the port + the renewal Scheduled Taskinstall.ps1forces TLS 1.2 for downloads and can pin a specific release:.\install.ps1 -Version v2.2.9.1701. If the signature check ofwacs.exefails, the script stops β do not bypass it (see pitfalls below).In Pohoda: DatabΓ‘ze β POHODA mServer β instance β Upravit (Edit) β HTTPS tab:
store: pick the certificate from the list (identify it by the thumbprint the script printed),pem: enter the pathsC:\admin\pohoda-cert\mserver-cert.pem+C:\admin\pohoda-cert\mserver-key.pem(or the combinedmserver.pemfor both),- Save β restart the instance.
Verify from outside (commands below) and put the
.icsreminder from the ZIP into your calendar.
Renewal (renewal hook)
A Let's Encrypt certificate is valid for 90 days. win-acme creates a Scheduled Task (win-acme renew (acme-v02.api.letsencrypt.org)) that renews after roughly 60 days. The thumbprint changes on renewal β without a further step http.sys would keep serving the old certificate and the PEM files would go stale.
That is why issue.ps1:
- copies
renewal-hook-mserver.ps1toC:\Program Files\win-acme\Scripts\renewal-hook-mserver.ps1, - registers it with win-acme via
--installation script --script β¦ --scriptparameters "-NewCertThumbprint '{CertThumbprint}' β¦".
win-acme runs the hook on the first issuance and after every renewal. The hook:
store: deletes the oldnetshbinding and adds a new one with the current thumbprint (certstorename=MY),pem: re-exportsmserver-cert.pem(fullchain),mserver-key.pemandmserver.pemintoC:\admin\pohoda-certβ the directory ACL is locked before anything is written,- optionally restarts the mServer instance (
pohoda.exe /http stop|start "Instance") β just uncomment the lines at the end of the hook.
Older versions of this guide mentioned a script called
PohodaMServerRebind.ps1β it does not exist. The correct name isrenewal-hook-mserver.ps1and it must sit next toissue.ps1(otherwiseissue.ps1stops with an error before it could create a renewal with a broken hook).
Rehearsal: .\renew-test.ps1 (wacs.exe --renew --test) and & 'C:\Program Files\win-acme\wacs.exe' --list β the renewal must show the installation script.
C:\admin\pohoda-cert and permissions (pem mode)
Both
export-pem.ps1and the hook create the directory and first set its ACL toSYSTEMandAdministratorsonly (icacls β¦ /inheritance:r /grant:r "SYSTEM:(OI)(CI)F" "Administrators:(OI)(CI)F"), and only then write the PEM files. The key is never readable by other accounts, not even for a moment.mServer typically runs as
SYSTEM(service) or under the logged-in administrator β nothing to do then.If mServer runs under its own service account, grant it read access:
icacls C:\admin\pohoda-cert /grant "DOMAIN\pohoda-svc:(OI)(CI)(R)"If the account loses access after a renewal (the hook re-applies permissions), add the same line to the end of
C:\Program Files\win-acme\Scripts\renewal-hook-mserver.ps1.mserver-cert.pemcontains the fullchain (leaf + intermediate, without the root CA) β without the intermediate most clients would reject the certificate.
Certificates in the store are never deleted automatically
issue.ps1 no longer removes anything from LocalMachine\My. Every issuance/renewal adds a new certificate; deploy-mserver.ps1, export-pem.ps1 and the hook always pick the newest Let's Encrypt certificate for the domain (in pem mode additionally only one with an exportable key). Old certificates do no harm, they only take up space β cleanup is up to you:
# First look at what would be deleted
Get-ChildItem Cert:\LocalMachine\My |
Where-Object { $_.Issuer -like "*Let's Encrypt*" -and $_.NotAfter -lt (Get-Date) } |
Format-Table Thumbprint, Subject, NotAfter
# β¦and only then (expired ones only)
Get-ChildItem Cert:\LocalMachine\My |
Where-Object { $_.Issuer -like "*Let's Encrypt*" -and $_.NotAfter -lt (Get-Date) } |
Remove-Item
Switching store β pem after issuance: the key of the existing certificate is not exportable. Generate the scripts again in pem mode, run install.ps1 (turns on PrivateKeyExportable) and issue.ps1; export-pem.ps1 then uses the newest certificate with an exportable key. Should win-acme reuse a cached certificate and the export keep failing, force a fresh issuance: & 'C:\Program Files\win-acme\wacs.exe' --renew --force (mind the rate limits).
Verification
# Let's Encrypt certificates in LocalMachine\My (HasPrivateKey must be True)
Get-ChildItem Cert:\LocalMachine\My | Where-Object { $_.Issuer -like "*Let's Encrypt*" } |
Format-Table Thumbprint, Subject, NotAfter, HasPrivateKey
# Current SSL binding of the port (store mode) β Certificate Hash = thumbprint of the new cert
netsh http show sslcert ipport=0.0.0.0:444
# The port is open and answers
Test-NetConnection pohoda.company.com -Port 444
Invoke-WebRequest -Uri "https://pohoda.company.com:444/" -UseBasicParsing | Select-Object StatusCode
# Chain: must print 2+ certificates (leaf + intermediate); openssl ships e.g. with Git for Windows
'' | openssl s_client -connect pohoda.company.com:444 -servername pohoda.company.com -showcerts
# Renewal
& 'C:\Program Files\win-acme\wacs.exe' --list
Get-ScheduledTask -TaskName 'win-acme*' | Get-ScheduledTaskInfo |
Format-List TaskName, LastRunTime, LastTaskResult, NextRunTime
# From the Pohoda command line
& 'C:\Program Files\STORMWARE\POHODA\Pohoda.exe' /http list
& 'C:\Program Files\STORMWARE\POHODA\Pohoda.exe' /http start "InstanceName"
verify.ps1 from the ZIP does all of this in one go. General procedures (openssl, curl, SSL Labs, rate limits, CAAβ¦) are in troubleshooting.
Known pitfalls
- Cert in
CurrentUser\Myinstead ofLocalMachine\Myβ neithernetshnor Pohoda will find it. The scripts store into Local Machine; watch out when importing by hand. - Cert without a private key β
netsherror 1312 ("A specified logon session does not exist"). CheckHasPrivateKey(above); if it isFalse, runissue.ps1again. - "Cannot export non-exportable private key" (
export-pem.ps1) β the certificate was created instoremode (or with older settings).PrivateKeyExportableis only enabled inpemmode β see thestore β pemswitch above. - ECDSA key β
export-pem.ps1supports RSA only (PKCS#1). Keep win-acme's default RSA key if you usepemmode. - The port is already used by another application (typically IIS on
:443) β choose a different port for mServer (444, 8443) both in the HTTPS tab and in the wizard.netsh http show sslcertshows who holds the port. - Firewall β nobody lets the mServer port in:
New-NetFirewallRule -DisplayName "Pohoda mServer HTTPS" -Direction Inbound -LocalPort 444 -Protocol TCP -Action Allow - PowerShell refuses to run the downloaded scripts β
Unblock-File .\*.ps1and, if needed,Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass. install.ps1reports an invalid Authenticode signature ofwacs.exeβ the downloaded archive is corrupted or something on the way modified it (TLS-inspecting proxy, antivirus). Do not bypass it; download the release manually from github.com/win-acme/win-acme/releases and verify withGet-AuthenticodeSignature .\wacs.exe.- Cloudflare plugin does not match the
wacs.exeversion ("Unable to find validation plugin cloudflare" / assembly load error) β the plugin must come from the same release aswacs.exe.install.ps1takes care of that; after a manual win-acme update runinstall.ps1again (optionally with-Version). - Hook not registered (older installations) β
wacs.exe --listshows no installation script β runissue.ps1again (the renewal is overwritten). - PEM without the intermediate certificate (fullchain) β clients without AIA fetching reject the cert.
openssl s_client β¦ -showcertsabove must show at least 2 certificates. - mServer runs under its own service account β it lacks read access to
C:\admin\pohoda-cert, see the permissions section above. - Let's Encrypt rate limits on repeated attempts β "Dry run first" (
--test), then for real. Details in troubleshooting.