Skip to content

Commit

Permalink
Work around Doxygen 1.9.7 change
Browse files Browse the repository at this point in the history 
Doxygen 1.9.7 avoids duplicating member definitions in the XML
documents for groups and header files (doxygen/doxygen#9797).  This
change breaks the current Doxygen-REST bridge, which expects to find
memberdef elements in krb5_8hin.xml.  To work around this problem,
remove the @group and @ref declarations in krb5.hin; they were not
translated into REST as it was.

Also remove a deprecated setting in Doxyfile.

ticket: 9104 (new)
tags: pullup
target_version: 1.21-next
target_version: 1.20-next
  • Loading branch information
@greghudson
greghudson committed Sep 21, 2023
1 parent 635c8cc commit 6ed1f8e
Show file tree
Hide file tree
Showing 2 changed files with 32 additions and 62 deletions.
1 change: 0 additions & 1 deletion src/doc/Doxyfile.in
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,5 @@ GENERATE_HTML = NO
GENERATE_LATEX = NO
GENERATE_XML = YES
PREDEFINED = KRB5_DEPRECATED KRB5_OLD_CRYPTO
CLASS_DIAGRAMS = NO
CASE_SENSE_NAMES = NO
QUIET = YES
93 changes: 32 additions & 61 deletions src/include/krb5/krb5.hin
View file
Original file line number Diff line number Diff line change
Expand Up @@ -52,10 +52,6 @@
#ifndef KRB5_GENERAL__
#define KRB5_GENERAL__
/** @defgroup KRB5_H krb5 library API
* @{
*/

/* By default, do not expose deprecated interfaces. */
#ifndef KRB5_DEPRECATED
#define KRB5_DEPRECATED 0
Expand Down Expand Up @@ -410,7 +406,7 @@ typedef struct _krb5_enc_data {
* structures before calling into an iov API.
*/
typedef struct _krb5_crypto_iov {
krb5_cryptotype flags; /**< @ref KRB5_CRYPTO_TYPE type of the iov */
krb5_cryptotype flags; /**< iov type (see KRB5_CRYPTO_TYPE macros) */
krb5_data data;
} krb5_crypto_iov;

Expand Down Expand Up @@ -500,7 +496,7 @@ enum {
*
* @param [in] context Library context
* @param [in] key Encryption key
* @param [in] usage Key usage (see @ref KRB5_KEYUSAGE types)
* @param [in] usage Key usage (see KRB5_KEYUSAGE macros)
* @param [in,out] cipher_state Cipher state; specify NULL if not needed
* @param [in] input Data to be encrypted
* @param [out] output Encrypted data
Expand Down Expand Up @@ -528,7 +524,7 @@ krb5_c_encrypt(krb5_context context, const krb5_keyblock *key,
*
* @param [in] context Library context
* @param [in] key Encryption key
* @param [in] usage Key usage (see @ref KRB5_KEYUSAGE types)
* @param [in] usage Key usage (see KRB5_KEYUSAGE macros)
* @param [in,out] cipher_state Cipher state; specify NULL if not needed
* @param [in] input Encrypted data
* @param [out] output Decrypted data
Expand Down Expand Up @@ -601,7 +597,7 @@ krb5_c_keylengths(krb5_context context, krb5_enctype enctype,
*
* @param [in] context Library context
* @param [in] key Key
* @param [in] usage Key usage (see @ref KRB5_KEYUSAGE types)
* @param [in] usage Key usage (see KRB5_KEYUSAGE macros)
* @param [out] new_state New cipher state
*
* @retval 0 Success; otherwise - Kerberos error codes
Expand Down Expand Up @@ -854,7 +850,7 @@ krb5_c_enctype_compare(krb5_context context, krb5_enctype e1, krb5_enctype e2,
* @param [in] context Library context
* @param [in] cksumtype Checksum type (0 for mandatory type)
* @param [in] key Encryption key for a keyed checksum
* @param [in] usage Key usage (see @ref KRB5_KEYUSAGE types)
* @param [in] usage Key usage (see KRB5_KEYUSAGE macros)
* @param [in] input Input data
* @param [out] cksum Generated checksum
*
Expand Down Expand Up @@ -936,9 +932,6 @@ krb5_error_code KRB5_CALLCONV
krb5_c_keyed_checksum_types(krb5_context context, krb5_enctype enctype,
unsigned int *count, krb5_cksumtype **cksumtypes);

/** @defgroup KRB5_KEYUSAGE KRB5_KEYUSAGE
* @{
*/
#define KRB5_KEYUSAGE_AS_REQ_PA_ENC_TS 1
#define KRB5_KEYUSAGE_KDC_REP_TICKET 2
#define KRB5_KEYUSAGE_AS_REP_ENCPART 3
Expand Down Expand Up @@ -969,15 +962,15 @@ krb5_c_keyed_checksum_types(krb5_context context, krb5_enctype enctype,

/* Defined in Integrating SAM Mechanisms with Kerberos draft */
#define KRB5_KEYUSAGE_PA_SAM_CHALLENGE_CKSUM 25
/** Note conflict with @ref KRB5_KEYUSAGE_PA_S4U_X509_USER_REQUEST */
/* Note conflict with KRB5_KEYUSAGE_PA_S4U_X509_USER_REQUEST */
#define KRB5_KEYUSAGE_PA_SAM_CHALLENGE_TRACKID 26
/** Note conflict with @ref KRB5_KEYUSAGE_PA_S4U_X509_USER_REPLY */
/* Note conflict with KRB5_KEYUSAGE_PA_S4U_X509_USER_REPLY */
#define KRB5_KEYUSAGE_PA_SAM_RESPONSE 27

/* Defined in [MS-SFU] */
/** Note conflict with @ref KRB5_KEYUSAGE_PA_SAM_CHALLENGE_TRACKID */
/* Note conflict with KRB5_KEYUSAGE_PA_SAM_CHALLENGE_TRACKID */
#define KRB5_KEYUSAGE_PA_S4U_X509_USER_REQUEST 26
/** Note conflict with @ref KRB5_KEYUSAGE_PA_SAM_RESPONSE */
/* Note conflict with KRB5_KEYUSAGE_PA_SAM_RESPONSE */
#define KRB5_KEYUSAGE_PA_S4U_X509_USER_REPLY 27

/* unused */
Expand All @@ -1002,7 +995,6 @@ krb5_c_keyed_checksum_types(krb5_context context, krb5_enctype enctype,
* implementation. */
#define KRB5_KEYUSAGE_PA_FX_COOKIE 513 /**< Used for encrypted FAST cookies */
#define KRB5_KEYUSAGE_PA_AS_FRESHNESS 514 /**< Used for freshness tokens */
/** @} */ /* end of KRB5_KEYUSAGE group */

/**
* Verify that a specified encryption type is a valid Kerberos encryption type.
Expand Down Expand Up @@ -1046,9 +1038,6 @@ krb5_boolean KRB5_CALLCONV
krb5_c_is_keyed_cksum(krb5_cksumtype ctype);

/* AEAD APIs */
/** @defgroup KRB5_CRYPTO_TYPE KRB5_CRYPTO_TYPE
* @{
*/
#define KRB5_CRYPTO_TYPE_EMPTY 0 /**< [in] ignored */
#define KRB5_CRYPTO_TYPE_HEADER 1 /**< [out] header */
#define KRB5_CRYPTO_TYPE_DATA 2 /**< [in, out] plaintext */
Expand All @@ -1059,15 +1048,14 @@ krb5_c_is_keyed_cksum(krb5_cksumtype ctype);
#define KRB5_CRYPTO_TYPE_STREAM 7 /**< [in] entire message without
decomposing the structure into
header, data and trailer buffers */
/** @} */ /* end of KRB5_CRYPTO_TYPE group */

/**
* Fill in a checksum element in IOV array (operates on keyblock)
*
* @param [in] context Library context
* @param [in] cksumtype Checksum type (0 for mandatory type)
* @param [in] key Encryption key for a keyed checksum
* @param [in] usage Key usage (see @ref KRB5_KEYUSAGE types)
* @param [in] usage Key usage (see KRB5_KEYUSAGE macros)
* @param [in,out] data IOV array
* @param [in] num_data Size of @a data
*
Expand All @@ -1093,7 +1081,7 @@ krb5_c_make_checksum_iov(krb5_context context, krb5_cksumtype cksumtype,
* @param [in] context Library context
* @param [in] cksumtype Checksum type (0 for mandatory type)
* @param [in] key Encryption key for a keyed checksum
* @param [in] usage Key usage (see @ref KRB5_KEYUSAGE types)
* @param [in] usage Key usage (see KRB5_KEYUSAGE macros)
* @param [in] data IOV array
* @param [in] num_data Size of @a data
* @param [out] valid Non-zero for success, zero for failure
Expand All @@ -1120,7 +1108,7 @@ krb5_c_verify_checksum_iov(krb5_context context, krb5_cksumtype cksumtype,
*
* @param [in] context Library context
* @param [in] keyblock Encryption key
* @param [in] usage Key usage (see @ref KRB5_KEYUSAGE types)
* @param [in] usage Key usage (see KRB5_KEYUSAGE macros)
* @param [in] cipher_state Cipher state; specify NULL if not needed
* @param [in,out] data IOV array. Modified in-place.
* @param [in] num_data Size of @a data
Expand Down Expand Up @@ -1155,7 +1143,7 @@ krb5_c_encrypt_iov(krb5_context context, const krb5_keyblock *keyblock,
*
* @param [in] context Library context
* @param [in] keyblock Encryption key
* @param [in] usage Key usage (see @ref KRB5_KEYUSAGE types)
* @param [in] usage Key usage (see KRB5_KEYUSAGE macros)
* @param [in] cipher_state Cipher state; specify NULL if not needed
* @param [in,out] data IOV array. Modified in-place.
* @param [in] num_data Size of @a data
Expand Down Expand Up @@ -1190,7 +1178,7 @@ krb5_c_decrypt_iov(krb5_context context, const krb5_keyblock *keyblock,
*
* @param [in] context Library context
* @param [in] enctype Encryption type
* @param [in] type Type field (See @ref KRB5_CRYPTO_TYPE types)
* @param [in] type Type field (See KRB5_CRYPTO_TYPE macros)
* @param [out] size Length of the @a type specific to @a enctype
*
* @retval 0 Success; otherwise - Kerberos error codes
Expand Down Expand Up @@ -1273,7 +1261,7 @@ krb5_k_key_enctype(krb5_context context, krb5_key key);
*
* @param [in] context Library context
* @param [in] key Encryption key
* @param [in] usage Key usage (see @ref KRB5_KEYUSAGE types)
* @param [in] usage Key usage (see KRB5_KEYUSAGE macros)
* @param [in,out] cipher_state Cipher state; specify NULL if not needed
* @param [in] input Data to be encrypted
* @param [out] output Encrypted data
Expand Down Expand Up @@ -1301,7 +1289,7 @@ krb5_k_encrypt(krb5_context context, krb5_key key, krb5_keyusage usage,
*
* @param [in] context Library context
* @param [in] key Encryption key
* @param [in] usage Key usage (see @ref KRB5_KEYUSAGE types)
* @param [in] usage Key usage (see KRB5_KEYUSAGE macros)
* @param [in] cipher_state Cipher state; specify NULL if not needed
* @param [in,out] data IOV array. Modified in-place.
* @param [in] num_data Size of @a data
Expand Down Expand Up @@ -1336,7 +1324,7 @@ krb5_k_encrypt_iov(krb5_context context, krb5_key key, krb5_keyusage usage,
*
* @param [in] context Library context
* @param [in] key Encryption key
* @param [in] usage Key usage (see @ref KRB5_KEYUSAGE types)
* @param [in] usage Key usage (see KRB5_KEYUSAGE macros)
* @param [in,out] cipher_state Cipher state; specify NULL if not needed
* @param [in] input Encrypted data
* @param [out] output Decrypted data
Expand Down Expand Up @@ -1365,7 +1353,7 @@ krb5_k_decrypt(krb5_context context, krb5_key key, krb5_keyusage usage,
*
* @param [in] context Library context
* @param [in] key Encryption key
* @param [in] usage Key usage (see @ref KRB5_KEYUSAGE types)
* @param [in] usage Key usage (see KRB5_KEYUSAGE macros)
* @param [in] cipher_state Cipher state; specify NULL if not needed
* @param [in,out] data IOV array. Modified in-place.
* @param [in] num_data Size of @a data
Expand Down Expand Up @@ -1400,7 +1388,7 @@ krb5_k_decrypt_iov(krb5_context context, krb5_key key, krb5_keyusage usage,
* @param [in] context Library context
* @param [in] cksumtype Checksum type (0 for mandatory type)
* @param [in] key Encryption key for a keyed checksum
* @param [in] usage Key usage (see @ref KRB5_KEYUSAGE types)
* @param [in] usage Key usage (see KRB5_KEYUSAGE macros)
* @param [in] input Input data
* @param [out] cksum Generated checksum
*
Expand Down Expand Up @@ -1430,7 +1418,7 @@ krb5_k_make_checksum(krb5_context context, krb5_cksumtype cksumtype,
* @param [in] context Library context
* @param [in] cksumtype Checksum type (0 for mandatory type)
* @param [in] key Encryption key for a keyed checksum
* @param [in] usage Key usage (see @ref KRB5_KEYUSAGE types)
* @param [in] usage Key usage (see KRB5_KEYUSAGE macros)
* @param [in,out] data IOV array
* @param [in] num_data Size of @a data
*
Expand Down Expand Up @@ -1484,7 +1472,7 @@ krb5_k_verify_checksum(krb5_context context, krb5_key key, krb5_keyusage usage,
* @param [in] context Library context
* @param [in] cksumtype Checksum type (0 for mandatory type)
* @param [in] key Encryption key for a keyed checksum
* @param [in] usage Key usage (see @ref KRB5_KEYUSAGE types)
* @param [in] usage Key usage (see KRB5_KEYUSAGE macros)
* @param [in] data IOV array
* @param [in] num_data Size of @a data
* @param [out] valid Non-zero for success, zero for failure
Expand Down Expand Up @@ -1662,11 +1650,9 @@ krb5_verify_checksum(krb5_context context, krb5_cksumtype ctype,

/* definitions for ap_options fields */

/** @defgroup AP_OPTS AP_OPTS
*
/*
* ap_options are 32 bits; each host is responsible to put the 4 bytes
* representing these bits into net order before transmission
* @{
*/
#define AP_OPTS_RESERVED 0x80000000
#define AP_OPTS_USE_SESSION_KEY 0x40000000 /**< Use session key */
Expand Down Expand Up @@ -1707,7 +1693,6 @@ krb5_verify_checksum(krb5_context context, krb5_cksumtype ctype,


#define AP_OPTS_WIRE_MASK 0xfffffff0
/** @} */ /* end of AP_OPTS group */

/* definitions for ad_type fields. */
#define AD_TYPE_RESERVED 0x8000
Expand Down Expand Up @@ -1863,9 +1848,6 @@ krb5_verify_checksum(krb5_context context, krb5_cksumtype ctype,

/* authorization data types. See RFC 4120 section 5.2.6 */

/** @defgroup KRB5_AUTHDATA KRB5_AUTHDATA
* @{
*/
#define KRB5_AUTHDATA_IF_RELEVANT 1
#define KRB5_AUTHDATA_KDC_ISSUED 4
#define KRB5_AUTHDATA_AND_OR 5
Expand All @@ -1880,7 +1862,6 @@ krb5_verify_checksum(krb5_context context, krb5_cksumtype ctype,
#define KRB5_AUTHDATA_FX_ARMOR 71
#define KRB5_AUTHDATA_AUTH_INDICATOR 97
#define KRB5_AUTHDATA_AP_OPTIONS 143
/** @} */ /* end of KRB5_AUTHDATA group */

/* password change constants */
#define KRB5_KPASSWD_SUCCESS 0 /**< Success */
Expand Down Expand Up @@ -2190,9 +2171,6 @@ typedef struct _krb5_pa_pac_req {
* begin "safepriv.h"
*/

/** @defgroup KRB5_AUTH_CONTEXT KRB5_AUTH_CONTEXT
* @{
*/
/** Prevent replays with timestamps and replay cache. */
#define KRB5_AUTH_CONTEXT_DO_TIME 0x00000001
/** Save timestamps for application. */
Expand All @@ -2203,7 +2181,6 @@ typedef struct _krb5_pa_pac_req {
#define KRB5_AUTH_CONTEXT_RET_SEQUENCE 0x00000008
#define KRB5_AUTH_CONTEXT_PERMIT_ALL 0x00000010
#define KRB5_AUTH_CONTEXT_USE_SUBKEY 0x00000020
/** @} */ /* end of KRB5_AUTH_CONTEXT group */

/**
* Replay data.
Expand Down Expand Up @@ -3033,17 +3010,13 @@ krb5_server_decrypt_ticket_keytab(krb5_context context, const krb5_keytab kt,
void KRB5_CALLCONV
krb5_free_tgt_creds(krb5_context context, krb5_creds **tgts);

/** @defgroup KRB5_GC KRB5_GC
* @{
*/
#define KRB5_GC_USER_USER 1 /**< Want user-user ticket */
#define KRB5_GC_CACHED 2 /**< Want cached ticket only */
#define KRB5_GC_CANONICALIZE 4 /**< Set canonicalize KDC option */
#define KRB5_GC_NO_STORE 8 /**< Do not store in credential cache */
#define KRB5_GC_FORWARDABLE 16 /**< Acquire forwardable tickets */
#define KRB5_GC_NO_TRANSIT_CHECK 32 /**< Disable transited check */
#define KRB5_GC_CONSTRAINED_DELEGATION 64 /**< Constrained delegation */
/** @} */ /* end of KRB5_GC group */

/**
* Get an additional ticket.
Expand Down Expand Up @@ -3142,7 +3115,7 @@ krb5_get_credentials_renew(krb5_context context, krb5_flags options,
*
* @param [in] context Library context
* @param [in,out] auth_context Pre-existing or newly created auth context
* @param [in] ap_req_options @ref AP_OPTS options
* @param [in] ap_req_options Options (see AP_OPTS macros)
* @param [in] service Service name, or NULL to use @c "host"
* @param [in] hostname Host name, or NULL to use local hostname
* @param [in] in_data Application data to be checksummed in the
Expand Down Expand Up @@ -3170,7 +3143,7 @@ krb5_mk_req(krb5_context context, krb5_auth_context *auth_context,
*
* @param [in] context Library context
* @param [in,out] auth_context Pre-existing or newly created auth context
* @param [in] ap_req_options @ref AP_OPTS options
* @param [in] ap_req_options Options (see AP_OPTS macros)
* @param [in] in_data Application data to be checksummed in the
* authenticator, or NULL
* @param [in] in_creds Credentials for the service with valid ticket
Expand Down Expand Up @@ -5279,7 +5252,7 @@ krb5_kt_read_service_key(krb5_context context, krb5_pointer keyprocarg,
*
* Fields in @a auth_context specify the checksum type, the keyblock that
* can be used to seed the checksum, full addresses (host and port) for
* the sender and receiver, and @ref KRB5_AUTH_CONTEXT flags.
* the sender and receiver, and KRB5_AUTH_CONTEXT flags.
*
* The local address in @a auth_context must be set, and is used to form the
* sender address used in the KRB-SAFE message. The remote address is
Expand Down Expand Up @@ -5367,7 +5340,7 @@ krb5_mk_priv(krb5_context context, krb5_auth_context auth_context,
* with the receiver's application version
* @param [in] client Client principal
* @param [in] server Server principal
* @param [in] ap_req_options @ref AP_OPTS options
* @param [in] ap_req_options Options (see AP_OPTS macros)
* @param [in] in_data Data to be sent to the server
* @param [in] in_creds Input credentials, or NULL to use @a ccache
* @param [in] ccache Credential cache
Expand Down Expand Up @@ -6608,13 +6581,13 @@ krb5_prompter_posix(krb5_context context, void *data, const char *name,
/**
* A container for a set of preauthentication questions and answers
*
* A responder context is supplied by the krb5 authentication system to a @ref
* A responder context is supplied by the krb5 authentication system to a
* krb5_responder_fn callback. It contains a list of questions and can receive
* answers. Questions contained in a responder context can be listed using
* krb5_responder_list_questions(), retrieved using
* krb5_responder_get_challenge(), or answered using
* krb5_responder_set_answer(). The form of a question's challenge and
* answer depend on the question name.
* krb5_responder_set_answer(). The form of a question's challenge and answer
* depend on the question name.
*
* @version New in 1.11
*/
Expand Down Expand Up @@ -7527,7 +7500,7 @@ typedef struct _krb5_tkt_creds_context *krb5_tkt_creds_context;
* @param[in] context Library context
* @param[in] ccache Credential cache handle
* @param[in] creds Input credentials
* @param[in] options @ref KRB5_GC options for this request.
* @param[in] options Options (see KRB5_GC macros)
* @param[out] ctx New TGS request context
*
* This function prepares to obtain credentials matching @a creds, either by
Expand Down Expand Up @@ -8064,7 +8037,7 @@ krb5_clear_error_message(krb5_context ctx);
* Unwrap authorization data.
*
* @param [in] context Library context
* @param [in] type @ref KRB5_AUTHDATA type of @a container
* @param [in] type Container type (see KRB5_AUTHDATA macros)
* @param [in] container Authorization data to be decoded
* @param [out] authdata List of decoded authorization data
*
Expand All @@ -8081,7 +8054,7 @@ krb5_decode_authdata_container(krb5_context context,
* Wrap authorization data in a container.
*
* @param [in] context Library context
* @param [in] type @ref KRB5_AUTHDATA type of @a container
* @param [in] type Container type (see KRB5_AUTHDATA macros)
* @param [in] authdata List of authorization data to be encoded
* @param [out] container List of encoded authorization data
*
Expand Down Expand Up @@ -8614,6 +8587,4 @@ KRB5INT_END_DECLS

#undef KRB5_ATTR_DEPRECATED

/** @} */ /* end of KRB5_H group */

#endif /* KRB5_GENERAL__ */

0 comments on commit 6ed1f8e

Please sign in to comment.