====== Troubleshooting ======

Here you'll find solutions for common problems during OpenSSL build.

----

===== Build Errors =====

==== "stdlib.h not found" or "windows.h not found" ====

**Symptom:**
<code>
fatal error C1083: Cannot open include file: 'stdlib.h': No such file or directory
</code>

**Cause:** Windows SDK not installed or not in PATH.

**Solution:**

<code powershell>
# Option 1: Install Windows SDK
winget install Microsoft.WindowsSDK.10.0.22621

# Option 2: In Visual Studio Installer
# → "Individual Components" → select "Windows 10 SDK"
</code>

Then: Reload Visual Studio environment:

<code batch>
call "C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvars64.bat"
</code>

----

==== "perl is not recognized" ====

**Symptom:**
<code>
'perl' is not recognized as an internal or external command
</code>

**Cause:** Perl not installed or not in PATH.

**Solution:**

<code powershell>
# Install Perl
winget install StrawberryPerl.StrawberryPerl

# Set PATH manually (if still not found after restart)
set PATH=C:\Strawberry\perl\bin;%PATH%
</code>

----

==== "NASM not found" ====

**Symptom:**
<code>
NASM not found - please read INSTALL.md
</code>

**Cause:** NASM not installed or not in PATH.

**Solution A: Install NASM (recommended)**

<code powershell>
winget install NASM.NASM

# Set PATH (path may vary!)
set PATH=%LOCALAPPDATA%\bin\NASM;%PATH%

# Verify
nasm -v
</code>

**Solution B: Build without NASM (slower)**

<code batch>
perl Configure VC-WIN64A no-asm --prefix=D:\Projects\openssl-3.6.0\bin
</code>

<WRAP important>
Without NASM, AES and SHA are significantly slower!
</WRAP>

----

==== "cl.exe not found" ====

**Symptom:**
<code>
'cl' is not recognized as an internal or external command
</code>

**Cause:** Visual Studio environment not loaded.

**Solution:**

<code batch>
call "C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvars64.bat"
</code>

<WRAP tip>
**Tip:** Always start with "Developer Command Prompt for VS 2022" from the Start Menu - the environment is already loaded there.
</WRAP>

----

==== "nmake hangs at 'nmake clean'" ====

**Symptom:** ''nmake clean'' doesn't respond or exits with error.

**Cause:** Known issue with previous failed builds.

**Solution:**

<code batch>
# Delete makefile manually
del makefile

# Reconfigure
perl Configure VC-WIN64A --prefix=D:\Projects\openssl-3.6.0\bin

# Rebuild
nmake
</code>

----

==== "LNK1181: cannot open input file '*.obj'" ====

**Symptom:**
<code>
LINK : fatal error LNK1181: cannot open input file 'crypto\aes\aes-x86_64.obj'
</code>

**Cause:** Previous build failed, object files missing.

**Solution:**

<code batch>
# Delete everything and restart
del makefile
nmake clean 2>nul
perl Configure VC-WIN64A --prefix=D:\Projects\openssl-3.6.0\bin
nmake
</code>

----

===== PowerShell Problems =====

==== "cl.exe causes error despite success" ====

**Symptom:** PowerShell script aborts even though ''cl.exe'' works.

**Cause:** ''cl.exe'' writes version info to stderr, which is interpreted as error with ''$ErrorActionPreference = "Stop"''.

**Solution in script:**

<code powershell>
# Handle cl.exe output correctly
try {
    $clOutput = & cl 2>&1 | Out-String
    Write-Host "cl.exe found"
} catch {
    Write-Host "cl.exe found (stderr ignored)"
}
</code>

----

==== "Execution Policy prevents script" ====

**Symptom:**
<code>
File D:\...\build_openssl.ps1 cannot be loaded because running scripts is disabled
</code>

**Solution:**

<code powershell>
# Option 1: Allow for this session
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

# Option 2: Bypass when calling
powershell.exe -ExecutionPolicy Bypass -File "build_openssl.ps1"
</code>

----

===== Runtime Problems =====

==== "DLL not found" at program start ====

**Symptom:**
<code>
The program can't start because libcrypto-3-x64.dll is missing
</code>

**Solution:**

1. Copy DLLs to application folder:
<code powershell>
copy D:\Projects\openssl-3.6.0\bin\bin\libcrypto-3-x64.dll .\
copy D:\Projects\openssl-3.6.0\bin\bin\libssl-3-x64.dll .\
</code>

2. Or copy automatically in .csproj:
<code xml>
<ItemGroup>
  <None Update="libcrypto-3-x64.dll">
    <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
  </None>
  <None Update="libssl-3-x64.dll">
    <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
  </None>
</ItemGroup>
</code>

----

==== "ML-DSA/ML-KEM not available" ====

**Symptom:**
<code>
openssl list -signature-algorithms | findstr mldsa
# No output
</code>

**Possible causes:**

1. **Wrong OpenSSL version** - Requires 3.6.0 or newer
<code powershell>
openssl version
# Must be: OpenSSL 3.6.0 or higher
</code>

2. **Provider not loaded**
<code powershell>
openssl list -providers
# Should show "default" and possibly "oqsprovider"
</code>

----

==== "FIPS provider not available" ====

**Symptom:**
<code>
openssl list -providers
# Shows no "fips"
</code>

**Solution:**

1. Was it built with ''enable-fips''?
<code batch>
perl Configure VC-WIN64A enable-fips --prefix=...
nmake
nmake install_sw install_fips
</code>

2. Is ''openssl.cnf'' correctly configured?
<code ini>
# In openssl.cnf:
[openssl_init]
providers = provider_sect

[provider_sect]
fips = fips_sect
base = base_sect

[fips_sect]
activate = 1

[base_sect]
activate = 1
</code>

----

===== Network Problems =====

==== "Git clone fails" ====

**Symptom:** Timeout or connection error during ''git clone''.

**Solution for corporate proxy:**

<code powershell>
# Configure proxy
git config --global http.proxy http://proxy.company.com:8080
git config --global https.proxy http://proxy.company.com:8080
</code>

**Solution for SSL certificate errors:**

<code powershell>
# Temporarily disable SSL verification (only for download!)
git config --global http.sslVerify false

# Re-enable after download
git config --global http.sslVerify true
</code>

----

===== Further Help =====

If your problem is not listed here:

  * [[https://github.com/openssl/openssl/blob/master/NOTES-WINDOWS.md|OpenSSL Windows Notes]]
  * [[https://github.com/openssl/openssl/issues|OpenSSL GitHub Issues]]
  * [[https://stackoverflow.com/questions/tagged/openssl|StackOverflow OpenSSL]]

----
//Wolfgang van der Stille @ EMSR DATA d.o.o. - Post-Quantum Cryptography Professional//