Difference between revisions of "Projects/PAC and principal APIs"

Revision as of 13:37, 14 September 2009

The PAC and principal APIs project defines some APIs that are useful in an active-directory enviroment.

PAC API

Microsoft Windows uses a data structure called the PAC in order to convey authorization information. See the expired draft-brezak-win2k-krb-authz-00 for documentation. The PAC is logically a set of type-length-value elements. That is, it is a collection of typed data items, and lengths are associated with each type. Typically the data items are NDR encoded. This API provides facilities to create and sign a PAC and to extract a given typed buffer from a PAC. NDR encoders and decoders are not provided.

/*
 * Windows PAC
 */
struct krb5_pac_data;
typedef struct krb5_pac_data *krb5_pac;

krb5_error_code KRB5_CALLCONV
krb5_pac_add_buffer
(krb5_context context,
                krb5_pac pac,
                krb5_ui_4 type,
                const krb5_data *data);

void KRB5_CALLCONV
krb5_pac_free
(krb5_context context,
                krb5_pac pac);

krb5_error_code KRB5_CALLCONV
krb5_pac_get_buffer
(krb5_context context,
                krb5_pac pac,
                krb5_ui_4 type,
                krb5_data *data);

krb5_error_code KRB5_CALLCONV
krb5_pac_get_types
(krb5_context context,
                krb5_pac pac,
                size_t *len,
                krb5_ui_4 **types);

krb5_error_code KRB5_CALLCONV
krb5_pac_init
(krb5_context context,
                krb5_pac *pac);

krb5_error_code KRB5_CALLCONV
krb5_pac_parse
(krb5_context context,
                const void *ptr,
                size_t len,
                krb5_pac *pac);

krb5_error_code KRB5_CALLCONV
krb5_pac_verify
(krb5_context context,
                const krb5_pac pac,
                krb5_timestamp authtime,
                krb5_const_principal principal,
                const krb5_keyblock *server,
                const krb5_keyblock *privsvr);

The krb5_pac_parse function will allocate a new PAC.

In addition, the following internal API is defined:

krb5_error_code KRB5_CALLCONV
krb5int_pac_sign(krb5_context context,
                 krb5_pac pac,
                 krb5_timestamp authtime,
                 krb5_const_principal principal,
                 const krb5_keyblock *server_key,
                 const krb5_keyblock *privsvr_key,
                 krb5_data *data);

This function signs and outputs a PAC. It is internal because it is only useful in the KDC.

Principal parsing and comparison

Several principal parsing and comparison functions are introduced. Several of these are Heimdal compatible.

#define KRB5_PRINCIPAL_UNPARSE_SHORT    1 /* Omit realm if it is the local realm */
#define KRB5_PRINCIPAL_UNPARSE_NO_REALM 2 /* Omit realm always */
#define KRB5_PRINCIPAL_UNPARSE_DISPLAY  4 /* Don't escape special characters */
krb5_error_code KRB5_CALLCONV krb5_unparse_name_flags
        (krb5_context,
                krb5_const_principal,
                int,
                char **);
krb5_error_code KRB5_CALLCONV krb5_unparse_name_flags_ext
        (krb5_context,
                krb5_const_principal,
                int,
                char **,
                unsigned int *);
#define KRB5_PRINCIPAL_PARSE_NO_REALM      1 /* Error if realm is present */
#define KRB5_PRINCIPAL_PARSE_REQUIRE_REALM 2 /* Error if realm is not present */
#define KRB5_PRINCIPAL_PARSE_ENTERPRISE    4 /* Create single-component enterprise principle */
krb5_error_code KRB5_CALLCONV krb5_parse_name_flags
        (krb5_context,
                const char *,
                int,
                krb5_principal * );

krb5_boolean KRB5_CALLCONV krb5_principal_compare_any_realm
        (krb5_context,
                krb5_const_principal,
                krb5_const_principal);
#define KRB5_PRINCIPAL_COMPARE_IGNORE_REALM         1
#define KRB5_PRINCIPAL_COMPARE_ENTERPRISE           2 /* compare UPNs as real principals */
#define KRB5_PRINCIPAL_COMPARE_CASEFOLD             4 /* case-insensitive comparison */
#define KRB5_PRINCIPAL_COMPARE_UTF8                 8 /* treat principals as UTF-8 */

krb5_boolean KRB5_CALLCONV krb5_principal_compare_flags
        (krb5_context,
                krb5_const_principal,
                krb5_const_principal,
                int);

User to User tickets

The following flag is defined for krb5_get_credentials:

#define KRB5_GC_USER_USER       1       /* want user-user ticket */
#define KRB5_GC_CANONICALIZE    4       /* set canonicalize KDC option */

The user_user flag searches the ccache for a credential encrypted in the right TGT.

Constants

/* Name in form of SMTP email name */
#define KRB5_NT_SMTP_NAME               7
/* Windows 2000 UPN */
#define KRB5_NT_ENTERPRISE_PRINCIPAL    10
/* 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 ADDRTYPE_NETBIOS        0x0014
#define KDC_OPT_CNAME_IN_ADDL_TKT       0x00020000
#define CKSUMTYPE_MD5_HMAC_ARCFOUR -137 /*Microsoft netlogon cksumtype*/
#define KRB5_PADATA_SVR_REFERRAL_INFO   20 /* Windows 2000 referrals */
#define KRB5_PADATA_PAC_REQUEST         128 /* include Windows PAC */
#define KRB5_PADATA_FOR_USER            129 /* username protocol transition request */
#define KRB5_PADATA_S4U_X509_USER       130 /* certificate protocol transition request */
#define KRB5_AUTHDATA_WIN2K_PAC 128
#define KRB5_AUTHDATA_ETYPE_NEGOTIATION 129     /* RFC 4537 */

Review

This section documents the review of the project according to Project policy. It is divided into multiple sections. First, approvals should be listed. To list an approval type

#~~~~

on its own line. The next section is for discussion. Use standard talk page conventions. In particular, sign comments with

--~~~~

and indent replies.

Members of Krbcore raising Blocking objections should preface their comment with {{project-block}}. The member who raised the objection should remove this markup when their objection is handled.

Approvals

Greg Hudson, December 30, 2008

Discussion