├── .gitignore ├── CONTRIBUTING ├── LICENSE ├── Makefile ├── README ├── foundations └── about │ └── about.tex └── openssl-book.tex /.gitignore: -------------------------------------------------------------------------------- 1 | #PDF, aux and log files 2 | *.pdf 3 | *.log 4 | *.aux 5 | 6 | #Top level auto-generated files 7 | openssl-book.out 8 | openssl-book.toc 9 | -------------------------------------------------------------------------------- /CONTRIBUTING: -------------------------------------------------------------------------------- 1 | To report a problem with this guide please open an issue on GitHub. 2 | 3 | To submit a minor patch to this guide please open a pull request on GitHub. Note 4 | that we do not accept merge commits; You will be asked to remove them before a 5 | patch is considered acceptable. 6 | 7 | To contribute significant content (e.g. a new chapter) you should also open a 8 | pull request on GitHub. However please discuss the outline of your chapter 9 | content on the openssl-dev email list before starting work (see 10 | https://mta.openssl.org for details). 11 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | The License is TBD. It will most likely be one of 2 | 3 | Apache v2 License 4 | CC-BY 4.0 5 | The OpenSSL License 6 | 7 | Please only contribute to this project if you are willing for your content to be 8 | licensed using one of the above or a similar Open Source license. 9 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | # Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. 2 | # 3 | #Location of the openssl version we are using. May not be the same as the system 4 | #version 5 | OSSLDIR= /usr/local/ssl 6 | CC= gcc 7 | CFLAGS= -I$(OSSLDIR)/include -L$(OSSLDIR)/lib -g -lcrypto -lssl 8 | 9 | #No exe's to build yet 10 | EXE= 11 | 12 | BOOKELEMS= openssl-book.tex 13 | 14 | all: openssl-book.pdf 15 | 16 | $(EXE): %: %.c 17 | $(CC) -o $@ $< $(CFLAGS) 18 | 19 | #We run this twice to ensure that any references etc are updated 20 | openssl-book.pdf: $(BOOKELEMS) $(EXE) 21 | pdflatex openssl-book 22 | pdflatex openssl-book 23 | 24 | code: $(EXE) 25 | 26 | clean-code: 27 | rm $(EXE) 28 | 29 | clean-book: 30 | rm openssl-book.pdf openssl-book.log openssl-book.aux openssl-book.out 31 | 32 | #Add clean-code here when we actually have code to clean 33 | clean: clean-book 34 | -------------------------------------------------------------------------------- /README: -------------------------------------------------------------------------------- 1 | Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. 2 | 3 | Overview 4 | ======== 5 | 6 | The OpenSSL Guide is an attempt to create better documentation for the OpenSSL 7 | Toolkit. Until now the following types of documentation exist: 8 | 9 | 1) Man pages 10 | 2) Wiki 11 | 12 | The man pages are a reference guide and useful for looking up the specific usage 13 | of a particular command or function. The wiki is a an unreviewed community 14 | resource which may contain content on a wide range of subjects. Typically this 15 | content is relatively short and focussed on a particular subject area. The wiki 16 | is intended to have a relatively low barrier of entry to encourage community 17 | collaboration. 18 | 19 | This book is intended to fill a "gap" in this documentation, i.e. to provide a 20 | definitive, trusted source of introductory and "guide" style material that will 21 | enable a reader who is unfamiliar with OpenSSL to learn more about it. It will 22 | contain content that should enable the reader to get to a level of familiarity 23 | with OpenSSL that they can then use the other documentation sources (such as the 24 | man pages) to find detailed information as required. 25 | 26 | NOTE: This is a very initial draft and there is no content in the guide yet! 27 | 28 | Building the OpenSSL Guide 29 | ========================== 30 | 31 | The following prerequisites are needed in order to build the guide: 32 | 33 | - TeX Live 34 | - gcc 35 | - make 36 | 37 | Assuming you have all of the above installed on your system, then creating the 38 | guide is simply a matter of typing "make" from the command line: 39 | 40 | $ make 41 | 42 | The output should be "openssl-book.pdf". 43 | -------------------------------------------------------------------------------- /foundations/about/about.tex: -------------------------------------------------------------------------------- 1 | \chapter{About OpenSSL} 2 | 3 | \todo{Add some text here.} 4 | -------------------------------------------------------------------------------- /openssl-book.tex: -------------------------------------------------------------------------------- 1 | \documentclass[oneside]{book} 2 | \author{The OpenSSL Project} 3 | \title{The OpenSSL Guide} 4 | 5 | \usepackage{color} 6 | \usepackage{colortbl} 7 | \usepackage{graphicx} 8 | \usepackage[hidelinks]{hyperref} 9 | \usepackage{listings} 10 | \usepackage{xcolor} 11 | \usepackage{outline} 12 | \newcommand\todo[1]{\textcolor{red}{[TODO:#1]}} 13 | \definecolor{LightGray}{gray}{0.9} 14 | \lstdefinestyle{osslc}{ 15 | breaklines=true, 16 | frame=single, 17 | xleftmargin=\parindent, 18 | language=C, 19 | showstringspaces=false, 20 | basicstyle=\footnotesize\ttfamily, 21 | numbers=left, 22 | numberstyle=\tiny, 23 | captionpos=b 24 | } 25 | 26 | \begin{document} 27 | \lstset{style=osslc} 28 | \maketitle 29 | \tableofcontents 30 | 31 | \part{Foundations} 32 | 33 | \chapter{Outline - to be deleted} 34 | 35 | \begin{outline} 36 | \item{Part: Foundations} 37 | \begin{outline} 38 | \item{Chapter: Introduction} 39 | \begin{outline} 40 | \item{Purpose of this book} 41 | \item{Layout and how to navigate this book} 42 | \item{This is an open source book} 43 | \item{About the authors} 44 | \end{outline} 45 | \item{Chapter: About OpenSSL} 46 | \begin{outline} 47 | \item{What is OpenSSL} 48 | \begin{outline} 49 | \item{Describe OpenSSL as a command line tool} 50 | \item{Describe OpenSSL as a SSL/TLS/DTLS library} 51 | \item{Describe OpenSSL as a crypto library} 52 | \end{outline} 53 | \item{OpenSSL History} 54 | \begin{outline} 55 | \item{SSLeay} 56 | \item{OpenSSL formation} 57 | \item{The lean years and FIPS} 58 | \item{Changes in the team membership and processes} 59 | \item{OpenSSL today} 60 | \end{outline} 61 | \end{outline} 62 | \item{Chapter: Getting OpenSSL} 63 | \begin{outline} 64 | \item{OpenSSL Version Numbering} 65 | \item{Using pre-built binaries} 66 | \item{Pre-requisites for building OpenSSL from source} 67 | \item{Compiling and installing from source} 68 | \item{Troubleshooting some common build issues} 69 | \end{outline} 70 | \item{Chapter: Programming Fundamentals} 71 | \begin{outline} 72 | \item{Memory management} 73 | \begin{outline} 74 | \item{new and free functions} 75 | \item{OPENSSL\_malloc, OPENSSL\_zalloc and OPENSSL\_free} 76 | \item{get0, get1, set0, set1 etc} 77 | \item{Debugging memory issues} 78 | \end{outline} 79 | \item{BIOs} 80 | \item{Serialisation and De-serialisation} 81 | \begin{outline} 82 | \item{i2d and d2i functions} 83 | \end{outline} 84 | \item{Stacks} 85 | \item{LHashes} 86 | \item{NIDs} 87 | \item{Identifying the OpenSSL version} 88 | \item{Automatic Library Initialisation and De-initialisation} 89 | \item{Threads} 90 | \end{outline} 91 | \item{Chapter: Certificates and Certificate Authorities} 92 | \item{Chapter: Working with Certificate and Key files} 93 | \begin{outline} 94 | \item{PEM files} 95 | \item{PKCS8 files} 96 | \item{PCKS12 files} 97 | \end{outline} 98 | \item{Chapter: Certificate Revocation} 99 | \begin{outline} 100 | \item{CRLs} 101 | \item{OCSP} 102 | \end{outline} 103 | \item{Chapter: Configuration via CONF} 104 | \item{Chapter: Engines (Advanced Topic)} 105 | \item{Chapter: Stores (Advanced Topic)} 106 | \item{Chapter: Advanced Certificates (Advanced Topic)} 107 | \item{Chapter: Certificate Transparency (Advanced Topic)} 108 | \item{Chapter: Asynchronous operation (Advanced Topic)} 109 | \item{Chapter: ASN.1 (Advanced Topic)} 110 | \item{Chapter: UIs (Advanced Topic)} 111 | \end{outline} 112 | \item{Part: SSL/TLS/DTLS} 113 | \begin{outline} 114 | \item{Chapter: Understanding SSL/TLS} 115 | \begin{outline} 116 | \item{Security properties of an SSL/TLS connection} 117 | \item{Overview of SSL/TLS versions} 118 | \item{Overview of establishing identity} 119 | \item{Overview of ciphersuites} 120 | \item{Records} 121 | \item{Overview of the Handshake} 122 | \item{Sessions and resumption} 123 | \end{outline} 124 | \item{Chapter: Getting Started} 125 | \begin{outline} 126 | \item{Creating an SSL\_CTX} 127 | \item{Creating a self-signed certificate} 128 | \item{Starting the test server} 129 | \item{A simple client} 130 | \begin{outline} 131 | \item{Connecting} 132 | \item{Exchanging data} 133 | \item{Shutting down} 134 | \end{outline} 135 | \item{Compilation} 136 | \item{Running the client} 137 | \item{Adding the trusted CAs} 138 | \item{A simple server} 139 | \begin{outline} 140 | \item{Setting up the SSL\_CTX} 141 | \item{Accepting incoming connections} 142 | \end{outline} 143 | \end{outline} 144 | \item{Chapter: Ciphersuites} 145 | \begin{outline} 146 | \item{Parts of the Ciphersuite} 147 | \item{Ciphersuite Naming} 148 | \item{TLSv1.3 Ciphersuites} 149 | \item{Configuring the available Ciphersuites} 150 | \item{Ciphersuite selection (client vs server preference)} 151 | \item{Key Exchange Mechanisms} 152 | \begin{outline} 153 | \item{RSA} 154 | \item{DHE} 155 | \item{ECDHE (covering some basics of curve types: P-256, X25519 etc)} 156 | \item{SRP} 157 | \item{PSK} 158 | \end{outline} 159 | \item{Authentication} 160 | \begin{outline} 161 | \item{RSA} 162 | \item{ECDSA} 163 | \item{EdDSA? (future)} 164 | \end{outline} 165 | \item{Encryption} 166 | \begin{outline} 167 | \item{AES} 168 | \item{Camellia} 169 | \item{ChaCha} 170 | \item{etc} 171 | \end{outline} 172 | \item{MAC/AEAD} 173 | \end{outline} 174 | \item{Chapter: Basic Operation} 175 | \begin{outline} 176 | \item{The read and write BIOs} 177 | \item{Alerts} 178 | \item{Version Negotiation} 179 | \item{SSL\_read, SSL\_write and SSL\_get\_error} 180 | \begin{outline} 181 | \item{Non-blocking IO} 182 | \item{Pending data} 183 | \end{outline} 184 | \item{Shutting down} 185 | \item{Client Authentication} 186 | \item{Renegotiation} 187 | \item{Compression} 188 | \item{SSL BIO} 189 | \item{Exporting secrets} 190 | \end{outline} 191 | \item{Chapter: Sessions} 192 | \begin{outline} 193 | \item{Resumption handshakes} 194 | \item{Simple sessions and session files} 195 | \item{Session tickets} 196 | \item{Session caches} 197 | \end{outline} 198 | \item{Chapter: Configuration} 199 | \begin{outline} 200 | \item{Setting options and modes} 201 | \begin{outline} 202 | \item{Some common options/modes} 203 | \begin{outline} 204 | \item{SSL\_MODE\_AUTO\_RETRY} 205 | \item{SSL\_MODE\_RELEASE\_BUFFERS} 206 | \end{outline} 207 | \end{outline} 208 | \item{Signature Algorithms} 209 | \item{Supported Groups} 210 | \item{Configuration using SSL\_CONF} 211 | \item{Security levels and the security callbacks} 212 | \end{outline} 213 | \item{Chapter: DTLS} 214 | \begin{outline} 215 | \item{Key differences with TLS} 216 | \item{Transports} 217 | \begin{outline} 218 | \item{UDP} 219 | \item{SCTP} 220 | \item{MTU issues} 221 | \end{outline} 222 | \item{Retransmissions and the DTLS timer} 223 | \item{Listening for connections and cookies} 224 | \end{outline} 225 | \item{Chapter: TLSv1.3} 226 | \item{Chapter: Debugging Connection Failures} 227 | \item{Chapter: Advanced Extensions (Advanced Topic)} 228 | \begin{outline} 229 | \item{SNI} 230 | \item{ALPN and NPN} 231 | \item{SRTP} 232 | \item{EC point formats} 233 | \item{Extended Master Secret} 234 | \item{Encrypt-Then-MAC} 235 | \item{OCSP in SSL/TLS} 236 | \item{Certificate Transparency in SSL/TLS} 237 | \item{Custom extensions} 238 | \end{outline} 239 | \item{Chapter: DANE (Advanced Topic)} 240 | \item{Chapter: Optimisation (Advanced Topic)} 241 | \begin{outline} 242 | \item{Multiblock} 243 | \item{Async} 244 | \item{Pipelining} 245 | \item{Fragment sizes} 246 | \item{Read ahead} 247 | \end{outline} 248 | \end{outline} 249 | \item{Part: Cryptography} 250 | \begin{outline} 251 | \item{Chapter: Working with BIGNUMs} 252 | \item{Chapter: Random Numbers} 253 | \item{Chapter: Encryption and Decryption (Symmetric)} 254 | \begin{outline} 255 | \item{What is symmetric encryption} 256 | \item{Block and stream ciphers} 257 | \item{Modes} 258 | \item{IVs and Nonces} 259 | \item{A simple encryption/decryption example} 260 | \item{AEAD} 261 | \begin{outline} 262 | \item{Tags} 263 | \item{GCM} 264 | \item{OCB} 265 | \item{CCM} 266 | \item{ChaCha20-Poly1305} 267 | \end{outline} 268 | \item{XTS} 269 | \end{outline} 270 | \item{Chapter: Asymmetric encryption and decryption} 271 | \item{Chapter: Digital signatures} 272 | \item{Chapter: Hashes} 273 | \item{Chapter: Message Authentication Codes} 274 | \item{Chapter: Key Generation and Derivation} 275 | \item{Chapter: CMS (PKCS.7) and S/MIME (Advanced Topic)} 276 | \item{Chapter: Elliptic Curves (Advanced Topic)} 277 | \end{outline} 278 | \end{outline} 279 | 280 | \include{foundations/about/about} 281 | 282 | \part{SSL/TLS/DTLS} 283 | 284 | \part{Cryptography} 285 | 286 | \end{document} 287 | --------------------------------------------------------------------------------