From: Zhanna Tsitkov Date: Thu, 13 Jan 2011 15:32:47 +0000 (+0000) Subject: Doxygen style re-formating of the existing comments X-Git-Tag: krb5-1.10-alpha1~618 X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=098699e4e6407961fdceb9ed12e2d66e142d18c9;p=krb5.git Doxygen style re-formating of the existing comments git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@24596 dc483132-0cff-0310-8789-dd5450dbe970 --- diff --git a/src/include/krb5/krb5.hin b/src/include/krb5/krb5.hin index 51d7d728d..d74cf307e 100644 --- a/src/include/krb5/krb5.hin +++ b/src/include/krb5/krb5.hin @@ -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().