TWSocketServer.IcsHosts

When originally designed TWSocketServer only supported listening on a single IP address and port, subsequently MultiListenSockets were added to listen on multiple IP addresses and ports, and TSslWSocketServer SSL support required a lot of extra code in the application to specify SSL certificates, protocols, ciphers and security using multiple SslContexts for multiple hosts.

The IcsHosts property is an alternate way for specifying multiple listeners for TSslWSocketServer that allows multiple hosts to be specified, each with one or two IP addresses and non-SSL and SSL port bindings, SSL certificates and private key (usually combined in a bundle), SSL context and security level, and other web server host related properties (used by higher level components). Each IcsHost has one or more HostNames to which it will recognise, that can share IP addresses. The same IP address can be used by two more IcsHosts with differing host names and other settings. IcsHosts include properties for use by other components, such as web, proxy and FTP servers, and for automatic SSL/TLS certificate ordering.

If IcsHosts is specified, TSslWSocketServer ignores existing bindings and SSL context, and creates new bindings and initializes an SSL context for each host checking and reporting all server certificate chains. To ease implementation, functions are provided to read IcsHosts and TWSocketServer from an INI file, or they may be specified through IDE form properties and saved by other means.

Note IcsHosts is only available for TSslWSocketServer, not TWSocketServer, but you don't need to use SSL for any Hosts.

HostNames	One or more domain Host Names to which the server will respond, comma separated list, no quotes. Host Names are matched initially against SSL Server Name Indication (SNI), or against the HTTP Host: header if no SSL or SNI for web and proxy servers. Note INI file reads as Hosts. Wild card host names are not allowed, but SNI may match a wild card certificate to an IcsHost.
HostEnabled	True or False if this IcsHost is enabled, NOTE INI file also reads Enabled if HostEnabled missing for backward compatibility.
BindIpAddr	Listening IP Address for this IcsHost, may be 0.0.0.0 for all IP Addresses, must exist. Multiple IcsHosts can use the same IP Address which will then be chosen from HostNames using SNI or Host: header.
BindIpAddr2	Optional second IP Address for this IcsHost, perhaps an IPv6 address.
BindNonPort	Optional non-SSL/TLS Port, may be blank or zero if only SSL is supported by IcsHost, usually 80 for HTTP, required if WellKnownPath specified for SSL automatic certificates.
BindSslPort	Optional SSL/TLS Port, may be blank or zero if SSL not supported by IcsHost, if used generally 443 for HTTPS, and several other SSL parameters are required. Either BindNonPort or BindSslPort is required.
HostTag	A short alphabetic name for the IcsHost, used variously in high level servers. The web application server uses HostTag in the AddGetHandler, AddPostHandler and AddGetAllowedPath to cause that handler to be matched. The proxy server uses HostTag to match source to one or more targets. When SocketServer creates a TWSocketClient for a new connection it sets the IcsHostIdx and HostTag properties to this value, also ServerAddr and ServerPort for the bindings.
Descr	Optional free description of the IcsHost, may be used for logging.
Proto	Optional high level protocol used by this IcsHost, used variously in servers. The proxy server uses HTTP, SMTP, POP3, etc.
ForwardProxy	Optional True/False used by the proxy server if this IcsHost is functioning as a Forward Proxy rather than a Reverse Proxy. A forward supports multiple targets according to the URL, while a reverse proxy generally ignores the URL and has a single fixed target, sometimes multiple fixed targets depending on the URL. See OverbyteIcsProxy.pas for more information.
WebDocDir	Optional default web document directory for this IcsHost, used by the web server.
WebTemplDir	Optional default web template directory for this IcsHost, used by the web server.
WebDefDoc	Optional default web document for this IcsHost, used by the web server.
WebLogDir	Optional web logging directory for this IcsHost, for use by web server applications (not by the server itself which has not ogging).
AuthSslCmd	Optional, if SSL/TLS should be initialised to support an AUTH SSL command or similar on an initial non-SSL connection. Used by FTP.
AuthForceSsl	Optional, if login only allowed once SSL/TLS negotiated so credentials never sent clear. Used by FTP.
SslLoadSource	Optional, specifies the source for loading SSL/TLS certificates. Defaults to CertLoadFile for PEM/PFX files where SslCert is a file name with path and extension. CertWinStoreMachine or CertWinStoreUser specifies load from the Windows Certificate Stores where HostNames[0] is the common name, part friendly name or a single host name to choose from the store, if there are duplicates the longest expiry data will be chosen. If the certificate name is a wildcard (*), this will also matched with any first node. Note only certificates with exportable private keys will be selected, and the application must have administrator rights to access the Local Machine store.
SslCert	Optional SSL server certificate file name, may be PEM, DER, PFX, P12, P7 format, optionally a bundle including a private key and one or more intermediate certificates. Required if BindSslPort set. If a private key is included, will use SslPassword for an encrypted file. Rather than a file name, may be an ASCII PEM string containing the certificate without any line endings. HostNames will be checked against those listed on the certificate, and a not warning given for mismatches so a single certificate needs to contain all the HostName, or wild cards * so they match. TSslWSocketServer has a method RecheckSslCerts that should be called from the server application periodically, at least once a day, which will check the certificate file time stamp and reload it if changed, issue warnings if it expires within CertExpireDays (default 30) and optionally order a new certificate, see CertSupplierProto below. Note if automatic certificate ordering is used, the file name in SslCert must conform to the format used by the TSslX509Certs component, with the host name having all dots replaced by underscore and * by x, then with suffix .pfx or -bundle.pem, ie test3_telecom-tariffs_co_uk-bundle.pem or test3_telecom-tariffs_co_uk.pfx.Important: if the SslCert file does not exist, ICS will create it signed by the ICS intermediate and root, so the server cam start, generally expecting it to be replaced automatically by one automatically ordered from Let's Encrypt or Google Trust Services.
SslKey	Optional SSL private key file name, PEM format, will use SslPassword for an encrypted file. Ignored if SslCert was a bundle file with a private key. Note all SSL servers need an SSL certificate and matching private key to function, and these are checked before the server will start. Rather than a file name, may be an ASCII PEM string containing the private key without any line endings.
SslInter	Optional SSL intermediate certificate bundle file name, PEM, DER, P12 or P7 format. Ignored if SslCert was a bundle with intermediate certificates. The SSL certificate chains is checked to ensure the server certificate is signed by an intermediate or trusted root certificate, and likewise the intermediate(s). The TSslWSocketServer RootCA property specifies a PEM bundle file containing the trusted root certificates, if not specified an internal bundle of about 36 major root certificates is used.
SslPassword	Optional password for the SSL private key, if encrypted. Note this is clear text in the INI file, steps should be taken to read an encrypted password if security is required. Beware most PFX/P12 bundles need a password, since Windows will not import them without a password.
SslSrvSecurity	Optional SSL server security level, that sets protocol, cipher and SslSecLevel according to eight levels from type TSslSrvSecurity: sslSrvSecNone, sslSrvSecSsl3, sslSrvSecBack, sslSrvSecInter, sslSrvSecInterFS, sslSrvSecHigh, sslSrvSecHigh128, sslSrvSecHigh192. Details of each are in the OverbyteIcsSSLEAY.pas unit. Beware the server may not start, ie High128 requires an RSA private key length greater than the 2,048 bits commonly used. If not specified, sslSrvSecDefault is used which is currently sslSrvSecHigh meaning TLSv1.2 or later with forward security ciphers.
CliCertMethod	Optional, defaults to sslCliCertNone, allows host to request a client SSL certificate from the browser or remote application, as type TSslCliCertMethod, for sslCliCertOptional or sslCliCertRequire. Require will close the connection unless a valid certificate is received and validated against RootCA. Beware requesting a client certificate usually causes the browser to prompt the user for which certificate to send which can be obtrusive.
SslCipherList12	Optional, list of ciphers the server will accept for TLSv1.2 connections, see constant sslCiphersMozillaSrvTLS12 for example.
SslCipherList13	Optional, list of ciphers the server will accept for TLSv1.3 connections, see constant sslCipherSuitesTLS13 for example.
SslCryptoGroups	Optional, list of crypto groups the server will accept, see constant sslCryptoGroupsDef for example.
SslRawKeyFile	Optional, the private key file for Raw Public Key (RPK) authentication instead of using an X509 certificate. RPK maybe used for client or server authentication. NOTE RPK not finished yet
WellKnownPath	Optional, full file directory path for .Well-Known web URLs, used by the web and proxy servers for automated SSL certificates.
WebRedirectURL	Optional, a web server redirection URL, used in the proxy server to redirect HTTP connections to HTTPS, if WebRedirectStat is none zero. Not currently used by the web server, but web server applications can add event code to use these values, see event SslHttpAppSrv1GetDocument in OverbyteIcsSslMultiWebServ1.pas. Or more intelligent redirection could be implemented like changing http:// to https://.
WebRedirectStat	Optional, a web server redirection status code, 301, 302, 307 or 308 depending on reason.
CertSupplierProto	Optional, if SSL X509 certificates are to be automatically ordered, downloaded and installed, specifies the Supplier and Protocol to be used as type TSupplierProto. Currently supports SuppProtoNone, SuppProtoAcmeV2 and SuppProtoCertCentre. Ignored unless TSslWSocketServer property SslCertAutoOrder is True. Note any SSL certificates ordered will use all HostNames so must support multiple Subject Alternative Names if more than one host is specified. Note wild card certificates can not currently be ordered by IcsHosts, but can be done using TSslX509Certs. Automatic certificate ordering is triggered by calling the server method RecheckSslCerts after the server has started listening, which checks all certificates and chains for expiry within CertExpireDays (default 30) and will then order a new certificate for any that fail, including certificate file missing. The server application should call RecheckSslCerts at least once a day, but it can be more often to give more chances to check for ordering problems. The TSslX509Certs has an internal timer that checks for order completion and calls an onNewCert event when the new certificate is ready, this event should call RecheckSslCerts again which will find the new certificate file and load it into SslContext.
CertDirWork	Optional, ignored if CertSupplierProto is not SuppProtoNone. For V9.5 and later, not needed since accounts are saved by SupplierName, generally in C:\ProgramData\ICS-Acme-Accounts. For earlier versions, specifies the Certificate Database Working Directory, in which an account that matches CertSupplierProto should already have been created.
CSupplierTitle	Optional, defaults to SrvSupplierTitle in TSslWSocketServer so generally not needed in IcsHosts. Supplier Account Title, used to look up AcmeSupplier and CertDirWork from ics-acme-accounts.db.
CAcmeSupplier	Optional, defaults to SrvAcmeSupplier in TSslWSocketServer so generally not needed in IcsHosts. Specifies one of several ACME suppliers of type TAcmeSupplier: AcmeLetsEncrypt, AcmeLetsEncryptTest, AcmeZeroSSL, AcmeGoogle, AcmeGoogleTest, AcmeDigicert, AcmeDigicertTest, AcmeSslcomRSA, AcmeSslcomECC. The names with test specify use the suppliers testing or staging servers that generally issue fake certificates for testing and don't care about errors.
CAcmeCertProfile	Optional, defaults to SrvAcmeCertProfile in TSslWSocketServer so generally not needed in IcsHosts. Currently only used by Let's Encrypt to specify certificate profile: classic, tlsserver or shortlived (seven days).
AcmeCertValidity	Optional, defaults to SrvAcmeCertValidity in TSslWSocketServer so generally not needed in IcsHosts. Currently Google only, specifies the certificate expiry days, default 90, seven supported.
CertChallenge	Optional, defaults to SrvCertChallenge in TSslWSocketServer so generally not needed in IcsHosts. Specifies the Challenge Type as TChallengeType, used by the supplier to check the domain names for the certificate resolve to this server. Currently supports ChallNone, ChallFileUNC, ChallDNS and ChallEmail. Note that DNS require extra code in the server application to update DNS records. ChallFileUNC means the server will create a special file in the .Well-Known directory which the supplier will read for each different HostName to confirm they can all be accessed from the public internet, this usually happens within a few seconds for domain validated certificates. ChallEmail means that manual validation of the host names will be needed, with notification by email when ready, but the component will periodically check with the supplier to see when the order is completed and can be downloaded and installed.
CertPKeyType	Optional, defaults to SrvCertPKeyType in TSslWSocketServer so generally not needed in IcsHosts. Specifies the new SSL certificate Private Key algorithm and key length as type TSslPrivKeyType. Typically use PrivKeyRsa2048, PrivKeyRsa3072, PrivKeyRsa4096, PrivKeyECsecp256, PrivKeyECsecp384, PrivKeyECsecp512 or PrivKeyEd25519, although the supplier may reject any of them. Beware RSA keys longer than 4,096 bits can take many minute to generate blocking the server.
CertSignDigest	Optional, defaults to SrvCertSignDigest in TSslWSocketServer so generally not needed in IcsHosts. Specifies the new SSL certificate request signing digest as type TEvpDigest. Typically use Digest_sha256, Digest_sha384 or Digest_sha512, there are now SHA3 options but unlikely to be supported by suppliers yet.

Example from \Samples\Delphi\SslInternet\OverbyteIcsSslMultiWebServ.ini which can be read using the functions IcsLoadTHttpAppSrvFromIni and IcsLoadIcsHostsFromIni.

[WebAppServer]
SslCertAutoOrder=True
CertExpireDays=30
X509ProxyURL=
SrvSupplierTitle=LetsEncrypt-New
SrvAcmeSupplier=AcmeLetsEncrypt
SrvAcmeCertProfile=tlsserver
SrvAcmeCertValidity=90
SrvCertChallenge=ChallAlpnApp
SrvCertPKeyType=PrivKeyECsecp256
SrvCertSignDigest=Digest_sha256

[Host4]
Hosts=test7.ftptest.org,test7.ftptest.org.uk,test7.ftptest.co.uk
HostTag=HTTP-FTPTEST
Desc=test7-LetsEncrypt
BindIpAddr=192.168.1.123
BindNonPort=80
BindSslPort=443
HostEnabled=False
SslSecLevel=sslSrvSecInterFS
WellKnownPath=c:\websites\well-known\
WebRedirectURL=https://www.telecom-tariffs.co.uk/
WebRedirectStat=301
SslCert=c:\certificates\local\test7_ftptest_org.pfx
SslPassword=password
CliCertMethod=sslCliCertNone
CertSupplierProto=SuppProtoAcmeV2

Once IcsHosts have been validated, a number of read only properties are available with more information about the IcsHost from the certificate and bindings, that may be usefully logged for configuration and error checking purposes.

SslCtx	TSslContext component used by IcsHost.
HostNameTot	Number of items in HostNames TStrings.
DisplayName	IcsHost display name, variously using HostTag, Descr, and bind IP addresses and ports.
CertDomains	Comma separated list of SSL certificate host names from Subject aternate Names field.
CertInfo	A long multiple line text block describing all the main fields of one or more SSL certificates in the chain including subject, issuer, expiry, public key type and signature method.
BindInfo	List of one or more IP addresses and ports.
CertExiry	SSL certificate expiry date and time, as TDateTime.
CertFStamp	Unix file time stamp for SSL server certificate, to check if changed.
InterFStamp	Unix file time stamp for SSL intermediate certificates, to check if changed.
CertErrs	Description of any errors found in the SSL certificate chain during validation.
CertValRes	SSL certificate chain validation result as type TChainResult, chainOK, chainFail, chainWarn, chainNone.
BindIdxNone	MultiListenIdx for first IP address, non-SSL.
BindIdxSsl	MultiListenIdx for first IP address, SSL.
BindIdx2None	MultiListenIdx for second IP address, non-SSL.
BindIdx2Ssl	MultiListenIdx for second IP address, SSL.
BindSrvPort	Actual listening port, useful if Port=0 for dynamic port.
RenewalDays	For automatically issued certificates, how many days before expiry the supplier recommends renewing the certificate, generally two thirds of the way through duration, but could be sooner if the certificate is cancelled or revoked. Internally, this tells ICS when to order a new certificate.
RenewRetryDT	For automatically issued certificates, when the supplier recommends next checking the renew dates, they may change. Usually every six to 24 hours.
RenewCheckDT	For automatically issued certificates, when last checkedrenewal dates.