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.

ticket: 7641 (new)
target_version: 1.11.3
tags: pullup

1 files changed, 19 insertions, 9 deletions

diff --git a/src/include/krb5/krb5.hin b/src/include/krb5/krb5.hin
index a41fae07d..270ad8249 100644
--- a/src/include/krb5/krb5.hin
+++ b/src/include/krb5/krb5.hin
@@ -5152,17 +5152,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.