From: Zhanna Tsitkov Date: Fri, 13 May 2011 12:33:52 +0000 (+0000) Subject: Updated documentation for PAC API. Moved PAC type definitions into krb5.hin X-Git-Tag: krb5-1.10-alpha1~427 X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=f1eb636f8854d5a3f70137e4beeea34ca7382b85;p=krb5.git Updated documentation for PAC API. Moved PAC type definitions into krb5.hin git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@24928 dc483132-0cff-0310-8789-dd5450dbe970 --- diff --git a/src/include/krb5/krb5.hin b/src/include/krb5/krb5.hin index ae55eb1da..07f6811c9 100644 --- a/src/include/krb5/krb5.hin +++ b/src/include/krb5/krb5.hin @@ -6835,31 +6835,137 @@ krb5_verify_authdata_kdc_issued(krb5_context context, /* * Windows PAC */ + +/* 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 /**< Client name and ticket information */ +#define PAC_UPN_DNS_INFO 12 /**< User principal name and DNS information */ + + +/** PAC data structure to convey authorization information */ struct krb5_pac_data; typedef struct krb5_pac_data *krb5_pac; +/** Add a buffer to the provided PAC and update header. + * + * @param [in] context Context structure + * @param [in,out] pac PAC handle + * @param [in] type Type of data contained in @a data + * @param [in] data Buffer to add + * + * This function adds a new @a data to @a pac if there isn't already a buffer + * of this type in @a pac. + * + * The valid values of @type is one of the following: + * @li @c PAC_LOGON_INFO - Logon information + * @li @c PAC_CREDENTIALS_INFO - Credentials information + * @li @c PAC_SERVER_CHECKSUM - Server checksum + * @li @c PAC_PRIVSVR_CHECKSUM - KDC checksum + * @li @c PAC_CLIENT_INFO - Client name and ticket information + * @li @c PAC_DELEGATION_INFO - Constrained delegation information + * @li @c PAC_UPN_DNS_INFO - User principal name and DNS information + * + * @retval 0 Success; Otherwise - Kerberos error codes + */ krb5_error_code KRB5_CALLCONV krb5_pac_add_buffer(krb5_context context, krb5_pac pac, krb5_ui_4 type, const krb5_data *data); +/** Free the storage assigned to a PAC. + * + * @param context Context structure + * @param [in] pac PAC to be freed + * + * This function zeros out and frees the content of a @a pac and then + * releases @a pac itself. + */ void KRB5_CALLCONV krb5_pac_free(krb5_context context, krb5_pac pac); +/** Find a buffer in a PAC and copy data into output buffer. + * + * @param [in] context Context structure + * @param [in] pac PAC handle + * @param [in] type Type of the buffer to be copied + * @param [out] data Copy of a buffer to be filled in + * + * Use krb5_free_data_contents() to free @a data when it is no longer needed. + * + * @retval 0 Success; Otherwise - Kerberos error codes + */ krb5_error_code KRB5_CALLCONV krb5_pac_get_buffer(krb5_context context, krb5_pac pac, krb5_ui_4 type, krb5_data *data); +/** Return an array of the types of data in the PAC. + * + * @param [in] context Context structure + * @param [in,out] pac PAC handle + * @param [out] len Number of entries in the @a types array. + * @param [out] types If non-null, contains an array of types + * + * Free @a types when it is no linger needed. + * + * @retval 0 Success; Otherwise - Kerberos error codes + */ krb5_error_code KRB5_CALLCONV krb5_pac_get_types(krb5_context context, krb5_pac pac, size_t *len, krb5_ui_4 **types); +/** Create and initialize Privilege Attribute Certificate (PAC). + * + * @param [in] context Context structure + * @param [out] pac PAC handle + * + * Use krb5_pac_free() to free @a pac when it is no longer needed. + * + * @retval 0 Success; Otherwise - Kerberos error codes + */ krb5_error_code KRB5_CALLCONV krb5_pac_init(krb5_context context, krb5_pac *pac); +/** Parse the supplied data into the newly allocated PAC. + * + * @param [in] context Context structure + * @param [in] ptr PAC buffer + * @param [in] len Size of @a ptr + * @param [out] pac PAC handle + * + * Use krb5_pac_free() to free @a pac when it is no longer needed. + * + * @retval 0 Success; Otherwise - Kerberos error codes + */ krb5_error_code KRB5_CALLCONV krb5_pac_parse(krb5_context context, const void *ptr, size_t len, krb5_pac *pac); +/** Verify a PAC. + * + * @param [in] context Context structure + * @param [in] pac PAC handle + * @param [in] authtime Timestamp to be compared with one in @a pac + * @param [in] principal If non-null, use it to validate PAC's client name + * and ticket information. + * @param [in] server Compare it with PAC'c server checksum. + * Must not be NULL. + * @param [in] privsvr If non-null, compare it with PAC'c KDC checksum + * + * This function validates @a pac against the supplied @a server, @a privsvr, + * @a principal and @a authtime and then, if successful, sets @a pac->verified + * to TRUE. + * + * @note A checksum mismatch can occur if the PAC was copied from a cross-realm + * TGT by an ignorant KDC; also Apple Mac OS X Server Open Directory (as of 10.6) + * generates PACs with no server checksum at all. One should consider not failing + * the whole authentication because of this reason, but, instead, marking PAC + * as not verified. + * + * @retval 0 Success; Otherwise - Kerberos error codes + */ krb5_error_code KRB5_CALLCONV krb5_pac_verify(krb5_context context, const krb5_pac pac, krb5_timestamp authtime, krb5_const_principal principal, diff --git a/src/lib/krb5/krb/authdata.h b/src/lib/krb5/krb/authdata.h index 7108fd32d..77db5fc4b 100644 --- a/src/lib/krb5/krb/authdata.h +++ b/src/lib/krb5/krb/authdata.h @@ -73,14 +73,6 @@ struct krb5_pac_data { #define PAC_SIGNATURE_DATA_LENGTH 4U #define PAC_CLIENT_INFO_LENGTH 10U #define PAC_INFO_BUFFER_LENGTH 16 -/* ulType */ -#define PAC_LOGON_INFO 1 -#define PAC_CREDENTIALS_INFO 2 -#define PAC_SERVER_CHECKSUM 6 -#define PAC_PRIVSVR_CHECKSUM 7 -#define PAC_CLIENT_INFO 10 -#define PAC_DELEGATION_INFO 11 -#define PAC_UPN_DNS_INFO 12 #define NT_TIME_EPOCH 11644473600LL