doc/rst_source/krb_appldev/init_creds.rst

   1 Initial credentials
   2 ===================
   3
   4 Software that performs tasks such as logging users into a computer
   5 when they type their Kerberos password needs to get initial
   6 credentials (usually ticket granting tickets) from Kerberos.  Such
   7 software shares some behavior with the :ref:`kinit(1)` program.
   8
   9 Whenever a program grants access to a resource (such as a local login
  10 session on a desktop computer) based on a user successfully getting
  11 initial Kerberos credentials, it must verify those credentials against
  12 a secure shared secret (e.g., a host keytab) to ensure that the user
  13 credentials actually originate from a legitimate KDC.  Failure to
  14 perform this verification is a critical vulnerability, because a
  15 malicious user can execute the "Zanarotti attack": the user constructs
  16 a fake response that appears to come from the legitimate KDC, but
  17 whose contents come from an attacker-controlled KDC.
  18
  19 Some applications read a Kerberos password over the network (ideally
  20 over a secure channel), which they then verify against the KDC.  While
  21 this technique may be the only practical way to integrate Kerberos
  22 into some existing legacy systems, its use is contrary to the original
  23 design goals of Kerberos.
  24
  25 The function :c:func:`krb5_get_init_creds_password` will get initial
  26 credentials for a client using a password.  An application that needs
  27 to verify the credentials can call :c:func:`krb5_verify_init_creds`.
  28
  29 Options for get_init_creds
  30 --------------------------
  31
  32 The function :c:func:`krb5_get_init_creds_password` takes an options
  33 parameter (which can be a null pointer).  Use the function
  34 :c:func:`krb5_get_init_creds_opt_alloc` to allocate an options
  35 structure, and :c:func:`krb5_get_init_creds_opt_free` to free it.
  36
  37 Verifying initial credentials
  38 -----------------------------
  39
  40 Use the function :c:func:`krb5_verify_init_creds` to verify initial
  41 credentials.  It takes an options structure (which can be a null
  42 pointer).  Use :c:func:`krb5_verify_init_creds_opt_init` to initialize
  43 the caller-allocated options structure, and
  44 :c:func:`krb5_verify_init_creds_opt_set_ap_req_nofail` to set the
  45 "nofail" option.
  46
  47 The confusingly named "nofail" option, when set, means that the
  48 verification must actually succeed in order for
  49 :c:func:`krb5_verify_init_creds` to indicate success.  The default
  50 state of this option (cleared) means that if there is no key material
  51 available to verify the user credentials, the verification will
  52 succeed anyway.  (The default can be changed by a configuration file
  53 setting.)
  54
  55 This accommodates a use case where a large number of unkeyed shared
  56 desktop workstations need to allow users to log in using Kerberos.
  57 The security risks from this practice are mitigated by the absence of
  58 valuable state on the shared workstations -- any valuable resources
  59 that the users would access reside on networked servers.