svn rev #24596: trunk/src/include/krb5/
tsitkova@MIT.EDU
tsitkova at MIT.EDU
Thu Jan 13 10:32:47 EST 2011
http://src.mit.edu/fisheye/changelog/krb5/?cs=24596
Commit By: tsitkova
Log Message:
Doxygen style re-formating of the existing comments.
Changed Files:
U trunk/src/include/krb5/krb5.hin
Modified: trunk/src/include/krb5/krb5.hin
===================================================================
--- trunk/src/include/krb5/krb5.hin 2011-01-12 23:31:58 UTC (rev 24595)
+++ trunk/src/include/krb5/krb5.hin 2011-01-13 15:32:47 UTC (rev 24596)
@@ -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 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 @@
* begin "hostaddr.h"
*/
-/* structure for address */
+/** structure for address */
typedef struct _krb5_address {
krb5_magic magic;
krb5_addrtype addrtype;
@@ -350,7 +348,7 @@
* 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 @@
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 @@
* 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 @@
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_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 @@
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 @@
} 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_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_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_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 @@
* 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 @@
} 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 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 @@
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 @@
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_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_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_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 @@
#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 @@
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().
More information about the cvs-krb5
mailing list