doc/internals.texi

   1 This chapter is to give a brief description of the
   2 way @acronym{GnuTLS} works. The focus is to give an idea
   3 to potential developers and those who want to know what
   4 happens inside the black box.
   5
   6 @section The TLS protocol
   7 The main needs for the TLS protocol to be used are
   8 shown in the image below.
   9
  10 @image{arch/client-server-use-case,9cm}
  11
  12 This is being accomplished by the following object diagram.
  13 Note that since @acronym{GnuTLS} is being developed in C
  14 object are just structures with attributes. The operations listed
  15 are functions that require the first parameter to be that object.
  16 @image{arch/objects,15cm}
  17
  18 @section TLS Handshake protocol
  19 The @acronym{GnuTLS} handshake protocol is implemented as a state
  20 machine that waits for input or returns immediately when the non-blocking
  21 transport layer functions are used. The main idea is shown in the following
  22 figure.
  23
  24 @image{arch/handshake-state,9cm}
  25
  26 Also the way the input is processed varies per ciphersuite. Several
  27 implementations of the internal handlers are available and
  28 @ref{gnutls_handshake} only multiplexes the input to the appropriate
  29 handler. For example a @acronym{PSK} ciphersuite has a different
  30 implementation of the @code{process_client_key_exchange} than a
  31 certificate ciphersuite.
  32
  33 @image{arch/handshake-sequence,12cm}
  34
  35 @section TLS authentication methods
  36 In @acronym{GnuTLS} authentication methods can be implemented quite easily.
  37 Since the required changes to add a new authentication method affect only the
  38 handshake protocol, a simple interface is used. An authentication method needs
  39 only to implement the functions as seen in the figure below.
  40
  41 @image{arch/mod_auth_st,12cm}
  42
  43 The functions that need to be implemented are the ones responsible for interpreting
  44 the handshake protocol messages. It is common for such functions to read data from
  45 one or more @code{credentials_t} structures@footnote{such as the @code{gnutls_certificate_credentials_t} structures} and write data, such as certificates, usernames etc. to @code{auth_info_t} structures.
  46
  47 Simple examples of existing authentication methods can be seen in @code{auth_psk.c}
  48 for PSK ciphersuites and @code{auth_srp.c} for SRP ciphersuites. After implementing these functions
  49 the structure holding its pointers has to be registered in @code{gnutls_algorithms.c}
  50 in the @code{_gnutls_kx_algorithms} structure.
  51
  52 @section TLS Extension handling
  53 As with authentication methods, the TLS extensions handlers can be implemented
  54 using the following interface.
  55
  56 @image{arch/extensions_st,12cm}
  57
  58 Here there are two functions, one for receiving the extension data
  59 and one for sending. These functions have to check internally whether
  60 they operate in client or server side.
  61
  62 A simple example of an extension handler can be seen in @code{ext_srp.c}
  63 After implementing these functions, together with the extension number they
  64 handle, they have to be registered in @code{gnutls_extensions.c} in the
  65 @code{_gnutls_extensions} structure.
  66
  67
  68 @section Certificate handling
  69 What is provided by the certificate handling functions
  70 is summarized in the following diagram.
  71
  72 @image{arch/certificate-user-use-case,12cm}