Jason's Home Page - Linux HOWTOs

openssl - The Open Source toolkit for SSL/TLS ChangeLog

Web site:	https://openssl-library.org/
Repository:	https://github.com/openssl/openssl
Wikipedia:	https://en.wikipedia.org/wiki/OpenSSL

HOWTO

# OpenSSL
# =======
# This is the main OpenSSL HOWTO.  Select a specific branch below
# for version-specific info, including the installation process.

# Slackware 14.0: openssl, openssl-solibs 1.0.1c
# Slackware 14.1: openssl, openssl-solibs 1.0.1e
# Slackware 14.2: openssl, openssl-solibs 1.0.2h
# Slackware 15.0: openssl, openssl-solibs 1.1.1m
#
# Check Slackware's 'patches' directory for security upgrades if you
# decide against installing it from source.

# As of 2024, the openssl.org web site now links to three other places:
# OpenSSL Library (openssl-library.org)
# Bouncy Castle (bouncycastle.org)
# cryptlib (cryptlib.com)
#
# If you find broken links below under openssl.org, this is probably why.

# If you are not 100% confident in doing this, you may want to consider
# making your own replacement packages, or using someone else's.
# slackbook: Package Management
# Slackware Linux Essentials: Chapter 18 Slackware Package Management
# Wikipedia: Slackware - Packages
# linux.com: Intro to Slackware Package Management
# SlackWiki: Building A Package
# packages.slackware.com
# slackpkg
# Wikipedia: slapt-get
# slackbuilds.org
# slackware.pkgs.org
# alien-pkg-convert
# rpm2tgz
# ...

# Keep in mind, if you upgrade OpenSSL, which is used by every SSL/TLS using
# piece of software (unless it uses GnuTLS or wolfSSL instead), you may have some
# serious issues.  For example, you could get yourself kicked out of the
# OpenSSH connection you're using to upgrade it.  If you can't be local, in
# person, you may want to temporarily enable telnet and use that - even
# though, normally, you should never, ever use that.

# OpenSSL Mailing Lists
# mail-archive.com: openssl-announce archive
# marc.info: openssl-announce archive

# OpenSSL: Git Repository
# GitHub: OpenSSL releases

# OpenSSL News
# OpenSSL Wiki
# OpenSSL Documentation
# OpenSSL FAQ
# OpenSSL GitHub issues
# OpenSSL GitHub discussions
# OpenSSL Vulnerabilities
# OpenSSL Blog
# OpenSSL Corporation

# OpenSSL Release Strategy
# As of 3.0.0, releases are major.minor.patch
#
# This is the status of various branches of OpenSSL:
#
# 1.1.0 - no longer supported
# 1.1.1 - no longer supported, EoL as of 2023-09-11
# 3.0   - current LTS version, supported until 2026-09-07
# 3.1   - no longer supported, EoL as of 2025-03-14
# 3.2   - supported until 2025-11-23
# 3.3   - supported until 2026-04-09
# 3.4 - supported until 2026-10-22

# If you have trouble with the download URL (GitHub Releases), you
# can also download it from SourceForge:
# https://sourceforge.net/projects/openssl-project.mirror/files/

# If you get an error about certificate verification when downloading with
# wget, you can use 'wget --no-check-certificate URL', but you're better off
# fixing/implementing certificates for verification.  If you have Slackware's
# 'ca-certificates' package, for example, making /usr/local/ssl/certs a
# symlink to /etc/ssl/certs will take care of that problem.

# I get the tarball checksums from multiple sources where possible to
# make sure that the match up with each other.  The announce mailing
# list, the .sha256 file listed on the GitHub Release page, etc.
# Follow along to verify it using programs from coreutils and/or
# GnuPG (gpg).

# With OpenSSL 3.x, the shared library files are:
# libcrypto.so.3
# libssl.so.3
# and libcrypto.so and libssl.so symlinks pointing to those.
#
# With OpenSSL 1.1.x it was:
# libcrypto.so.1.1
# libssl.so.1.1
# and libcrypto.so.1 and libssl.so.1 symlinks pointing to those,
# and libcrypto.so and libssl.so symlinks.
#
# Just make sure you don't have OpenSSL installed in multiple locations
# or you may have trouble.  If you have libcrypto.so.3 and
# libcrypto.so.1.1 in the same place, that is fine, unless you are
# very low on disk space, leave it.  Something compiled in the past
# may be using the older one - recompile and install it to get it
# to use the newer one, assuming it supports that version.
#
# If you remove the old ones, some things may break until you re-compile
# them.  Running this as root:
#   lsof /usr/local/ssl/lib*/libssl.so* | awk '{ print $1 }' | sort | uniq
#   lsof /usr/local/lib*/lib{crypto,ssl}.so*
#   lsof /usr/lib*/lib{crypto,ssl}.so*
# should give you an idea of some OpenSSL-linked daemons that are currently
# running on your system.
#
# There is a list of OpenSSL-using applications at the bottom of this page
# that may help if some command-line programs stop working.  To see if
# a particular binary is linked with an OpenSSL shared library or not, run
# ldd on it (ldd /bin/foo), looking for libcrypto or libssl in the output.
# The safe solution would be to just leave the old files there until you're
# positive that nothing is using them.

# Note:
# As of 1.0.1s and 1.0.2g, SSLv2 is disabled
# As of 1.1.0, SSLv2 support was removed
# As of 1.1.1, TLSv1.3 was added

# Prerequisites for all versions:
# Perl
# bc (for certain 'make test' tests)

# Version specific HOWTOs:
# OpenSSL 1.1.x
# OpenSSL 3.0.x
# OpenSSL 3.1.x
# OpenSSL 3.2.x

# Post-install setup
# ==================
# If you installed >= 1.1.0 into the /usr prefix, then you don't need to do
# anything related to setting PATH, MANPATH, PKG_CONFIG_PATH, the
# symlink to /etc/ssl/certs, etc.  Do continue to the list of things you may
# need to restart or rebuild though.

# Become root
# su, sudo bash, whatever your preference
su -

# If you had previously used prefix /usr/local/ssl and upgraded to >= 1.1.0
# using prefix /usr/local, you should not need an /etc/profile.d/openssl.sh
# to update PATH, MANPATH, and PKG_CONFIG_PATH any more.  If you do remove
# it, you will need to log out and back in to see the changes (or source it).
#
# If you use --prefix=/usr/local/ssl (default < 1.1.0), create an
# /etc/profile.d/openssl.sh that will set up the correct directories in PATH
# and MANPATH and with the update to PKG_CONFIG_PATH, the pkg-config program
# will be able to find libcrypto.pc, libssl.pc, and openssl.pc  If you use
# other shells like csh, create a /etc/profile.d/openssl.csh too.
cat << EOF > /etc/profile.d/openssl.sh
#!/bin/sh
test -d /usr/local/ssl/bin &&
export PATH=/usr/local/ssl/bin:\$PATH
test -d /usr/local/ssl/man &&
export MANPATH=/usr/local/ssl/man:\$MANPATH
if [ -d /usr/local/ssl/lib64/pkgconfig ]; then
  SSLPCDIR=/usr/local/ssl/lib64/pkgconfig
elif [ -d /usr/local/ssl/lib/pkgconfig ]; then
  SSLPCDIR=/usr/local/ssl/lib/pkgconfig
fi
if [ -n "\$SSLPCDIR" -a -d "\$SSLPCDIR" -a ! -L "\$SSLPCDIR" ]; then
  if [ -n "\$PKG_CONFIG_PATH" ]; then
    PKG_CONFIG_PATH="\$PKG_CONFIG_PATH:\${SSLPCDIR}"
  else
    PKG_CONFIG_PATH="\$SSLPCDIR"
  fi
  export PKG_CONFIG_PATH
fi
unset SSLPCDIR
EOF
chmod 755 /etc/profile.d/openssl.sh

# If you have Slackware's ca-certificates package installed, do this to keep
# an updated list that the new OpenSSL will be aware of.  You can also
# update ETCCERTSDIR in update-ca-certificates to avoid having to create the
# symlink.  If you used --prefix=/usr and --openssldir=/etc/ssh, you don't
# need a symlink because that is the real path used already.
test ! -L /usr/local/ssl/certs &&
test -d /usr/local/ssl/certs &&
  rmdir /usr/local/ssl/certs &&
   test -d /etc/ssl/certs &&
    ln -s /etc/ssl/certs /usr/local/ssl/certs
test -x /usr/sbin/update-ca-certificates &&
/usr/sbin/update-ca-certificates --verbose

## If there are security fixes in the new version, you should immediately
## rebuild any apps that linked with the static libraries (.a) and you should
## at least restart anything that is linked with the shared libraries
## (.so) from the old version - which will only help if they are binary
## compatible with the new version libraries.  To find ones that are
## currently running, try running something like this as root for
## libssl and libcrypto.  If you changed prefixes while upgrading and
## you have not restarted anything yet, use the path to the old version.
# find /usr/local/lib*/ -name "libssl.so*" -exec lsof {} \;
# find /usr/local/ssl/lib*/ -name "libssl.so*" -exec lsof {} \;
# find /usr/lib*/ -name "libssl.so*" -exec lsof {} \;

# If you're not sure if a particular binary is linked to OpenSSL or not, run
# ldd on it.  If it is linked with the shared libraries it will output
# something like this:
# libssl.so.1.0.0 => /usr/local/ssl/lib64/libssl.so.1.0.0 (0xabcd12345678efgh)
# libcrypto.so.1.0.0 => /usr/local/ssl/lib64/libcrypto.so.1.0.0 (0xabcd12345678efgh)
# or this:
# libcrypto.so.1.1 => /usr/local/lib64/libcrypto.so.1.1 (0xabcd12345678efgh)
# libssl.so.1.1 => /usr/local/lib64/libssl.so.1.1 (0xabcd12345678efgh)
# or this:
# libcrypto.so.3 => /usr/local/lib64/libcrypto.so.3 (0xabcd12345678efgh)
# libssl.so.3 => /usr/local/lib64/libssl.so.3 (0xabcd12345678efgh)

## If you run BIND named in a chroot jail, you may need to copy the
## shared library files there
# mkdir -p /named/files/are/in/here/usr/local/lib64/engines-3
# find /usr/local/lib64/ -maxdepth 1 -name libcrypto.* \
#  -exec cp -p {} /named/files/are/in/here/usr/local/lib64/ \;
# find /usr/local/lib64/ -maxdepth 1 -name libssl.* \
#  -exec cp -p {} /named/files/are/in/here/usr/local/lib64/ \;
# find /usr/local/lib64/engines-3/ -type f \
#  -exec cp -p {} /named/files/are/in/here/usr/local/lib64/engines-3/ \;
# find /usr/local/lib64/ossl-modules/ -type f \
#  -exec cp -p {} /named/files/are/in/here/usr/local/lib64/ossl-modules/ \;
## Example of doing all of it with BIND chroot in /var/named
test -d /var/named/usr/local/lib64 &&
( cd /var/named/usr/local/lib64
   cp -a /usr/local/lib64/libcrypto.* .
   cp -a /usr/local/lib64/libssl.* .
   mkdir -p -m 0700 engines-3 ossl-modules
   cp -a /usr/local/lib64/engines-3/* engines-3/
   cp -a /usr/local/lib64/ossl-modules/* ossl-modules/ )

# You may want to install certwatch as the Slackware package does, run
# out of /etc/cron.daily:
# http://ftp.slackware.com/pub/slackware/slackware-current/source/n/openssl/certwatch.gz

# Become your non-root user again
exit

# If you created a /etc/profile.d/openssl.sh, source it to add the
# appropriate directories to your current shell's PATH, MANPATH, and
# PKG_CONFIG_PATH
test -f /etc/profile.d/openssl.sh && . /etc/profile.d/openssl.sh

# Here are some daemon-type software that is commonly linked with OpenSSL
# libraries:
# Apache 2.x's httpd (named 'apache2' in Ubuntu)
# BIND's named (and dig, host, ...)
# CUPS' cupsd
# Cyrus IMAP's master, fud, imapd, lmtpd, pop3d
# Cyrus SASL's saslauthd
# fetchmail (when running as a daemon)
# IMAP Proxy's in.imapproxyd
# MariaDB's mysqld
# MySQL's mysqld
# NTP's ntpd
# NUT's upsd, upsmon, usbhid-ups, ...
# OpenLDAP's slapd and slurpd
# OpenSSH's sshd
# Postfix's master, qmgr, pickup
# ProFTPD
# Python (e.g. Mailman)
# Samba's smbd and nmbd
# sendmail
# stunnel
# syslog-ng
# ucd/net-snmp's snmpd
# vsftpd
#
# Here are some non-daemon commandline programs that may be linked with
# openssl:
#
# curl
# lftp
# links
# lynx
# nail, mailx's /bin/mail
# neon
# Pine/Alpine/Re-Alpine
# Python
# rsync
# tcpdump
# wget

# Creating SSL certs for an application to use
# ============================================
# You can create self-signed certificates, or have them signed by a
# "real" CA.  Or, you may want to look at the certbot HOWTO
# for information about using Let's Encrypt certificates.
#
# Continue below to read about creating a self-signed certificate.

# If you have an older version of OpenSSL installed <= 1.1.0, add
# /usr/local/ssl/bin to your PATH.  Newer versions would use
# /usr/local/bin by default instead.
test -x /usr/local/ssl/bin &&
echo $PATH | grep -q "/usr/local/ssl/bin" ||
  export PATH=$PATH:/usr/local/ssl/bin

# OpenSSL < 1.1.0 installed from source is installed under /usr/local/ssl by
# default, leaving the openssl binary in /usr/local/ssl/bin.  Newer versions
# installed from source would put it in /usr/local/bin.  If you are using a
# distribution package, or it was installed from source under the /usr
# prefix, your openssl binary will be in /usr/bin, which is usually in the
# PATH by default.

# In /usr prefix installations, CA.pl may be in /etc/ssl/misc as in
# Slackware or /usr/lib/ssl/misc as in Ubuntu.
# Source-installed CA.pl is generally found in /usr/local/ssl/misc,
# whether you have < 1.1.0 installed or newer.

# I typically modify CA.pl with these changes:
# - Change $DAYS if you want (self-signed) certificates longer than 1 year
# - Change $CADAYS if you want the CA to exist longer than 3 years
# - Change $CATOP if you want the CA files to go somewhere other than
#   ~/demoCA/
# - This is not an issue with recent releases, but if your OpenSSL uses a
#   default of 1024 bits, to change the CA from 1024 to 2048 bits, somewhere
#   around row 114 you'll find something like this:
#     print "Making CA certificate ...\n";
#     system ("$REQ -new -keyout " .
#         "${CATOP}/private/$CAKEY -out ${CATOP}/$CAREQ");
#   Replace "-new" with "-newkey rsa:2048"
#
# You can now set OPENSSL_CONFIG to the full path of the configuration file
# (/usr/local/ssl/openssl.cnf)
# 'man CA.pl' says OPENSSL_CONF, but if you look in CA.pl...

# And I modify /usr/local/ssl/openssl.cnf with a few:
# - Any paths I need changed, including demoCA (dir = ) as changed in CA.pl
# - default_days to whatever is set in CA.pl
# - default_bits if using something other than 1024 bit CSRs
# - If you want to pre-fill your country, state, town, etc. for certs you
#   can do that in there

# Move any old files out of the way if creating a new CA or keys, certs
cd
test -d ./demoCA.old2 && rm -r ./demoCA.old2/
test -d ./demoCA.old && mv -f ./demoCA.old ./demoCA.old2
test -d ./demoCA && mv -f ./demoCA ./demoCA.old
test -f newcert.pem && mv -f newcert.pem newcert.pem.old
test -f newreq.pem && mv -f newreq.pem newreq.pem.old
test -f newkey.pem && mv -f newkey.pem newkey.pem.old

# Create a CA - certificate authority, to self-sign certificates
/usr/local/ssl/misc/CA.pl -newca
# <enter>
# <CA password - make up one>
# <CA password again>
# Country Code (US)
# State or Province (New Jersey)
# City, Town, Borough, whatever (Fooville)
# Organization Name (example.com)
# Organizational Unit name (root)
# Common Name (example.com CA)
# E-mail address (root@example.com)
# <enter>
# <enter>
# <CA password>

# Create a CSR (certificate signing request) and a new private key with
# no password (so you don't have to enter the password when you start
# Apache or whatever it is).  Output files will be newreq.pem and newkey.pem
/usr/local/ssl/misc/CA.pl -newreq-nodes
# Country Code (US)
# State or Province Name (New Jersey)
# City, Town, Borough, whatever (Fooville)
# Organization (example.com)
# Organizational Unit Name (root, postmaster, webmaster, etc.)
# Certificate name (serverhostnameorappropriatecname.example.com)
# E-mail address (root@example.com)
# <enter>
# <enter>

# Now if you need to get a certificate from CAcert or another
# certificate authority, you will probably need to go to their web site and
# cut and paste the contents of the newreq.pem file in order for them to
# create your certificate, which they then generally e-mail to you, or e-mail
# you to go to a web page to download it.  Just be aware that if you
# modified $DAYS above, that will have no effect on whoever you pay to
# sign your SSL certificate, that would only matter if you self-sign yours.
#
# Save the certificate, for now, as newcert.pem

# If you are not using a non-free CA or CAcert, you can self-sign the
# CSR to get you a newcert.pem
/usr/local/ssl/misc/CA.pl -sign
# <CA password>
# y
# y

# If you will be using your own CA to sign and verify certificates, you
# will need to keep everything in ./demoCA/  Otherwise, you can remove that,
# but I would recommend backing it up first.  You may find that you need
# it later...  Same goes for the CSR, key, and cert files.  You may find
# too that you need to convert from one format to another depending on
# what you are using it for.

# The files that OpenSSL uses to verify certificates that it has signed and
# to create CRLs
# Once you copy the *.pem files to whatever location is configured for the
# application (Apache, sendmail, Cyrus-IMAP, whatever), you can remove the
# originals after maybe saving a backup copy and ./demoCA/ if you won't be
# using your own CA again.