Atlas Knowledge Base
Dashboard
Certificates

Certificates

APIEngine serves its API over HTTPS. On Windows, IIS presents the certificate bound to the site's HTTPS binding. On Linux, Apache terminates TLS in front of APIEngine and presents the certificate named in its vhost.

What APIEngine needs

RequirementDetail
Server certificateIssued for each host name clients use, for example api.example.com. A wildcard certificate such as *.example.com covers one extra label: api.example.com, but not test.api.example.com
Private keyThe certificate must be imported with its private key. Certificates without one are not offered by the installer and cannot be bound
ValidityInside its valid-from and expiry dates
TrustIssued by a certificate authority the clients trust. A self-signed certificate works only on computers that have been told to trust it
Store (Windows)LocalMachine\My (Personal) or LocalMachine\WebHosting (Web Hosting) on the APIEngine server

The application pool identity needs no access to the private key. IIS (http.sys) serves the certificate from the machine store.

Choosing a certificate during install (Windows)

The installer lists every usable certificate in LocalMachine\My and LocalMachine\WebHosting: one with a private key that is inside its validity dates. Each row shows the subject, store, issuer and expiry. Certificates that cover the host name entered for the site are listed first, trusted certificates before untrusted ones, then the latest expiry first. The default is the first trusted certificate that covers the host name.

AnswerResult
A certificate numberThe certificate is bound to the HTTPS binding from its own store
No certificate, then Yes to "Create a self-signed certificate for this host and bind it to https?"A self-signed certificate is created and bound (see below)
No certificate, and No to the self-signed offerNo HTTPS binding is created. The installer prints No https binding was created - there is no certificate to bind to one. and the site answers only on the local HTTP port 127.0.0.1:8080

When another IIS site already uses the HTTPS port, the APIEngine binding shares the port with a host name and Server Name Indication (SNI), and its certificate is bound for that host name only.

After binding, the installer reads the binding back and checks that HTTPS answers. A failed TLS handshake is reported as a failed check at the end of the run, with the thumbprint and the fix.

Unattended installs

OptionResult
-CertThumbprint <thumbprint>Binds that certificate. It is looked up in LocalMachine\My, then LocalMachine\WebHosting
-Unattended with no -CertThumbprintBinds the one trusted certificate covering the host name. With none, with several, or with no host name, a self-signed certificate is created and bound

Self-signed certificate

The installer creates the certificate in LocalMachine\My with the friendly name APIEngine HTTPS (<site name>), valid for five years. It covers the site's host name, the server's computer name, its fully qualified name and localhost. The installer adds a copy to LocalMachine\Root on the APIEngine server, so a browser on the server opens the site without a warning. Running the installer again reuses that certificate while it is valid, and removes older ones it created for the same site.

A self-signed certificate suits testing and internal servers. Every client computer that calls APIEngine must trust it, otherwise the client refuses the connection or shows a certificate warning. To trust it on a client, export it on the server and import it into the client's Trusted Root store. On the APIEngine server:

Export-Certificate -Cert Cert:\LocalMachine\My\<thumbprint> -FilePath C:\Temp\apiengine.cer

On each client, from PowerShell as Administrator:

Import-Certificate -FilePath C:\Temp\apiengine.cer -CertStoreLocation Cert:\LocalMachine\Root

For servers that clients outside your network call, use a certificate from a public certificate authority.

Binding or changing the certificate after install (Windows)

Importing the certificate

Import the certificate, with its private key, into the Local Computer Personal store. From PowerShell as Administrator:

Import-PfxCertificate -FilePath C:\Temp\api.example.com.pfx -CertStoreLocation Cert:\LocalMachine\My -Password (Read-Host -AsSecureString "PFX password")
Get-ChildItem Cert:\LocalMachine\My | Select-Object Thumbprint, Subject, NotAfter

Import into LocalMachine (Local Computer). A certificate in the current user's store cannot be bound to an IIS site.

IIS Manager

  1. Open IIS Manager and select the site, for example APIEngine-default.
  2. Select Bindings in the Actions pane.
  3. Select the https binding and select Edit. If the site has no https binding, select Add and set Type to https, Port to 443 and Host name to the name clients use.
  4. Tick Require Server Name Indication when another site on the server uses the same port.
  5. Pick the certificate in SSL certificate and select OK.
  6. Recycle the site's application pool.
IMAGE NEEDED - IIS Edit Site Binding dialog Shows: the Edit Site Binding dialog for an APIEngine site with Type https, Port 443, Host name api.example.com, Require Server Name Indication ticked and a certificate selected in SSL certificate Capture: IIS Manager, select the APIEngine site, Bindings, select the https row, Edit Crop: the dialog only, about 500x400 px

The local HTTP binding on 127.0.0.1:8080 needs no certificate. Leave it in place: it serves the checks below.

Re-running the installer

An upgrade asks Keep every current setting (quick install)?. Answer Y to keep the bound certificate. Answer N to walk through the HTTPS port, host name, local HTTP port and certificate: the certificate list opens with the current certificate as the default, and 0 keeps it. The installer rebinds the site and puts the old bindings back if the change fails. When the HTTPS port moves, the certificate entry on the old port is removed.

Command line check

The installer prints the thumbprint in its plan and in any failed certificate check. To see which certificate http.sys holds for the site, use the first form for a binding without a host name and the second for a binding with a host name and SNI:

netsh http show sslcert ipport=0.0.0.0:443
netsh http show sslcert hostnameport=api.example.com:443

Certificate Hash is the bound thumbprint and Certificate Store Name is MY or WebHosting. To bind a thumbprint from the command line when IIS Manager is not available:

netsh http add sslcert ipport=0.0.0.0:443 certhash=<thumbprint> certstorename=MY appid={<GUID>}
netsh http add sslcert hostnameport=api.example.com:443 certhash=<thumbprint> certstorename=MY appid={<GUID>}

appid takes any GUID; New-Guid generates one. Use certstorename=WebHosting for a certificate in the Web Hosting store. If an entry already exists for the address, remove it first with netsh http delete sslcert ipport=0.0.0.0:443 (or hostnameport=api.example.com:443).

Renewing or replacing a certificate (Windows)

  1. Import the new certificate, with its private key, into LocalMachine\My.
  2. Bind it to the site's https binding in IIS Manager (steps above), or re-run the installer and answer N to the quick-install question.
  3. Recycle the site's application pool.
  4. Check from a client (below), then remove the old certificate from the store.

Certificates the installer created are not removed by the uninstaller. Remove them from LocalMachine\My and LocalMachine\Root by their friendly name APIEngine HTTPS (<site name>) when no longer needed.

Linux

APIEngine listens on plain HTTP on the loopback address only (127.0.0.1:5080 by default). Apache terminates TLS and forwards requests to it.

On a fresh install, install.sh writes the vhost <unit name>.conf (apiengine.conf by default) to /etc/apache2/sites-available on Debian and Ubuntu, or /etc/httpd/conf.d on Red Hat family systems. The vhost listens on port 443 and points at the system's self-signed placeholder certificate:

SSLCertificateFile /etc/ssl/certs/ssl-cert-snakeoil.pem
SSLCertificateKeyFile /etc/ssl/private/ssl-cert-snakeoil.key

The installer warns that the placeholder must be replaced before serving traffic. It never changes certificates. An upgrade leaves an existing vhost as it is.

To bind the server's certificate, or to renew it:

  1. Copy the certificate and its private key to the server.
  2. Point SSLCertificateFile and SSLCertificateKeyFile in the vhost at them.
  3. Check the configuration with apachectl -t (apache2ctl -t on Debian and Ubuntu).
  4. Reload Apache: systemctl reload apache2 (Debian and Ubuntu) or systemctl reload httpd.

Apache must have the ssl module enabled. The installer stops with exit code 13 when it is missing.

v95 and earlier

Certificate binding for the .NET Framework 4.8 line is covered on Installing v95 and earlier.

Checking HTTPS

WhereRequestHealthy result
A client computerhttps://api.example.com/api/v1/ping{"result":true}, with no certificate warning
A client computerhttps://api.example.com/api/v1/diagnostic/version{"result":"<version>"}
The Windows serverhttp://127.0.0.1:8080/api/v1/ping{"result":true}
The Linux serverhttp://127.0.0.1:5080/api/v1/ping{"result":true}

The loopback addresses answer on the server only and need no certificate, so they separate an APIEngine problem from a certificate problem. Ping calls the database and fails until the data server is saved on the Settings page; the version request answers before that.

For HTTPS errors after an install, see APIEngine will not start on Troubleshooting.

Related Articles

Installing & Uninstalling

Troubleshooting

Start Here

APIEngine - Install (v95 and earlier)

SBN Tunnel Security Architecture

Was this helpful?