crypto/heimdal/doc/doxyout/krb5/man/man3/krb5_introduction.3

   1 .TH "krb5_introduction" 3 "11 Jan 2012" "Version 1.5.2" "HeimdalKerberos5library" \" -*- nroff -*-
   2 .ad l
   3 .nh
   4 .SH NAME
   5 krb5_introduction \- Introduction to the Kerberos 5 API
   6 .SH "Kerberos 5 API Overview"
   7 .PP
   8 All functions are documented in manual pages. This section tries to give an overview of the major components used in Kerberos library, and point to where to look for a specific function.
   9 .SS "Kerberos context"
  10 A kerberos context (krb5_context) holds all per thread state. All global variables that are context specific are stored in this structure, including default encryption types, credential cache (for example, a ticket file), and default realms.
  11 .PP
  12 The internals of the structure should never be accessed directly, functions exist for extracting information.
  13 .PP
  14 See the manual page for \fBkrb5_init_context()\fP how to create a context and module \fBHeimdal Kerberos 5 library\fP for more information about the functions.
  15 .SS "Kerberos authentication context"
  16 Kerberos authentication context (krb5_auth_context) holds all context related to an authenticated connection, in a similar way to the kerberos context that holds the context for the thread or process.
  17 .PP
  18 The krb5_auth_context is used by various functions that are directly related to authentication between the server/client. Example of data that this structure contains are various flags, addresses of client and server, port numbers, keyblocks (and subkeys), sequence numbers, replay cache, and checksum types.
  19 .SS "Kerberos principal"
  20 The Kerberos principal is the structure that identifies a user or service in Kerberos. The structure that holds the principal is the krb5_principal. There are function to extract the realm and elements of the principal, but most applications have no reason to inspect the content of the structure.
  21 .PP
  22 The are several ways to create a principal (with different degree of portability), and one way to free it.
  23 .PP
  24 See also the page \fBThe principal handing functions.\fP for more information and also module \fBHeimdal Kerberos 5 principal functions\fP.
  25 .SS "Credential cache"
  26 A credential cache holds the tickets for a user. A given user can have several credential caches, one for each realm where the user have the initial tickets (the first krbtgt).
  27 .PP
  28 The credential cache data can be stored internally in different way, each of them for different proposes. File credential (FILE) caches and processes based (KCM) caches are for permanent storage. While memory caches (MEMORY) are local caches to the local process.
  29 .PP
  30 Caches are opened with \fBkrb5_cc_resolve()\fP or created with \fBkrb5_cc_new_unique()\fP.
  31 .PP
  32 If the cache needs to be opened again (using \fBkrb5_cc_resolve()\fP) \fBkrb5_cc_close()\fP will close the handle, but not the remove the cache. \fBkrb5_cc_destroy()\fP will zero out the cache, remove the cache so it can no longer be referenced.
  33 .PP
  34 See also \fBThe credential cache functions\fP and \fBHeimdal Kerberos 5 credential cache functions\fP .
  35 .SS "Kerberos errors"
  36 Kerberos errors are based on the com_err library. All error codes are 32-bit signed numbers, the first 24 bits define what subsystem the error originates from, and last 8 bits are 255 error codes within the library. Each error code have fixed string associated with it. For example, the error-code -1765328383 have the symbolic name KRB5KDC_ERR_NAME_EXP, and associated error string ``Client's entry in database has expired''.
  37 .PP
  38 This is a great improvement compared to just getting one of the unix error-codes back. However, Heimdal have an extention to pass back customised errors messages. Instead of getting ``Key table entry not found'', the user might back ``failed to find host/host.example.com@EXAMLE.COM(kvno 3) in keytab /etc/krb5.keytab (des-cbc-crc)''. This improves the chance that the user find the cause of the error so you should use the customised error message whenever it's available.
  39 .PP
  40 See also module \fBHeimdal Kerberos 5 error reporting functions\fP .
  41 .SS "Keytab management"
  42 A keytab is a storage for locally stored keys. Heimdal includes keytab support for Kerberos 5 keytabs, Kerberos 4 srvtab, AFS-KeyFile's, and for storing keys in memory.
  43 .PP
  44 Keytabs are used for servers and long-running services.
  45 .PP
  46 See also \fBThe keytab handing functions\fP and \fBHeimdal Kerberos 5 keytab handling functions\fP .
  47 .SS "Kerberos crypto"
  48 Heimdal includes a implementation of the Kerberos crypto framework, all crypto operations. To create a crypto context call \fBkrb5_crypto_init()\fP.
  49 .PP
  50 See also module \fBHeimdal Kerberos 5 cryptography functions\fP .
  51 .SH "Walkthrough of a sample Kerberos 5 client"
  52 .PP
  53 This example contains parts of a sample TCP Kerberos 5 clients, if you want a real working client, please look in appl/test directory in the Heimdal distribution.
  54 .PP
  55 All Kerberos error-codes that are returned from kerberos functions in this program are passed to krb5_err, that will print a descriptive text of the error code and exit. Graphical programs can convert error-code to a human readable error-string with the krb5_get_error_message() function.
  56 .PP
  57 Note that you should not use any Kerberos function before \fBkrb5_init_context()\fP have completed successfully. That is the reason err() is used when \fBkrb5_init_context()\fP fails.
  58 .PP
  59 First the client needs to call krb5_init_context to initialise the Kerberos 5 library. This is only needed once per thread in the program. If the function returns a non-zero value it indicates that either the Kerberos implementation is failing or it's disabled on this host.
  60 .PP
  61 .PP
  62 .nf
  63  #include <krb5.h>
  64
  65  int
  66  main(int argc, char **argv)
  67  {
  68          krb5_context context;
  69
  70          if (krb5_init_context(&context))
  71                  errx (1, 'krb5_context');
  72 .fi
  73 .PP
  74 .PP
  75 Now the client wants to connect to the host at the other end. The preferred way of doing this is using getaddrinfo (for operating system that have this function implemented), since getaddrinfo is neutral to the address type and can use any protocol that is available.
  76 .PP
  77 .PP
  78 .nf
  79          struct addrinfo *ai, *a;
  80          struct addrinfo hints;
  81          int error;
  82
  83          memset (&hints, 0, sizeof(hints));
  84          hints.ai_socktype = SOCK_STREAM;
  85          hints.ai_protocol = IPPROTO_TCP;
  86
  87          error = getaddrinfo (hostname, 'pop3', &hints, &ai);
  88          if (error)
  89                  errx (1, '%s: %s', hostname, gai_strerror(error));
  90
  91          for (a = ai; a != NULL; a = a->ai_next) {
  92                  int s;
  93
  94                  s = socket (a->ai_family, a->ai_socktype, a->ai_protocol);
  95                  if (s < 0)
  96                          continue;
  97                  if (connect (s, a->ai_addr, a->ai_addrlen) < 0) {
  98                          warn ('connect(%s)', hostname);
  99                              close (s);
 100                              continue;
 101                  }
 102                  freeaddrinfo (ai);
 103                  ai = NULL;
 104          }
 105          if (ai) {
 106                      freeaddrinfo (ai);
 107                      errx ('failed to contact %s', hostname);
 108          }
 109 .fi
 110 .PP
 111 .PP
 112 Before authenticating, an authentication context needs to be created. This context keeps all information for one (to be) authenticated connection (see krb5_auth_context).
 113 .PP
 114 .PP
 115 .nf
 116          status = krb5_auth_con_init (context, &auth_context);
 117          if (status)
 118                  krb5_err (context, 1, status, 'krb5_auth_con_init');
 119 .fi
 120 .PP
 121 .PP
 122 For setting the address in the authentication there is a help function krb5_auth_con_setaddrs_from_fd() that does everything that is needed when given a connected file descriptor to the socket.
 123 .PP
 124 .PP
 125 .nf
 126          status = krb5_auth_con_setaddrs_from_fd (context,
 127                                                   auth_context,
 128                                                   &sock);
 129          if (status)
 130                  krb5_err (context, 1, status,
 131                            'krb5_auth_con_setaddrs_from_fd');
 132 .fi
 133 .PP
 134 .PP
 135 The next step is to build a server principal for the service we want to connect to. (See also \fBkrb5_sname_to_principal()\fP.)
 136 .PP
 137 .PP
 138 .nf
 139          status = krb5_sname_to_principal (context,
 140                                            hostname,
 141                                            service,
 142                                            KRB5_NT_SRV_HST,
 143                                            &server);
 144          if (status)
 145                  krb5_err (context, 1, status, 'krb5_sname_to_principal');
 146 .fi
 147 .PP
 148 .PP
 149 The client principal is not passed to krb5_sendauth() function, this causes the krb5_sendauth() function to try to figure it out itself.
 150 .PP
 151 The server program is using the function krb5_recvauth() to receive the Kerberos 5 authenticator.
 152 .PP
 153 In this case, mutual authentication will be tried. That means that the server will authenticate to the client. Using mutual authentication is good since it enables the user to verify that they are talking to the right server (a server that knows the key).
 154 .PP
 155 If you are using a non-blocking socket you will need to do all work of krb5_sendauth() yourself. Basically you need to send over the authenticator from krb5_mk_req() and, in case of mutual authentication, verifying the result from the server with krb5_rd_rep().
 156 .PP
 157 .PP
 158 .nf
 159          status = krb5_sendauth (context,
 160                                  &auth_context,
 161                                  &sock,
 162                                  VERSION,
 163                                  NULL,
 164                                  server,
 165                                  AP_OPTS_MUTUAL_REQUIRED,
 166                                  NULL,
 167                                  NULL,
 168                                  NULL,
 169                                  NULL,
 170                                  NULL,
 171                                  NULL);
 172          if (status)
 173                  krb5_err (context, 1, status, 'krb5_sendauth');
 174 .fi
 175 .PP
 176 .PP
 177 Once authentication has been performed, it is time to send some data. First we create a krb5_data structure, then we sign it with krb5_mk_safe() using the auth_context that contains the session-key that was exchanged in the krb5_sendauth()/krb5_recvauth() authentication sequence.
 178 .PP
 179 .PP
 180 .nf
 181          data.data   = 'hej';
 182          data.length = 3;
 183
 184          krb5_data_zero (&packet);
 185
 186          status = krb5_mk_safe (context,
 187                                 auth_context,
 188                                 &data,
 189                                 &packet,
 190                                 NULL);
 191          if (status)
 192                  krb5_err (context, 1, status, 'krb5_mk_safe');
 193 .fi
 194 .PP
 195 .PP
 196 And send it over the network.
 197 .PP
 198 .PP
 199 .nf
 200          len = packet.length;
 201          net_len = htonl(len);
 202
 203          if (krb5_net_write (context, &sock, &net_len, 4) != 4)
 204                  err (1, 'krb5_net_write');
 205          if (krb5_net_write (context, &sock, packet.data, len) != len)
 206                  err (1, 'krb5_net_write');
 207 .fi
 208 .PP
 209 .PP
 210 To send encrypted (and signed) data krb5_mk_priv() should be used instead. krb5_mk_priv() works the same way as krb5_mk_safe(), with the exception that it encrypts the data in addition to signing it.
 211 .PP
 212 .PP
 213 .nf
 214          data.data   = 'hemligt';
 215          data.length = 7;
 216
 217          krb5_data_free (&packet);
 218
 219          status = krb5_mk_priv (context,
 220                                 auth_context,
 221                                 &data,
 222                                 &packet,
 223                                 NULL);
 224          if (status)
 225                  krb5_err (context, 1, status, 'krb5_mk_priv');
 226 .fi
 227 .PP
 228 .PP
 229 And send it over the network.
 230 .PP
 231 .PP
 232 .nf
 233          len = packet.length;
 234          net_len = htonl(len);
 235
 236          if (krb5_net_write (context, &sock, &net_len, 4) != 4)
 237                  err (1, 'krb5_net_write');
 238          if (krb5_net_write (context, &sock, packet.data, len) != len)
 239                  err (1, 'krb5_net_write');
 240 .fi
 241 .PP
 242 .PP
 243 The server is using krb5_rd_safe() and krb5_rd_priv() to verify the signature and decrypt the packet.
 244 .SH "Validating a password in an application"
 245 .PP
 246 See the manual page for krb5_verify_user().
 247 .SH "API differences to MIT Kerberos"
 248 .PP
 249 This section is somewhat disorganised, but so far there is no overall structure to the differences, though some of the have their root in that Heimdal uses an ASN.1 compiler and MIT doesn't.
 250 .SS "Principal and realms"
 251 Heimdal stores the realm as a krb5_realm, that is a char *. MIT Kerberos uses a krb5_data to store a realm.
 252 .PP
 253 In Heimdal krb5_principal doesn't contain the component name_type; it's instead stored in component name.name_type. To get and set the nametype in Heimdal, use \fBkrb5_principal_get_type()\fP and \fBkrb5_principal_set_type()\fP.
 254 .PP
 255 For more information about principal and realms, see krb5_principal.
 256 .SS "Error messages"
 257 To get the error string, Heimdal uses krb5_get_error_message(). This is to return custom error messages (like ``Can't find host/datan.example.com@CODE.COM in /etc/krb5.conf.'' instead of a ``Key table entry not found'' that error_message returns.
 258 .PP
 259 Heimdal uses a threadsafe(r) version of the com_err interface; the global com_err table isn't initialised. Then error_message returns quite a boring error string (just the error code itself).