#ifndef KRB5_GENERAL__
#define KRB5_GENERAL__
-/* By default, do not expose deprecated interfaces. */
+/** @defgroup KRB5_H krb5 library API
+ * @{
+ */
+
+ /* By default, do not expose deprecated interfaces. */
#ifndef KRB5_DEPRECATED
#define KRB5_DEPRECATED 0
#endif
char *data;
} krb5_data;
+/* Originally introduced for PKINIT; now unused. Do not use this. */
typedef struct _krb5_octet_data {
krb5_magic magic;
unsigned int length;
* Per V5 spec on definition of principal types
*/
-/* Name type not known */
-#define KRB5_NT_UNKNOWN 0
-/* Just the name of the principal as in DCE, or for users */
-#define KRB5_NT_PRINCIPAL 1
-/* Service and other unique instance (krbtgt) */
-#define KRB5_NT_SRV_INST 2
-/* Service with host name as instance (telnet, rcommands) */
-#define KRB5_NT_SRV_HST 3
-/* Service with host as remaining components */
-#define KRB5_NT_SRV_XHST 4
-/* Unique ID */
-#define KRB5_NT_UID 5
-/* PKINIT */
-#define KRB5_NT_X500_PRINCIPAL 6
-/* Name in form of SMTP email name */
-#define KRB5_NT_SMTP_NAME 7
-/* Windows 2000 UPN */
-#define KRB5_NT_ENTERPRISE_PRINCIPAL 10
-#define KRB5_NT_WELLKNOWN 11
-/* First component of NT_WELLKNOWN principals */
-#define KRB5_WELLKNOWN_NAMESTR "WELLKNOWN"
-/* Windows 2000 UPN and SID */
-#define KRB5_NT_MS_PRINCIPAL -128
-/* NT 4 style name */
-#define KRB5_NT_MS_PRINCIPAL_AND_ID -129
-/* NT 4 style name and SID */
-#define KRB5_NT_ENT_PRINCIPAL_AND_ID -130
+#define KRB5_NT_UNKNOWN 0 /**< Name type not known */
+#define KRB5_NT_PRINCIPAL 1 /**< Just the name of the principal
+ as in DCE, or for users */
+#define KRB5_NT_SRV_INST 2 /**< Service and other unique instance (krbtgt) */
+#define KRB5_NT_SRV_HST 3 /**< Service with host name as instance
+ (telnet, rcommands) */
+#define KRB5_NT_SRV_XHST 4 /**< Service with host as remaining components */
+#define KRB5_NT_UID 5 /**< Unique ID */
+#define KRB5_NT_X500_PRINCIPAL 6 /**< PKINIT */
+#define KRB5_NT_SMTP_NAME 7 /**< Name in form of SMTP email name */
+#define KRB5_NT_ENTERPRISE_PRINCIPAL 10 /**< Windows 2000 UPN */
+#define KRB5_NT_WELLKNOWN 11 /**< Well-known (special) principal */
+#define KRB5_WELLKNOWN_NAMESTR "WELLKNOWN" /**< First component of
+ NT_WELLKNOWN principals */
+#define KRB5_NT_MS_PRINCIPAL -128 /**< Windows 2000 UPN and SID */
+#define KRB5_NT_MS_PRINCIPAL_AND_ID -129 /**< NT 4 style name */
+#define KRB5_NT_ENT_PRINCIPAL_AND_ID -130 /**< NT 4 style name and SID */
/** Constant version of krb5_principal_data */
typedef const krb5_principal_data *krb5_const_principal;
*
* This function returns constant storage that must not be freed.
*
- * @sa KRB5_ANONYMOUS_PRINCSTR
+ * @sa #KRB5_ANONYMOUS_PRINCSTR
*/
krb5_const_principal KRB5_CALLCONV
krb5_anonymous_principal(void);
-#define KRB5_ANONYMOUS_REALMSTR "WELLKNOWN:ANONYMOUS"
-#define KRB5_ANONYMOUS_PRINCSTR "ANONYMOUS" /* wellknown name type */
+#define KRB5_ANONYMOUS_REALMSTR "WELLKNOWN:ANONYMOUS" /**< Anonymous realm */
+#define KRB5_ANONYMOUS_PRINCSTR "ANONYMOUS" /**< Anonymous principal name */
/*
* end "base-defs.h"
*/
#define CKSUMTYPE_NIST_SHA 0x0009
#define CKSUMTYPE_HMAC_SHA1_DES3 0x000c
#define CKSUMTYPE_HMAC_SHA1_96_AES128 0x000f /**< RFC 3962. Used with
- ENCTYPE_AES128_CTS_HMAC_SHA1_96 */
+ ENCTYPE_AES128_CTS_HMAC_SHA1_96 */
#define CKSUMTYPE_HMAC_SHA1_96_AES256 0x0010 /**< RFC 3962. Used with
- ENCTYPE_AES256_CTS_HMAC_SHA1_96 */
+ ENCTYPE_AES256_CTS_HMAC_SHA1_96 */
#define CKSUMTYPE_MD5_HMAC_ARCFOUR -137 /*Microsoft netlogon cksumtype*/
#define CKSUMTYPE_HMAC_MD5_ARCFOUR -138 /*Microsoft md5 hmac cksumtype*/
#define KRB5_CRYPTO_TYPE_TRAILER 5 /**< [out] checksum for encrypt */
#define KRB5_CRYPTO_TYPE_CHECKSUM 6 /**< [out] checksum for MIC */
#define KRB5_CRYPTO_TYPE_STREAM 7 /**< [in] entire message without
- decomposing the structure into
- header, data and trailer buffers */
+ decomposing the structure into
+ header, data and trailer buffers */
/** @} */ /* end of KRB5_CRYPTO_TYPE group */
/**
#define AP_OPTS_RESERVED 0x80000000
#define AP_OPTS_USE_SESSION_KEY 0x40000000 /**< Use session key */
#define AP_OPTS_MUTUAL_REQUIRED 0x20000000 /**< Perform a mutual
- authentication exchange */
+ authentication exchange */
#define AP_OPTS_ETYPE_NEGOTIATION 0x00000002
#define AP_OPTS_USE_SUBKEY 0x00000001 /**< Generate a subsession key
- from the current session key
- obtained from the
- credentials */
+ from the current session key
+ obtained from the
+ credentials */
/* #define AP_OPTS_RESERVED 0x10000000 */
/* #define AP_OPTS_RESERVED 0x08000000 */
/* #define AP_OPTS_RESERVED 0x04000000 */
/** @} */ /* end of KRB5_AUTHDATA group */
/* password change constants */
-#define KRB5_KPASSWD_SUCCESS 0
-#define KRB5_KPASSWD_MALFORMED 1
-#define KRB5_KPASSWD_HARDERROR 2
-#define KRB5_KPASSWD_AUTHERROR 3
-#define KRB5_KPASSWD_SOFTERROR 4
+#define KRB5_KPASSWD_SUCCESS 0 /**< Success */
+#define KRB5_KPASSWD_MALFORMED 1 /**< Malformed request */
+#define KRB5_KPASSWD_HARDERROR 2 /**< Server error */
+#define KRB5_KPASSWD_AUTHERROR 3 /**< Authentication error */
+#define KRB5_KPASSWD_SOFTERROR 4 /**< Password change rejected */
/* These are Microsoft's extensions in RFC 3244, and it looks like
they'll become standardized, possibly with other additions. */
#define KRB5_KPASSWD_ACCESSDENIED 5 /* unused */
/** Ticket start time, end time, and renewal duration. */
typedef struct _krb5_ticket_times {
krb5_timestamp authtime; /**< Time at which KDC issued the initial ticket that corresponds to this ticket */
- /* XXX ? should ktime in KDC_REP == authtime
- in ticket? otherwise client can't get this */
+ /* XXX ? should ktime in KDC_REP == authtime
+ in ticket? otherwise client can't get this */
krb5_timestamp starttime; /**< optional in ticket, if not present, use @a authtime */
krb5_timestamp endtime; /**< Ticket expiration time */
krb5_timestamp renew_till; /**< Latest time at which renewal of ticket can be valid */
krb5_data tr_contents; /**< Contents */
} krb5_transited;
- /** Encrypted part of ticket. */
+/** Encrypted part of ticket. */
typedef struct _krb5_enc_tkt_part {
krb5_magic magic;
/* to-be-encrypted portion */
krb5_octet *contents; /**< Data */
} krb5_pa_data;
-/*
- * The FAST error handling logic currently assumes that pointers to 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.
- */
-/** Typed data */
+/* Don't use this; use krb5_pa_data instead. */
typedef struct _krb5_typed_data {
krb5_magic magic;
krb5_int32 type;
krb5_cred_enc_part *enc_part2; /**< Unencrypted version, if available */
} krb5_cred;
-/*
- * Sandia password generation structure
- * Used by internal functions only
- */
+/* Unused, but here for API compatibility. */
typedef struct _passwd_phrase_element {
krb5_magic magic;
krb5_data *passwd;
krb5_data *phrase;
} passwd_phrase_element;
-/*
- * Password data.
- * Used by internal functions only
- */
+/* Unused, but here for API compatibility. */
typedef struct _krb5_pwd_data {
krb5_magic magic;
int sequence_count;
passwd_phrase_element **element;
} krb5_pwd_data;
-/* these need to be here so the typedefs are available for the prototypes */
-/*
- * Note for Windows 2000 compatibility this is encoded
- * in the enc_padata field of the krb5_enc_kdc_rep_part.
- */
+/* Unused, but here for API compatibility. */
typedef struct _krb5_pa_svr_referral_data {
/** Referred name, only realm is required */
krb5_principal principal;
} krb5_pa_svr_referral_data;
+/* Unused, but here for API compatibility. */
typedef struct _krb5_pa_server_referral_data {
krb5_data *referred_realm;
krb5_principal true_principal_name;
/** @defgroup KRB5_AUTH_CONTEXT KRB5_AUTH_CONTEXT
* @{
*/
-#define KRB5_AUTH_CONTEXT_DO_TIME 0x00000001 /**< set timestamp in the message */
+/** Prevent replays with timestamps and replay cache. */
+#define KRB5_AUTH_CONTEXT_DO_TIME 0x00000001
+/** Save timestamps for application. */
#define KRB5_AUTH_CONTEXT_RET_TIME 0x00000002
-#define KRB5_AUTH_CONTEXT_DO_SEQUENCE 0x00000004 /**< set sequence number in the message */
+/** Prevent replays with sequence numbers. */
+#define KRB5_AUTH_CONTEXT_DO_SEQUENCE 0x00000004
+/** Save sequence numbers for application. */
#define KRB5_AUTH_CONTEXT_RET_SEQUENCE 0x00000008
#define KRB5_AUTH_CONTEXT_PERMIT_ALL 0x00000010
#define KRB5_AUTH_CONTEXT_USE_SUBKEY 0x00000020
* @param [in] cache Credential cache handle
* @param [out] fullname_out Full name of cache
*
+ * @version First introduced in 1.10
*/
krb5_error_code KRB5_CALLCONV
krb5_cc_get_full_name(krb5_context context, krb5_ccache cache,
* @param [out] name Key table name
* @param [in] namelen Maximum length to fill in name
*
- * Fills in @a with the name of @a keytab including the type and delimiter.
+ * Fills in @a name with the name of @a keytab including the type and delimiter.
*
* @sa MAX_KEYTAB_NAME_LEN
*
#define KRB5_PRINCIPAL_PARSE_NO_REALM 0x1 /**< Error if realm is present */
#define KRB5_PRINCIPAL_PARSE_REQUIRE_REALM 0x2 /**< Error if realm is not present */
#define KRB5_PRINCIPAL_PARSE_ENTERPRISE 0x4 /**< Create single-component
- enterprise principle */
+ enterprise principle */
/**
* Convert a string principal name to a krb5_principal with flags
krb5_copy_authdata(krb5_context context,
krb5_authdata *const *in_authdat, krb5_authdata ***out);
+/**
+ * Find authorization data elements.
+ *
+ * @param [in] context Library context
+ * @param [in] ticket_authdata Authorization data list from ticket
+ * @param [in] ap_req_authdata Authorization data list from AP request
+ * @param [in] ad_type Authorization data type to find
+ * @param [out] results List of matching entries
+ *
+ * This function searches @a ticket_authdata and @a ap_req_authdata for
+ * elements of type @a ad_type. Either input list may be NULL, in which case
+ * it will not be searched; otherwise, the input lists must be terminated by
+ * NULL entries. This function will search inside AD-IF-RELEVANT containers if
+ * found in either list. Use krb5_free_authdata() to free @a results when it
+ * is no longer needed.
+ *
+ * @version First introduced in 1.10
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_find_authdata(krb5_context context, krb5_authdata *const *ticket_authdata,
+ krb5_authdata *const *ap_req_authdata,
+ krb5_authdatatype ad_type, krb5_authdata ***results);
+
/**
* Merge two authorization data lists into a new list.
*
*
* @param [in] context Library context
*
- * Try the environment variable KRB5CCNAME first then, if it is not set,
+ * Try the environment variable @a KRB5CCNAME first then, if it is not set,
* fall back on the default ccache name for the OS.
*
* @return
* @param [in] context Library context
* @param [in] type Credential cache type
*
+ * @version First introduced in 1.10
+ *
* @retval TRUE if @a type supports switching
* @retval FALSE if it does not or is not a valid credential cache type.
*/
* @retval KRB5_CC_NOTFOUND
*
* @sa krb5_cccol_cursor_new
+ *
+ * @version First introduced in 1.10
*/
krb5_error_code KRB5_CALLCONV
krb5_cc_cache_match(krb5_context context, krb5_principal client,
*
* Any other error code indicates a fatal error in the processing of a cache
* selection mechanism.
+ *
+ * @version First introduced in 1.10
*/
krb5_error_code KRB5_CALLCONV
krb5_cc_select(krb5_context context, krb5_principal server,
void KRB5_CALLCONV
krb5_free_data(krb5_context context, krb5_data *val);
-/**
- * Free storage associated with a @c krb5_octet_data structure and its pointer.
- *
- * @param [in] context Context structure
- * @param [in] val Data structure to be freed
- *
- * @return
- * None
- */
+/* Free a krb5_octet_data structure (should be unused). */
void KRB5_CALLCONV
krb5_free_octet_data(krb5_context context, krb5_octet_data *val);
*
* @param [in] context Library context
* @param [in] val String to be freed
+ *
+ * @version First introduced in 1.10
*/
void KRB5_CALLCONV
krb5_free_string(krb5_context context, char *val);
krb5_error_code KRB5_CALLCONV
krb5_timeofday(krb5_context context, register krb5_timestamp *timeret);
+/**
+ * Check if a timestamp is within the allowed clock skew of the current time.
+ *
+ * @param [in] context Library context
+ * @param [in] date Timestamp to check
+ *
+ * This function checks if @a date is close enough to the current time
+ * according to the configured allowable clock skew.
+ *
+ * @version First introduced in 1.10
+ *
+ * @retval 0 Success
+ * @retval KRB5KRB_AP_ERR_SKEW @a date is not within allowable clock skew
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_check_clockskew(krb5_context context, krb5_timestamp date);
+
/**
* Return all interface addresses for this host.
*
*
* The @a type can be one of the following:
*
- * @li #KRB5_NT_SRV_HOST canonicalizes the host name before looking up the
+ * @li #KRB5_NT_SRV_HST canonicalizes the host name before looking up the
* realm and generating the principal.
*
* @li #KRB5_NT_UNKNOWN accepts the hostname as given, and does not
* This function sets the send subkey in @a ac to @a key, incrementing its
* reference count.
*
+ * @version First introduced in 1.9
+ *
* @retval 0 Success; otherwise - Kerberos error codes
*/
krb5_error_code KRB5_CALLCONV
* This function sets the receiving subkey in @a ac to @a key, incrementing its
* reference count.
*
+ * @version First introduced in 1.9
+ *
* @retval 0 Success; otherwise - Kerberos error codes
*/
krb5_error_code KRB5_CALLCONV
* (like "aes128-cts-hmac-sha1-96"). If @a shortest is TRUE, it return the
* enctype's shortest alias (like "aes128-cts").
*
+ * @version First introduced in 1.9
+ *
* @retval 0 Success; otherwise - Kerberos error codes
*/
krb5_error_code KRB5_CALLCONV
*
* This function is similar to krb5_get_init_creds_opt_set_fast_ccache_name(),
* but uses a credential cache handle instead of a name.
+ *
+ * @version First introduced in 1.9
*/
krb5_error_code KRB5_CALLCONV
krb5_get_init_creds_opt_set_fast_ccache(krb5_context context,
* @warning Setting an expire callback with this API will cause
* krb5_get_init_creds_password() not to send password expiry warnings to the
* prompter, as it ordinarily may.
+ *
+ * @version First introduced in 1.9
*/
krb5_error_code KRB5_CALLCONV
krb5_get_init_creds_opt_set_expire_callback(krb5_context context,
struct _krb5_init_creds_context;
typedef struct _krb5_init_creds_context *krb5_init_creds_context;
-#define KRB5_INIT_CREDS_STEP_FLAG_CONTINUE 0x1 /* More responses needed */
+#define KRB5_INIT_CREDS_STEP_FLAG_CONTINUE 0x1 /**< More responses needed */
/**
* Free an initial credentials context.
*
* Use krb5_tkt_creds_free() to free @a ctx when it is no longer needed.
*
+ * @version First introduced in 1.9
+ *
* @retval 0 Success; otherwise - Kerberos error codes
*/
krb5_error_code KRB5_CALLCONV
* krb5_tkt_creds_init(). On successful return, the credentials can be
* retrieved with krb5_tkt_creds_get_creds().
*
+ * @version First introduced in 1.9
+ *
* @retval 0 Success; otherwise - Kerberos error codes
*/
krb5_error_code KRB5_CALLCONV
* krb5_tkt_creds_step(). Use krb5_free_cred_contents() to free @a creds when
* it is no longer needed.
*
+ * @version First introduced in 1.9
+ *
* @retval 0 Success; otherwise - Kerberos error codes
*/
krb5_error_code KRB5_CALLCONV
*
* @param[in] context Library context
* @param[in] ctx TGS request context
+ *
+ * @version First introduced in 1.9
*/
void KRB5_CALLCONV
krb5_tkt_creds_free(krb5_context context, krb5_tkt_creds_context ctx);
-#define KRB5_TKT_CREDS_STEP_FLAG_CONTINUE 0x1 /* More responses needed. */
+#define KRB5_TKT_CREDS_STEP_FLAG_CONTINUE 0x1 /**< More responses needed */
/**
* Get the next KDC request in a TGS exchange.
* transmit the next request using TCP rather than UDP. If this function
* returns any other error, the TGS exchange has failed.
*
+ * @version First introduced in 1.9
+ *
* @retval 0 Success; otherwise - Kerberos error codes
*/
krb5_error_code KRB5_CALLCONV
* The TGS request context must have completed obtaining credentials via either
* krb5_tkt_creds_get() or krb5_tkt_creds_step().
*
+ * @version First introduced in 1.9
+ *
* @retval 0 Success; otherwise - Kerberos error codes
*/
krb5_error_code KRB5_CALLCONV
/*
* Prompter enhancements
*/
+/** Prompt for password */
#define KRB5_PROMPT_TYPE_PASSWORD 0x1
+/** Prompt for new password (during password change) */
#define KRB5_PROMPT_TYPE_NEW_PASSWORD 0x2
+/** Prompt for new password again */
#define KRB5_PROMPT_TYPE_NEW_PASSWORD_AGAIN 0x3
+/** Prompt for preauthentication data (such as an OTP value) */
#define KRB5_PROMPT_TYPE_PREAUTH 0x4
typedef krb5_int32 krb5_prompt_type;
*/
void KRB5_CALLCONV
krb5_vset_error_message(krb5_context ctx, krb5_error_code code,
- const char *fmt, va_list args)
+ const char *fmt, va_list args)
#if !defined(__cplusplus) && (__GNUC__ > 2)
__attribute__((__format__(__printf__, 3, 0)))
#endif
*/
/* Microsoft defined types of data */
-#define PAC_LOGON_INFO 1 /**< Logon information */
-#define PAC_CREDENTIALS_INFO 2 /**< Credentials information */
-#define PAC_SERVER_CHECKSUM 6 /**< Server checksum */
-#define PAC_PRIVSVR_CHECKSUM 7 /**< KDC checksum */
-#define PAC_CLIENT_INFO 10 /**< Client name and ticket information */
-#define PAC_DELEGATION_INFO 11 /**< Constrained delegation information */
-#define PAC_UPN_DNS_INFO 12 /**< User principal name and DNS information */
+#define KRB5_PAC_LOGON_INFO 1 /**< Logon information */
+#define KRB5_PAC_CREDENTIALS_INFO 2 /**< Credentials information */
+#define KRB5_PAC_SERVER_CHECKSUM 6 /**< Server checksum */
+#define KRB5_PAC_PRIVSVR_CHECKSUM 7 /**< KDC checksum */
+#define KRB5_PAC_CLIENT_INFO 10 /**< Client name and ticket info */
+#define KRB5_PAC_DELEGATION_INFO 11 /**< Constrained delegation info */
+#define KRB5_PAC_UPN_DNS_INFO 12 /**< User principal name and DNS info */
struct krb5_pac_data;
/** PAC data structure to convey authorization information */
* if there isn't already a buffer of this type present.
*
* The valid values of @a type is one of the following:
- * @li #PAC_LOGON_INFO - Logon information
- * @li #PAC_CREDENTIALS_INFO - Credentials information
- * @li #PAC_SERVER_CHECKSUM - Server checksum
- * @li #PAC_PRIVSVR_CHECKSUM - KDC checksum
- * @li #PAC_CLIENT_INFO - Client name and ticket information
- * @li #PAC_DELEGATION_INFO - Constrained delegation information
- * @li #PAC_UPN_DNS_INFO - User principal name and DNS information
+ * @li #KRB5_PAC_LOGON_INFO - Logon information
+ * @li #KRB5_PAC_CREDENTIALS_INFO - Credentials information
+ * @li #KRB5_PAC_SERVER_CHECKSUM - Server checksum
+ * @li #KRB5_PAC_PRIVSVR_CHECKSUM - KDC checksum
+ * @li #KRB5_PAC_CLIENT_INFO - Client name and ticket information
+ * @li #KRB5_PAC_DELEGATION_INFO - Constrained delegation information
+ * @li #KRB5_PAC_UPN_DNS_INFO - User principal name and DNS information
*
* @retval 0 Success; otherwise - Kerberos error codes
*/
* @param [in] pac PAC handle
* @param [in] authtime Expected timestamp
* @param [in] principal Expected principal name (or NULL)
- * @param [in] server Key to validate server checksum
+ * @param [in] server Key to validate server checksum (or NULL)
* @param [in] privsvr Key to validate KDC checksum (or NULL)
*
* This function validates @a pac against the supplied @a server, @a privsvr,
* @a principal and @a authtime. If @a principal is NULL, the principal and
- * authtime are not verified. If @a privsvr is NULL, the KDC checksum is not
- * verified.
+ * authtime are not verified. If @a server or @a privsvr is NULL, the
+ * corresponding checksum is not verified.
*
* If successful, @a pac is marked as verified.
*
* and returns the signed encoding in @a data. @a pac is modified to include
* the server and KDC checksum buffers. Use krb5_free_data_contents() to free
* @a data when it is no longer needed.
+ *
+ * @version First introduced in 1.10
*/
krb5_error_code KRB5_CALLCONV
krb5_pac_sign(krb5_context context, krb5_pac pac, krb5_timestamp authtime,
* second argument so it can clean up @a cb_data. Supply a NULL value for @a
* fn to disable trace callbacks within @a context.
*
+ * @note This function overrides the information passed through the
+ * @a KRB5_TRACE environment variable.
+ *
+ * @version First introduced in 1.9
+ *
* @return Returns KRB5_TRACE_NOSUPP if tracing is not supported in the library
* (unless @a fn is NULL).
*/
* Open @a filename for appending (creating it, if necessary) and set up a
* callback to write trace events to it.
*
+ * @note This function overrides the information passed through the
+ * @a KRB5_TRACE environment variable.
+ *
+ * @version First introduced in 1.9
+ *
* @retval KRB5_TRACE_NOSUPP Tracing is not supported in the library.
*/
krb5_error_code KRB5_CALLCONV
#undef KRB5_ATTR_DEPRECATED
-#endif /* KRB5_GENERAL__ */
+/** @} */ /* end of KRB5_H group */
+#endif /* KRB5_GENERAL__ */
projects / krb5.git / blobdiff