From 04de6c523f45e4607da214a7382d2dab93fd62c1 Mon Sep 17 00:00:00 2001 From: Tom Yu Date: Fri, 27 Apr 2012 20:39:13 +0000 Subject: [PATCH] Draft initial credentials API documentation git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@25835 dc483132-0cff-0310-8789-dd5450dbe970 --- doc/rst_source/krb_appldev/index.rst | 1 + doc/rst_source/krb_appldev/init_creds.rst | 59 +++++++++++++++++++++++ 2 files changed, 60 insertions(+) create mode 100644 doc/rst_source/krb_appldev/init_creds.rst diff --git a/doc/rst_source/krb_appldev/index.rst b/doc/rst_source/krb_appldev/index.rst index dd0ec5388..3d62045ca 100644 --- a/doc/rst_source/krb_appldev/index.rst +++ b/doc/rst_source/krb_appldev/index.rst @@ -6,6 +6,7 @@ For application developers gssapi.rst h5l_mit_apidiff.rst + init_creds.rst princ_handle.rst .. toctree:: diff --git a/doc/rst_source/krb_appldev/init_creds.rst b/doc/rst_source/krb_appldev/init_creds.rst new file mode 100644 index 000000000..0750bd82b --- /dev/null +++ b/doc/rst_source/krb_appldev/init_creds.rst @@ -0,0 +1,59 @@ +Initial credentials +=================== + +Software that performs tasks such as logging users into a computer +when they type their Kerberos password needs to get initial +credentials (usually ticket granting tickets) from Kerberos. Such +software shares some behavior with the :ref:`kinit(1)` program. + +Whenever a program grants access to a resource (such as a local login +session on a desktop computer) based on a user successfully getting +initial Kerberos credentials, it must verify those credentials against +a secure shared secret (e.g., a host keytab) to ensure that the user +credentials actually originate from a legitimate KDC. Failure to +perform this verification is a critical vulnerability, because a +malicious user can execute the "Zanarotti attack": the user constructs +a fake response that appears to come from the legitimate KDC, but +whose contents come from an attacker-controlled KDC. + +Some applications read a Kerberos password over the network (ideally +over a secure channel), which they then verify against the KDC. While +this technique may be the only practical way to integrate Kerberos +into some existing legacy systems, its use is contrary to the original +design goals of Kerberos. + +The function :c:func:`krb5_get_init_creds_password` will get initial +credentials for a client using a password. An application that needs +to verify the credentials can call :c:func:`krb5_verify_init_creds`. + +Options for get_init_creds +-------------------------- + +The function :c:func:`krb5_get_init_creds_password` takes an options +parameter (which can be a null pointer). Use the function +:c:func:`krb5_get_init_creds_opt_alloc` to allocate an options +structure, and :c:func:`krb5_get_init_creds_opt_free` to free it. + +Verifying initial credentials +----------------------------- + +Use the function :c:func:`krb5_verify_init_creds` to verify initial +credentials. It takes an options structure (which can be a null +pointer). Use :c:func:`krb5_verify_init_creds_opt_init` to initialize +the caller-allocated options structure, and +:c:func:`krb5_verify_init_creds_opt_set_ap_req_nofail` to set the +"nofail" option. + +The confusingly named "nofail" option, when set, means that the +verification must actually succeed in order for +:c:func:`krb5_verify_init_creds` to indicate success. The default +state of this option (cleared) means that if there is no key material +available to verify the user credentials, the verification will +succeed anyway. (The default can be changed by a configuration file +setting.) + +This accommodates a use case where a large number of unkeyed shared +desktop workstations need to allow users to log in using Kerberos. +The security risks from this practice are mitigated by the absence of +valuable state on the shared workstations -- any valuable resources +that the users would access reside on networked servers. -- 2.26.2