Doxygen style re-formating of the existing comments
authorZhanna Tsitkov <tsitkova@mit.edu>
Thu, 13 Jan 2011 15:32:47 +0000 (15:32 +0000)
committerZhanna Tsitkov <tsitkova@mit.edu>
Thu, 13 Jan 2011 15:32:47 +0000 (15:32 +0000)
git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@24596 dc483132-0cff-0310-8789-dd5450dbe970

src/include/krb5/krb5.hin

index 51d7d728da49cf8dd32ac897542321d072f31b8c..d74cf307e9f6f0dd3093a6e03f88ce8473c4cfbf 100644 (file)
@@ -1,7 +1,7 @@
 /* -*- mode: c; c-basic-offset: 4; indent-tabs-mode: nil -*- */
-/* include/krb5.h
+/* include/krb5.h - General definitions for Kerberos version 5.
  *
- * Copyright 1989,1990,1995,2001, 2003, 2007  by the Massachusetts Institute of Technology.
+ * Copyright 1989,1990,1995,2001, 2003, 2007 by the Massachusetts Institute of Technology.
  * All Rights Reserved.
  *
  * Export of this software from the United States of America may
@@ -23,8 +23,6 @@
  * this software for any purpose.  It is provided "as is" without express
  * or implied warranty.
  *
- *
- * General definitions for Kerberos version 5.
  */
 
 /*
@@ -232,7 +230,7 @@ typedef void const * krb5_const_pointer;
 typedef struct krb5_principal_data {
     krb5_magic magic;
     krb5_data realm;
-    krb5_data *data;            /* An array of strings */
+    krb5_data *data;            /**< An array of strings */
     krb5_int32 length;
     krb5_int32 type;
 } krb5_principal_data;
@@ -310,7 +308,7 @@ krb5_const_principal KRB5_CALLCONV krb5_anonymous_principal(void);
  * begin "hostaddr.h"
  */
 
-/* structure for address */
+/** structure for address */
 typedef struct _krb5_address {
     krb5_magic magic;
     krb5_addrtype addrtype;
@@ -350,7 +348,7 @@ struct _krb5_cryptosystem_entry;
  * begin "encryption.h"
  */
 
-/* Exposed contents of a key. */
+/** @brief  Exposed contents of a key. */
 typedef struct _krb5_keyblock {
     krb5_magic magic;
     krb5_enctype enctype;
@@ -358,7 +356,7 @@ typedef struct _krb5_keyblock {
     krb5_octet *contents;
 } krb5_keyblock;
 
-/*
+/**
  * Opaque identifier for a key.  Use with the krb5_k APIs for better
  * performance for repeated operations with the same key usage.  Key
  * identifiers must not be used simultaneously within multiple
@@ -1088,17 +1086,17 @@ krb5_verify_checksum(krb5_context context, krb5_cksumtype ctype,
  * end "proto.h"
  */
 
-/* Time set */
+/**  @brief  Time set */
 typedef struct _krb5_ticket_times {
     krb5_timestamp authtime; /* XXX ? should ktime in KDC_REP == authtime
                                 in ticket? otherwise client can't get this */
-    krb5_timestamp starttime;           /* optional in ticket, if not present,
+    krb5_timestamp starttime;           /**< optional in ticket, if not present,
                                            use authtime */
     krb5_timestamp endtime;
     krb5_timestamp renew_till;
 } krb5_ticket_times;
 
-/* structure for auth data */
+/**  @brief  structure for auth data */
 typedef struct _krb5_authdata {
     krb5_magic magic;
     krb5_authdatatype ad_type;
@@ -1106,7 +1104,7 @@ typedef struct _krb5_authdata {
     krb5_octet *contents;
 } krb5_authdata;
 
-/* structure for transited encoding */
+/**  @brief  structure for transited encoding */
 typedef struct _krb5_transited {
     krb5_magic magic;
     krb5_octet tr_type;
@@ -1116,35 +1114,35 @@ typedef struct _krb5_transited {
 typedef struct _krb5_enc_tkt_part {
     krb5_magic magic;
     /* to-be-encrypted portion */
-    krb5_flags flags;                   /* flags */
-    krb5_keyblock *session;             /* session key: includes enctype */
-    krb5_principal client;              /* client name/realm */
-    krb5_transited transited;           /* list of transited realms */
-    krb5_ticket_times times;            /* auth, start, end, renew_till */
-    krb5_address **caddrs;      /* array of ptrs to addresses */
-    krb5_authdata **authorization_data; /* auth data */
+    krb5_flags flags;                   /**< flags */
+    krb5_keyblock *session;             /**< session key: includes enctype */
+    krb5_principal client;              /**< client name/realm */
+    krb5_transited transited;           /**< list of transited realms */
+    krb5_ticket_times times;            /**< auth, start, end, renew_till */
+    krb5_address **caddrs;      /**< array of ptrs to addresses */
+    krb5_authdata **authorization_data; /**< auth data */
 } krb5_enc_tkt_part;
 
 typedef struct _krb5_ticket {
     krb5_magic magic;
     /* cleartext portion */
-    krb5_principal server;              /* server name/realm */
-    krb5_enc_data enc_part;             /* encryption type, kvno, encrypted
+    krb5_principal server;              /**< server name/realm */
+    krb5_enc_data enc_part;             /**< encryption type, kvno, encrypted
                                            encoding */
-    krb5_enc_tkt_part *enc_part2;       /* ptr to decrypted version, if
+    krb5_enc_tkt_part *enc_part2;       /**< ptr to decrypted version, if
                                            available */
 } krb5_ticket;
 
-/* the unencrypted version */
+/**  @brief  the unencrypted version */
 typedef struct _krb5_authenticator {
     krb5_magic magic;
-    krb5_principal client;              /* client name/realm */
-    krb5_checksum *checksum;    /* checksum, includes type, optional */
-    krb5_int32 cusec;                   /* client usec portion */
-    krb5_timestamp ctime;               /* client sec portion */
-    krb5_keyblock *subkey;              /* true session key, optional */
-    krb5_ui_4 seq_number;               /* sequence #, optional */
-    krb5_authdata **authorization_data; /* New add by Ari, auth data */
+    krb5_principal client;              /**< client name/realm */
+    krb5_checksum *checksum;    /**< checksum, includes type, optional */
+    krb5_int32 cusec;                   /**< client usec portion */
+    krb5_timestamp ctime;               /**< client sec portion */
+    krb5_keyblock *subkey;              /**< true session key, optional */
+    krb5_ui_4 seq_number;               /**< sequence #, optional */
+    krb5_authdata **authorization_data; /**< New add by Ari, auth data */
 } krb5_authenticator;
 
 typedef struct _krb5_tkt_authent {
@@ -1154,32 +1152,32 @@ typedef struct _krb5_tkt_authent {
     krb5_flags ap_options;
 } krb5_tkt_authent;
 
-/* credentials:  Ticket, session key, etc. */
+/**  @brief  credentials:  Ticket, session key, etc. */
 typedef struct _krb5_creds {
     krb5_magic magic;
-    krb5_principal client;              /* client's principal identifier */
-    krb5_principal server;              /* server's principal identifier */
-    krb5_keyblock keyblock;             /* session encryption key info */
-    krb5_ticket_times times;            /* lifetime info */
-    krb5_boolean is_skey;               /* true if ticket is encrypted in
+    krb5_principal client;              /**< client's principal identifier */
+    krb5_principal server;              /**< server's principal identifier */
+    krb5_keyblock keyblock;             /**< session encryption key info */
+    krb5_ticket_times times;            /**< lifetime info */
+    krb5_boolean is_skey;               /**< true if ticket is encrypted in
                                            another ticket's skey */
-    krb5_flags ticket_flags;            /* flags in ticket */
-    krb5_address **addresses;   /* addrs in ticket */
-    krb5_data ticket;                   /* ticket string itself */
-    krb5_data second_ticket;            /* second ticket, if related to
+    krb5_flags ticket_flags;            /**< flags in ticket */
+    krb5_address **addresses;   /**< addrs in ticket */
+    krb5_data ticket;                   /**< ticket string itself */
+    krb5_data second_ticket;            /**< second ticket, if related to
                                            ticket (via DUPLICATE-SKEY or
                                            ENC-TKT-IN-SKEY) */
-    krb5_authdata **authdata;   /* authorization data */
+    krb5_authdata **authdata;   /**< authorization data */
 } krb5_creds;
 
-/* Last request fields */
+/**  @brief Last request fields */
 typedef struct _krb5_last_req_entry {
     krb5_magic magic;
     krb5_int32 lr_type;
     krb5_timestamp value;
 } krb5_last_req_entry;
 
-/* pre-authentication data */
+/**  @brief  pre-authentication data */
 typedef struct _krb5_pa_data {
     krb5_magic magic;
     krb5_preauthtype  pa_type;
@@ -1188,7 +1186,7 @@ typedef struct _krb5_pa_data {
 } krb5_pa_data;
 
 /* typed data */
-/*
+/**
  * The FAST error handling logic currently assumes that this structure and
  * krb5_pa_data * can be safely cast to each other if this structure changes,
  * that code needs to be updated to copy.
@@ -1202,25 +1200,25 @@ typedef struct _krb5_typed_data {
 
 typedef struct _krb5_kdc_req {
     krb5_magic magic;
-    krb5_msgtype msg_type;              /* AS_REQ or TGS_REQ? */
-    krb5_pa_data **padata;      /* e.g. encoded AP_REQ */
+    krb5_msgtype msg_type;              /*krb5_kdc_req AS_REQ or TGS_REQ? */
+    krb5_pa_data **padata;      /*krb5_kdc_req e.g. encoded AP_REQ */
     /* real body */
-    krb5_flags kdc_options;             /* requested options */
-    krb5_principal client;              /* includes realm; optional */
-    krb5_principal server;              /* includes realm (only used if no
+    krb5_flags kdc_options;             /**< requested options */
+    krb5_principal client;              /**< includes realm; optional */
+    krb5_principal server;              /**< includes realm (only used if no
                                            client) */
-    krb5_timestamp from;                /* requested starttime */
-    krb5_timestamp till;                /* requested endtime */
-    krb5_timestamp rtime;               /* (optional) requested renew_till */
-    krb5_int32 nonce;                   /* nonce to match request/response */
-    int nktypes;                        /* # of ktypes, must be positive */
-    krb5_enctype *ktype;                /* requested enctype(s) */
-    krb5_address **addresses;   /* requested addresses, optional */
-    krb5_enc_data authorization_data;   /* encrypted auth data; OPTIONAL */
-    krb5_authdata **unenc_authdata; /* unencrypted auth data,
+    krb5_timestamp from;                /**< requested starttime */
+    krb5_timestamp till;                /**< requested endtime */
+    krb5_timestamp rtime;               /**< (optional) requested renew_till */
+    krb5_int32 nonce;                   /**< nonce to match request/response */
+    int nktypes;                        /**< # of ktypes, must be positive */
+    krb5_enctype *ktype;                /**< requested enctype(s) */
+    krb5_address **addresses;   /**< requested addresses, optional */
+    krb5_enc_data authorization_data;   /**< encrypted auth data; OPTIONAL */
+    krb5_authdata **unenc_authdata; /**< unencrypted auth data,
                                        if available */
-    krb5_ticket **second_ticket;/* second ticket array; OPTIONAL */
-    /* the following field is added in March 2009; it is a hack so
+    krb5_ticket **second_ticket;/**< second ticket array; OPTIONAL */
+    /** the following field is added in March 2009; it is a hack so
      * that FAST state can be carried to pre-authentication plugins.
      * A new plugin interface may be a better long-term approach.  It
      * is believed to be safe to extend this structure because it is
@@ -1232,52 +1230,52 @@ typedef struct _krb5_kdc_req {
 typedef struct _krb5_enc_kdc_rep_part {
     krb5_magic magic;
     /* encrypted part: */
-    krb5_msgtype msg_type;              /* krb5 message type */
-    krb5_keyblock *session;             /* session key */
-    krb5_last_req_entry **last_req; /* array of ptrs to entries */
-    krb5_int32 nonce;                   /* nonce from request */
-    krb5_timestamp key_exp;             /* expiration date */
-    krb5_flags flags;                   /* ticket flags */
-    krb5_ticket_times times;            /* lifetime info */
-    krb5_principal server;              /* server's principal identifier */
-    krb5_address **caddrs;      /* array of ptrs to addresses,
+    krb5_msgtype msg_type;              /**< krb5 message type */
+    krb5_keyblock *session;             /**< session key */
+    krb5_last_req_entry **last_req; /**< array of ptrs to entries */
+    krb5_int32 nonce;                   /**< nonce from request */
+    krb5_timestamp key_exp;             /**< expiration date */
+    krb5_flags flags;                   /**< ticket flags */
+    krb5_ticket_times times;            /**< lifetime info */
+    krb5_principal server;              /**< server's principal identifier */
+    krb5_address **caddrs;      /**< array of ptrs to addresses,
                                    optional */
-    krb5_pa_data **enc_padata;          /* Windows 2000 compat */
+    krb5_pa_data **enc_padata;          /**< Windows 2000 compat */
 } krb5_enc_kdc_rep_part;
 
 typedef struct _krb5_kdc_rep {
     krb5_magic magic;
     /* cleartext part: */
-    krb5_msgtype msg_type;              /* AS_REP or KDC_REP? */
-    krb5_pa_data **padata;      /* preauthentication data from KDC */
-    krb5_principal client;              /* client's principal identifier */
-    krb5_ticket *ticket;                /* ticket */
-    krb5_enc_data enc_part;             /* encryption type, kvno, encrypted
+    krb5_msgtype msg_type;              /**< AS_REP or KDC_REP? */
+    krb5_pa_data **padata;      /**< preauthentication data from KDC */
+    krb5_principal client;              /**< client's principal identifier */
+    krb5_ticket *ticket;                /**< ticket */
+    krb5_enc_data enc_part;             /**< encryption type, kvno, encrypted
                                            encoding */
-    krb5_enc_kdc_rep_part *enc_part2;/* unencrypted version, if available */
+    krb5_enc_kdc_rep_part *enc_part2;/**< unencrypted version, if available */
 } krb5_kdc_rep;
 
-/* error message structure */
+/** @brief error message structure */
 typedef struct _krb5_error {
     krb5_magic magic;
     /* some of these may be meaningless in certain contexts */
-    krb5_timestamp ctime;               /* client sec portion; optional */
-    krb5_int32 cusec;                   /* client usec portion; optional */
-    krb5_int32 susec;                   /* server usec portion */
-    krb5_timestamp stime;               /* server sec portion */
-    krb5_ui_4 error;                    /* error code (protocol error #'s) */
-    krb5_principal client;              /* client's principal identifier;
+    krb5_timestamp ctime;               /**< client sec portion; optional */
+    krb5_int32 cusec;                   /**< client usec portion; optional */
+    krb5_int32 susec;                   /**< server usec portion */
+    krb5_timestamp stime;               /**< server sec portion */
+    krb5_ui_4 error;                    /**< error code (protocol error #'s) */
+    krb5_principal client;              /**< client's principal identifier;
                                            optional */
-    krb5_principal server;              /* server's principal identifier */
-    krb5_data text;                     /* descriptive text */
-    krb5_data e_data;                   /* additional error-describing data */
+    krb5_principal server;              /**< server's principal identifier */
+    krb5_data text;                     /**< descriptive text */
+    krb5_data e_data;                   /**< additional error-describing data */
 } krb5_error;
 
 typedef struct _krb5_ap_req {
     krb5_magic magic;
-    krb5_flags ap_options;              /* requested options */
-    krb5_ticket *ticket;                /* ticket */
-    krb5_enc_data authenticator;        /* authenticator (already encrypted) */
+    krb5_flags ap_options;              /**< requested options */
+    krb5_ticket *ticket;                /**< ticket */
+    krb5_enc_data authenticator;        /**< authenticator (already encrypted) */
 } krb5_ap_req;
 
 typedef struct _krb5_ap_rep {
@@ -1287,47 +1285,45 @@ typedef struct _krb5_ap_rep {
 
 typedef struct _krb5_ap_rep_enc_part {
     krb5_magic magic;
-    krb5_timestamp ctime;               /* client time, seconds portion */
-    krb5_int32 cusec;                   /* client time, microseconds portion */
-    krb5_keyblock *subkey;              /* true session key, optional */
-    krb5_ui_4 seq_number;               /* sequence #, optional */
+    krb5_timestamp ctime;               /**< client time, seconds portion */
+    krb5_int32 cusec;                   /**< client time, microseconds portion */
+    krb5_keyblock *subkey;              /**< true session key, optional */
+    krb5_ui_4 seq_number;               /**< sequence #, optional */
 } krb5_ap_rep_enc_part;
 
 typedef struct _krb5_response {
     krb5_magic magic;
     krb5_octet message_type;
     krb5_data response;
-    krb5_int32 expected_nonce;  /* The expected nonce for KDC_REP messages */
-    krb5_timestamp request_time;   /* When we made the request */
+    krb5_int32 expected_nonce;  /**< The expected nonce for KDC_REP messages */
+    krb5_timestamp request_time;   /**< When we made the request */
 } krb5_response;
 
 typedef struct _krb5_cred_info {
     krb5_magic magic;
-    krb5_keyblock *session;             /* session key used to encrypt */
-                                        /* ticket */
-    krb5_principal client;              /* client name/realm, optional */
-    krb5_principal server;              /* server name/realm, optional */
-    krb5_flags flags;                   /* ticket flags, optional */
-    krb5_ticket_times times;            /* auth, start, end, renew_till, */
-                                        /* optional */
-    krb5_address **caddrs;      /* array of ptrs to addresses */
+    krb5_keyblock *session;             /**< session key used to encrypt ticket */
+    krb5_principal client;              /**< client name/realm, optional */
+    krb5_principal server;              /**< server name/realm, optional */
+    krb5_flags flags;                   /**< ticket flags, optional */
+    krb5_ticket_times times;            /**< auth, start, end, renew_till, optional */
+    krb5_address **caddrs;      /**< array of ptrs to addresses */
 } krb5_cred_info;
 
 typedef struct _krb5_cred_enc_part {
     krb5_magic magic;
-    krb5_int32 nonce;                   /* nonce, optional */
-    krb5_timestamp timestamp;           /* client time */
-    krb5_int32 usec;                    /* microsecond portion of time */
-    krb5_address *s_address;    /* sender address, optional */
-    krb5_address *r_address;    /* recipient address, optional */
+    krb5_int32 nonce;                   /**< nonce, optional */
+    krb5_timestamp timestamp;           /**< client time */
+    krb5_int32 usec;                    /**< microsecond portion of time */
+    krb5_address *s_address;    /**< sender address, optional */
+    krb5_address *r_address;    /**< recipient address, optional */
     krb5_cred_info **ticket_info;
 } krb5_cred_enc_part;
 
 typedef struct _krb5_cred {
     krb5_magic magic;
-    krb5_ticket **tickets;      /* tickets */
-    krb5_enc_data enc_part;             /* encrypted part */
-    krb5_cred_enc_part *enc_part2;      /* unencrypted version, if available*/
+    krb5_ticket **tickets;      /**< tickets */
+    krb5_enc_data enc_part;             /**< encrypted part */
+    krb5_cred_enc_part *enc_part2;      /**< unencrypted version, if available*/
 } krb5_cred;
 
 /* Sandia password generation structures */
@@ -1349,7 +1345,7 @@ typedef struct _krb5_pwd_data {
  * in the enc_padata field of the krb5_enc_kdc_rep_part.
  */
 typedef struct _krb5_pa_svr_referral_data {
-    /* Referred name, only realm is required */
+    /** Referred name, only realm is required */
     krb5_principal     principal;
 } krb5_pa_svr_referral_data;
 
@@ -1362,7 +1358,7 @@ typedef struct _krb5_pa_server_referral_data {
 } krb5_pa_server_referral_data;
 
 typedef struct _krb5_pa_pac_req {
-    /* TRUE if a PAC should be included in TGS-REP */
+    /** TRUE if a PAC should be included in TGS-REP */
     krb5_boolean       include_pac;
 } krb5_pa_pac_req;
 
@@ -1561,10 +1557,10 @@ typedef krb5_pointer krb5_kt_cursor;    /* XXX */
 
 typedef struct krb5_keytab_entry_st {
     krb5_magic magic;
-    krb5_principal principal;   /* principal of this key */
-    krb5_timestamp timestamp;   /* time entry written to keytable */
-    krb5_kvno vno;              /* key version number */
-    krb5_keyblock key;          /* the secret key */
+    krb5_principal principal;   /**< principal of this key */
+    krb5_timestamp timestamp;   /**< time entry written to keytable */
+    krb5_kvno vno;              /**< key version number */
+    krb5_keyblock key;          /**< the secret key */
 } krb5_keytab_entry;
 
 struct _krb5_kt;
@@ -2311,7 +2307,7 @@ void KRB5_CALLCONV
 krb5_get_init_creds_opt_set_change_password_prompt(krb5_get_init_creds_opt
                                                    *opt, int prompt);
 
-/* Generic preauth option attribute/value pairs */
+/** @brief  Generic preauth option attribute/value pairs */
 typedef struct _krb5_gic_opt_pa_data {
     char *attr;
     char *value;
@@ -2483,7 +2479,7 @@ struct _krb5_tkt_creds_context;
 typedef struct _krb5_tkt_creds_context *krb5_tkt_creds_context;
 
 /**
- * Create a context to get credentials from a KDC's Ticket Granting Service.
+ * @brief Create a context to get credentials from a KDC's Ticket Granting Service.
  *
  * The resulting TGS acquisition context can be used asynchronously with
  * krb5_tkt_creds_step() or synchronously with krb5_tkt_creds_get().  See also
@@ -2503,7 +2499,7 @@ krb5_tkt_creds_init(krb5_context context, krb5_ccache ccache,
                     krb5_tkt_creds_context *ctx);
 
 /**
- * Synchronously obtain credentials within an acquisition context.
+ * @brief Synchronously obtain credentials within an acquisition context.
  *
  * This function repeatedly generates requests, sends them to the appropriate
  * realms' KDCs, and processes the replies until credentials are available for
@@ -2516,7 +2512,7 @@ krb5_error_code KRB5_CALLCONV
 krb5_tkt_creds_get(krb5_context context, krb5_tkt_creds_context ctx);
 
 /**
- * Retrieve credentials from an acquisition context, filling in @a creds.
+ * @brief Retrieve credentials from an acquisition context, filling in @a creds.
  *
  * The acquisition context must have completed obtaining credentials via either
  * krb5_tkt_creds_get() or krb5_tkt_creds_step().
@@ -2530,7 +2526,7 @@ krb5_tkt_creds_get_creds(krb5_context context, krb5_tkt_creds_context ctx,
                          krb5_creds *creds);
 
 /**
- * Release the resources used by an acquisition context.
+ * @brief Release the resources used by an acquisition context.
  *
  * @param[in]  context  A krb5 library context (see krb5_init_context())
  * @param[in]  ctx      A TGS acquisition context (see krb5_tkt_creds_init())
@@ -2541,7 +2537,7 @@ krb5_tkt_creds_free(krb5_context context, krb5_tkt_creds_context ctx);
 #define KRB5_TKT_CREDS_STEP_FLAG_CONTINUE 0x1  /* More responses needed. */
 
 /**
- * Process a response and generate the next request to acquire credentials.
+ * @brief Process a response and generate the next request to acquire credentials.
  *
  * On the first call, @a in should be empty or NULL.  If more responses are
  * needed, the @a flags output parameter will contain @a
@@ -2562,7 +2558,7 @@ krb5_tkt_creds_step(krb5_context context, krb5_tkt_creds_context ctx,
                     unsigned int *flags);
 
 /**
- * Retrieve ticket times for obtained credentials, filling in @a times.
+ * @brief Retrieve ticket times for obtained credentials, filling in @a times.
  *
  * The acquisition context must have completed obtaining credentials via either
  * krb5_tkt_creds_get() or krb5_tkt_creds_step().