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 c 2001-2015 Free Software Foundation, Inc. Copyright c 2001-2015 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 used in the record layer.............8 2.3.3. Weaknesses and countermeasures......................8 2.3.4. On record padding..............................9 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.............................. 11 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. Application Layer Protocol Negotiation (ALPN)............. 17 2.6.9. 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............................. 18 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. Advanced certificate verification...................... 38 3.1.4. Digital signatures............................... 39 iii Contents 3.2. More on certificate authentication......................... 41 3.2.1. PKCS #10 certificate requests....................... 41 3.2.2. PKIX certificate revocation lists...................... 44 3.2.3. OCSP certificate status checking...................... 47 3.2.4. Managing encrypted keys.......................... 51 3.2.5. Invoking certtool............................... 55 3.2.6. Invoking ocsptool............................... 72 3.2.7. Invoking danetool.............................. 76 3.3. Shared-key and anonymous authentication..................... 82 3.3.1. SRP authentication............................. 82 3.3.2. PSK authentication............................. 86 3.3.3. Anonymous authentication......................... 88 3.4. Selecting an appropriate authentication method.................. 88 3.4.1. Two peers with an out-of-band channel.................. 88 3.4.2. Two peers without an out-of-band channel................ 89 3.4.3. Two peers and a trusted third party.................... 89 4. Abstract keys types and Hardware security modules 97 4.1. Abstract key types.................................. 97 4.1.1. Public keys.................................. 98 4.1.2. Private keys.................................. 100 4.1.3. Operations.................................. 102 4.2. System and application-specific keys........................ 105 4.2.1. System-specific keys............................. 105 4.2.2. Application-specific keys........................... 105 4.3. Smart cards and HSMs................................ 107 4.3.1. Initialization................................. 107 4.3.2. Accessing objects that require a PIN.................... 109 4.3.3. Reading objects................................ 110 4.3.4. Writing objects................................ 113 4.3.5. Using a PKCS #11 token with TLS.................... 114 4.3.6. Invoking p11tool............................... 114 4.3.7. p11tool help/usage (\--help")....................... 115 4.3.8. token-related-options options........................ 117 4.3.9. object-list-related-options options...................... 117 4.3.10. keygen-related-options options....................... 118 4.3.11. write-object-related-options options.................... 119 4.3.12. other-options options............................. 121 4.3.13. p11tool exit status.............................. 123 4.3.14. p11tool See Also............................... 123 4.3.15. p11tool Examples.............................. 123 4.4. Trusted Platform Module (TPM).......................... 124 4.4.1. Keys in TPM................................. 124 4.4.2. Key generation................................ 125 4.4.3. Using keys.................................. 126 4.4.4. Invoking tpmtool............................... 127 iv Contents 4.4.5. tpmtool help/usage (\--help")....................... 128 4.4.6. debug option (-d)............................... 129 4.4.7. generate-rsa option.............................. 129 4.4.8. user option.................................. 129 4.4.9. system option................................. 129 4.4.10. test-sign option................................ 130 4.4.11. sec-param option............................... 130 4.4.12. inder option.................................. 130 4.4.13. outder option................................. 130 4.4.14. tpmtool exit status.............................. 130 4.4.15. tpmtool See Also............................... 130 4.4.16. tpmtool Examples.............................. 131 5. How to use GnuTLS in applications 133 5.1. Introduction...................................... 133 5.1.1. General idea................................. 133 5.1.2. Error handling................................ 134 5.1.3. Common types................................ 135 5.1.4. Debugging and auditing........................... 135 5.1.5. Thread safety................................. 136 5.1.6. Running in a sandbox............................ 137 5.1.7. Sessions and fork............................... 138 5.1.8. Callback functions.............................. 138 5.2. Preparation...................................... 139 5.2.1. Headers.................................... 139 5.2.2. Initialization................................. 139 5.2.3. Version check................................. 139 5.2.4. Building the source.............................. 140 5.3. Session initialization................................. 140 5.4. Associating the credentials.............................. 142 5.4.1. Certificates.................................. 142 5.4.2. SRP...................................... 147 5.4.3. PSK...................................... 149 5.4.4. Anonymous.................................. 150 5.5. Setting up the transport layer............................ 151 5.5.1. Asynchronous operation........................... 154 5.5.2. DTLS sessions................................ 155 5.6. TLS handshake.................................... 156 5.7. Data transfer and termination............................ 158 5.8. Buffered data transfer................................ 161 5.9. Handling alerts.................................... 161 5.10. Priority strings.................................... 163 5.11. Selecting cryptographic key sizes.......................... 168 5.12. Advanced topics................................... 170 5.12.1. Session resumption.............................. 170 5.12.2. Certificate verification............................ 172 v Contents 5.12.3. Re-authentication.............................. 175 5.12.4. Parameter generation............................ 177 5.12.5. Deriving keys for other applications/protocols............... 178 5.12.6. Channel bindings............................... 178 5.12.7. Interoperability................................ 179 5.12.8. Compatibility with the OpenSSL library.................. 179 6. GnuTLS application examples 181 6.1. Client examples.................................... 181 6.1.1. Simple client example with X.509 certificate support........... 181 6.1.2. Simple client example with SSH-style certificate verification....... 184 6.1.3. Simple client example with anonymous authentication.......... 186 6.1.4. Simple datagram TLS client example.................... 188 6.1.5. Obtaining session information........................ 191 6.1.6. Using a callback to select the certificate to use.............. 193 6.1.7. Verifying a certificate............................ 198 6.1.8. Using a smart card with TLS........................ 200 6.1.9. Client with resume capability example................... 203 6.1.10. Simple client