horse-ssl-tls

Horse SSL / TLS (HTTPS)

In production environments, always encrypt data in transit using SSL/TLS. Depending on the transport provider you select, the configuration for HTTPS differs.

---

1. Native HTTPS with HTTP.sys (Windows Kernel-Mode)

When using the native Horse.Provider.HTTPsys provider on Windows, the SSL handshake is handled entirely by the operating system kernel.

Step 1: Bind SSL Cert in Windows

You do not configure certificates inside your Delphi code. Instead, bind your SSL certificate (using its thumbprint) to the target port using the Windows command line tool netsh (requires Administrator privileges):

netsh http add sslcert ipport=0.0.0.0:443 certhash=YOUR_CERT_THUMBPRINT appid={YOUR-APP-GUID}

Step 2: Configure HTTP.sys in Delphi

Just start the Horse server normally. HTTP.sys will route HTTPS traffic on the bound port to your application automatically:

program SecureAPI;

{$APPTYPE CONSOLE}

uses
  Horse,
  Horse.Provider.HTTPsys;

begin
  THorse.Get('/ping',
    procedure(Req: THorseRequest; Res: THorseResponse; Next: TProc)
    begin
      Res.Send('pong');
    end);

  // Starts the server. HTTP.sys routes both HTTP/HTTPS automatically depending on OS bindings.
  THorse.Listen(443);
end.

---

2. SSL/TLS with OverbyteICS Provider (ICS)

The horse-provider-ics provider handles OpenSSL 1.1.1 / 3.x / 4.x directly within the application process.

Configuration

Load your certificate .pem or .crt files and private key files during initialization:

uses
  Horse,
  Horse.Provider.ICS;

begin
  // Set up SSL certificate paths and properties fluently
  THorse.Provider.ICS.SSLSecured := True;
  THorse.Provider.ICS.SSLCertFile := 'C:\certs\server.crt';
  THorse.Provider.ICS.SSLPrivateKeyFile := 'C:\certs\server.key';
  THorse.Provider.ICS.SSLPassword := 'my_private_key_password';
  
  // Optionally enable Server-side Mutual TLS (mTLS)
  THorse.Provider.ICS.SSLVerifyPeer := True;
  THorse.Provider.ICS.SSLCACertFile := 'C:\certs\ca.crt'; // CA certificate to verify clients

  THorse.Get('/ping',
    procedure(Req: THorseRequest; Res: THorseResponse; Next: TProc)
    begin
      Res.Send('pong');
    end);

  THorse.Listen(8443);
end.