krb5 commit [krb5-1.11]: Clarify krb5_rd_req documentation

[Tom Yu]

https://github.com/krb5/krb5/commit/84c31f692530c6be3e106e4b700c54e0c2160e30
commit 84c31f692530c6be3e106e4b700c54e0c2160e30
Author: Greg Hudson <ghudson at mit.edu>
Date:   Wed May 22 01:55:12 2013 -0400

    Clarify krb5_rd_req documentation
    
    For the user-to-user case, document that callers should pass a server
    principal to krb5_rd_req.  For the keytab case, more accurately
    document which keytab keys are tried against the ticket.
    
    (cherry picked from commit 98aa233e18245981b491affe5fa70623cb83b705)
    
    ticket: 7641
    version_fixed: 1.11.3
    status: resolved

 src/include/krb5/krb5.hin |   28 +++++++++++++++++++---------
 1 files changed, 19 insertions(+), 9 deletions(-)

diff --git a/src/include/krb5/krb5.hin b/src/include/krb5/krb5.hin
index 9d528bb..1543172 100644
--- a/src/include/krb5/krb5.hin
+++ b/src/include/krb5/krb5.hin
@@ -5122,17 +5122,27 @@ krb5_get_in_tkt_with_keytab(krb5_context context, krb5_flags options,
  * This function parses, decrypts and verifies a AP-REQ message from @a inbuf
  * and stores the authenticator in @a auth_context.
  *
- * If a keyblock is present in the @a auth_context, it is used to decrypt the
- * ticket in AP-REQ message. (This is useful for user-to-user authentication.)
- * Otherwise, the decryption key is obtained from the @a keytab.  If @a keytab
- * is iterable, all of its key entries it will be tried against the ticket;
- * otherwise, the server principal in the ticket will be looked up in the
- * keytab and that key will be tried.
+ * If a keyblock was specified in @a auth_context using
+ * krb5_auth_con_setuseruserkey(), that key is used to decrypt the ticket in
+ * AP-REQ message and @a keytab is ignored.  In this case, @a server should be
+ * specified as a complete principal name to allow for proper transited-path
+ * checking and replay cache selection.
+ *
+ * Otherwise, the decryption key is obtained from @a keytab, or from the
+ * default keytab if it is NULL.  In this case, @a server may be a complete
+ * principal name, a matching principal (see krb5_sname_match()), or NULL to
+ * match any principal name.  The keys tried against the encrypted part of the
+ * ticket are determined as follows:
+ *
+ * - If @a server is a complete principal name, then its entry in @a keytab is
+ *   tried.
+ * - Otherwise, if @a keytab is iterable, then all entries in @a keytab which
+ *   match @a server are tried.
+ * - Otherwise, the server principal in the ticket must match @a server, and
+ *   its entry in @a keytab is tried.
  *
  * The client specified in the decrypted authenticator must match the client
- * specified in the decrypted ticket.  If @a server is non-null, the key in
- * which the ticket is encrypted must correspond to a principal in @a keytab
- * matching @a server according to the rules of krb5_sname_match().
+ * specified in the decrypted ticket.
  *
  * If the @a remote_addr field of @a auth_context is set, the request must come
  * from that address.