#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;
krb5_octet *data;
} krb5_octet_data;
-/*
- * Hack length for crypto library to use the afs_string_to_key It is
- * equivalent to -1 without possible sign extension
- * We also overload for an unset salt type length - which is also -1, but
- * hey, why not....
- */
+/* Originally used to recognize AFS and default salts. No longer used. */
#define SALT_TYPE_AFS_LENGTH UINT_MAX
#define SALT_TYPE_NO_LENGTH UINT_MAX
* 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"
*/
/** @} */ /* 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 */
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 [in] context Library context
* @param [in] name String representation of a principal name
- * @param [out] nprincipal Principal
+ * @param [out] principal_out New principal
*
* Convert a string representation of a principal name to a krb5_principal
* structure.
* @note The realm in a Kerberos @a name cannot contain slash, colon,
* or NULL characters.
*
- * Use krb5_free_principal() to free @a nprincipal when it is no longer needed.
+ * Use krb5_free_principal() to free @a principal_out when it is no longer
+ * needed.
*
* @retval
* 0 Success
* Kerberos error codes
*/
krb5_error_code KRB5_CALLCONV
-krb5_parse_name(krb5_context context, const char *name, krb5_principal *nprincipal);
+krb5_parse_name(krb5_context context, const char *name,
+ krb5_principal *principal_out);
#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 */
enterprise principle */
/**
- * Convert a string principal name to a krb5_principal with flags
+ * Convert a string principal name to a krb5_principal with flags.
*
* @param [in] context Library context
* @param [in] name String representation of a principal name
* @param [in] flags Flag
- * @param [out] nprincipal Principal
+ * @param [out] principal_out New principal
*
* Similar to krb5_parse_name(), this function converts a single-string
* representation of a principal name to a krb5_principal structure.
* @li #KRB5_PRINCIPAL_PARSE_ENTERPRISE - create single-component enterprise
* principal
*
- * Use krb5_free_principal() to free @a nprincipal when it is no longer needed.
+ * Use krb5_free_principal() to free @a principal_out when it is no longer
+ * needed.
*
* @retval
* 0 Success
*/
krb5_error_code KRB5_CALLCONV
krb5_parse_name_flags(krb5_context context, const char *name,
- int flags, krb5_principal *nprincipal);
+ int flags, krb5_principal *principal_out);
/**
* Convert a krb5_principal structure to a string representation.
* 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,
* @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);
* 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
*/
*
* 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
int *result_code, krb5_data *result_code_string,
krb5_data *result_string);
+/**
+ * Get a result message for changing or setting a password.
+ *
+ * @param [in] context Library context
+ * @param [in] server_string Data returned from the remote system
+ * @param [out] message_out A message displayable to the user
+ *
+ * This function processes the @a server_string returned in the @a
+ * result_string parameter of krb5_change_password(), krb5_set_password(), and
+ * related functions, and returns a displayable string. If @a server_string
+ * contains Active Directory structured policy information, it will be
+ * converted into human-readable text.
+ *
+ * Use krb5_free_string() to free @a message_out when it is no longer needed.
+ *
+ * @retval
+ * 0 Success
+ * @return
+ * Kerberos error codes
+ *
+ * @version First introduced in 1.11
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_chpw_message(krb5_context context, const krb5_data *server_string,
+ char **message_out);
+
/**
* Retrieve configuration profile from the context.
*
* 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,
*/
krb5_error_code KRB5_CALLCONV
krb5_get_init_creds_password(krb5_context context, krb5_creds *creds,
- krb5_principal client, char *password,
+ krb5_principal client, const char *password,
krb5_prompter_fct prompter, void *data,
- krb5_deltat start_time, char *in_tkt_service,
+ krb5_deltat start_time,
+ const char *in_tkt_service,
krb5_get_init_creds_opt *k5_gic_options);
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
krb5_error_code KRB5_CALLCONV
krb5_get_init_creds_keytab(krb5_context context, krb5_creds *creds,
krb5_principal client, krb5_keytab arg_keytab,
- krb5_deltat start_time, char *in_tkt_service,
+ krb5_deltat start_time, const char *in_tkt_service,
krb5_get_init_creds_opt *k5_gic_options);
typedef struct _krb5_verify_init_creds_opt {
*
* @param [in] context Library context
* @param [in] creds Initial credentials to be verified
- * @param [in] server_arg Server principal (or NULL)
- * @param [in] keytab_arg Key table (NULL to use default keytab)
- * @param [in,out] ccache_arg Credential cache for fetched creds (or NULL)
+ * @param [in] server Server principal (or NULL)
+ * @param [in] keytab Key table (NULL to use default keytab)
+ * @param [in,out] ccache Credential cache for fetched creds (or NULL)
* @param [in] options Verification options (NULL for default options)
*
* This function attempts to verify that @a creds were obtained from a KDC with
- * knowledge of a key in @a keytab_arg. If @a server_arg is provided, the
- * highest-kvno key entry for that principal name is used to verify the
- * credentials; otherwise, the highest-kvno key entry for the first principal
- * listed in @a keytab_arg is used.
+ * knowledge of a key in @a keytab, or the default keytab if @a keytab is NULL.
+ * If @a server is provided, the highest-kvno key entry for that principal name
+ * is used to verify the credentials; otherwise, all unique "host" service
+ * principals in the keytab are tried.
*
* If the specified keytab does not exist, or is empty, or cannot be read, or
- * does not contain an entry for @a server_arg, then credential verification
- * may be skipped unless configuration demands that it succeed. The caller can
+ * does not contain an entry for @a server, then credential verification may be
+ * skipped unless configuration demands that it succeed. The caller can
* control this behavior by providing a verification options structure; see
* krb5_verify_init_creds_opt_init() and
* krb5_verify_init_creds_opt_set_ap_req_nofail().
*
- * If @a ccache_arg is NULL, any additional credentials fetched during the
- * verification process will be destroyed. If @a ccache_arg points to NULL, a
+ * If @a ccache is NULL, any additional credentials fetched during the
+ * verification process will be destroyed. If @a ccache points to NULL, a
* memory ccache will be created for the additional credentials and returned in
- * @a ccache_arg. If @a ccache_arg points to a valid credential cache handle,
- * the additional credentials will be stored in that cache.
+ * @a ccache. If @a ccache points to a valid credential cache handle, the
+ * additional credentials will be stored in that cache.
*
* @retval 0 Success; otherwise - Kerberos error codes
*/
krb5_error_code KRB5_CALLCONV
krb5_verify_init_creds(krb5_context context, krb5_creds *creds,
- krb5_principal server_arg, krb5_keytab keytab_arg,
- krb5_ccache *ccache_arg, krb5_verify_init_creds_opt *options);
+ krb5_principal server, krb5_keytab keytab,
+ krb5_ccache *ccache,
+ krb5_verify_init_creds_opt *options);
/**
* Get validated credentials from the KDC.
krb5_error_code KRB5_CALLCONV
krb5_get_validated_creds(krb5_context context, krb5_creds *creds,
krb5_principal client, krb5_ccache ccache,
- char *in_tkt_service);
+ const char *in_tkt_service);
/**
* Get renewed credential from KDC using an existing credential.
krb5_error_code KRB5_CALLCONV
krb5_get_renewed_creds(krb5_context context, krb5_creds *creds,
krb5_principal client, krb5_ccache ccache,
- char *in_tkt_service);
+ const char *in_tkt_service);
/**
* Decode an ASN.1-formatted ticket.
/*
* 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;
* 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
*/
* 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,
* @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).
*/
* @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
+/** @} */ /* end of KRB5_H group */
+
#endif /* KRB5_GENERAL__ */
projects / krb5.git / blobdiff