openssl is a set of subcommands for cryptography and TLS: create a key and a certificate, read a certificate, sign it with your own certificate authority, connect to a server and see what it serves. The first word is always the subcommand: x509, req, s_client, genpkey, verify…
Syntax
openssl SUBCOMMAND [options]
openssl SUBCOMMAND -help # options of a specific subcommand
Files are usually in PEM format — text between -----BEGIN …----- and -----END …----- lines. The binary form of the same thing is DER.
| PEM header | What's inside |
|---|
BEGIN CERTIFICATE | a certificate |
BEGIN CERTIFICATE REQUEST | a certificate signing request (CSR) |
BEGIN PRIVATE KEY | a private key in PKCS#8 format (BEGIN RSA PRIVATE KEY — the old RSA format) |
BEGIN ENCRYPTED PRIVATE KEY | a password-encrypted private key |
BEGIN PUBLIC KEY | a public key |
x509 — inspect and sign certificates
| Option | What it does |
|---|
-in file | input certificate (-inform DER — if it is in DER) |
-noout | don't print the certificate itself in PEM — only the requested fields |
-text | the whole content in readable form |
-subject / -issuer | issued to / signed by; -nameopt RFC2253 — as CN=…,O=… |
-dates, -startdate, -enddate | validity period: notBefore and notAfter |
-serial | serial number |
-fingerprint -sha256 | certificate fingerprint |
-ext subjectAltName | a single extension: SAN, keyUsage, basicConstraints… |
-pubkey | public key from the certificate |
-modulus | RSA key modulus (RSA only) |
-checkend N | exit code 1 and Certificate will expire if it expires within N seconds |
-outform DER -out file | convert to DER |
-req -in csr -CA ca.pem -CAkey ca.key | issue a certificate from a CSR, signing it with your CA |
-CAcreateserial | create the CA serial number file if it doesn't exist |
-days N | validity period of the issued certificate |
-copy_extensions copy | carry extensions (SAN) over from the CSR to the certificate (OpenSSL 3) |
x509 -text fields
| Field | Meaning |
|---|
Serial Number | unique number within this CA |
Signature Algorithm | what it is signed with: sha256WithRSAEncryption, ecdsa-with-SHA256 |
Issuer | who signed it; for a self-signed one it equals Subject |
Validity: Not Before / Not After | from when and until when it is valid (time in GMT) |
Subject | who it is issued to: CN (name), O (organization), C (country) |
Subject Public Key Info | key algorithm and size: rsaEncryption 2048 bit, id-ecPublicKey 256 bit |
X509v3 Subject Alternative Name | names and IPs the certificate is valid for |
X509v3 Basic Constraints | CA:TRUE — the certificate can sign others |
X509v3 Key Usage / Extended Key Usage | what the key is for: signing, encryption, TLS Web Server Authentication |
req — requests and self-signed certificates
| Option | What it does |
|---|
-new | create a CSR |
-x509 | issue a self-signed certificate right away instead of a CSR |
-newkey rsa:2048 / ec -pkeyopt ec_paramgen_curve:P-256 | create a new key at the same time |
-key file | use an existing key |
-keyout file / -out file | where to write the new key / the CSR or certificate |
-nodes (in OpenSSL 3 also -noenc) | don't encrypt the key with a password |
-subj '/CN=name/O=Org' | subject without interactive prompts |
-addext 'subjectAltName=DNS:a,IP:1.2.3.4' | add an extension |
-days N | validity for -x509 |
-in csr -noout -text / -verify | inspect a CSR / verify its signature |
Keys
| Command | What it does |
|---|
genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 | RSA key |
genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 | elliptic curve key |
genpkey -algorithm ed25519 | Ed25519 key |
genrsa -out key.pem 2048 | RSA key, the old command |
pkey -in key.pem -pubout | public key from the private key |
pkey -in key.pem -noout -text | key parameters |
pkey -in key.pem -check -noout | check key integrity |
rsa -in key.pem -noout -modulus | RSA key modulus |
s_client — connect to a TLS server
| Option | What it does |
|---|
-connect host:port | where to connect |
-servername name | SNI: which site name to ask the server for |
-showcerts | print the whole chain the server sent |
-CAfile ca.pem | trust this CA when verifying |
-verify_hostname name | check that the certificate is issued for this name |
-verify_return_error | abort the connection if verification fails (exit code 1) |
-brief | short summary: protocol, cipher, certificate |
-tls1_2 / -tls1_3 | only this protocol version |
-starttls smtp | TLS on top of a plain protocol (smtp, imap, ftp, postgres…) |
The important lines in the output are subject= / issuer= (the server certificate), Protocol/Cipher and Verify return code: 0 (ok) — chain verified; 18 — self-signed; 20/21 — CA not found; 10 — expired; 62 — name mismatch.
Other
| Command | What it does |
|---|
verify -CAfile ca.pem cert.pem | verify the chain signature; -untrusted inter.pem — intermediate certificates |
dgst -sha256 file | file hash |
rand -hex 16 / rand -base64 24 | random bytes: passwords, tokens |
passwd -6 'password' | password hash for /etc/shadow; -apr1 — for htpasswd |
enc -aes-256-cbc -pbkdf2 -in f -out f.enc | encrypt a file with a password; -d — decrypt |
pkcs12 -export -in cert.pem -inkey key.pem -out b.p12 | pack a certificate and key into PKCS#12 (.p12/.pfx) |
pkcs12 -in b.p12 -nokeys | extract certificates from PKCS#12 |
Examples
# self-signed certificate for localhost, valid for a year, key without a password
openssl req -x509 -newkey rsa:2048 -nodes -days 365 \
-keyout key.pem -out cert.pem \
-subj '/CN=localhost' -addext 'subjectAltName=DNS:localhost'
# issued to whom, by whom, and until when
openssl x509 -in cert.pem -noout -subject -issuer -dates
# does it expire within the next 30 days
openssl x509 -in cert.pem -noout -checkend $((30*86400)) || echo 'expires soon'
# your own CA and a certificate signed by it
openssl req -x509 -newkey rsa:2048 -nodes -days 3650 -subj '/CN=Demo CA' -keyout ca.key -out ca.pem
openssl req -new -newkey rsa:2048 -nodes -subj '/CN=localhost' \
-addext 'subjectAltName=DNS:localhost' -keyout srv.key -out srv.csr
openssl x509 -req -in srv.csr -CA ca.pem -CAkey ca.key -CAcreateserial \
-days 90 -copy_extensions copy -out srv.pem
openssl verify -CAfile ca.pem srv.pem
# does the key match the certificate: the public keys must be equal
diff <(openssl x509 -in cert.pem -noout -pubkey) <(openssl pkey -in key.pem -pubout) && echo 'match'
# the same for RSA via the modulus
openssl x509 -in cert.pem -noout -modulus | sha256sum
openssl rsa -in key.pem -noout -modulus | sha256sum
# what a TLS server serves; </dev/null — so the command doesn't wait for input
openssl s_client -connect localhost:8443 -servername localhost </dev/null
# server certificate straight into x509: validity and subject
openssl s_client -connect localhost:8443 -servername localhost </dev/null 2>/dev/null \
| openssl x509 -noout -subject -dates
# random password
openssl rand -base64 24
Pitfalls
s_client hangs without </dev/null. After the handshake it waits for keyboard input. For a one-off check, feed it an empty stdin.
-servername matters: without SNI, a server hosting several sites may return the wrong site's certificate.
s_client doesn't drop the connection on a verification error. Verify return code: 18 — the connection is established, the certificate just isn't signed by anyone. For strict verification add -verify_return_error, for your own CA — -CAfile.
- CN is no longer what counts. Browsers and Go programs match the host name only against
subjectAltName and ignore CN. curl may still accept a certificate without SAN, a browser won't. Add -addext 'subjectAltName=…'.
- SAN from the CSR isn't carried over automatically.
x509 -req drops the request's extensions by default. You need -copy_extensions copy (OpenSSL 3) or -extfile with the required lines.
-modulus exists only for RSA. For EC and ed25519, compare public keys via -pubkey / pkey -pubout — this method works for any key.
- Without
-nodes the key is encrypted with a password, and nginx will ask for it on every start.
- The
genrsa format has changed. In OpenSSL 3 it writes BEGIN PRIVATE KEY (PKCS#8), not BEGIN RSA PRIVATE KEY. If instructions look for the old header, it's the version, not the key.
- Order in a chain file: the server certificate first, then the intermediates. The server doesn't need to send the root CA.
- The key is a secret: mode
600, owned by whoever reads it.
See also
nginx · curl · ssh · checksums · base64