openssl (the command line)

Active contributors: Matt Caswell, Tomas Mraz, Pauli, Dr. David von Oheimb, Richard Levitte, slontis, Dr. Stephen Henson

Purpose

The openssl command-line program is a multiplexer that exposes most of libcrypto and libssl functionality in a shell-friendly form. A single binary dispatches to ~70 subcommands. It is also OpenSSL's own integration test client (apps/s_client.c), server (apps/s_server.c), benchmark suite (apps/speed.c), and CA workflow (apps/ca.c).

Directory layout

apps/
├── openssl.c            -- main(): dispatcher
├── progs.pl             -- generates progs.h: name → function table
├── apps.c, apps.h       -- shared helpers (option parsing, BIO setup)
├── lib/                 -- per-domain helpers used by multiple subcommands
│   ├── apps_ui.c, app_libctx.c, app_provider.c, …
│   ├── opt.c, names.c, fmt.c, http_server.c, …
│   ├── s_cb.c, s_socket.c, tlssrp_depr.c, …
│   └── …
├── include/             -- per-app headers (apps.h, opt.h, fmt.h, names.h, http_server.h, …)
├── <subcommand>.c       -- one .c per subcommand
├── openssl.cnf          -- the default config file shipped with OpenSSL
├── CA.pl.in             -- a Perl wrapper that wraps openssl req/x509/ca for ad-hoc CA management
├── server.pem, ca-cert.srl, …  -- demo PEM files used by tests
└── tsget.in             -- Time-Stamp client wrapper (Perl)

The biggest subcommand source files give a sense of where complexity lives:

File	Lines	Purpose
apps/speed.c	4,774	benchmarking
apps/s_server.c	~4,800	TLS/DTLS/QUIC server
apps/s_client.c	~4,500	TLS/DTLS/QUIC client
apps/cmp.c	~3,800	CMP client/server
apps/req.c	~1,700	Certificate requests
apps/list.c	~1,800	List providers/algorithms
apps/ca.c	~2,500	Minimal CA
apps/cms.c, apps/pkcs12.c, apps/x509.c	~1,200–1,500 each	their respective commands

How dispatch works

The list of subcommands is defined in apps/progs.pl. At build time the script reads the list of .c files and emits apps/progs.h (in the build tree), which contains a FUNCTION functions[] table. apps/openssl.c:main() matches argv[1] against this table and calls the function pointer with argc-1, argv+1. The function returns an exit code.

graph LR
    Argv["argv: openssl s_client -connect host:443"] --> Main[apps/openssl.c main]
    Main --> Init[apps_startup<br/>OPENSSL_init_ssl + setup_ui_method]
    Main --> Lookup[do_cmd<br/>looks up s_client in functions array]
    Lookup --> Sub[apps/s_client.c<br/>s_client_main]
    Sub --> Lib[libssl + libcrypto]

A subcommand's *_main(int argc, char **argv) is the canonical entry point. By convention it parses options with the shared apps/lib/opt.c helpers, opens BIOs, calls into libcrypto/libssl, and returns an int. See apps/include/opt.h for the option-parsing primitives (OPT_*).

Subcommand catalogue (selected)

The full list is openssl help. Roughly grouped:

Group	Subcommands
Keys	genpkey, pkey, pkeyparam, pkeyutl, genrsa, rsa, gendsa, dsa, dsaparam, dhparam, ec, ecparam, skeyutl
Certificates / CSRs / CRLs	req, x509, verify, crl, ca, nseq, crl2pkcs7, cms, ts, dgst, sess_id
Containers	pkcs7, pkcs8, pkcs12, smime, spkac, storeutl
Symmetric / encoding	enc, mac, kdf, dgst, passwd, prime, rand
Networking	s_client, s_server, s_time, ocsp, ciphers
Online protocols	cmp, ts, ocsp
FIPS	fipsinstall
Discovery / debugging	list, info, version, errstr, help, rehash
ECH	ech

apps/openssl.cnf is the example configuration file; it shows how to enable and configure providers, the Engine subsystem, the SSL section, and TS / CA workflows.

How a typical subcommand is laid out

Take apps/x509.c as an example. It:

1. Defines an OPTIONS array describing every command-line flag (-in, -out, -text, -noout, -set_serial, …).
2. Implements a _main that calls opt_init, loops over options, opens input/output BIOs, and dispatches to the requested operation.
3. Uses helpers from apps/lib/ (load_cert, load_key, set_cert_times, do_X509_sign, print_cert, …).
4. Returns 0 on success, non-zero on failure.

Subcommands also share infrastructure in apps/lib/:

File	Purpose
apps/lib/app_libctx.c	Manage the apps' default OSSL_LIB_CTX (loaded providers, properties).
apps/lib/app_provider.c	-provider, -propquery flag handling.
apps/lib/opt.c	Option parsing.
apps/lib/apps.c	BIO/file helpers, password callbacks, load_cert/key/crl, do_X509_sign.
apps/lib/s_cb.c	TLS callback helpers (info, msg, alert, verify) shared by s_client/s_server.
apps/lib/s_socket.c	Socket helpers (do_server, init_client).
apps/lib/http_server.c	A tiny HTTP server used by s_server -www and ocsp responder mode.
apps/lib/tlssrp_depr.c	SRP support (deprecated but still wired).

Two helpers worth knowing

• apps/CA.pl.in is a small Perl wrapper around openssl req, openssl ca, openssl pkcs12. It is what most tutorials suggest before users learn the underlying commands.
• apps/tsget.in is a Perl-based RFC 3161 timestamp-request client.

Demo CAs and certs

apps/ca-cert.pem, apps/ca-key.pem, apps/server.pem, apps/client.pem, … are demo material used by apps/openssl.cnf and by the test suite. They are not for production use.

Entry points for modification

• Adding a new subcommand: create apps/<name>.c with a <name>_main(int, char **) function and an OPTIONS array, declare it in apps/include/progs.h.in (or extend apps/progs.pl), add it to apps/build.info, and write a POD page under doc/man1/openssl-<name>.pod.
• Modifying option parsing: see apps/lib/opt.c and apps/include/opt.h.
• Adjusting TLS client/server defaults shown in tutorials: edit apps/s_client.c, apps/s_server.c, and the matching POD pages.

Documentation

Each subcommand has a POD man page named doc/man1/openssl-<name>.pod (e.g. openssl-genpkey.pod, openssl-x509.pod). The umbrella man page is doc/man1/openssl.pod.