-
+

Initial credentials

Software that performs tasks such as logging users into a computer when they type their Kerberos password needs to get initial @@ -81,13 +72,13 @@ 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 krb5_get_init_creds_password() will get initial +

The function 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 krb5_verify_init_creds(). +to verify the credentials can call krb5_verify_init_creds(). Here is an example of code to obtain and verify TGT credentials, given strings princname and password for the client principal name and password:

-
krb5_error_code ret;
+
krb5_error_code ret;
 krb5_creds creds;
 krb5_principal client_princ = NULL;
 
@@ -107,14 +98,14 @@ password:

 return ret;
 

 

-

+

 
Options for get_init_creds

-
The function krb5_get_init_creds_password() takes an options
+
The function krb5_get_init_creds_password() takes an options
 parameter (which can be a null pointer).  Use the function
-krb5_get_init_creds_opt_alloc() to allocate an options
-structure, and krb5_get_init_creds_opt_free() to free it.  For
+krb5_get_init_creds_opt_alloc() to allocate an options
+structure, and krb5_get_init_creds_opt_free() to free it.  For
 example:

-
krb5_error_code ret;
+
krb5_error_code ret;
 krb5_get_init_creds_opt *opt = NULL;
 krb5_creds creds;
 
@@ -134,8 +125,8 @@ example:

 return ret;
 

 

-

-

+

+

 
Getting anonymous credentials

 
As of release 1.8, it is possible to obtain fully anonymous or
 partially anonymous (realm-exposed) credentials, if the KDC supports
@@ -144,14 +135,14 @@ release 1.8 if configured appropriately (see 
 
To obtain fully anonymous credentials, call
-krb5_get_init_creds_opt_set_anonymous() on the options
+krb5_get_init_creds_opt_set_anonymous() on the options
 structure to set the anonymous flag, and specify a client principal
 with the KDC’s realm and a single empty data component (the principal
-obtained by parsing @realmname).  Authentication will take
+obtained by parsing @realmname).  Authentication will take
 place using anonymous PKINIT; if successful, the client principal of
 the resulting tickets will be
-WELLKNOWN/ANONYMOUS@WELLKNOWN:ANONYMOUS.  Here is an example:

-
krb5_get_init_creds_opt_set_anonymous(opt, 1);
+WELLKNOWN/ANONYMOUS@WELLKNOWN:ANONYMOUS.  Here is an example:

+
krb5_get_init_creds_opt_set_anonymous(opt, 1);
 ret = krb5_build_principal(context, &client_princ, strlen(myrealm),
                            myrealm, "", (char *)NULL);
 if (ret)
@@ -166,22 +157,22 @@ the resulting tickets will be
 on the options structure as above, but specify a normal client
 principal in order to prove membership in the realm.  Authentication
 will take place as it normally does; if successful, the client
-principal of the resulting tickets will be WELLKNOWN/ANONYMOUS@realmname.

-

-

+principal of the resulting tickets will be WELLKNOWN/ANONYMOUS@realmname.

+

+

 
User interaction

 
Authenticating a user usually requires the entry of secret
 information, such as a password.  A password can be supplied directly
-to krb5_get_init_creds_password() via the password
+to krb5_get_init_creds_password() via the password
 parameter, or the application can supply prompter and/or responder
 callbacks instead.  If callbacks are used, the user can also be
 queried for other secret information such as a PIN, informed of
 impending password expiration, or prompted to change a password which
 has expired.

-

+

 
Prompter callback

 
A prompter callback can be specified via the prompter and data
-parameters to krb5_get_init_creds_password().  The prompter
+parameters to krb5_get_init_creds_password().  The prompter
 will be invoked each time the krb5 library has a question to ask or
 information to present.  When the prompter callback is invoked, the
 banner argument (if not null) is intended to be displayed to the
@@ -189,82 +180,82 @@ user, and the questions to be answered are specified in the prompts
 array.  Each prompt contains a text question in the prompt field, a
 hidden bit to indicate whether the answer should be hidden from
 display, and a storage area for the answer in the reply field.  The
-callback should fill in each question’s reply->data with the
-answer, up to a maximum number of reply->length bytes, and then
-reset reply->length to the length of the answer.

-
A prompter callback can call krb5_get_prompt_types() to get an
+callback should fill in each question’s reply->data with the
+answer, up to a maximum number of reply->length bytes, and then
+reset reply->length to the length of the answer.

+
A prompter callback can call krb5_get_prompt_types() to get an
 array of type constants corresponding to the prompts, to get
 programmatic information about the semantic meaning of the questions.
-krb5_get_prompt_types() may return a null pointer if no prompt
+krb5_get_prompt_types() may return a null pointer if no prompt
 type information is available.

 
Text-based applications can use a built-in text prompter
-implementation by supplying krb5_prompter_posix() as the
+implementation by supplying krb5_prompter_posix() as the
 prompter parameter and a null pointer as the data parameter.  For
 example:

-
ret = krb5_get_init_creds_password(context, &creds, client_princ,
+
ret = krb5_get_init_creds_password(context, &creds, client_princ,
                                    NULL, krb5_prompter_posix, NULL, 0,
                                    NULL, NULL);
 

 

-

-

+

+

 
Responder callback

 
A responder callback can be specified through the init_creds options
-using the krb5_get_init_creds_opt_set_responder() function.
+using the krb5_get_init_creds_opt_set_responder() function.
 Responder callbacks can present a more sophisticated user interface
 for authentication secrets.  The responder callback is usually invoked
 only once per authentication, with a list of questions produced by all
 of the allowed preauthentication mechanisms.

 
When the responder callback is invoked, the rctx argument can be
 accessed to obtain the list of questions and to answer them.  The
-krb5_responder_list_questions() function retrieves an array of
+krb5_responder_list_questions() function retrieves an array of
 question types.  For each question type, the
-krb5_responder_get_challenge() function retrieves additional
+krb5_responder_get_challenge() function retrieves additional
 information about the question, if applicable, and the
-krb5_responder_set_answer() function sets the answer.

+krb5_responder_set_answer() function sets the answer.

 
Responder question types, challenges, and answers are UTF-8 strings.
 The question type is a well-known string; the meaning of the challenge
 and answer depend on the question type.  If an application does not
 understand a question type, it cannot interpret the challenge or
 provide an answer.  Failing to answer a question typically results in
 the prompter callback being used as a fallback.

-

+

 
Password question

-
The KRB5_RESPONDER_QUESTION_PASSWORD (or "password")
+
The KRB5_RESPONDER_QUESTION_PASSWORD (or "password")
 question type requests the user’s password.  This question does not
 have a challenge, and the response is simply the password string.

-

-

+

+

 
One-time password question

-
The KRB5_RESPONDER_QUESTION_OTP (or "otp") question
+
The KRB5_RESPONDER_QUESTION_OTP (or "otp") question
 type requests a choice among one-time password tokens and the PIN and
 value for the chosen token.  The challenge and answer are JSON-encoded
 strings, but an application can use convenience functions to avoid
 doing any JSON processing itself.

-
The krb5_responder_otp_get_challenge() function decodes the
+
The krb5_responder_otp_get_challenge() function decodes the
 challenge into a krb5_responder_otp_challenge structure.  The
-krb5_responder_otp_set_answer() function selects one of the
+krb5_responder_otp_set_answer() function selects one of the
 token information elements from the challenge and supplies the value
 and pin for that token.

-

-

+

+

 
PKINIT password or PIN question

-
The KRB5_RESPONDER_QUESTION_PKINIT (or "pkinit") question
+
The KRB5_RESPONDER_QUESTION_PKINIT (or "pkinit") question
 type requests PINs for hardware devices and/or passwords for encrypted
 credentials which are stored on disk, potentially also supplying
 information about the state of the hardware devices.  The challenge and
 answer are JSON-encoded strings, but an application can use convenience
 functions to avoid doing any JSON processing itself.

-
The krb5_responder_pkinit_get_challenge() function decodes the
+
The krb5_responder_pkinit_get_challenge() function decodes the
 challenges into a krb5_responder_pkinit_challenge structure.  The
-krb5_responder_pkinit_set_answer() function can be used to
+krb5_responder_pkinit_set_answer() function can be used to
 supply the PIN or password for a particular client credential, and can
 be called multiple times.

-

-

+
+

Example

Here is an example of using a responder callback:

-
static krb5_error_code
+
static krb5_error_code
 my_responder(krb5_context context, void *data,
              krb5_responder_context rctx)
 {
@@ -315,18 +306,18 @@ be called multiple times.

 }
 

 

-
-
-
-
+ + + +

Verifying initial credentials

-

Use the function krb5_verify_init_creds() to verify initial +

Use the function krb5_verify_init_creds() to verify initial credentials. It takes an options structure (which can be a null -pointer). Use krb5_verify_init_creds_opt_init() to initialize +pointer). Use krb5_verify_init_creds_opt_init() to initialize the caller-allocated options structure, and -krb5_verify_init_creds_opt_set_ap_req_nofail() to set the +krb5_verify_init_creds_opt_set_ap_req_nofail() to set the “nofail” option. For example:

-
krb5_verify_init_creds_opt vopt;
+
krb5_verify_init_creds_opt vopt;
 
 krb5_verify_init_creds_opt_init(&vopt);
 krb5_verify_init_creds_opt_set_ap_req_nofail(&vopt, 1);
@@ -335,7 +326,7 @@ the caller-allocated options structure, and
 

 
The confusingly named “nofail” option, when set, means that the
 verification must actually succeed in order for
-krb5_verify_init_creds() to indicate success.  The default
+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
@@ -345,15 +336,17 @@ 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.

-

-
+
+ +