← Full reference

openssl

Certificates and keys — inspect, create, sign with your own CA, check a TLS server and a key↔certificate pair

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 headerWhat's inside
BEGIN CERTIFICATEa certificate
BEGIN CERTIFICATE REQUESTa certificate signing request (CSR)
BEGIN PRIVATE KEYa private key in PKCS#8 format (BEGIN RSA PRIVATE KEY — the old RSA format)
BEGIN ENCRYPTED PRIVATE KEYa password-encrypted private key
BEGIN PUBLIC KEYa public key

x509 — inspect and sign certificates

OptionWhat it does
-in fileinput certificate (-inform DER — if it is in DER)
-nooutdon't print the certificate itself in PEM — only the requested fields
-textthe whole content in readable form
-subject / -issuerissued to / signed by; -nameopt RFC2253 — as CN=…,O=…
-dates, -startdate, -enddatevalidity period: notBefore and notAfter
-serialserial number
-fingerprint -sha256certificate fingerprint
-ext subjectAltNamea single extension: SAN, keyUsage, basicConstraints…
-pubkeypublic key from the certificate
-modulusRSA key modulus (RSA only)
-checkend Nexit code 1 and Certificate will expire if it expires within N seconds
-outform DER -out fileconvert to DER
-req -in csr -CA ca.pem -CAkey ca.keyissue a certificate from a CSR, signing it with your CA
-CAcreateserialcreate the CA serial number file if it doesn't exist
-days Nvalidity period of the issued certificate
-copy_extensions copycarry extensions (SAN) over from the CSR to the certificate (OpenSSL 3)

x509 -text fields

FieldMeaning
Serial Numberunique number within this CA
Signature Algorithmwhat it is signed with: sha256WithRSAEncryption, ecdsa-with-SHA256
Issuerwho signed it; for a self-signed one it equals Subject
Validity: Not Before / Not Afterfrom when and until when it is valid (time in GMT)
Subjectwho it is issued to: CN (name), O (organization), C (country)
Subject Public Key Infokey algorithm and size: rsaEncryption 2048 bit, id-ecPublicKey 256 bit
X509v3 Subject Alternative Namenames and IPs the certificate is valid for
X509v3 Basic ConstraintsCA:TRUE — the certificate can sign others
X509v3 Key Usage / Extended Key Usagewhat the key is for: signing, encryption, TLS Web Server Authentication

req — requests and self-signed certificates

OptionWhat it does
-newcreate a CSR
-x509issue a self-signed certificate right away instead of a CSR
-newkey rsa:2048 / ec -pkeyopt ec_paramgen_curve:P-256create a new key at the same time
-key fileuse an existing key
-keyout file / -out filewhere 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 Nvalidity for -x509
-in csr -noout -text / -verifyinspect a CSR / verify its signature

Keys

CommandWhat it does
genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048RSA key
genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256elliptic curve key
genpkey -algorithm ed25519Ed25519 key
genrsa -out key.pem 2048RSA key, the old command
pkey -in key.pem -puboutpublic key from the private key
pkey -in key.pem -noout -textkey parameters
pkey -in key.pem -check -nooutcheck key integrity
rsa -in key.pem -noout -modulusRSA key modulus

s_client — connect to a TLS server

OptionWhat it does
-connect host:portwhere to connect
-servername nameSNI: which site name to ask the server for
-showcertsprint the whole chain the server sent
-CAfile ca.pemtrust this CA when verifying
-verify_hostname namecheck that the certificate is issued for this name
-verify_return_errorabort the connection if verification fails (exit code 1)
-briefshort summary: protocol, cipher, certificate
-tls1_2 / -tls1_3only this protocol version
-starttls smtpTLS 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

CommandWhat it does
verify -CAfile ca.pem cert.pemverify the chain signature; -untrusted inter.pem — intermediate certificates
dgst -sha256 filefile hash
rand -hex 16 / rand -base64 24random bytes: passwords, tokens
passwd -6 'password'password hash for /etc/shadow; -apr1 — for htpasswd
enc -aes-256-cbc -pbkdf2 -in f -out f.encencrypt a file with a password; -d — decrypt
pkcs12 -export -in cert.pem -inkey key.pem -out b.p12pack a certificate and key into PKCS#12 (.p12/.pfx)
pkcs12 -in b.p12 -nokeysextract 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