This Document Includes Text Contributed by Nikos Mavrogiannopoulos, Simon Josefsson, Daiki Ueno, Carolin Latze, Alfredo Pironti, Ted Zlatanov and Andrew Mcdonald
Total Page:16
File Type:pdf, Size:1020Kb
This document includes text contributed by Nikos Mavrogiannopoulos, Simon Josefsson, Daiki Ueno, Carolin Latze, Alfredo Pironti, Ted Zlatanov and Andrew McDonald. Several corrections are due to Patrick Pelletier and Andreas Metzler. ISBN 978-1-326-00266-4 Copyright © 2001-2015 Free Software Foundation, Inc. Copyright © 2001-2019 Nikos Mavrogiannopoulos Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled \GNU Free Documentation License". Contents Preface xiii 1. Introduction to GnuTLS1 1.1. Downloading and installing.............................1 1.2. Installing for a software distribution........................2 1.3. Overview.......................................3 2. Introduction to TLS and DTLS5 2.1. TLS Layers......................................5 2.2. The Transport Layer.................................5 2.3. The TLS record protocol...............................6 2.3.1. Encryption algorithms used in the record layer..............6 2.3.2. Compression algorithms and the record layer...............8 2.3.3. On record padding..............................8 2.4. The TLS alert protocol...............................9 2.5. The TLS handshake protocol............................ 10 2.5.1. TLS ciphersuites............................... 11 2.5.2. Authentication................................ 11 2.5.3. Client authentication............................. 11 2.5.4. Resuming sessions.............................. 12 2.6. TLS extensions.................................... 12 2.6.1. Maximum fragment length negotiation................... 12 2.6.2. Server name indication............................ 12 2.6.3. Session tickets................................ 13 2.6.4. HeartBeat................................... 13 2.6.5. Safe renegotiation.............................. 14 2.6.6. OCSP status request............................. 15 2.6.7. SRTP..................................... 16 2.6.8. False Start.................................. 17 2.6.9. Application Layer Protocol Negotiation (ALPN)............. 17 2.6.10. Extensions and Supplemental Data..................... 18 2.7. How to use TLS in application protocols...................... 18 2.7.1. Separate ports................................ 18 2.7.2. Upward negotiation............................. 19 2.8. On SSL 2 and older protocols............................ 20 3. Authentication methods 21 3.1. Certificate authentication.............................. 21 3.1.1. X.509 certificates............................... 21 3.1.2. OpenPGP certificates............................ 36 3.1.3. Raw public-keys............................... 36 3.1.4. Advanced certificate verification...................... 37 iii Contents 3.1.5. Digital signatures............................... 38 3.2. More on certificate authentication......................... 39 3.2.1. PKCS #10 certificate requests....................... 39 3.2.2. PKIX certificate revocation lists...................... 42 3.2.3. OCSP certificate status checking...................... 45 3.2.4. OCSP stapling................................ 49 3.2.5. Managing encrypted keys.......................... 51 3.2.6. Invoking certtool............................... 55 3.2.7. Invoking ocsptool............................... 76 3.2.8. Invoking danetool.............................. 81 3.3. Shared-key and anonymous authentication..................... 87 3.3.1. PSK authentication............................. 87 3.3.2. SRP authentication............................. 89 3.3.3. Anonymous authentication......................... 92 3.4. Selecting an appropriate authentication method.................. 93 3.4.1. Two peers with an out-of-band channel.................. 93 3.4.2. Two peers without an out-of-band channel................ 93 3.4.3. Two peers and a trusted third party.................... 93 4. Abstract key types and Hardware security modules 101 4.1. Abstract key types.................................. 101 4.1.1. Public keys.................................. 102 4.1.2. Private keys.................................. 104 4.1.3. Operations.................................. 107 4.2. System and application-specific keys........................ 110 4.2.1. System-specific keys............................. 110 4.2.2. Application-specific keys........................... 111 4.3. Smart cards and HSMs................................ 112 4.3.1. Initialization................................. 112 4.3.2. Manual initialization of user-specific modules............... 113 4.3.3. Accessing objects that require a PIN.................... 114 4.3.4. Reading objects................................ 116 4.3.5. Writing objects................................ 119 4.3.6. Low Level Access............................... 120 4.3.7. Using a PKCS #11 token with TLS.................... 120 4.3.8. Verifying certificates over PKCS #11.................... 121 4.3.9. Invoking p11tool............................... 121 4.4. Trusted Platform Module (TPM).......................... 133 4.4.1. Keys in TPM................................. 134 4.4.2. Key generation................................ 134 4.4.3. Using keys.................................. 135 4.4.4. Invoking tpmtool............................... 136 5. How to use GnuTLS in applications 141 5.1. Introduction...................................... 141 5.1.1. General idea................................. 141 iv Contents 5.1.2. Error handling................................ 142 5.1.3. Common types................................ 143 5.1.4. Debugging and auditing........................... 143 5.1.5. Thread safety................................. 145 5.1.6. Running in a sandbox............................ 145 5.1.7. Sessions and fork............................... 146 5.1.8. Callback functions.............................. 146 5.2. Preparation...................................... 147 5.2.1. Headers.................................... 147 5.2.2. Initialization................................. 147 5.2.3. Version check................................. 147 5.2.4. Building the source.............................. 148 5.3. Session initialization................................. 149 5.4. Associating the credentials.............................. 149 5.4.1. Certificates.................................. 149 5.4.2. Raw public-keys............................... 156 5.4.3. SRP...................................... 156 5.4.4. PSK...................................... 158 5.4.5. Anonymous.................................. 160 5.5. Setting up the transport layer............................ 160 5.5.1. Asynchronous operation........................... 164 5.5.2. Reducing round-trips............................. 165 5.5.3. Zero-roundtrip mode............................. 166 5.5.4. Anti-replay protection............................ 167 5.5.5. DTLS sessions................................ 168 5.5.6. DTLS and SCTP............................... 169 5.6. TLS handshake.................................... 170 5.7. Data transfer and termination............................ 171 5.8. Buffered data transfer................................ 173 5.9. Handling alerts.................................... 174 5.10. Priority strings.................................... 176 5.11. Selecting cryptographic key sizes.......................... 179 5.12. Advanced topics................................... 180 5.12.1. Virtual hosts and credentials........................ 180 5.12.2. Session resumption.............................. 181 5.12.3. Certificate verification............................ 185 5.12.4. TLS 1.2 re-authentication.......................... 188 5.12.5. TLS 1.3 re-authentication and re-key.................... 189 5.12.6. Parameter generation............................ 190 5.12.7. Deriving keys for other applications/protocols............... 192 5.12.8. Channel bindings............................... 193 5.12.9. Interoperability................................ 193 5.12.10.Compatibility with the OpenSSL library.................. 194 v Contents 6. GnuTLS application examples 203 6.1. Client examples.................................... 203 6.1.1. Client example with X.509 certificate support............... 203 6.1.2. Datagram TLS client example....................... 206 6.1.3. Using a smart card with TLS........................ 208 6.1.4. Client with resume capability example................... 211 6.1.5. Client example with SSH-style certificate verification........... 214 6.2. Server examples.................................... 216 6.2.1. Echo server with X.509 authentication................... 216 6.2.2. DTLS echo server with X.509 authentication............... 220 6.3. More advanced client and servers.......................... 227 6.3.1. Client example with anonymous authentication.............. 227 6.3.2. Using a callback to select the certificate to use.............. 229 6.3.3. Obtaining session information........................ 233 6.3.4. Advanced certificate verification...................... 235 6.3.5. Client example with PSK authentication.................. 238 6.3.6. Client example with SRP authentication.................. 241 6.3.7. Legacy client example with X.509 certificate support........... 243 6.3.8. Client example using the C++ API.................... 246 6.3.9. Echo server with PSK authentication...................