OpenSSL Cookbook The Definitive Guide To The Most Useful Command Line Features 3rd Edition Ivan Ristić Download PDF
OpenSSL Cookbook The Definitive Guide To The Most Useful Command Line Features 3rd Edition Ivan Ristić Download PDF
com
OR CLICK BUTTON
DOWLOAD NOW
More products digital (pdf, epub, mobi) instant
download maybe you interests ...
https://ebookmeta.com/product/openssl-cookbook-3rd-edition-ivan-
ristic/
https://ebookmeta.com/product/efficient-linux-at-the-command-
line-boost-your-command-line-skills-1st-edition-daniel-j-barrett/
https://ebookmeta.com/product/take-control-of-the-mac-command-
line-with-terminal-3rd-edition-joe-kissell/
https://ebookmeta.com/product/spice-mix-cookbook-the-definitive-
guide-to-every-spice-mix-2nd-edition-booksumo-press/
JavaScript JSON Cookbook Over 80 recipes to make the
most of JSON in your desktop server web and mobile
applications 1st Edition Ray Rischpater
https://ebookmeta.com/product/javascript-json-cookbook-
over-80-recipes-to-make-the-most-of-json-in-your-desktop-server-
web-and-mobile-applications-1st-edition-ray-rischpater/
https://ebookmeta.com/product/the-linux-command-line-a-complete-
introduction-2nd-edition-william-shotts/
https://ebookmeta.com/product/the-linux-command-line-a-complete-
introduction-second-edition-william-shotts/
https://ebookmeta.com/product/command-line-rust-1st-edition-ken-
youens-clark/
https://ebookmeta.com/product/the-linux-command-line-a-complete-
introduction-2d-edition-william-e-shotts/
THIRD
EDITION
OPENSSL
COOKBOOK
The Definitive Guide to the Most
Useful Command Line Features
Ivan Ristić
Last update: Thu Feb 17 04:24:43 GMT 2022 (build 766)
OpenSSL Cookbook
Ivan Ristić
OpenSSL Cookbook
by Ivan Ristić
Third edition (build 766). Published in February 2022.
Copyright © 2022 Feisty Duck Limited. All rights reserved.
All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or
by any means, without the prior permission in writing of the publisher.
The author and publisher have taken care in preparation of this book, but make no expressed or implied warranty of any kind and
assume no responsibility for errors or omissions. No liability is assumed for incidental or consequential damages in connection
with or arising out of the use of the information or programs contained herein.
Table of Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . v
Feedback v
Acknowledgments vi
About Bulletproof TLS and PKI vi
About the Author vii
1. OpenSSL Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Getting Started 1
Determine OpenSSL Version and Configuration 2
Building OpenSSL 3
Examine Available Commands 5
Building a Trust Store 7
Key and Certificate Management 8
Key Generation 8
Creating Certificate Signing Requests 12
Creating CSRs from Existing Certificates 14
Unattended CSR Generation 14
Signing Your Own Certificates 15
Creating Certificates Valid for Multiple Hostnames 15
Examining Certificates 16
Examining Public Certificates 17
Key and Certificate Conversion 20
Configuration 23
Obtaining Supported Suites 24
Understanding Security Levels 25
Configuring TLS 1.3 26
Configuring OpenSSL Defaults 28
Recommended Suite Configuration 29
Generating DH Parameters 31
Legacy Suite Configuration 31
iii
Performance 36
Creating a Private Certification Authority 39
Features and Limitations 40
Creating a Root CA 40
Creating a Subordinate CA 47
2. Testing TLS with OpenSSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Custom-Compile OpenSSL for Testing 51
Connecting to TLS Services 52
Certificate Verification 56
Testing Protocols That Upgrade to TLS 57
Extracting Remote Certificates 57
Testing Protocol Support 58
Testing Cipher Suite Configuration 59
Testing Cipher Suite Preference 61
Testing Named Groups 62
Testing DANE 64
Testing Session Resumption 65
Keeping Session State across Connections 66
Checking OCSP Revocation 67
Testing OCSP Stapling 69
Checking CRL Revocation 70
Testing Renegotiation 72
Testing for Heartbleed 74
Determining the Strength of Diffie-Hellman Parameters 77
iv
Preface
For all its warts, OpenSSL is one of the most successful and most important open source
projects. It’s successful because it’s so widely used; it’s important because the security of large
parts of the Internet infrastructure relies on it. The project consists of a high-performance
implementation of key cryptographic algorithms, a complete TLS and PKI stack, and a com-
mand-line toolkit. I think it’s safe to say that if your job has something to do with security,
web development, or system administration, you can’t avoid having to deal with OpenSSL
on at least some level. The majority of the Internet is powered by open source products, and
most of them rely on OpenSSL.
This book covers two ways in which OpenSSL can be used. Chapter 1, OpenSSL Command
Line, will help users who need to perform routine tasks of key and certificate generation, and
configure programs that rely on OpenSSL for TLS functionality. This chapter also discusses
how to create a complete private CA, which is useful for development and similar internal
environments. Chapter 2, Testing TLS with OpenSSL, focuses on server security testing using
OpenSSL. Although sometimes time consuming, this type of low-level testing can’t be avoided
when you wish to know exactly what’s going on.
Both chapters are borrowed from my larger work, called Bulletproof TLS and PKI. I decided
to publish the OpenSSL chapters as a separate free book because there is a severe lack of good
and easily available documentation. As is often true for complex and long-lived projects, the
OpenSSL documentation you can find on the Internet is often wrong and outdated.
Besides, publishers often give away one or more chapters in order to show what the book is
like, and I thought I should make the most of this practice by not only making the OpenSSL
chapters free, but also by committing to continue to maintain and improve them over time.
So here they are.
Feedback
Reader feedback is always very important, but especially so in this case, because this is a living
book. In traditional publishing, often years pass before reader feedback goes back into the
book, and then only if another edition actually sees the light of day (which often does not
v
happen for technical books, because of the small market size). With this book, you’ll see new
content appear in a matter of days. Ultimately, what you send to me will affect how the book
will evolve.
The best way to contact me is to use my email address, [email protected]. Sometimes I
may also be able to respond via Twitter, where you will find me under the handle @ivanristic.
Acknowledgments
This is a short book, but it’s packed with technical information. As a result, there are ample
opportunities for mistakes. I am very grateful to Matt Caswell for his help in keeping the mis-
takes away. Matt, who is a member of the OpenSSL development team, joined me as technical
reviewer for the third edition.
Various people have written to me with their thoughts and corrections. They, too, made this
book better. I extend my thanks to Brian Howson, Christian Folini, Jeff Kayser, Martin Car-
penter, Michael Reschly, Karsten Weiss, Olivier Levillain, and Stephen N. Henson.
My special thanks goes to my copyeditor, Melinda Rankin. She has been a pleasure to work
with, as always.
vi Preface
About the Author
Ivan Ristić writes computer security books and builds security products. His book Bulletproof
TLS and PKI, the result of more than a decade of research and study, is widely recognized
as the de-facto SSL/TLS and PKI reference manual. His work on SSL Labs made hundreds
of thousands of web sites more secure. Before that, he created ModSecurity, a leading open
source web application firewall.
More recently, Ivan founded Hardenize, a platform for continuous security monitoring that
provides free assessments to everyone. He’s a member of Let’s Encrypt’s technical advisory
board.
Getting Started
If you’re using one of the Unix platforms, getting started with OpenSSL should be easy; you’re
virtually guaranteed to have it already installed on your system. Still, things could go wrong.
For example, you could have a version that’s just not right, or there could be other tools (e.g.,
LibreSSL) configured to respond when OpenSSL is invoked. For this reason, it’s best to first
check what you have installed and resort to using a custom installation only if absolutely
necessary. Another option is to look for a packaging platform. For example, for OS X you
1
The letters “eay” in the name SSLeay are Eric A. Young’s initials.
1
could use Brew or MacPorts. As always, compiling something from scratch once is rarely a
problem; maintaining that piece of software indefinitely is.
In this chapter, I assume that you’re using a Unix platform because that’s the natural envi-
ronment for OpenSSL. On Windows, it’s less common to compile software from scratch be-
cause the tooling is not readily available. You can still compile OpenSSL yourself, but it might
take more work. Alternatively, you can consider downloading the binaries from the Shining
Light Productions web site.2 If you’re downloading binaries from multiple web sites, you need
to ensure that they’re not compiled under different versions of OpenSSL. If they are, you
might experience crashes that are difficult to troubleshoot. The best approach is to use a single
bundle of programs that includes everything that you need. For example, if you want to run
Apache on Windows, you can get your binaries from the Apache Lounge web site.3
At the time of writing, OpenSSL 1.1.1 is the dominant branch used in production and has
all the nice features. On older systems, you may find a release from the 1.1.0 branch, which
is fine because it can be used securely with TLS 1.2, but it won’t support modern features,
such as TLS 1.3. In the other direction is OpenSSL 3.0, which introduces a major update of
the libraries, with substantial architectural changes and a switch to the Apache License 2.0 for
better interoperability with other programs and libraries. The command-line tooling, which
is what I am covering in this chapter and the next, should be pretty much the same. That
said, every release—and especially the major ones—is very likely to change the tools’ behavior,
often in subtle ways. When you’re changing from one branch to another, it’s worth going
through the change documentation to understand what the differences might be.
Note
Although you wouldn’t know it from looking at the version number, various oper-
ating systems often don’t actually ship the exact official OpenSSL releases. More of-
ten than not, they contain forks that are either customized for a specific platform
or patched to address various known issues. However, the version number generally
2
Win32/Win64 OpenSSL (Shining Light Productions, retrieved 19 July 2020)
3
Apache 2.4 VS16 Windows Binaries and Modules (Apache Lounge, retrieved 18 September 2021)
I don’t suppose that you would find this output very interesting initially, but it’s useful to know
where you can find out how your OpenSSL was compiled. Of special interest is the OPENSSLDIR
setting, which in my example points to /usr/lib/ssl; it will tell you where OpenSSL looks
for its default configuration and root certificates. On my system, that location is essentially an
alias for /etc/ssl, Ubuntu’s main location for PKI-related files:
lrwxrwxrwx 1 root root 14 Apr 20 11:53 certs -> /etc/ssl/certs
drwxr-xr-x 2 root root 4096 May 14 21:38 misc
lrwxrwxrwx 1 root root 20 Apr 20 11:53 openssl.cnf -> /etc/ssl/openssl.cnf
lrwxrwxrwx 1 root root 16 Apr 20 11:53 private -> /etc/ssl/private
The misc/ folder contains a few supplementary scripts, the most interesting of which are the
scripts that allow you to implement a private certification authority (CA). You may or may
not end up using it, but later in this chapter I will show you how to do the equivalent work
from scratch.
Building OpenSSL
In most cases, you will be using the system-supplied version of OpenSSL, but sometimes there
are good reasons to use a newer or indeed an older version. For example, if you have an older
system, it may be stuck with a version of OpenSSL that does not support TLS 1.3. On the
other side, newer OpenSSL versions might not support SSL 2 or SSL 3. Although this is the
Building OpenSSL 3
right thing to do in a general case, you’ll need support for these older features if your job is
to test systems for security.
You can start by downloading the most recent version of OpenSSL (in my case, 1.1.1g):
$ wget https://www.openssl.org/source/openssl-1.1.1g.tar.gz
The next step is to configure OpenSSL before compilation. For this, you will usually use
the config script, which first attempts to guess your architecture and then runs through the
configuration process:
$ ./config \
--prefix=/opt/openssl \
--openssldir=/opt/openssl \
no-shared \
-DOPENSSL_TLS_SECURITY_LEVEL=2 \
enable-ec_nistp_64_gcc_128
The automated architecture detection can sometimes fail (e.g., with older versions of
OpenSSL on OS X), in which case you should instead invoke the Configure script with the
explicit architecture string. The configuration syntax is otherwise the same.
Unless you’re sure you want to do otherwise, it is essential to use the --prefix option to install
OpenSSL to a private location that doesn’t clash with the system-provided version. Getting
this wrong may break your server. The other important option is no-shared, which forces
static linking and makes self-contained command-line tools. If you don’t use this option,
you’ll need to play with your LD_LIBRARY_PATH configuration to get your tools to work.
When compiling OpenSSL 1.1.0 or later, the OPENSSL_TLS_SECURITY_LEVEL option configures
the default security level, which establishes default minimum security requirements for all
library users. It’s very useful to set this value at compile time as it can be used to prevent
configuration mistakes. I discuss security levels in more detail later in this chapter.
The enable-ec_nistp_64_gcc_128 parameter activates optimized versions of certain frequent-
ly used elliptic curves. This optimization depends on a compiler feature that can’t be auto-
matically detected, which is why it’s disabled by default. The complete set of configuration
options is available on the OpenSSL wiki.4
Note
When compiling software, it’s important to be familiar with the default configuration
of your compiler. System-provided packages are usually compiled using various
hardening options, but if you compile some software yourself there is no guarantee
that the same options will be used.5
4
Compilation and Installation (OpenSSL, retrieved 12 August 2020)
5
Hardening (Debian, 3 August 2020)
OpenSSL 1.1.0 and above will do this automatically, so you can proceed to build the main
package with the following:
$ make
$ make test
$ sudo make install
The private/ folder is empty, but that’s normal; you do not yet have any private keys. On the
other hand, you’ll probably be surprised to learn that the certs/ folder is empty too. OpenSSL
does not include any root certificates; maintaining a trust store is considered outside the scope
of the project. Luckily, your operating system probably already comes with a trust store that
you can use immediately. The following worked on my server:
$ cd /opt/openssl
$ sudo rmdir certs
$ sudo ln -s /etc/ssl/certs
The first part of the help output lists all available utilities. To get more information about a
particular utility, use the man command followed by the name of the utility. For example, man
Standard commands
asn1parse ca ciphers cms
crl crl2pkcs7 dgst dhparam
dsa dsaparam ec ecparam
enc engine errstr gendsa
genpkey genrsa help list
nseq ocsp passwd pkcs12
pkcs7 pkcs8 pkey pkeyparam
pkeyutl prime rand rehash
req rsa rsautl s_client
s_server s_time sess_id smime
speed spkac srp storeutl
ts verify version x509
The help output doesn’t actually end there, but the rest is somewhat less interesting. In the
second part, you get the list of message digest commands:
Message Digest commands (see the `dgst' command for more details)
blake2b512 blake2s256 gost md4
md5 rmd160 sha1 sha224
sha256 sha3-224 sha3-256 sha3-384
sha3-512 sha384 sha512 sha512-224
sha512-256 shake128 shake256 sm3
And then in the third part, you’ll see the list of all cipher commands:
Cipher commands (see the `enc' command for more details)
aes-128-cbc aes-128-ecb aes-192-cbc aes-192-ecb
aes-256-cbc aes-256-ecb aria-128-cbc aria-128-cfb
aria-128-cfb1 aria-128-cfb8 aria-128-ctr aria-128-ecb
aria-128-ofb aria-192-cbc aria-192-cfb aria-192-cfb1
aria-192-cfb8 aria-192-ctr aria-192-ecb aria-192-ofb
aria-256-cbc aria-256-cfb aria-256-cfb1 aria-256-cfb8
aria-256-ctr aria-256-ecb aria-256-ofb base64
bf bf-cbc bf-cfb bf-ecb
bf-ofb camellia-128-cbc camellia-128-ecb camellia-192-cbc
camellia-192-ecb camellia-256-cbc camellia-256-ecb cast
cast-cbc cast5-cbc cast5-cfb cast5-ecb
cast5-ofb des des-cbc des-cfb
des-ecb des-ede des-ede-cbc des-ede-cfb
des-ede-ofb des-ede3 des-ede3-cbc des-ede3-cfb
des-ede3-ofb des-ofb des3 desx
rc2 rc2-40-cbc rc2-64-cbc rc2-cbc
rc2-cfb rc2-ecb rc2-ofb rc4
rc4-40 seed seed-cbc seed-cfb
Unfortunately, its certificate collection is in a proprietary format, which is not of much use to
others as is. If you don’t mind getting the collection via a third party, the Curl project provides
a regularly updated conversion in Privacy-Enhanced Mail (PEM) format, which you can use
directly:
http://curl.haxx.se/docs/caextract.html
If you’d rather work directly with Mozilla, you can convert its data using the same tool that
the Curl project is using. You’ll find more information about it in the following section.
Note
If you have an itch to write your own conversion script, note that Mozilla’s root
certificate file is not a simple list of certificates. Although most of the certificates are
those that are considered trusted, there are also some that are explicitly disallowed.
Additionally, some certificates may only be considered trusted for certain types of
usage. The Perl script I describe here is smart enough to know the difference.
At this point, what you have is a root store with all trusted certificates in the same file. This
will work fine if you’re only going to be using it with, say, the s_client tool. In that case, all
you need to do is point the -CAfile switch to your root store. Replacing the root store on a
server will require more work, depending on what operating system is used.
On Ubuntu, for example, you’ll need to replace the contents of the /etc/ssl/certs folder.
Ubuntu ships with a tool called update-ca-certificates that might work. Alternatively, you
6
Mozilla CA Certificate Store (Mozilla; 9 August 2020)
"It will not be nice for me; I shall not wish to see him; I
don't remember him."
Mrs. Arundel could not keep back a sigh, and Tom was
quick to perceive it. He hated himself for his petulance, and
yet he felt unable to overcome it.
"All right!" said Tom, with a trifle more energy. And then
finding he could look up into the trees with his telescope, he
began to adjust it, and Mrs. Arundel went indoors.
"But, Walter, you should not tell them your bill of fare so
early in the day," said Nellie, laughing.
"Well, anyone who likes all these dainties combined,
must be at this door at half-past eleven precisely."
Next came Arthur and Ada, and the riding party were all
ready.
Mrs. Arundel, Tom, and the baby, with the two servants
and two hampers, were packed into the carriage.
Mrs. Ross and Alfy came to the door to see them off.
The carriage started at the pace of the donkeys, Walter
generally walking by Nellie, and holding Dolly's bridle.
"Pickled salmon?"
"I'm glad you are satisfied; now then to enjoy it. But
first we will ask a blessing." He raised his hat reverently,
and calling to Dolly to be still a moment, he thanked God
for giving them all this pleasure.
"I know where we can get some more," said Ada. "I saw
a little cottage down the other side, and there was a board
up, 'Water or tea to be obtained here.'"
"We will fetch it, won't we, Arthur?" said Ada, jumping
up.
"All right," said Arthur, taking a last bite of a nice tart.
"And look here, mother, I don't think I have quite finished.
Don't you clear it all away!" And with a laugh, he and Ada
scampered off.
He started up. "I? Well I will sing a funny one; and then
when the others come we will see if we can sing something
all together."
"Yes," said Ada, sighing; "I often think of him all alone,
only it spoils one's pleasure so to think about it."
Mary, the nurse, sang a nice second, and they all drew
together into one circle, and the familiar words sounded
wonderfully sweet with all the voices.
"I do not think I need ask how you have been getting
on; your face, your whole life, shows that it is well with
you."
All were very glad of their tea, and the chat was very
merry. Tom was propped up as high as possible, and pushed
close up to the table, and for once felt himself one of the
party. His eyes shone with pleasure, and his mother thought
the sea air must be doing him good. He even stretched out
one of his little thin hands to help pass the cups to his
mamma, and all looked delighted at the success with which
he managed it.
"Well baby can't answer," said Arthur, "so I'll answer for
him: 'Eats and sleeps.'"
"Play with our dolls, and dig, and help Dolly over the
shingle."
"Walk, and dig, and carry baby, and sleep, and eat, and
bathe, and enjoy myself."
"Ah, that's it, is it? Well and good; but I do not mean to
tell you that to-day. Is that hard? I am only going to give
you a hint, which will last you till to-morrow to think about.
I shall not even explain a word about it, and just leave you
this text to think of. I will tell you my little plans to-
morrow."
* * * * * *
By the time all reached the farm, they were pretty well
tired out. Tom was carried up to his mother's room, and she
and Simmons quickly and tenderly undressed him, and laid
him in his little bed. Nurse meanwhile did the same for her
baby; Dolly had a few tears, but denied that she was the
least tired. Nevertheless, before Nellie had well tucked her
up, she was fast asleep. The rest were glad to take arm-
chairs, sofas, or stools, and to rest quietly; while Mrs.
Arundel took out the interesting book she was reading to
them and offered to begin.
CHAPTER VIII.
SETTING TO WORK.
WHEN Walter and Arthur were returning together next
morning from their early bath, Walter referred to the
conversation of the previous evening.
"On and off I have thought about that sort of thing for a
good while," said Arthur, reddening; "but I do not quite see
what you want me to do now."
"You all know that there are many children down here,
come like yourselves for a summer holiday. Of these many,
no doubt, are from Christian families, and have been taught
about God and the Bible as you have. But there are others
who have heard very little of Jesus, or having heard, have
not cared. Should we not like to reach even one of these
children who have never heard?"
Mrs. Arundel had her camp stool close to little Tom, and
she too would be able to help the singing.
If Ada had not loved Nellie she told herself that she
would not have joined, but in order to help her sister she
did her best. And before the end of the first verse, the
children took it up, and the hymn went well to the end.
"'You are not your own!' Now whom do you belong to?"
"The traveller smiled. 'Will you, Harry? And why will you
do anything in the world for me?'
"Yes, children, you are not your own; you are bought
with a price! What price? Is it money? No! Something much
more precious than money! What can it be?
"Now all repeat our text once more: 'Ye are not your
own. For ye are bought with a price: therefore glorify God in
your body, and in your spirit, which are God's.'"
"Your brother?"
CHAPTER IX.
CHRISTINA.
"I do not say it lightly, my dear; nor can I tell you why I
think so; but I feel assured of it."
The people at the lodgings dared not wake her, but sent
quickly for the doctor, who lived near. He soon came; and in
a moment whispered that "their care must be for her."