Getting started

This page walks through cloning, configuring, building, testing, and running OpenSSL from source on a Unix-like system. The authoritative install document is INSTALL.md; the platform-specific notes are in NOTES-UNIX.md, NOTES-WINDOWS.md, NOTES-ANDROID.md, NOTES-VMS.md, NOTES-DJGPP.md, NOTES-NONSTOP.md.

Prerequisites

From INSTALL.md:

• A make implementation
• Perl 5 with core modules and the Text::Template module (see NOTES-PERL.md)
• A C99 compiler (gcc, clang, MSVC, …)
• POSIX C library (POSIX.1-2008 or compatible) and development headers
• A supported operating system

For development you also probably want:

• git
• clang-format (the formatting style is enforced — see how-to-contribute/patterns-and-conventions)
• valgrind or an ASan-capable compiler (see NOTES-VALGRIND.md)

Clone

git clone https://github.com/openssl/openssl.git
cd openssl

The main GitHub repo is a public mirror of a private upstream; pull requests are still made against openssl/openssl on GitHub. See README.md and CONTRIBUTING.md.

Configure

The configuration step is a single Perl script, Configure (or the autodetecting wrapper config). It reads Configurations/*.conf, your command-line options, and emits Makefile, configdata.pm, and a tree of .S/.h generated files. See reference/build-system for the full picture.

Smallest useful configuration:

./Configure

Common variations:

# Auto-detect and print what it picked
./config

# Strict warnings, debug build
./Configure --strict-warnings --debug

# Install elsewhere
./Configure --prefix=/opt/openssl --openssldir=/opt/openssl/ssl

# Enable the FIPS provider
./Configure enable-fips

# Disable a feature
./Configure no-quic no-deprecated

# Cross-compile
./Configure --cross-compile-prefix=aarch64-linux-gnu- linux-aarch64

The full list of enable-* / no-* flags is in INSTALL.md and at the bottom of Configure. Notable ones include enable-fips, enable-asan, enable-ubsan, enable-msan, enable-trace, enable-ec_nistp_64_gcc_128, no-deprecated, no-shared, no-pinshared, enable-ssl-trace, enable-zlib, enable-zstd, enable-brotli.

Build

# Use as many cores as you can spare
make -j"$(nproc)"

Useful targets:

Target	What it does
make	Build everything
make build_libs	Just libcrypto and libssl
make build_apps	Just the apps/openssl executable
make build_tests	Build the test suite
make doc-nits	Lint POD man pages
make update	Regenerate generated files in the source tree (e.g. libcrypto.num, error code maps) — needed after adding public symbols
make clean	Remove built artefacts
make distclean	Remove configuration as well

Without installing, you can run the just-built binary via the wrapper that sets LD_LIBRARY_PATH correctly:

./util/wrap.pl apps/openssl version

Test

make test                    # everything
make test V=1                # full verbosity
make TESTS='test_ssl*' test  # only TLS tests
make TESTS='-99' test        # everything except the slow group
make HARNESS_JOBS=4 test     # in parallel
make list-tests              # what's available

See test/README.md for the full set of options (random-ordered runs, repeating with a saved seed, mfail-style allocation-failure injection, valgrind integration via OSSL_USE_VALGRIND=yes).

Install

sudo make install

This effectively runs install_sw, install_ssldirs, install_docs, and (when enable-fips was used) install_fips. To install just one piece:

sudo make install_sw       # libraries + headers + apps, no docs
sudo make install_docs     # man pages and HTML docs
sudo make install_fips     # FIPS provider only

For FIPS, see README-FIPS.md. The post-install step is openssl fipsinstall which writes fipsmodule.cnf after running the module's self-tests.

Run

The CLI ships as a single multiplexer:

./util/wrap.pl apps/openssl help                                          # list subcommands
./util/wrap.pl apps/openssl genpkey -algorithm RSA -out key.pem
./util/wrap.pl apps/openssl req -x509 -key key.pem -out cert.pem -subj /CN=demo
./util/wrap.pl apps/openssl s_server -cert cert.pem -key key.pem -www
./util/wrap.pl apps/openssl s_client -connect localhost:4433
./util/wrap.pl apps/openssl list -providers                                # what's loaded
./util/wrap.pl apps/openssl list -cipher-algorithms                        # symmetric ciphers

For programmatic use:

#include <openssl/evp.h>
#include <openssl/provider.h>

OSSL_PROVIDER *fips = OSSL_PROVIDER_load(NULL, "fips");
OSSL_PROVIDER *base = OSSL_PROVIDER_load(NULL, "base");

EVP_MD *sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");
/* ... use sha256 ... */
EVP_MD_free(sha256);

OSSL_PROVIDER_unload(base);
OSSL_PROVIDER_unload(fips);

demos/ has more substantial example programs covering BIO, CMS, KDF, MAC, PKEY, encoding/decoding, SSL echo, QUIC, and HTTP/3.

What to read after this

• The OpenSSL Guide (also in doc/man7/ossl-guide-*.pod) is the official tutorial series.
• features/tls for a TLS connection from start to finish.
• features/quic for QUIC client and server.
• how-to-contribute/development-workflow once you want to send patches.