1 /* -*- mode: c; c-basic-offset: 4; indent-tabs-mode: nil -*- */ 2 /* 3 * Copyright 1990, 1991, 2016 by the Massachusetts Institute of Technology. 4 * All Rights Reserved. 5 * 6 * Export of this software from the United States of America may 7 * require a specific license from the United States Government. 8 * It is the responsibility of any person or organization contemplating 9 * export to obtain such a license before exporting. 10 * 11 * WITHIN THAT CONSTRAINT, permission to use, copy, modify, and 12 * distribute this software and its documentation for any purpose and 13 * without fee is hereby granted, provided that the above copyright 14 * notice appear in all copies and that both that copyright notice and 15 * this permission notice appear in supporting documentation, and that 16 * the name of M.I.T. not be used in advertising or publicity pertaining 17 * to distribution of the software without specific, written prior 18 * permission. Furthermore if you modify this software you must label 19 * your software as modified software and not distribute it in such a 20 * fashion that it might be confused with the original M.I.T. software. 21 * M.I.T. makes no representations about the suitability of 22 * this software for any purpose. It is provided "as is" without express 23 * or implied warranty. 24 */ 25 /* 26 * Copyright (C) 1998 by the FundsXpress, INC. 27 * 28 * All rights reserved. 29 * 30 * Export of this software from the United States of America may require 31 * a specific license from the United States Government. It is the 32 * responsibility of any person or organization contemplating export to 33 * obtain such a license before exporting. 34 * 35 * WITHIN THAT CONSTRAINT, permission to use, copy, modify, and 36 * distribute this software and its documentation for any purpose and 37 * without fee is hereby granted, provided that the above copyright 38 * notice appear in all copies and that both that copyright notice and 39 * this permission notice appear in supporting documentation, and that 40 * the name of FundsXpress. not be used in advertising or publicity pertaining 41 * to distribution of the software without specific, written prior 42 * permission. FundsXpress makes no representations about the suitability of 43 * this software for any purpose. It is provided "as is" without express 44 * or implied warranty. 45 * 46 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR 47 * IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED 48 * WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. 49 */ 50 /* 51 * Copyright 2009 Sun Microsystems, Inc. All rights reserved. 52 * Use is subject to license terms. 53 */ 54 55 /* KDC Database interface definitions */ 56 57 /* This API is not considered as stable as the main krb5 API. 58 * 59 * - We may make arbitrary incompatible changes between feature 60 * releases (e.g. from 1.7 to 1.8). 61 * - We will make some effort to avoid making incompatible changes for 62 * bugfix releases, but will make them if necessary. 63 */ 64 65 #ifndef KRB5_KDB5__ 66 #define KRB5_KDB5__ 67 68 #include <krb5.h> 69 70 /* This version will be incremented when incompatible changes are made to the 71 * KDB API, and will be kept in sync with the libkdb major version. */ 72 #define KRB5_KDB_API_VERSION 10 73 74 /* Salt types */ 75 #define KRB5_KDB_SALTTYPE_NORMAL 0 76 /* #define KRB5_KDB_SALTTYPE_V4 1 */ 77 #define KRB5_KDB_SALTTYPE_NOREALM 2 78 #define KRB5_KDB_SALTTYPE_ONLYREALM 3 79 #define KRB5_KDB_SALTTYPE_SPECIAL 4 80 /* #define KRB5_KDB_SALTTYPE_AFS3 5 */ 81 #define KRB5_KDB_SALTTYPE_CERTHASH 6 82 83 /* Attributes */ 84 #define KRB5_KDB_DISALLOW_POSTDATED 0x00000001 85 #define KRB5_KDB_DISALLOW_FORWARDABLE 0x00000002 86 #define KRB5_KDB_DISALLOW_TGT_BASED 0x00000004 87 #define KRB5_KDB_DISALLOW_RENEWABLE 0x00000008 88 #define KRB5_KDB_DISALLOW_PROXIABLE 0x00000010 89 #define KRB5_KDB_DISALLOW_DUP_SKEY 0x00000020 90 #define KRB5_KDB_DISALLOW_ALL_TIX 0x00000040 91 #define KRB5_KDB_REQUIRES_PRE_AUTH 0x00000080 92 #define KRB5_KDB_REQUIRES_HW_AUTH 0x00000100 93 #define KRB5_KDB_REQUIRES_PWCHANGE 0x00000200 94 #define KRB5_KDB_DISALLOW_SVR 0x00001000 95 #define KRB5_KDB_PWCHANGE_SERVICE 0x00002000 96 #define KRB5_KDB_SUPPORT_DESMD5 0x00004000 97 #define KRB5_KDB_NEW_PRINC 0x00008000 98 #define KRB5_KDB_OK_AS_DELEGATE 0x00100000 99 #define KRB5_KDB_OK_TO_AUTH_AS_DELEGATE 0x00200000 /* S4U2Self OK */ 100 #define KRB5_KDB_NO_AUTH_DATA_REQUIRED 0x00400000 101 #define KRB5_KDB_LOCKDOWN_KEYS 0x00800000 102 103 /* Creation flags */ 104 #define KRB5_KDB_CREATE_BTREE 0x00000001 105 #define KRB5_KDB_CREATE_HASH 0x00000002 106 107 /* Entry get flags */ 108 /* Name canonicalization requested */ 109 #define KRB5_KDB_FLAG_CANONICALIZE 0x00000010 110 /* Include authorization data generated by backend */ 111 #define KRB5_KDB_FLAG_INCLUDE_PAC 0x00000020 112 /* Is AS-REQ (client referrals only) */ 113 #define KRB5_KDB_FLAG_CLIENT_REFERRALS_ONLY 0x00000040 114 /* Map cross-realm principals */ 115 #define KRB5_KDB_FLAG_MAP_PRINCIPALS 0x00000080 116 /* Protocol transition */ 117 #define KRB5_KDB_FLAG_PROTOCOL_TRANSITION 0x00000100 118 /* Constrained delegation */ 119 #define KRB5_KDB_FLAG_CONSTRAINED_DELEGATION 0x00000200 120 /* User-to-user */ 121 #define KRB5_KDB_FLAG_USER_TO_USER 0x00000800 122 /* Cross-realm */ 123 #define KRB5_KDB_FLAG_CROSS_REALM 0x00001000 124 /* Issuing referral */ 125 #define KRB5_KDB_FLAG_ISSUING_REFERRAL 0x00004000 126 127 128 #define KRB5_KDB_FLAGS_S4U ( KRB5_KDB_FLAG_PROTOCOL_TRANSITION | \ 129 KRB5_KDB_FLAG_CONSTRAINED_DELEGATION ) 130 131 /* KDB iteration flags */ 132 #define KRB5_DB_ITER_WRITE 0x00000001 133 #define KRB5_DB_ITER_REV 0x00000002 134 #define KRB5_DB_ITER_RECURSE 0x00000004 135 136 /* String attribute names recognized by krb5 */ 137 #define KRB5_KDB_SK_SESSION_ENCTYPES "session_enctypes" 138 #define KRB5_KDB_SK_REQUIRE_AUTH "require_auth" 139 140 #if !defined(_WIN32) 141 142 /* 143 * Note --- these structures cannot be modified without changing the 144 * database version number in libkdb.a, but should be expandable by 145 * adding new tl_data types. 146 */ 147 typedef struct _krb5_tl_data { 148 struct _krb5_tl_data* tl_data_next; /* NOT saved */ 149 krb5_int16 tl_data_type; 150 krb5_ui_2 tl_data_length; 151 krb5_octet * tl_data_contents; 152 } krb5_tl_data; 153 154 /* String attributes (currently stored inside tl-data) map C string keys to 155 * values. They can be set via kadmin and consumed by KDC plugins. */ 156 typedef struct krb5_string_attr_st { 157 char *key; 158 char *value; 159 } krb5_string_attr; 160 161 /* 162 * If this ever changes up the version number and make the arrays be as 163 * big as necessary. 164 * 165 * Currently the first type is the enctype and the second is the salt type. 166 */ 167 typedef struct _krb5_key_data { 168 krb5_int16 key_data_ver; /* Version */ 169 krb5_ui_2 key_data_kvno; /* Key Version */ 170 krb5_int16 key_data_type[2]; /* Array of types */ 171 krb5_ui_2 key_data_length[2]; /* Array of lengths */ 172 krb5_octet * key_data_contents[2]; /* Array of pointers */ 173 } krb5_key_data; 174 175 #define KRB5_KDB_V1_KEY_DATA_ARRAY 2 /* # of array elements */ 176 177 typedef struct _krb5_keysalt { 178 krb5_int16 type; 179 krb5_data data; /* Length, data */ 180 } krb5_keysalt; 181 182 /* 183 * A principal database entry. Extensions to this structure currently use the 184 * tl_data list. The e_data and e_length fields are not used by any calling 185 * code except kdb5_util dump and load, which marshal and unmarshal the array 186 * in the dump record. KDB modules may use these fields internally as long as 187 * they set e_length appropriately (non-zero if the data should be marshalled 188 * across dump and load, zero if not) and handle null e_data values in 189 * caller-constructed principal entries. 190 */ 191 typedef struct _krb5_db_entry_new { 192 krb5_magic magic; /* NOT saved */ 193 krb5_ui_2 len; 194 krb5_ui_4 mask; /* members currently changed/set */ 195 krb5_flags attributes; 196 krb5_deltat max_life; 197 krb5_deltat max_renewable_life; 198 krb5_timestamp expiration; /* When the client expires */ 199 krb5_timestamp pw_expiration; /* When its passwd expires */ 200 krb5_timestamp last_success; /* Last successful passwd */ 201 krb5_timestamp last_failed; /* Last failed passwd attempt */ 202 krb5_kvno fail_auth_count; /* # of failed passwd attempt */ 203 krb5_int16 n_tl_data; 204 krb5_int16 n_key_data; 205 krb5_ui_2 e_length; /* Length of extra data */ 206 krb5_octet * e_data; /* Extra data to be saved */ 207 208 krb5_principal princ; /* Length, data */ 209 krb5_tl_data * tl_data; /* Linked list */ 210 211 /* key_data must be sorted by kvno in descending order. */ 212 krb5_key_data * key_data; /* Array */ 213 } krb5_db_entry; 214 215 typedef struct _osa_policy_ent_t { 216 int version; 217 char *name; 218 krb5_ui_4 pw_min_life; 219 krb5_ui_4 pw_max_life; 220 krb5_ui_4 pw_min_length; 221 krb5_ui_4 pw_min_classes; 222 krb5_ui_4 pw_history_num; 223 krb5_ui_4 policy_refcnt; /* no longer used */ 224 /* Only valid if version > 1 */ 225 krb5_ui_4 pw_max_fail; /* pwdMaxFailure */ 226 krb5_ui_4 pw_failcnt_interval; /* pwdFailureCountInterval */ 227 krb5_ui_4 pw_lockout_duration; /* pwdLockoutDuration */ 228 /* Only valid if version > 2 */ 229 krb5_ui_4 attributes; 230 krb5_ui_4 max_life; 231 krb5_ui_4 max_renewable_life; 232 char * allowed_keysalts; 233 krb5_int16 n_tl_data; 234 krb5_tl_data * tl_data; 235 } osa_policy_ent_rec, *osa_policy_ent_t; 236 237 typedef void (*osa_adb_iter_policy_func) (void *, osa_policy_ent_t); 238 239 typedef struct __krb5_key_salt_tuple { 240 krb5_enctype ks_enctype; 241 krb5_int32 ks_salttype; 242 } krb5_key_salt_tuple; 243 244 #define KRB5_KDB_MAGIC_NUMBER 0xdbdbdbdb 245 #define KRB5_KDB_V1_BASE_LENGTH 38 246 247 #define KRB5_KDB_MAX_ALLOWED_KS_LEN 512 248 249 #define KRB5_TL_LAST_PWD_CHANGE 0x0001 250 #define KRB5_TL_MOD_PRINC 0x0002 251 #define KRB5_TL_KADM_DATA 0x0003 252 #define KRB5_TL_KADM5_E_DATA 0x0004 253 #define KRB5_TL_RB1_CHALLENGE 0x0005 254 #ifdef SECURID 255 #define KRB5_TL_SECURID_STATE 0x0006 256 #endif /* SECURID */ 257 #define KRB5_TL_USER_CERTIFICATE 0x0007 258 #define KRB5_TL_MKVNO 0x0008 259 #define KRB5_TL_ACTKVNO 0x0009 260 #define KRB5_TL_MKEY_AUX 0x000a 261 262 /* String attributes may not always be represented in tl-data. kadmin clients 263 * must use the get_strings and set_string RPCs. */ 264 #define KRB5_TL_STRING_ATTRS 0x000b 265 266 #define KRB5_TL_PAC_LOGON_INFO 0x0100 /* NDR encoded validation info */ 267 #define KRB5_TL_SERVER_REFERRAL 0x0200 /* ASN.1 encoded ServerReferralInfo */ 268 #define KRB5_TL_SVR_REFERRAL_DATA 0x0300 /* ASN.1 encoded PA-SVR-REFERRAL-DATA */ 269 #define KRB5_TL_CONSTRAINED_DELEGATION_ACL 0x0400 /* Each entry is a permitted SPN */ 270 #define KRB5_TL_LM_KEY 0x0500 /* LM OWF */ 271 #define KRB5_TL_X509_SUBJECT_ISSUER_NAME 0x0600 /* <I>IssuerDN<S>SubjectDN */ 272 #define KRB5_TL_LAST_ADMIN_UNLOCK 0x0700 /* Timestamp of admin unlock */ 273 274 #define KRB5_TL_DB_ARGS 0x7fff 275 276 /* version number for KRB5_TL_ACTKVNO data */ 277 #define KRB5_TL_ACTKVNO_VER 1 278 279 /* version number for KRB5_TL_MKEY_AUX data */ 280 #define KRB5_TL_MKEY_AUX_VER 1 281 282 typedef struct _krb5_actkvno_node { 283 struct _krb5_actkvno_node *next; 284 krb5_kvno act_kvno; 285 krb5_timestamp act_time; 286 } krb5_actkvno_node; 287 288 typedef struct _krb5_mkey_aux_node { 289 struct _krb5_mkey_aux_node *next; 290 krb5_kvno mkey_kvno; /* kvno of mkey protecting the latest_mkey */ 291 krb5_key_data latest_mkey; /* most recent mkey */ 292 } krb5_mkey_aux_node; 293 294 typedef struct _krb5_keylist_node { 295 krb5_keyblock keyblock; 296 krb5_kvno kvno; 297 struct _krb5_keylist_node *next; 298 } krb5_keylist_node; 299 300 /* 301 * Determines the number of failed KDC requests before DISALLOW_ALL_TIX is set 302 * on the principal. 303 */ 304 #define KRB5_MAX_FAIL_COUNT 5 305 306 /* XXX depends on knowledge of krb5_parse_name() formats */ 307 #define KRB5_KDB_M_NAME "K/M" /* Kerberos/Master */ 308 309 /* prompts used by default when reading the KDC password from the keyboard. */ 310 #define KRB5_KDC_MKEY_1 "Enter KDC database master key" 311 #define KRB5_KDC_MKEY_2 "Re-enter KDC database master key to verify" 312 313 314 extern char *krb5_mkey_pwd_prompt1; 315 extern char *krb5_mkey_pwd_prompt2; 316 317 /* 318 * These macros specify the encoding of data within the database. 319 * 320 * Data encoding is little-endian. 321 */ 322 #ifdef _KRB5_INT_H 323 #include "k5-platform.h" 324 #define krb5_kdb_decode_int16(cp, i16) \ 325 *((krb5_int16 *) &(i16)) = load_16_le(cp) 326 #define krb5_kdb_decode_int32(cp, i32) \ 327 *((krb5_int32 *) &(i32)) = load_32_le(cp) 328 #define krb5_kdb_encode_int16(i16, cp) store_16_le(i16, cp) 329 #define krb5_kdb_encode_int32(i32, cp) store_32_le(i32, cp) 330 #endif /* _KRB5_INT_H */ 331 332 #define KRB5_KDB_OPEN_RW 0 333 #define KRB5_KDB_OPEN_RO 1 334 335 #ifndef KRB5_KDB_SRV_TYPE_KDC 336 #define KRB5_KDB_SRV_TYPE_KDC 0x0100 337 #endif 338 339 #ifndef KRB5_KDB_SRV_TYPE_ADMIN 340 #define KRB5_KDB_SRV_TYPE_ADMIN 0x0200 341 #endif 342 343 /* 0x0300 was KRB5_KDB_SRV_TYPE_PASSWD but it is no longer used. */ 344 345 #ifndef KRB5_KDB_SRV_TYPE_OTHER 346 #define KRB5_KDB_SRV_TYPE_OTHER 0x0400 347 #endif 348 349 #define KRB5_KDB_OPT_SET_DB_NAME 0 350 #define KRB5_KDB_OPT_SET_LOCK_MODE 1 351 352 #define KRB5_DB_LOCKMODE_SHARED 0x0001 353 #define KRB5_DB_LOCKMODE_EXCLUSIVE 0x0002 354 #define KRB5_DB_LOCKMODE_PERMANENT 0x0008 355 356 /* libkdb.spec */ 357 krb5_error_code krb5_db_setup_lib_handle(krb5_context kcontext); 358 krb5_error_code krb5_db_open( krb5_context kcontext, char **db_args, int mode ); 359 krb5_error_code krb5_db_init ( krb5_context kcontext ); 360 krb5_error_code krb5_db_create ( krb5_context kcontext, char **db_args ); 361 krb5_error_code krb5_db_inited ( krb5_context kcontext ); 362 krb5_error_code kdb5_db_create ( krb5_context kcontext, char **db_args ); 363 krb5_error_code krb5_db_fini ( krb5_context kcontext ); 364 const char * krb5_db_errcode2string ( krb5_context kcontext, long err_code ); 365 krb5_error_code krb5_db_destroy ( krb5_context kcontext, char **db_args ); 366 krb5_error_code krb5_db_promote ( krb5_context kcontext, char **db_args ); 367 krb5_error_code krb5_db_get_age ( krb5_context kcontext, char *db_name, time_t *t ); 368 krb5_error_code krb5_db_lock ( krb5_context kcontext, int lock_mode ); 369 krb5_error_code krb5_db_unlock ( krb5_context kcontext ); 370 krb5_error_code krb5_db_get_principal ( krb5_context kcontext, 371 krb5_const_principal search_for, 372 unsigned int flags, 373 krb5_db_entry **entry ); 374 void krb5_db_free_principal ( krb5_context kcontext, krb5_db_entry *entry ); 375 krb5_error_code krb5_db_put_principal ( krb5_context kcontext, 376 krb5_db_entry *entry ); 377 krb5_error_code krb5_db_delete_principal ( krb5_context kcontext, 378 krb5_principal search_for ); 379 krb5_error_code krb5_db_rename_principal ( krb5_context kcontext, 380 krb5_principal source, 381 krb5_principal target ); 382 383 /* 384 * Iterate over principals in the KDB. If the callback may write to the DB, 385 * the caller must get an exclusive lock with krb5_db_lock before iterating, 386 * and release it with krb5_db_unlock after iterating. 387 */ 388 krb5_error_code krb5_db_iterate ( krb5_context kcontext, 389 char *match_entry, 390 int (*func) (krb5_pointer, krb5_db_entry *), 391 krb5_pointer func_arg, krb5_flags iterflags ); 392 393 394 krb5_error_code krb5_db_store_master_key ( krb5_context kcontext, 395 char *keyfile, 396 krb5_principal mname, 397 krb5_kvno kvno, 398 krb5_keyblock *key, 399 char *master_pwd); 400 krb5_error_code krb5_db_store_master_key_list ( krb5_context kcontext, 401 char *keyfile, 402 krb5_principal mname, 403 char *master_pwd); 404 krb5_error_code krb5_db_fetch_mkey ( krb5_context context, 405 krb5_principal mname, 406 krb5_enctype etype, 407 krb5_boolean fromkeyboard, 408 krb5_boolean twice, 409 char *db_args, 410 krb5_kvno *kvno, 411 krb5_data *salt, 412 krb5_keyblock *key); 413 krb5_error_code 414 krb5_db_fetch_mkey_list( krb5_context context, 415 krb5_principal mname, 416 const krb5_keyblock * mkey ); 417 418 krb5_error_code 419 krb5_dbe_find_enctype( krb5_context kcontext, 420 krb5_db_entry *dbentp, 421 krb5_int32 ktype, 422 krb5_int32 stype, 423 krb5_int32 kvno, 424 krb5_key_data **kdatap); 425 426 427 krb5_error_code krb5_dbe_search_enctype ( krb5_context kcontext, 428 krb5_db_entry *dbentp, 429 krb5_int32 *start, 430 krb5_int32 ktype, 431 krb5_int32 stype, 432 krb5_int32 kvno, 433 krb5_key_data **kdatap); 434 435 krb5_error_code 436 krb5_db_setup_mkey_name ( krb5_context context, 437 const char *keyname, 438 const char *realm, 439 char **fullname, 440 krb5_principal *principal); 441 442 /** 443 * Decrypts the key given in @@a key_data. If @a mkey is specified, that 444 * master key is used. If @a mkey is NULL, then all master keys are tried. 445 */ 446 krb5_error_code 447 krb5_dbe_decrypt_key_data( krb5_context context, 448 const krb5_keyblock * mkey, 449 const krb5_key_data * key_data, 450 krb5_keyblock * dbkey, 451 krb5_keysalt * keysalt); 452 453 krb5_error_code 454 krb5_dbe_encrypt_key_data( krb5_context context, 455 const krb5_keyblock * mkey, 456 const krb5_keyblock * dbkey, 457 const krb5_keysalt * keysalt, 458 int keyver, 459 krb5_key_data * key_data); 460 461 krb5_error_code 462 krb5_dbe_fetch_act_key_list(krb5_context context, 463 krb5_principal princ, 464 krb5_actkvno_node **act_key_list); 465 466 krb5_error_code 467 krb5_dbe_find_act_mkey( krb5_context context, 468 krb5_actkvno_node * act_mkey_list, 469 krb5_kvno * act_kvno, 470 krb5_keyblock ** act_mkey); 471 472 krb5_error_code 473 krb5_dbe_find_mkey( krb5_context context, 474 krb5_db_entry * entry, 475 krb5_keyblock ** mkey); 476 477 /* Set *mkvno to mkvno in entry tl_data, or 0 if not present. */ 478 krb5_error_code 479 krb5_dbe_lookup_mkvno( krb5_context context, 480 krb5_db_entry * entry, 481 krb5_kvno * mkvno); 482 483 krb5_keylist_node * 484 krb5_db_mkey_list_alias( krb5_context kcontext ); 485 486 /* Set *mkvno to mkvno in entry tl_data, or minimum value from mkey_list. */ 487 krb5_error_code 488 krb5_dbe_get_mkvno( krb5_context context, 489 krb5_db_entry * entry, 490 krb5_kvno * mkvno); 491 492 krb5_error_code 493 krb5_dbe_lookup_mod_princ_data( krb5_context context, 494 krb5_db_entry * entry, 495 krb5_timestamp * mod_time, 496 krb5_principal * mod_princ); 497 498 krb5_error_code 499 krb5_dbe_lookup_mkey_aux( krb5_context context, 500 krb5_db_entry * entry, 501 krb5_mkey_aux_node ** mkey_aux_data_list); 502 krb5_error_code 503 krb5_dbe_update_mkvno( krb5_context context, 504 krb5_db_entry * entry, 505 krb5_kvno mkvno); 506 507 krb5_error_code 508 krb5_dbe_lookup_actkvno( krb5_context context, 509 krb5_db_entry * entry, 510 krb5_actkvno_node ** actkvno_list); 511 512 krb5_error_code 513 krb5_dbe_update_mkey_aux( krb5_context context, 514 krb5_db_entry * entry, 515 krb5_mkey_aux_node * mkey_aux_data_list); 516 517 krb5_error_code 518 krb5_dbe_update_actkvno(krb5_context context, 519 krb5_db_entry * entry, 520 const krb5_actkvno_node *actkvno_list); 521 522 krb5_error_code 523 krb5_dbe_update_last_pwd_change( krb5_context context, 524 krb5_db_entry * entry, 525 krb5_timestamp stamp); 526 527 krb5_error_code 528 krb5_dbe_update_last_admin_unlock( krb5_context context, 529 krb5_db_entry * entry, 530 krb5_timestamp stamp); 531 532 krb5_error_code 533 krb5_dbe_lookup_tl_data( krb5_context context, 534 krb5_db_entry * entry, 535 krb5_tl_data * ret_tl_data); 536 537 krb5_error_code 538 krb5_dbe_create_key_data( krb5_context context, 539 krb5_db_entry * entry); 540 541 542 krb5_error_code 543 krb5_dbe_update_mod_princ_data( krb5_context context, 544 krb5_db_entry * entry, 545 krb5_timestamp mod_date, 546 krb5_const_principal mod_princ); 547 548 /* 549 * These are wrappers around realloc() and free(). Applications and KDB 550 * modules can use them when manipulating principal and policy entries to 551 * ensure that they allocate and free memory in a manner compatible with the 552 * library. Using libkrb5 or libkbd5 functions to construct values (such as 553 * krb5_copy_principal() to construct the princ field of a krb5_db_entry) is 554 * also safe. On Unix platforms, just using malloc() and free() is safe as 555 * long as the application or module does not use a malloc replacement. 556 */ 557 void *krb5_db_alloc( krb5_context kcontext, 558 void *ptr, 559 size_t size ); 560 void krb5_db_free( krb5_context kcontext, 561 void *ptr); 562 563 564 krb5_error_code 565 krb5_dbe_lookup_last_pwd_change( krb5_context context, 566 krb5_db_entry * entry, 567 krb5_timestamp * stamp); 568 569 krb5_error_code 570 krb5_dbe_lookup_last_admin_unlock( krb5_context context, 571 krb5_db_entry * entry, 572 krb5_timestamp * stamp); 573 574 /* Retrieve the set of string attributes in entry, in no particular order. 575 * Free *strings_out with krb5_dbe_free_strings when done. */ 576 krb5_error_code 577 krb5_dbe_get_strings(krb5_context context, krb5_db_entry *entry, 578 krb5_string_attr **strings_out, int *count_out); 579 580 /* Retrieve a single string attribute from entry, or NULL if there is no 581 * attribute for key. Free *value_out with krb5_dbe_free_string when done. */ 582 krb5_error_code 583 krb5_dbe_get_string(krb5_context context, krb5_db_entry *entry, 584 const char *key, char **value_out); 585 586 /* Change or add a string attribute in entry, or delete it if value is NULL. */ 587 krb5_error_code 588 krb5_dbe_set_string(krb5_context context, krb5_db_entry *entry, 589 const char *key, const char *value); 590 591 krb5_error_code 592 krb5_dbe_delete_tl_data( krb5_context context, 593 krb5_db_entry * entry, 594 krb5_int16 tl_data_type); 595 596 krb5_error_code 597 krb5_db_update_tl_data(krb5_context context, 598 krb5_int16 * n_tl_datap, 599 krb5_tl_data **tl_datap, 600 krb5_tl_data * new_tl_data); 601 602 krb5_error_code 603 krb5_dbe_update_tl_data( krb5_context context, 604 krb5_db_entry * entry, 605 krb5_tl_data * new_tl_data); 606 607 /* Compute the salt for a key data entry given the corresponding principal. */ 608 krb5_error_code 609 krb5_dbe_compute_salt(krb5_context context, const krb5_key_data *key, 610 krb5_const_principal princ, krb5_int16 *salttype_out, 611 krb5_data **salt_out); 612 613 /* 614 * Modify the key data of entry to explicitly store salt values using the 615 * KRB5_KDB_SALTTYPE_SPECIAL salt type. 616 */ 617 krb5_error_code 618 krb5_dbe_specialize_salt(krb5_context context, krb5_db_entry *entry); 619 620 krb5_error_code 621 krb5_dbe_cpw( krb5_context kcontext, 622 krb5_keyblock * master_key, 623 krb5_key_salt_tuple * ks_tuple, 624 int ks_tuple_count, 625 char * passwd, 626 int new_kvno, 627 krb5_boolean keepold, 628 krb5_db_entry * db_entry); 629 630 631 krb5_error_code 632 krb5_dbe_ark( krb5_context context, 633 krb5_keyblock * master_key, 634 krb5_key_salt_tuple * ks_tuple, 635 int ks_tuple_count, 636 krb5_db_entry * db_entry); 637 638 krb5_error_code 639 krb5_dbe_crk( krb5_context context, 640 krb5_keyblock * master_key, 641 krb5_key_salt_tuple * ks_tuple, 642 int ks_tuple_count, 643 krb5_boolean keepold, 644 krb5_db_entry * db_entry); 645 646 krb5_error_code 647 krb5_dbe_apw( krb5_context context, 648 krb5_keyblock * master_key, 649 krb5_key_salt_tuple * ks_tuple, 650 int ks_tuple_count, 651 char * passwd, 652 krb5_db_entry * db_entry); 653 654 int 655 krb5_db_get_key_data_kvno( krb5_context context, 656 int count, 657 krb5_key_data * data); 658 659 krb5_error_code krb5_db_sign_authdata(krb5_context kcontext, 660 unsigned int flags, 661 krb5_const_principal client_princ, 662 krb5_const_principal server_princ, 663 krb5_db_entry *client, 664 krb5_db_entry *server, 665 krb5_db_entry *header_server, 666 krb5_db_entry *local_tgt, 667 krb5_keyblock *client_key, 668 krb5_keyblock *server_key, 669 krb5_keyblock *header_key, 670 krb5_keyblock *local_tgt_key, 671 krb5_keyblock *session_key, 672 krb5_timestamp authtime, 673 krb5_authdata **tgt_auth_data, 674 void *ad_info, 675 krb5_data ***auth_indicators, 676 krb5_authdata ***signed_auth_data); 677 678 krb5_error_code krb5_db_check_transited_realms(krb5_context kcontext, 679 const krb5_data *tr_contents, 680 const krb5_data *client_realm, 681 const krb5_data *server_realm); 682 683 krb5_error_code krb5_db_check_policy_as(krb5_context kcontext, 684 krb5_kdc_req *request, 685 krb5_db_entry *client, 686 krb5_db_entry *server, 687 krb5_timestamp kdc_time, 688 const char **status, 689 krb5_pa_data ***e_data); 690 691 krb5_error_code krb5_db_check_policy_tgs(krb5_context kcontext, 692 krb5_kdc_req *request, 693 krb5_db_entry *server, 694 krb5_ticket *ticket, 695 const char **status, 696 krb5_pa_data ***e_data); 697 698 void krb5_db_audit_as_req(krb5_context kcontext, krb5_kdc_req *request, 699 const krb5_address *local_addr, 700 const krb5_address *remote_addr, 701 krb5_db_entry *client, krb5_db_entry *server, 702 krb5_timestamp authtime, krb5_error_code error_code); 703 704 void krb5_db_refresh_config(krb5_context kcontext); 705 706 krb5_error_code krb5_db_check_allowed_to_delegate(krb5_context kcontext, 707 krb5_const_principal client, 708 const krb5_db_entry *server, 709 krb5_const_principal proxy); 710 711 krb5_error_code krb5_db_get_s4u_x509_principal(krb5_context kcontext, 712 const krb5_data *client_cert, 713 krb5_const_principal in_princ, 714 unsigned int flags, 715 krb5_db_entry **entry); 716 717 krb5_error_code krb5_db_allowed_to_delegate_from(krb5_context context, 718 krb5_const_principal client, 719 krb5_const_principal server, 720 void *server_ad_info, 721 const krb5_db_entry *proxy); 722 723 krb5_error_code krb5_db_get_authdata_info(krb5_context context, 724 unsigned int flags, 725 krb5_authdata **in_authdata, 726 krb5_const_principal client_princ, 727 krb5_const_principal server_princ, 728 krb5_keyblock *server_key, 729 krb5_keyblock *krbtgt_key, 730 krb5_db_entry *krbtgt, 731 krb5_timestamp authtime, 732 void **ad_info_out, 733 krb5_principal *client_out); 734 735 void krb5_db_free_authdata_info(krb5_context context, void *ad_info); 736 737 /** 738 * Sort an array of @a krb5_key_data keys in descending order by their kvno. 739 * Key data order within a kvno is preserved. 740 * 741 * @param key_data 742 * The @a krb5_key_data array to sort. This is sorted in place so the 743 * array will be modified. 744 * @param key_data_length 745 * The length of @a key_data. 746 */ 747 void 748 krb5_dbe_sort_key_data(krb5_key_data *key_data, size_t key_data_length); 749 750 /* default functions. Should not be directly called */ 751 /* 752 * Default functions prototype 753 */ 754 755 krb5_error_code 756 krb5_dbe_def_search_enctype( krb5_context kcontext, 757 krb5_db_entry *dbentp, 758 krb5_int32 *start, 759 krb5_int32 ktype, 760 krb5_int32 stype, 761 krb5_int32 kvno, 762 krb5_key_data **kdatap); 763 764 krb5_error_code 765 krb5_def_store_mkey_list( krb5_context context, 766 char *keyfile, 767 krb5_principal mname, 768 krb5_keylist_node *keylist, 769 char *master_pwd); 770 771 krb5_error_code 772 krb5_db_def_fetch_mkey( krb5_context context, 773 krb5_principal mname, 774 krb5_keyblock *key, 775 krb5_kvno *kvno, 776 char *db_args); 777 778 krb5_error_code 779 krb5_def_fetch_mkey_list( krb5_context context, 780 krb5_principal mprinc, 781 const krb5_keyblock *mkey, 782 krb5_keylist_node **mkeys_list); 783 784 krb5_error_code 785 krb5_dbe_def_cpw( krb5_context context, 786 krb5_keyblock * master_key, 787 krb5_key_salt_tuple * ks_tuple, 788 int ks_tuple_count, 789 char * passwd, 790 int new_kvno, 791 krb5_boolean keepold, 792 krb5_db_entry * db_entry); 793 794 krb5_error_code 795 krb5_dbe_def_decrypt_key_data( krb5_context context, 796 const krb5_keyblock * mkey, 797 const krb5_key_data * key_data, 798 krb5_keyblock * dbkey, 799 krb5_keysalt * keysalt); 800 801 krb5_error_code 802 krb5_dbe_def_encrypt_key_data( krb5_context context, 803 const krb5_keyblock * mkey, 804 const krb5_keyblock * dbkey, 805 const krb5_keysalt * keysalt, 806 int keyver, 807 krb5_key_data * key_data); 808 809 krb5_error_code 810 krb5_db_def_rename_principal( krb5_context kcontext, 811 krb5_const_principal source, 812 krb5_const_principal target); 813 814 krb5_error_code 815 krb5_db_create_policy( krb5_context kcontext, 816 osa_policy_ent_t policy); 817 818 krb5_error_code 819 krb5_db_get_policy ( krb5_context kcontext, 820 char *name, 821 osa_policy_ent_t *policy ); 822 823 krb5_error_code 824 krb5_db_put_policy( krb5_context kcontext, 825 osa_policy_ent_t policy); 826 827 krb5_error_code 828 krb5_db_iter_policy( krb5_context kcontext, 829 char *match_entry, 830 osa_adb_iter_policy_func func, 831 void *data); 832 833 krb5_error_code 834 krb5_db_delete_policy( krb5_context kcontext, 835 char *policy); 836 837 void 838 krb5_db_free_policy( krb5_context kcontext, 839 osa_policy_ent_t policy); 840 841 842 krb5_error_code 843 krb5_db_set_context(krb5_context, void *db_context); 844 845 krb5_error_code 846 krb5_db_get_context(krb5_context, void **db_context); 847 848 void 849 krb5_dbe_free_key_data_contents(krb5_context, krb5_key_data *); 850 851 void 852 krb5_dbe_free_key_list(krb5_context, krb5_keylist_node *); 853 854 void 855 krb5_dbe_free_actkvno_list(krb5_context, krb5_actkvno_node *); 856 857 void 858 krb5_dbe_free_mkey_aux_list(krb5_context, krb5_mkey_aux_node *); 859 860 void 861 krb5_dbe_free_tl_data(krb5_context, krb5_tl_data *); 862 863 void 864 krb5_dbe_free_strings(krb5_context, krb5_string_attr *, int count); 865 866 void 867 krb5_dbe_free_string(krb5_context, char *); 868 869 /* 870 * Register the KDB keytab type, allowing "KDB:" to be used as a keytab name. 871 * For this type to work, the context used for keytab operations must have an 872 * associated database handle (via krb5_db_open()). 873 */ 874 krb5_error_code krb5_db_register_keytab(krb5_context context); 875 876 #define KRB5_KDB_DEF_FLAGS 0 877 878 #define KDB_MAX_DB_NAME 128 879 #define KDB_REALM_SECTION "realms" 880 #define KDB_MODULE_POINTER "database_module" 881 #define KDB_MODULE_DEF_SECTION "dbdefaults" 882 #define KDB_MODULE_SECTION "dbmodules" 883 #define KDB_LIB_POINTER "db_library" 884 #define KDB_DATABASE_CONF_FILE DEFAULT_SECURE_PROFILE_PATH 885 #define KDB_DATABASE_ENV_PROF KDC_PROFILE_ENV 886 887 #define KRB5_KDB_OPEN_RW 0 888 #define KRB5_KDB_OPEN_RO 1 889 890 #define KRB5_KDB_OPT_SET_DB_NAME 0 891 #define KRB5_KDB_OPT_SET_LOCK_MODE 1 892 893 /* 894 * This number indicates the date of the last incompatible change to the DAL. 895 * The maj_ver field of the module's vtable structure must match this version. 896 */ 897 #define KRB5_KDB_DAL_MAJOR_VERSION 8 898 899 /* 900 * A krb5_context can hold one database object. Modules should use 901 * krb5_db_set_context and krb5_db_get_context to store state associated with 902 * the database object. 903 * 904 * Some module functions are mandatory for KDC operation; others are optional 905 * or apply only to administrative operations. If a function is optional, a 906 * module can leave the function pointer as NULL. Alternatively, modules can 907 * return KRB5_PLUGIN_OP_NOTSUPP when asked to perform an inapplicable action. 908 * 909 * Some module functions have default implementations which will call back into 910 * the vtable interface. Leave these functions as NULL to use the default 911 * implementations. 912 * 913 * The documentation in these comments describes the DAL as it is currently 914 * implemented and used, not as it should be. So if anything seems off, that 915 * probably means the current state of things is off. 916 * 917 * Modules must allocate memory for principal entries, policy entries, and 918 * other structures using an allocator compatible with malloc() as seen by 919 * libkdb5 and libkrb5. Modules may link against libkdb5 and call 920 * krb5_db_alloc() to be certain that the same malloc implementation is used. 921 */ 922 923 typedef struct _kdb_vftabl { 924 short int maj_ver; 925 short int min_ver; 926 927 /* 928 * Mandatory: Invoked after the module library is loaded, when the first DB 929 * using the module is opened, across all contexts. 930 */ 931 krb5_error_code (*init_library)(void); 932 933 /* 934 * Mandatory: Invoked before the module library is unloaded, after the last 935 * DB using the module is closed, across all contexts. 936 */ 937 krb5_error_code (*fini_library)(void); 938 939 /* 940 * Mandatory: Initialize a database object. Profile settings should be 941 * read from conf_section inside KDB_MODULE_SECTION. db_args communicates 942 * command-line arguments for module-specific flags. mode will be one of 943 * KRB5_KDB_OPEN_{RW,RO} or'd with one of 944 * KRB5_KDB_SRV_TYPE_{KDC,ADMIN,PASSWD,OTHER}. 945 */ 946 krb5_error_code (*init_module)(krb5_context kcontext, char *conf_section, 947 char **db_args, int mode); 948 949 /* 950 * Mandatory: Finalize the database object contained in a context. Free 951 * any state contained in the db_context pointer and null it out. 952 */ 953 krb5_error_code (*fini_module)(krb5_context kcontext); 954 955 /* 956 * Optional: Initialize a database object while creating the underlying 957 * database. conf_section and db_args have the same meaning as in 958 * init_module. This function may return an error if the database already 959 * exists. Used by kdb5_util create. 960 * 961 * If db_args contains the value "temporary", the module should create an 962 * exclusively locked side copy of the database suitable for loading in a 963 * propagation from primary to replica. This side copy will later be 964 * promoted with promote_db, allowing complete updates of the DB with no 965 * loss in read availability. If the module cannot comply with this 966 * architecture, it should return an error. 967 */ 968 krb5_error_code (*create)(krb5_context kcontext, char *conf_section, 969 char **db_args); 970 971 /* 972 * Optional: Destroy a database. conf_section and db_args have the same 973 * meaning as in init_module. Used by kdb5_util destroy. In current 974 * usage, the database is destroyed while open, so the module should handle 975 * that. 976 */ 977 krb5_error_code (*destroy)(krb5_context kcontext, char *conf_section, 978 char **db_args); 979 980 /* 981 * Deprecated: No longer used as of krb5 1.10; can be removed in the next 982 * DAL revision. Modules should leave as NULL. 983 */ 984 krb5_error_code (*get_age)(krb5_context kcontext, char *db_name, 985 time_t *age); 986 987 /* 988 * Optional: Lock the database, with semantics depending on the mode 989 * argument: 990 * 991 * KRB5_DB_LOCKMODE_SHARED: Lock may coexist with other shared locks. 992 * KRB5_DB_LOCKMODE_EXCLUSIVE: Lock may not coexist with other locks. 993 * KRB5_DB_LOCKMODE_PERMANENT: Exclusive lock surviving process exit. 994 * 995 * Used by the "kadmin lock" command, incremental propagation, and 996 * kdb5_util dump. Incremental propagation support requires shared locks 997 * to operate. kdb5_util dump will continue unlocked if the module returns 998 * KRB5_PLUGIN_OP_NOTSUPP. 999 */ 1000 krb5_error_code (*lock)(krb5_context kcontext, int mode); 1001 1002 /* Optional: Release a lock created with db_lock. */ 1003 krb5_error_code (*unlock)(krb5_context kcontext); 1004 1005 /* 1006 * Mandatory: Set *entry to an allocated entry for the principal 1007 * search_for. If the principal is not found, return KRB5_KDB_NOENTRY. 1008 * 1009 * The meaning of flags are as follows: 1010 * 1011 * KRB5_KDB_FLAG_CANONICALIZE: Set by the KDC when looking up entries for 1012 * an AS or TGS request with canonicalization requested. Determines 1013 * whether the module should return out-of-realm referrals. 1014 * 1015 * KRB5_KDB_FLAG_INCLUDE_PAC: Set by the KDC during an AS request when the 1016 * client requested PAC information during padata, and during most TGS 1017 * requests. Indicates that the module should include PAC information 1018 * when its sign_authdata method is invoked. 1019 * 1020 * KRB5_KDB_FLAG_CLIENT_REFERRALS_ONLY: Set by the KDC when looking up the 1021 * client entry in an AS request. Affects how the module should return 1022 * out-of-realm referrals. 1023 * 1024 * KRB5_KDB_FLAG_MAP_PRINCIPALS: Set by the KDC when looking up the client 1025 * entry during TGS requests, except for S4U TGS requests and requests 1026 * where the server entry has the KRB5_KDB_NO_AUTH_DATA_REQUIRED 1027 * attribute. Indicates that the module should map foreign principals 1028 * to local principals if it supports doing so. 1029 * 1030 * KRB5_KDB_FLAG_PROTOCOL_TRANSITION: Set by the KDC when looking up the 1031 * client entry during an S4U2Self TGS request. This affects the PAC 1032 * information which should be included when authorization data is 1033 * generated; see the Microsoft S4U specification for details. 1034 * 1035 * KRB5_KDB_FLAG_CONSTRAINED_DELEGATION: Set by the KDC when looking up the 1036 * client entry during an S4U2Proxy TGS request. Also affects PAC 1037 * generation. 1038 * 1039 * KRB5_KDB_FLAG_CROSS_REALM: Set by the KDC after looking up a server 1040 * entry during a TGS request, if the header ticket was issued by a 1041 * different realm. 1042 * 1043 * KRB5_KDB_FLAG_ISSUING_REFERRAL: Set by the KDC after looking up a server 1044 * entry during a TGS request, if the requested server principal is not 1045 * part of the realm being served, and a referral or alternate TGT will 1046 * be issued instead. 1047 * 1048 * A module may return an in-realm alias by setting (*entry)->princ to the 1049 * canonical name. The KDC will decide based on the request whether to use 1050 * the requested name or the canonical name in the issued ticket. 1051 * 1052 * A module can return a referral to another realm if 1053 * KRB5_KDB_FLAG_CANONICALIZE is set, or if 1054 * KRB5_KDB_FLAG_CLIENT_REFERRALS_ONLY is set and search_for->type is 1055 * KRB5_NT_ENTERPRISE_PRINCIPAL. If KRB5_KDB_FLAG_CLIENT_REFERRALS_ONLY is 1056 * set, the module should return a referral by simply filling in an 1057 * out-of-realm name in (*entry)->princ and setting all other fields to 1058 * NULL. Otherwise, the module should return the entry for the cross-realm 1059 * TGS of the referred-to realm. For TGS referals, the module can also 1060 * include tl-data of type KRB5_TL_SERVER_REFERRAL containing ASN.1-encoded 1061 * Windows referral data as documented in 1062 * draft-ietf-krb-wg-kerberos-referrals-11 appendix A; this will be 1063 * returned to the client as encrypted padata. 1064 */ 1065 krb5_error_code (*get_principal)(krb5_context kcontext, 1066 krb5_const_principal search_for, 1067 unsigned int flags, 1068 krb5_db_entry **entry); 1069 1070 /* 1071 * Optional: Create or modify a principal entry. db_args communicates 1072 * command-line arguments for module-specific flags. 1073 * 1074 * The mask field of an entry indicates the changed fields. Mask values 1075 * are defined in kadmin's admin.h header. If KADM5_PRINCIPAL is set in 1076 * the mask, the entry is new; otherwise it already exists. All fields of 1077 * an entry are expected to contain correct values, regardless of whether 1078 * they are specified in the mask, so it is acceptable for a module to 1079 * ignore the mask and update the entire entry. 1080 */ 1081 krb5_error_code (*put_principal)(krb5_context kcontext, 1082 krb5_db_entry *entry, char **db_args); 1083 1084 /* 1085 * Optional: Delete the entry for the principal search_for. If the 1086 * principal did not exist, return KRB5_KDB_NOENTRY. 1087 */ 1088 krb5_error_code (*delete_principal)(krb5_context kcontext, 1089 krb5_const_principal search_for); 1090 1091 /* 1092 * Optional with default: Rename a principal. If the source principal does 1093 * not exist, return KRB5_KDB_NOENTRY. If the target exists, return an 1094 * error. 1095 * 1096 * NOTE: If the module chooses to implement a custom function for renaming 1097 * a principal instead of using the default, then rename operations will 1098 * fail if iprop logging is enabled. 1099 */ 1100 krb5_error_code (*rename_principal)(krb5_context kcontext, 1101 krb5_const_principal source, 1102 krb5_const_principal target); 1103 1104 /* 1105 * Optional: For each principal entry in the database, invoke func with the 1106 * arguments func_arg and the entry data. If match_entry is specified, the 1107 * module may narrow the iteration to principal names matching that regular 1108 * expression; a module may alternatively ignore match_entry. 1109 */ 1110 krb5_error_code (*iterate)(krb5_context kcontext, 1111 char *match_entry, 1112 int (*func)(krb5_pointer, krb5_db_entry *), 1113 krb5_pointer func_arg, krb5_flags iterflags); 1114 1115 /* 1116 * Optional: Create a password policy entry. Return an error if the policy 1117 * already exists. 1118 */ 1119 krb5_error_code (*create_policy)(krb5_context kcontext, 1120 osa_policy_ent_t policy); 1121 1122 /* 1123 * Optional: Set *policy to the policy entry of the specified name. If the 1124 * entry does not exist, return KRB5_KDB_NOENTRY. 1125 */ 1126 krb5_error_code (*get_policy)(krb5_context kcontext, char *name, 1127 osa_policy_ent_t *policy); 1128 1129 /* 1130 * Optional: Modify an existing password policy entry to match the values 1131 * in policy. Return an error if the policy does not already exist. 1132 */ 1133 krb5_error_code (*put_policy)(krb5_context kcontext, 1134 osa_policy_ent_t policy); 1135 1136 /* 1137 * Optional: For each password policy entry in the database, invoke func 1138 * with the arguments data and the entry data. If match_entry is 1139 * specified, the module may narrow the iteration to policy names matching 1140 * that regular expression; a module may alternatively ignore match_entry. 1141 */ 1142 krb5_error_code (*iter_policy)(krb5_context kcontext, char *match_entry, 1143 osa_adb_iter_policy_func func, 1144 void *data); 1145 1146 /* 1147 * Optional: Delete the password policy entry with the name policy. Return 1148 * an error if the entry does not exist. 1149 */ 1150 krb5_error_code (*delete_policy)(krb5_context kcontext, char *policy); 1151 1152 /* 1153 * Optional with default: Retrieve a master keyblock from the stash file 1154 * db_args, filling in *key and *kvno. mname is the name of the master 1155 * principal for the realm. 1156 * 1157 * The default implementation reads the master keyblock from a keytab or 1158 * old-format stash file. 1159 */ 1160 krb5_error_code (*fetch_master_key)(krb5_context kcontext, 1161 krb5_principal mname, 1162 krb5_keyblock *key, krb5_kvno *kvno, 1163 char *db_args); 1164 1165 /* 1166 * Optional with default: Given a keyblock for some version of the 1167 * database's master key, fetch the decrypted master key values from the 1168 * database and store the list into *mkeys_list. The caller will free 1169 * *mkeys_list using a libkdb5 function which uses the standard free() 1170 * function, so the module must not use a custom allocator. 1171 * 1172 * The caller may not know the version number of the master key it has, in 1173 * which case it will pass IGNORE_VNO. 1174 * 1175 * The default implementation ignores kvno and tries the key against the 1176 * current master key data and all KRB5_TL_MKEY_AUX values, which contain 1177 * copies of the master keys encrypted with old master keys. 1178 */ 1179 krb5_error_code (*fetch_master_key_list)(krb5_context kcontext, 1180 krb5_principal mname, 1181 const krb5_keyblock *key, 1182 krb5_keylist_node **mkeys_list); 1183 1184 /* 1185 * Optional with default: Save a list of master keyblocks, obtained from 1186 * fetch_master_key_list, into the stash file db_arg. The caller will set 1187 * master_pwd to NULL, so the module should just ignore it. mname is the 1188 * name of the master principal for the realm. 1189 * 1190 * The default implementation saves the list of master keys in a 1191 * keytab-format file. 1192 */ 1193 krb5_error_code (*store_master_key_list)(krb5_context kcontext, 1194 char *db_arg, 1195 krb5_principal mname, 1196 krb5_keylist_node *keylist, 1197 char *master_pwd); 1198 1199 /* 1200 * Optional with default: Starting at position *start, scan the key data of 1201 * a database entry for a key matching the enctype ktype, the salt type 1202 * stype, and the version kvno. Store the resulting key into *kdatap and 1203 * set *start to the position after the key found. If ktype is negative, 1204 * match any enctype. If stype is negative, match any salt type. If kvno 1205 * is zero or negative, find the most recent key version satisfying the 1206 * other constraints. 1207 */ 1208 krb5_error_code (*dbe_search_enctype)(krb5_context kcontext, 1209 krb5_db_entry *dbentp, 1210 krb5_int32 *start, krb5_int32 ktype, 1211 krb5_int32 stype, krb5_int32 kvno, 1212 krb5_key_data **kdatap); 1213 1214 1215 /* 1216 * Optional with default: Change the key data for db_entry to include keys 1217 * derived from the password passwd in each of the specified key-salt 1218 * types, at version new_kvno. Discard the old key data if keepold is not 1219 * set. 1220 * 1221 * The default implementation uses the keyblock master_key to encrypt each 1222 * new key, via the function encrypt_key_data. 1223 */ 1224 krb5_error_code (*change_pwd)(krb5_context context, 1225 krb5_keyblock *master_key, 1226 krb5_key_salt_tuple *ks_tuple, 1227 int ks_tuple_count, char *passwd, 1228 int new_kvno, krb5_boolean keepold, 1229 krb5_db_entry *db_entry); 1230 1231 /* 1232 * Optional: Promote a temporary database to be the live one. context must 1233 * be initialized with an exclusively locked database created with the 1234 * "temporary" db_arg. On success, the database object contained in 1235 * context will be finalized. 1236 * 1237 * This method is used by kdb5_util load to replace the live database with 1238 * minimal loss of read availability. 1239 */ 1240 krb5_error_code (*promote_db)(krb5_context context, char *conf_section, 1241 char **db_args); 1242 1243 /* 1244 * Optional with default: Decrypt the key in key_data with master keyblock 1245 * mkey, placing the result into dbkey. Copy the salt from key_data, if 1246 * any, into keysalt. Either dbkey or keysalt may be left unmodified on 1247 * successful return if key_data does not contain key or salt information. 1248 * 1249 * The default implementation expects the encrypted key (in krb5_c_encrypt 1250 * format) to be stored in key_data_contents[0], with length given by 1251 * key_data_length[0]. If key_data_ver is 2, it expects the salt to be 1252 * stored, unencrypted, in key_data_contents[1], with length given by 1253 * key_data_length[1]. 1254 */ 1255 krb5_error_code (*decrypt_key_data)(krb5_context kcontext, 1256 const krb5_keyblock *mkey, 1257 const krb5_key_data *key_data, 1258 krb5_keyblock *dbkey, 1259 krb5_keysalt *keysalt); 1260 1261 /* 1262 * Optional with default: Encrypt dbkey with master keyblock mkey, placing 1263 * the result into key_data along with keysalt. 1264 * 1265 * The default implementation stores the encrypted key (in krb5_c_encrypt 1266 * format) in key_data_contents[0] and the length in key_data_length[0]. 1267 * If keysalt is specified, it sets key_data_ver to 2, and stores the salt 1268 * in key_data_contents[1] and its length in key_data_length[1]. If 1269 * keysalt is not specified, key_data_ver is set to 1. 1270 */ 1271 krb5_error_code (*encrypt_key_data)(krb5_context kcontext, 1272 const krb5_keyblock *mkey, 1273 const krb5_keyblock *dbkey, 1274 const krb5_keysalt *keysalt, 1275 int keyver, krb5_key_data *key_data); 1276 1277 /* 1278 * Optional: Generate signed authorization data, such as a Windows PAC, for 1279 * the ticket to be returned to the client. Place the signed authorization 1280 * data, if any, in *signed_auth_data. This function will be invoked for 1281 * an AS request if the client included padata requesting a PAC. This 1282 * function will be invoked for a TGS request if there is authorization 1283 * data in the TGT, if the client is from another realm, or if the TGS 1284 * request is an S4U2Self or S4U2Proxy request. This function will not be 1285 * invoked during TGS requests if the server principal has the 1286 * no_auth_data_required attribute set. Input parameters are: 1287 * 1288 * flags: The flags used to look up the client principal. 1289 * 1290 * client_princ: For S4U2Self and S4U2Proxy TGS requests, the client 1291 * principal requested by the service; for regular TGS requests, the 1292 * possibly-canonicalized client principal. 1293 * 1294 * server_princ: The server principal in the request. 1295 * 1296 * client: The DB entry of the client if it is in the local realm, NULL 1297 * if not. For S4U2Self and S4U2Proxy TGS requests, this is the DB 1298 * entry for the client principal requested by the service. 1299 * 1300 * server: The DB entry of the service principal, or of a cross-realm 1301 * krbtgt principal in case of referral. 1302 * 1303 * header_server: For S4U2Proxy requests, the DB entry of the second 1304 * ticket server. For other TGS requests, the DB entry of the header 1305 * ticket server. For AS requests, NULL. 1306 * 1307 * local_tgt: the DB entry of the local krbtgt principal. 1308 * 1309 * client_key: The reply key for the KDC request, before any FAST armor 1310 * is applied. For AS requests, this may be the client's long-term key 1311 * or a key chosen by a preauth mechanism. For TGS requests, this may 1312 * be the subkey found in the AP-REQ or the session key of the TGT. 1313 * 1314 * server_key: The server key used to encrypt the returned ticket. 1315 * 1316 * header_key: For S4U2Proxy requests, the key used to decrypt the second 1317 * ticket. For TGS requests, the key used to decrypt the header 1318 * ticket. For AS requests, NULL. 1319 * 1320 * local_tgt_key: The decrypted first key of local_tgt. 1321 * 1322 * session_key: The session key of the ticket being granted to the 1323 * requestor. 1324 * 1325 * authtime: The timestamp of the original client authentication time. 1326 * For AS requests, this is the current time. For TGS requests, this 1327 * is the authtime of the subject ticket (TGT or S4U2Proxy evidence 1328 * ticket). 1329 * 1330 * tgt_auth_data: For TGS requests, the authorization data present in the 1331 * subject ticket. For AS requests, NULL. 1332 * 1333 * ad_info: For TGS requests, the parsed authorization data if obtained 1334 * by get_authdata_info method from the authorization data present in 1335 * the subject ticket. Otherwise NULL. 1336 * 1337 * auth_indicators: Points to NULL or a null-terminated list of krb5_data 1338 * pointers, each containing an authentication indicator (RFC 8129). 1339 * The method may modify this list, or free it and replace 1340 * *auth_indicators with NULL, to change which auth indicators will be 1341 * included in the ticket. 1342 */ 1343 krb5_error_code (*sign_authdata)(krb5_context kcontext, 1344 unsigned int flags, 1345 krb5_const_principal client_princ, 1346 krb5_const_principal server_princ, 1347 krb5_db_entry *client, 1348 krb5_db_entry *server, 1349 krb5_db_entry *header_server, 1350 krb5_db_entry *local_tgt, 1351 krb5_keyblock *client_key, 1352 krb5_keyblock *server_key, 1353 krb5_keyblock *header_key, 1354 krb5_keyblock *local_tgt_key, 1355 krb5_keyblock *session_key, 1356 krb5_timestamp authtime, 1357 krb5_authdata **tgt_auth_data, 1358 void *ad_info, 1359 krb5_data ***auth_indicators, 1360 krb5_authdata ***signed_auth_data); 1361 1362 /* 1363 * Optional: Perform a policy check on a cross-realm ticket's transited 1364 * field. Return 0 if the check authoritatively succeeds, 1365 * KRB5_PLUGIN_NO_HANDLE to use the core transited-checking mechanisms, or 1366 * another error (other than KRB5_PLUGIN_OP_NOTSUPP) if the check fails. 1367 */ 1368 krb5_error_code (*check_transited_realms)(krb5_context kcontext, 1369 const krb5_data *tr_contents, 1370 const krb5_data *client_realm, 1371 const krb5_data *server_realm); 1372 1373 /* 1374 * Optional: Perform a policy check on an AS request, in addition to the 1375 * standard policy checks. Return 0 if the AS request is allowed. If the 1376 * AS request is not allowed: 1377 * - Place a short string literal into *status. 1378 * - If desired, place data into e_data. Any data placed here will be 1379 * freed by the caller using the standard free function. 1380 * - Return an appropriate error (such as KRB5KDC_ERR_POLICY). 1381 */ 1382 krb5_error_code (*check_policy_as)(krb5_context kcontext, 1383 krb5_kdc_req *request, 1384 krb5_db_entry *client, 1385 krb5_db_entry *server, 1386 krb5_timestamp kdc_time, 1387 const char **status, 1388 krb5_pa_data ***e_data); 1389 1390 /* 1391 * Optional: Perform a policy check on a TGS request, in addition to the 1392 * standard policy checks. Return 0 if the TGS request is allowed. If the 1393 * TGS request is not allowed: 1394 * - Place a short string literal into *status. 1395 * - If desired, place data into e_data. Any data placed here will be 1396 * freed by the caller using the standard free function. 1397 * - Return an appropriate error (such as KRB5KDC_ERR_POLICY). 1398 * The input parameter ticket contains the TGT used in the TGS request. 1399 */ 1400 krb5_error_code (*check_policy_tgs)(krb5_context kcontext, 1401 krb5_kdc_req *request, 1402 krb5_db_entry *server, 1403 krb5_ticket *ticket, 1404 const char **status, 1405 krb5_pa_data ***e_data); 1406 1407 /* 1408 * Optional: This method informs the module of a successful or unsuccessful 1409 * AS request. 1410 */ 1411 void (*audit_as_req)(krb5_context kcontext, krb5_kdc_req *request, 1412 const krb5_address *local_addr, 1413 const krb5_address *remote_addr, 1414 krb5_db_entry *client, krb5_db_entry *server, 1415 krb5_timestamp authtime, krb5_error_code error_code); 1416 1417 /* Note: there is currently no method for auditing TGS requests. */ 1418 1419 /* 1420 * Optional: This method informs the module of a request to reload 1421 * configuration or other state (that is, the KDC received a SIGHUP). 1422 */ 1423 void (*refresh_config)(krb5_context kcontext); 1424 1425 /* 1426 * Optional: Perform a policy check on server being allowed to obtain 1427 * tickets from client to proxy. (Note that proxy is the target of the 1428 * delegation, not the delegating service; the term "proxy" is from the 1429 * viewpoint of the delegating service asking another service to perform 1430 * some of its work in the authentication context of the client. This 1431 * terminology comes from the Microsoft S4U protocol documentation.) 1432 * Return 0 if policy allows it, or an appropriate error (such as 1433 * KRB5KDC_ERR_POLICY) if not. If this method is not implemented, all 1434 * S4U2Proxy delegation requests will be rejected. 1435 */ 1436 krb5_error_code (*check_allowed_to_delegate)(krb5_context context, 1437 krb5_const_principal client, 1438 const krb5_db_entry *server, 1439 krb5_const_principal proxy); 1440 1441 /* 1442 * Optional: Free the e_data pointer of a database entry. If this method 1443 * is not implemented, the e_data pointer in principal entries will be 1444 * freed with free() as seen by libkdb5. 1445 */ 1446 void (*free_principal_e_data)(krb5_context kcontext, krb5_octet *e_data); 1447 1448 /* 1449 * Optional: get a principal entry for S4U2Self based on X509 certificate. 1450 * 1451 * If flags include KRB5_KDB_FLAG_CLIENT_REFERRALS_ONLY, princ->realm 1452 * indicates the request realm, but the data components should be ignored. 1453 * The module can return an out-of-realm client referral as it would for 1454 * get_principal(). 1455 * 1456 * If flags does not include KRB5_KDB_FLAG_CLIENT_REFERRALS_ONLY, princ is 1457 * from PA-S4U-X509-USER. If it contains data components (and not just a 1458 * realm), the module should verify that it is the same as the lookup 1459 * result for client_cert. The module should not return a referral. 1460 */ 1461 krb5_error_code (*get_s4u_x509_principal)(krb5_context kcontext, 1462 const krb5_data *client_cert, 1463 krb5_const_principal princ, 1464 unsigned int flags, 1465 krb5_db_entry **entry_out); 1466 1467 /* 1468 * Optional: Perform a policy check on server being allowed to obtain 1469 * tickets from client to proxy. This method is similar to 1470 * check_allowed_to_delegate, but it operates on the target server DB entry 1471 * (called "proxy" here as in Microsoft's protocol documentation) rather 1472 * than the intermediate server entry. server_ad_info represents the 1473 * authdata of the intermediate server, as returned by the 1474 * get_authdata_info method on the header ticket. Return 0 if policy 1475 * allows the delegation, or an appropriate error (such as 1476 * KRB5KDC_ERR_POLICY) if not. 1477 * 1478 * This method is called for S4U2Proxy requests and implements the 1479 * resource-based constrained delegation variant, which can support 1480 * cross-realm delegation. If this method is not implemented or if it 1481 * returns a policy error, the KDC will fall back to 1482 * check_allowed_to_delegate if the intermediate and target servers are in 1483 * the same realm and the evidence ticket is forwardable. 1484 */ 1485 krb5_error_code (*allowed_to_delegate_from)(krb5_context context, 1486 krb5_const_principal client, 1487 krb5_const_principal server, 1488 void *server_ad_info, 1489 const krb5_db_entry *proxy); 1490 1491 /* 1492 * Optional: Perform verification and policy checks on authorization data, 1493 * such as a Windows PAC, based on the request client lookup flags. Return 1494 * 0 if all checks have passed. Optionally return a representation of the 1495 * authdata in *ad_info_out, to be consumed by allowed_to_delegate_from and 1496 * sign_authdata. Returning *ad_info_out is required to support 1497 * resource-based constrained delegation. 1498 * 1499 * If the KRB5_KDB_FLAG_CONSTRAINED_DELEGATION bit is set, a PAC must be 1500 * provided and verified, and an error should be returned if the client is 1501 * not allowed to delegate. If the KRB5_KDB_FLAG_CROSS_REALM bit is also 1502 * set, set *client_out to the client name in the PAC; this indicates the 1503 * requested client principal for a cross-realm S4U2Proxy request. 1504 * 1505 * This method is called for TGS requests on the authorization data from 1506 * the header ticket. For S4U2Proxy requests it is also called on the 1507 * authorization data from the evidence ticket. If the 1508 * KRB5_KDB_FLAG_PROTOCOL_TRANSITION bit is set in flags, the authdata is 1509 * from the header ticket of an S4U2Self referral request, and the supplied 1510 * client_princ is the requested client. 1511 */ 1512 krb5_error_code (*get_authdata_info)(krb5_context context, 1513 unsigned int flags, 1514 krb5_authdata **in_authdata, 1515 krb5_const_principal client_princ, 1516 krb5_const_principal server_princ, 1517 krb5_keyblock *server_key, 1518 krb5_keyblock *krbtgt_key, 1519 krb5_db_entry *krbtgt, 1520 krb5_timestamp authtime, 1521 void **ad_info_out, 1522 krb5_principal *client_out); 1523 1524 void (*free_authdata_info)(krb5_context context, 1525 void *ad_info); 1526 1527 /* End of minor version 0 for major version 8. */ 1528 } kdb_vftabl; 1529 1530 #endif /* !defined(_WIN32) */ 1531 1532 #endif /* KRB5_KDB5__ */ 1533