This message attempts to summarise SSL changes in ICS in the last six
months, up to V8.33.  Most relate to OpenSSL 1.1.0, some are from the
long term wish list, which still contains unfinished jobs, and
information about using and buying SSL certificates. 

OpenSSL 1.1.0 Changes

New DLL names, different for 32 and 64-bit: libeay32.dll is now
libcrypto-1_1.dll and libcrypto-1_1-x64.dll, ssleay32.dll is now
libssl-1_1.dll and libssl-1_1-x64.dll.  ICS handles this, but see below
for new global variables that control how OpenSSL is loaded. 

Security fixes: the 3DES and RC4 cipher suites are no longer used, 40
and 56-bit suites are gone, and compression is disabled by default, to
mitigate attacks. No effect on ICS, unless you need to support ancient

Support added for ChaCha20-Poly1305 encryption cipher suites by Google,
which is lower overhead for mobile ARM devices which don't have the
benefit of Intel x86 processor instructions for AES.  This is not easy
to test, since OpenSSL prefers AES on Windows and Firefox does not
support it yet even on Android, Chrome/Windows prefers AES,  so need to
use the Chrome/Android browser.  Did manage to force the ICS HTTP
client sample to use ChaCha20-Poly1305 once... 

Add support for setting the minimum and maximum supported SSL or TLS
protocol.  Previously only a single protocol could be specified, or all
protocols (the badly named sslV23 version method), and then option
flags used to disable certain protocols to leave the ones you really
wanted. SslContext adds SslMinVersion and SslMaxVersion properties to
specify the minimum and maximum SSL/TLS versions supported from:
sslVerSSL3, sslVerTLS1, sslVerTLS1_1, sslVerTLS1_2, sslVerTLS1_3,
sslVerMax, note 1.3 is not yet supported.  Although introduced for
1.1.0, these properties have also been implemented for 1.0.1/1.0.2 by
internally using Options.  SslVersionMethod is ignored for 1.1.0 if
SslMinVersion > sslVerSSL3 or SslMaxVersion < sslVerMax. 

Windows versions now call the Windows API CryptGenRandom to get entropy
for random numbers.  Not sure if this effects ICS, which has it's own
seed functions used when creating private keys for certificates.   

Many DLL exported functions have new (clearer) names, ICS hides most of
these and still uses the old names for backward compatibility, ie
function SSLeay was renamed to OpenSSL_version_num and SSLeay_version
to OpenSSL_version (and many others).  

OpenSSL now self initialises and self cleans up, so more functions have
gone, this is handled internally by ICS.  

Many internal structures are now opaque so applications can not access
or corrupt them, with new exported functions provided to access these
structures which were previously done by macros.  ICS hides all this,

OpenSSL now uses a new threading API, and thread related functions have
gone.  ICS has a unit OverbyteIcsSslThrdLock that handles static thread
locks for SSL applications that used threads.  This unit is still
needed for OpenSSL 1.0.2 support, but now checks which OpenSSL version
is running and ignores threads if not required.  This unit is
normally dropped on a form, and SSlStaticLock.Enabled set true during
program initialisation, which will load the OpenSSL DLLs.  Doing this
early avoid the DLLs being loaded and unloaded when SslContexts are
created and destroyed.

There are changes to the default cipher list and ECC default curves,
but ICS already provides three recommended lists for servers,
sslCiphersMozillaSrvBack, sslCiphersMozillaSrvInter and
sslCiphersMozillaSrvHigh.  Clients generally don't specify ciphers. 

Added ASN.1 and EVP_PKEY methods for X25519.  No real idea about this,
something to do with ecliptic curve.  

Changes to ecliptic curves which are now always enabled. For ICS, 
SslECDHMethod is ignored for 1.1.0.

Lots of long obsolete SslOptions have been removed, ICS hides all this
by ignoring ones no longer supported.  SSL debugging now reports all
set options.  
OpenSSL adds support to enable cryptographic operations to be performed
asynchronously as long as an asynchronous capable engine is used. No
idea if such an engine is included.

The handshaking state machine code has been significantly refactored in
order to remove much duplication of code and solve issues with the old
code. ICS has a new function IcsSslGetState which returns
TSslHandshakeState that returns about 37 states rather than the seven
earlier versions supported.  This really only effects ICS SSL debugging
when more detailed state information is reported during handshaking. 

Added support for OCB (Offset Codebook Mode) and CCM (CBC-MAC Mode)
mode ciphers, an alternate to GCM (AES Galois Counter Mode) with AES.  

Added secure heap for storage of private keys (when possible).

Support for RFC6698/RFC7671 DANE TLSA peer authentication. Obtaining
and performing DNSSEC validation of TLSA records is the application's
responsibility.  Not sure about this. 

Support for Certificate Transparency with a new callback that adds the
checking, not supported by ICS yet, potentially very, very slow. 

General ICS SSL Changes

Added public variable GSSL_DLL_DIR, if set before OpenSSL is loaded,
will use only this directory for DLLs, must have trailing \.  Otherwise
Windows first looks in the application directory, then any public paths.

Added public variable GSSLEAY_DLL_IgnoreNew which should be set to TRUE
before OpenSSL is loaded if OpenSSL 1.1.0 should be ignored.  

Added public variable GSSL_BUFFER_SIZE defaults to 16384, previously
fixed at 4096, may improve SSL performance if larger. 
Existing public variables can be reported to check which version of
OpenSSL has been loaded, GSSLEAY_DLL_FileName shows the actual path and
name, GSSLEAY_DLL_FileVersion and GSSLEAY_DLL_FileDescription report
the DLL version information, ICS_OPENSSL_VERSION_NUMBER is the numeric
version and OpenSslVersion is the printable version and date. 

Note that applications using public SSL variables GSSLEAY_xxx will need
to add OverbyteIcsSSLEAY to Uses since they have been consolidated in a
single unit.  

Internally, the two units that load the two OpenSSL DLLs both used the
same public functions Load and WhichFailedToLoad, so these have been
changed to be unique for easier use, should not effect applications.  

GetFileVerInfo renamed IcsGetFileVerInfo to prevent conflicts with
other libraries. 

SslContext now allows SSL certificates, private keys, CA bundles and
DHParams to be loaded from strings instead of files, allowing
them to be saved or created in the application without using any
files.  New properties SslCertLines, SslPrivKeyLines, SslCALines
and SslDHParamLines allow PEM formatted certificates and keys to
be saved with the form or loaded as TStrings.  SslCertLines may
be a single certificate or a bundle including one or more
intermediates, but must not include the private key.  There
are new public methods LoadCertFromString, LoadPKeyFromString,
LoadCAFromString and LoadDHParamsFromString that can be used to
update the certificates after SslContext is initialised.  Note
currently keys and certificates loaded from files can not be accessed
as strings, planned. 

X509Base has new methods LoadFromText and PrivateKeyLoadFromText
that load a PEM SSL certificate and private key from strings.
A certificate may already be saved to a string by GetRawText.

SslContext has a new method SslGetAllCiphers that returns a multi
line list of the ciphers supported by OpenSSL although some may
be unusable if the correct protocols, EC and DHParams are not set.

TSslWSocket has a new method SslGetSupportedCiphers (Supported, Remote)
that returns a multi line list of ciphers. Supported=True is only for
1.1.0 and later and returns the actual ciphers available for the
session allowed by the protocols, EC and DHParams.  Remote=True for
list received by server from remote client, Remote=False is list
supported by client or server. Supported=False is list of all ciphers.
This is illustrated at
which uses the ICS web server and reports which ciphers both the client
and server support. 

Added sslDHParams2048 and sslDHParams4096 constants, the latter is used
as SslDHParamLines default so applications support DH and ECDH ciphers
without needed a DHParams file.  Still better to generate your own
DHParams and load them.

Added sslRootCACertsBundle function to OverbyteIcsSslX509Utils that
returns a Root CA Certificate Bundle of 29 PEM certificates extracted
from Windows 2012 R2 server by OverbyteIcsPemtool, assign this to
SslContext.SslCALines.Text to verify remote SSL certificates in client
applications, not for servers.  This is not used as a default to avoid
linking the list unless needed.

SSL debug logging has been improved by logging SSL certificate
subjects when loaded from lines, and logging ciphers when
SslContext is initialised.

Pending ICS SSL Changes

New public SSL variable to prevent the old OpenSSL DLLs being loaded.

Methods to return SSL context certificates and keys as strings. 

Use OpenSSL functions (X509_check_host) added on 1.0.2 and later to
check SSL certificate valid host names and IP addresses, currently done
in ICS code but certificates may include wild card and partial formats
we don't recognise. 

Simplify the loading of OpenSSL DLL exports to make maintenance easier
and maybe save space. 

Sign SSL certificate requests with a root certificate. 

Support ACME protocol for automated SSL certificate requesting and
installation, as provided by Let's Encrypt and possibly others. 

Use of certificates for SSL clients

Client SSL applications will usually work without any certificates
because all the encryption is initiated by the server.  

If a client needs to confirm the identity of a server, set
SslVerifyPeer=true and specify a certificate authority root bundle as
SslCAFile, SslCAPath or SslCALines, that contains the certificates used
to sign the server certificate or intermediate certificate, to confirm
they are trusted.  To permanently trust an unknown certificate, save it
to the CA file or path, or add it temporarily using TrustCert. Note
this method requires the application to keep the root bundle up to date
for new CAs, ICS includes some as sslRootCACertsBundle, but this is
only major CAs. 

Alternatively to confirm the identity of a server, use the Windows CA
Store that is continually updated by Microsoft, and also supports
checking for revoked certificates (can be very slow).  The
OverbyteIcsMsSslUtils unit contains these function, see sample
OverbyteIcsMsVerify for usage and demos.   

More rarely in high security operations, the server will need a client
to identify itself with a private certificate before granting access,
and this is where a client SSL certificate and private key are needed.
Client certificate checking is controlled by the server.  An
SslPassPhrase is only needed if the private key is password protected.

Use of certificates for SSL servers

Server SSL applications always require an SSL certificate and matching
private key because these control the SSL encryption.  The certificate
may also confirm the identity of the web site using the domain name and
often the company name. To be trusted by browsers and other
applications, the SSL certificate needs to be signed by a root
certificate available for local checking.  SSL certificates are often
signed by intermediate certificates rather than root certificates, and
these also need to sent by the server as part of a chain, the
intermediate will have been signed by a trusted root certificate.  

To configure an SSL server, SslCertFile or SslCertLines specify the SSL
certificate and optionally intermediate certificates in same file as a
bundle; SslPrivKeyFile or SslPrivKeyLines specify the private key used
to generate the certificate, which may be optionally password protected
by SslPassPhrase; and SslCAFile, SslCAPath or SslCALines specifies the
intermediate certificates if not in the certificate file.  Note servers
must NEVER have a CA root bundle with lots of certificates since these
will seriously confuse the server.   Also, SslDHParamFile or
SslDHParamLines should specify DHParams which are a secondary
encryption key used for some ciphers, ICS has default DHParams but
ideally applications should use unique DHParams.

Sometimes SSL certificates are withdrawn due to misuse such as being
stolen and appear in Certificate Revocation Lists (CRL) that are
published by SSL certificate issuers.  Such lists in PEM format may be
loaded by LoadCrlFromFile or LoadCrlFromPath.

Rarely, a server may want to check the identify of clients by
requesting a client SSL certificate by setting
SslVerifyPeerModes=SslVerifyMode_PEER.  AddClientCAFromFile and
SetClientCAListFromFile are used to set acceptable CAs For the client

Buying SSL Certificates

Although free SSL certificates are increasingly becoming available,
they mostly require server side software to automate the request
process, and these usually only support common web servers like IIS and
Apache, or large hosting companies.  So we mostly need to still buy SSL
certificates from companies such as Verisign, Thawte, GeoTrust or
RapidSSL.  Prices vary dramatically and are often cheaper from
resellers such as Servertastic than from the main issuing companies.  

Domain validated certificates can usually be validated automatically by
email and so are cheap.  Putting your company name on the certificate
increases the price substantially since the CA must check you have
authority to buy on behalf of the company and that it exists.  Extended
validated certificates where the company name appears in the address
bar are the most expensive and may require lawyers letters.  Wild card
certificates cost more, but protect multiple sub-domains.

To buy and install an SSL certificate for use with ICS and OpenSSL
follow these steps:

1 - Build the SSL demo project OverbyteIcsPemTool. Take Extras, Create
Certificate Requests, fill in the various fields (check other
certificates if uncertain, the Common Name is the domain to protect, ie and E-Mail should be an email address at the than
domain, ideally admin or administrator, 2048 bits. Click Create, and
specify two file names, first for the private key (mykey.pem) then the
certificate request file (myreq.pem).  The request can also be done
using OpenSSL command line arguments, or you can build it into your own

2 - Choose your SSL supplier and certificate type, at some point during
the ordering process you will be asked for the certificate request, so
open the PEM file you saved with a text editor and copy the base64
encoded block starting -BEGIN CERTIFICATE REQUEST- into the web form.
It should be decoded and displayed so you check it's correct.  The
private key is not needed for the certificate to be issued and should
never be emailed or sent to anyone.  At this point the validation
process starts as mentioned above, which might take hours or weeks to

3 - Eventually the SSL certificate should be issued, either by email or
made available to download from the supplier's web site.  It should be
in X.509 format in a base64 encoded block starting -BEGIN CERTIFICATE-
which should be saved as a PEM file (mycert.pem).  There should also be
an Intermediate CA certificate, with which your new certificate was
signed, which should also be saved as a file (mycacert.pem). This may
also be downloadable from the supplier as a bundle file  and should be
common to any certificates they issue, ie RapidSSL_CA_bundle.pem.

4 - The OverbyteIcsPemTool tool has a View PEM button that allows
examination of your new PEM files.  It's also good practice to check
and report the certificate when your server application starts,
checking the expiry date in particular, since without a valid
certificate and chain, the SSL server is useless.  

5 - The three PEM files now need to be attached to the SslContext
component in your application, with properties SslCertFile,
SslPrivKeyFile and SslCAFile, or copied into the application as text
blocks and loaded as lines. The request certificate file has no further
use, although you can re-use it to buy a replacement certificate in one
or two years time (or create another).


To unsubscribe or change your settings for TWSocket mailing list
please goto
Visit our website at

Reply via email to