wolfSSL JNI/JSSE supports building on Windows using Visual Studio.
This README includes instructions and tips for building wolfSSL JNI/JSSE on Windows, along with environment setup instructions. wolfSSL JNI/JSSE depends on and links against the native wolfSSL SSL/TLS library. As such, native wolfSSL will need to be compiled first. Further instructions are below.
Make sure you have downloaded and installed a Java Developer Kit (JDK). Once
a JDK has been installed, JAVA_HOME
needs to be configured as a Windows
environment variable.
- Open the "Environment Variables" window. This can be found by searching for "Environment Variables", or by opening "System Properties", clicking on the "Advanced" tab, then "Environment Variables...".
- In "Environment Variables", add a new variable called
JAVA_HOME
under "System variables". The value for this variable should point to your JDK installation location. For example:
C:\Program Files\Java\jdk1.8.0_361
Apache ant needs to be downloaded in order to build the Java .JAR component of this package.
- Download Apache Ant from the
Apache Ant Binary Distributions page.
On the download page there should be a binary zip file. For example,
apache-ant-1.10.13-bin.zip
. Unzip this archive to a location on your PC where you would like to install Apache Ant.
- After you have downloaded and installed
ant
, configure a new Windows environment variable calledANT_HOME
. Follow similar steps as above to open the "Environment Variables" window. The value of this variable should be the directory that you placed ant in. For example:
C:\apache-ant-1.10.13
- After
ANT_HOME
has been configured as an environment variable, the WindowsPath
needs to be updated to contain theANT_HOME
location.
- Open "Environment Variables" window.
- Under "System variables", edit the "Path" variable.
- Add a new entry at the bottom of the
Path
value list for%ANT\_HOME%\bin
.
- To test that
ant
has been correctly installed:
- Open a Command Prompt window
- Typing
ant -v
should output something similar to the following:
ANT_OPTS is set to -Djava.security.manager=allow
Apache Ant(TM) version 1.10.13 compiled on January 4 2023
Trying the default build file: build.xml
BuildFile: build.xml does not exist!
Build failed
These instructions have been tested with Visual Studio 2019, although other versions should work as well. If not installed, download and install before continuing these instructions.
The Visual Studio projects included in this directory assume that the wolfSSL
JNI/JSSE and wolfSSL SSL/TLS directories are side-by-side on the file system,
and that the directories for each are simply named wolfssl
and wolfssljni
.
This may require renaming the wolfSSL and wolfSSL JNI/JSSE directories.
For example, your high-level directory structure should look like:
C:\wolfssl
C:\wolfssljni
For instructions on building the wolfSSL SSL/TLS DLL, see wolfSSL Manual Chapter 2 Building on Windows, or Using wolfSSL with Visual Studio.
There are a few different Visual Studio solutions which will compile wolfSSL, depending on what variant of wolfSSL you would like to build. Notes on each are provided below.
To build a normal, non-FIPS wolfSSL DLL, use the Visual Studio solution file located in the root of the wolfSSL package:
<wolfssl>\wolfssl64.sln
This will contain build configurations for both 32-bit and 64-bit DLL's, with either "DLL Debug" or "DLL Release". wolfSSL JNI/JSSE will expect to link against a wolfSSL DLL library.
wolfSSL proper's Visual Studio projects use a custom user_settings.h
header
file to customize preprocessor defines and configuration for the wolfSSL
library build. The user_settings.h
header that is used for this non-FIPS build
is located at:
<wolfssl>\IDE\WIN\user_settings.h
When builidng wolfSSL for use with wolfSSL JNI/JSSE, edit this header file
before compiling the library DLL and insert the following defines above the
section titled /* Configuration */
:
#define WOLFSSL_JNI
#define HAVE_EX_DATA
#define OPENSSL_ALL
#define HAVE_CRL
#define HAVE_OCSP
#define PERSIST_SESSION_CACHE
#define PERSIST_CERT_CACHE
#define HAVE_ECC
#define HAVE_DH
#define WOLFSSL_CERT_EXT
#define WOLFSSL_CERT_GEN
#define HAVE_TLS_EXTENSIONS
#define HAVE_SNI
#define HAVE_ALPN
After editing and saving the user_settings.h
file, select one of the following
DLL Library configurations and build the wolfSSL library solution:
- Win32 | DLL Debug
- Win32 | DLL Release
- x64 | DLL Debug
- x64 | DLL Release
The wolfSSL library DLL will be built and placed under one of the following directories:
wolfssl\DLL Debug\Win32
wolfssl\DLL Debug\x64
wolfssl\DLL Release\Win32
wolfssl\DLL Release\x64
When bulding wolfSSL JNI/JSSE, the Visual Studio project file for that library will look in the above locations to link against the wolfSSL DLL matching the same build configuration.
To build a wolfSSL FIPS 140-2 variant of wolfSSL for use with FIPS 140-2
certificate #3389 or later, use the Visual Studio solution file located under
the IDE\WIN10
directory inside the wolfSSL FIPS release package:
<wolfssl>\IDE\WIN10\wolfssl-fips.sln
Follow build instructions in the FIPS User Guide PDF included with the FIPS release package.
In summary:
- Open the above Visual Studio solution file.
- Select one of the following build configurations:
- x64 | DLL Debug
- x64 | DLL Release
- Open Project properties for the
wolfssl
andtest
projects, go toC/C++ -> Preprocessor
, and changeHAVE_FIPS_VERSION=5
toHAVE_FIPS_VERSION=2
. - Open the
user_settings.h
file under<wolfssl>\IDE\WIN10\user_settings.h
and set the values forHAVE_FIPS
,HAVE_FIPS_VERSION
, andHAVE_FIPS_VERSION_MINOR
to the following:
#if 1
#undef HAVE_FIPS
#define HAVE_FIPS
#undef HAVE_FIPS_VERSION
#define HAVE_FIPS_VERSION 2
#undef HAVE_FIPS_VERSION_MINOR
#define HAVE_FIPS_VERSION_MINOR 0
#endif
- When building for wolfSSL JNI/JSSE, add the following to the
user_settings.h
file mentioned in the previous step:
#define WOLFSSL_JNI
#define HAVE_EX_DATA
#define OPENSSL_ALL
#define HAVE_CRL
#define HAVE_OCSP
#define PERSIST_SESSION_CACHE
#define PERSIST_CERT_CACHE
#define HAVE_ECC
#define HAVE_DH
#define WOLFSSL_CERT_EXT
#define WOLFSSL_CERT_GEN
#define HAVE_TLS_EXTENSIONS
#define HAVE_SNI
#define HAVE_ALPN
- Build the
wolfssl-fips
project, which will create a DLL in one of the following locations:
<wolfssl>\IDE\WIN10\DLL Debug\x64\wolfssl-fips.dll
<wolfssl>\IDE\WIN10\DLL Release\x64\wolfssl-fips.dll
- Build the
test
project inside the wolfSSL Visual Studio solution, then run the wolfCrypt test by right clicking on thetest
project, selectingDebug
, thenRun New Instance
.
If a error shows up with "In Core Integrity check FIPS error", copy the
provided hash value, open fips_test.c
, update the verifyCore
array with
the given hash, then re-compile the wolfssl-fips
DLL. This is the FIPS
Power-On Integrity Check, which runs an HMAC-SHA256 over the object files
within the FIPS module boundary.
Re-compiling the test
project and re-running the application should result
in the wolfCrypt tests successfully running.
See the FIPS User Guide for more details on the FIPS verifyCore hash, or email support@wolfssl.com.
To build a version of wolfSSL that has been submitted for FIPS 140-3, use
the Visual Studio solution file under the IDE\WIN10
directory inside the
wolfSSL package:
<wolfssl>\IDE\WIN10\wolfssl-fips.sln
Follow instructions in the above section for 140-2 / 3389, except use the
following values for HAVE_FIPS
, HAVE_FIPS_VERSION
, and
HAVE_FIPS_VERSION_MINOR
in user_settings.h
:
#if 1
#undef HAVE_FIPS
#define HAVE_FIPS
#undef HAVE_FIPS_VERSION
#define HAVE_FIPS_VERSION 5
#undef HAVE_FIPS_VERSION_MINOR
#define HAVE_FIPS_VERSION_MINOR 1
#endif
The following additional defines will also need to be added to
user_settings.h
like above, for compilation and use with wolfSSL JNI/JSSE.
#define WOLFSSL_JNI
#define HAVE_EX_DATA
#define OPENSSL_ALL
#define HAVE_CRL
#define HAVE_OCSP
#define PERSIST_SESSION_CACHE
#define PERSIST_CERT_CACHE
#define HAVE_ECC
#define HAVE_DH
#define WOLFSSL_CERT_EXT
#define WOLFSSL_CERT_GEN
#define HAVE_TLS_EXTENSIONS
#define HAVE_SNI
#define HAVE_ALPN
For additional help, contact support@wolfssl.com.
After the wolfSSL SSL/TLS library DLL has been built (above), the wolfSSL JNI/JSSE library DLL can then be built using the Visual Studio solution located in this directory.
-
Open the Visual Studio solution
wolfssljni.sln
under this directory. -
Select the build configuration which matches the one you built wolfSSL proper above for. The following are the possible build configurations for the
wolfslsjni
project:
- Win32 | DLL Debug
- Win32 | DLL Release
- x64 | DLL Debug
- x64 | DLL Release
- x64 | DLL Debug FIPS (Requires wolfSSL FIPS 140-2/140-3 archive)
- x64 | DLL Release FIPS (Requires wolfSSL FIPS 140-2/140-3 archive)
- Build Solution
This will first compile the wolfssljni.dll
library and place it under one
of the following build directories, based on build configuration:
wolfssljni\IDE\WIN\DLL Debug\Win32
wolfssljni\IDE\WIN\DLL Debug\x64
wolfssljni\IDE\WIN\DLL Debug FIPS\x64
wolfssljni\IDE\WIN\DLL Release\Win32
wolfssljni\IDE\WIN\DLL Release\x64
wolfssljni\IDE\WIN\DLL Release FIPS\x64
It will also run a post-build action which runs ant
from the wolfssljni
root directory. This compiles the Java JAR file, and places that in the
following directory. There are two JAR files built, one that contains only
the thin JNI wrapper around native wolfSSL's APIs (wolfssl.jar
) and one that
includes both the thin JNI wrapper as well as the wolfSSL JSSE provider. For
JSSE users, the wolfssl-jsse.jar
library should be used.
wolfssljni\lib\wolfssl.jar
wolfssljni\lib\wolfssl-jsse.jar
wolfSSL JNI/JSSE includes ant tests that can be run from a Windows Command
Prompt or other shell that has access to the ant
executable.
You will need to download the following JUnit JAR files in order to run the wolfSSL JNI/JSSE tests:
junit-4.13.2.jar hamcrest-all-1.3.jar
Download and place these JAR files on your system, noting the location to be
used below to set the JUNIT_HOME
environment variable.
After wolfSSL and wolfSSL JNI/JSSE have been compiled using the above steps, the ant tests can be run with the following steps:
- Open the Windows Command Prompt
- Set the
JUNIT_HOME
environment variable to point to the directory which contains the JUnit JAR files you downloaded above:
set JUNIT_HOME=path\to\junit\jar\directory
- Navigate to the
wolfssljni
directory
cd path\to\wolfssljni
- Run one of the following ant test targets, depending on what library build configuration you compiled:
ant test-win32-debug
ant test-win32-release
ant test-win64-debug
ant test-win64-release
ant test-win32-debug-fips
ant test-win32-release-fips
ant test-win64-debug-fips
ant test-win64-release-fips
Windows batch scripts have been included to easily run some of the provided examples from the Windows command line.
After the above steps have been followed to compile native wolfSSL and wolfSSL JNI/JSSE, open a Command Prompt and navigate to the wolfSSL JNI/JSSE directory root (ie: wolfssljni).
Compile the examples:
ant examples
Edit the Windows configuration batch script to set the appropriate paths for native wolfSSL and wolfSSL JNI DLL locations. This can change between build types (ex: normal wolfSSL, FIPS 140-2, etc):
Edit examples\WindowsConfig.bat
From the root wolfssljni directory, run the desired .bat file. For example, to run the ProviderTest:
examples\provider\ProviderTest.bat
Or to run the X509v3 certificate or CSR generation example:
examples\X509v3CertificateGeneration.bat
examples\X509CertRequest.bat