README

DelphiLibOpenSSL

A Delphi unit that provides complete static bindings to OpenSSL. Instead of dynamically loading OpenSSL DLLs at runtime, this project compiles OpenSSL C source code into .obj files and statically links them into Delphi applications. This eliminates DLL deployment complexity and ensures version consistency.

Core Features

• Static linking - zero DLL deployment; everything compiles into a single .exe or .bpl
• Most complete Pascal translation of OpenSSL API headers (~16,000 lines), 4,993 API functions (~99.2% api coverage), support for all major OpenSSL subsystems ( SSL/TLS, X.509, EVP, BIO, ASN.1, PKCS, CMS etc). see Supported API Surface chapter
• Win32 + Win64 - pre-built objects for both platforms, multiple compiler toolchains
• Reproducible builds - build scripts for OpenSSL 3.x / 4.x branches see Building Object Files chapter
• DUnitX test suite - 144 tests for OpenSSL 3.6.1 and 146 for OpenSSL 4.1.0, including TLS handshakes and ABI regressions

Supported API Surface

Quick Start

1. Add libOpenSSL3 to the uses clause of your project
2. In libOpenSSL3.pas, verify the version define matches your needs (OPENSSL_3X or OPENSSL_4X)
3. Build for the desired platform (Win32 or Win64)

uses libOpenSSL3;

begin
  OPENSSL_init_ssl(OPENSSL_INIT_LOAD_SSL_STRINGS or
                   OPENSSL_INIT_LOAD_CRYPTO_STRINGS, nil);
  // Ready to use SSL/TLS, EVP, X.509, etc.
end.

By default the unit links 4.x objects. To switch to 3.x, comment out {$DEFINE OPENSSL_4X} and uncomment {$DEFINE OPENSSL_3X} at the top of libOpenSSL3.pas.

Compiler / Platform Matrix

To switch compilers, edit libOpenSSL3.pas — comment/uncomment the {$DEFINE C_COMPILER_*} lines in the compiler detection block (lines 86–97). For example, to use BCC64 for Win64 instead of the default MSVC:

{$IFDEF CPUX64}
   //{$DEFINE C_COMPILER_MSC_64}      // < comment out MSVC
   {$DEFINE C_COMPILER_BORLAND_64}    // < uncomment BCC64
{$ENDIF}

Building Object Files

Since static linking of C code in Delphi imposes certain requirements on the source code (such as the use of case-insensitive identifier names, linking order, and dependencies on external code), and the OpenSSL source code does not fully meet these requirements, this project uses an approach based on dynamically modifying the source file tree. This task is performed by a set of scripts located in the helpers/ directory. I have tried to describe the changes made in detail directly within these scripts. A huge thanks to Rudy Velthuis for his series of posts in which he described the potential challenges associated with directly using compiled C code. You are no longer with us, but your contribution remains invaluable.

Prerequisites

OpenSSL Branch Selection

The project supports two OpenSSL branches simultaneously:

In Pascal: set {$DEFINE OPENSSL_3X} or {$DEFINE OPENSSL_4X} at the top of libOpenSSL3.pas. Only one may be active at a time (a compile-time guard enforces this).

In build scripts: set the OPENSSL_BRANCH environment variable before running:

set OPENSSL_BRANCH=3
build_openssl3_msvc_win64.bat

If OPENSSL_BRANCH is not set, it defaults to 4.

Building Object Files

Prerequisites

Build Configuration — build_config.bat

All build scripts delegate environment setup to build_config.bat. Edit this file once to match your machine:

REM === Machine-specific paths (edit for your environment) ====================
set "PERL_DIR=C:\programdata\strawberry\perl\bin"
set "RAD_STUDIO=D:\Embarcadero RAD Studio\23.0"
set "VS_BUILD=D:\VisualStudio2019\VC\Auxiliary\Build"

build_config.bat reads OPENSSL_BRANCH (default 4) and resolves the source path and output directory automatically:

Supported targets: bcc32_classic, bcc32c, bcc64, msvc_win32, msvc_win64

Build Scripts

Each script:

1. Calls build_config.bat <target> to set up paths and compiler environment
2. Checks prerequisites (perl, compiler, make/nmake)
3. Runs OpenSSL Configure for the target toolchain
4. Applies helper patches (C89, Makefile, static link, case collisions)
5. Compiles with the platform-native make tool
6. Renames outputs with _win32 / _win64 suffixes into %OBJ_DIR%\<platform>\<compiler>\

Example — build OpenSSL 4.x objects for MSVC Win64:

set OPENSSL_BRANCH=4
build_openssl3_msvc_win64.bat

Example — build OpenSSL 3.x objects for BCC32 classic Win32:

set OPENSSL_BRANCH=3
build_openssl3_cbuilder_classic_win32.bat

Note: Embarcadero compiler scripts always build with no-asm because NASM output is incompatible with the Embarcadero linker.

Helper Scripts

Build Pipeline Helpers (helpers/)

Testing

Run both OpenSSL branches across all five compiler configurations:

tests\run_tests.bat all

Set OPENSSL_BRANCH=3 or OPENSSL_BRANCH=4 to test one branch. The platform argument can be win32, win64, or all. Compiler paths come from build_config.bat.

To repeat the matrix with an installed EurekaLog:

powershell -NoProfile -ExecutionPolicy Bypass -File tests\verify-matrix.ps1 -EurekaLog

The suite contains 144 DUnitX tests for OpenSSL 3.6.1 and 146 for OpenSSL 4.1.0 in tests/TestOpenSSL3API.pas, tests/TestOpenSSLRegressions.pas, tests/TestOpenSSLAdditionalABI.pas, and tests/TestOpenSSLCallbackABI.pas. Coverage includes verified TLS 1.2/1.3 handshakes over paired memory BIOs, binary application data, untrusted certificate rejection, negotiated session duplication, and close_notify. Crypto regressions cover RSA signing and tamper rejection, ECDH, AES-GCM known vectors and invalid tags, CBC padding rejection, PBKDF2, and provider HMAC. Interop tests cover OSSL_PARAM record returns and scalar widths, time_t, IPv4/IPv6 address formatting, BIO backpressure, ASN.1 time boundaries, and isolated provider reloads. OpenSSL 4.x adds SKEY and SKEYMGMT reference-counting tests. Additional ABI regressions cover callback conventions, CRYPTO_EX_DATA layout, per-toolchain BN_ULONG widths, parameter builders, octet output lengths, BIO va_list formatting, and version-specific X509_ALGOR_set_md return types, narrow TLS scalars, and HPKE suite records by value. Callback regressions cover four-argument legacy EVP enumeration, mutable ex-data duplication, BIO method getters and observers, async callback output pointers, provider dispatch tables, RAND method callbacks, and encrypted PEM passwords. The matrix compiles a small C probe from the selected release archive with each target C compiler and compares its sizeof/offsetof results for 13 public records with the Delphi declarations. This requires Python and the five C toolchains. The probe and its generated sources stay in the validation output directory; ABI_LAYOUT_PROBE enables these two C interop tests in the matrix runner.

The runner checks that every discovered test executes, rejects warnings and failed or ignored tests, and checks process termination as well as the test summary. Build outputs and logs are written to %LOCALAPPDATA%\DelphiLibOpenSSL-validation.

License

OpenSSL is licensed under the Apache License 2.0. The Delphi bindings in this repository follow the same license.

PostScriptum

I don't have enough time to fully maintain this project, so I've decided to make it publicly available; I hope others will find it useful.