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 <time.h> 69 #include <krb5.h> 70 71 /* This version will be incremented when incompatible changes are made to the 72 * KDB API, and will be kept in sync with the libkdb major version. */ 73 #define KRB5_KDB_API_VERSION 10 74 75 /* Salt types */ 76 #define KRB5_KDB_SALTTYPE_NORMAL 0 77 /* #define KRB5_KDB_SALTTYPE_V4 1 */ 78 #define KRB5_KDB_SALTTYPE_NOREALM 2 79 #define KRB5_KDB_SALTTYPE_ONLYREALM 3 80 #define KRB5_KDB_SALTTYPE_SPECIAL 4 81 /* #define KRB5_KDB_SALTTYPE_AFS3 5 */ 82 #define KRB5_KDB_SALTTYPE_CERTHASH 6 83 84 /* Attributes */ 85 #define KRB5_KDB_DISALLOW_POSTDATED 0x00000001 86 #define KRB5_KDB_DISALLOW_FORWARDABLE 0x00000002 87 #define KRB5_KDB_DISALLOW_TGT_BASED 0x00000004 88 #define KRB5_KDB_DISALLOW_RENEWABLE 0x00000008 89 #define KRB5_KDB_DISALLOW_PROXIABLE 0x00000010 90 #define KRB5_KDB_DISALLOW_DUP_SKEY 0x00000020 91 #define KRB5_KDB_DISALLOW_ALL_TIX 0x00000040 92 #define KRB5_KDB_REQUIRES_PRE_AUTH 0x00000080 93 #define KRB5_KDB_REQUIRES_HW_AUTH 0x00000100 94 #define KRB5_KDB_REQUIRES_PWCHANGE 0x00000200 95 #define KRB5_KDB_DISALLOW_SVR 0x00001000 96 #define KRB5_KDB_PWCHANGE_SERVICE 0x00002000 97 #define KRB5_KDB_SUPPORT_DESMD5 0x00004000 98 #define KRB5_KDB_NEW_PRINC 0x00008000 99 #define KRB5_KDB_OK_AS_DELEGATE 0x00100000 100 #define KRB5_KDB_OK_TO_AUTH_AS_DELEGATE 0x00200000 /* S4U2Self OK */ 101 #define KRB5_KDB_NO_AUTH_DATA_REQUIRED 0x00400000 102 #define KRB5_KDB_LOCKDOWN_KEYS 0x00800000 103 104 /* Creation flags */ 105 #define KRB5_KDB_CREATE_BTREE 0x00000001 106 #define KRB5_KDB_CREATE_HASH 0x00000002 107 108 /* Entry get flags */ 109 /* Okay to generate a referral on lookup */ 110 #define KRB5_KDB_FLAG_REFERRAL_OK 0x00000010 111 /* Client principal lookup (client referrals only) */ 112 #define KRB5_KDB_FLAG_CLIENT 0x00000040 113 /* Map cross-realm principals */ 114 #define KRB5_KDB_FLAG_MAP_PRINCIPALS 0x00000080 115 /* Protocol transition */ 116 #define KRB5_KDB_FLAG_PROTOCOL_TRANSITION 0x00000100 117 /* Constrained delegation */ 118 #define KRB5_KDB_FLAG_CONSTRAINED_DELEGATION 0x00000200 119 /* User-to-user */ 120 #define KRB5_KDB_FLAG_USER_TO_USER 0x00000800 121 /* Cross-realm */ 122 #define KRB5_KDB_FLAG_CROSS_REALM 0x00001000 123 /* Issuing referral */ 124 #define KRB5_KDB_FLAG_ISSUING_REFERRAL 0x00004000 125 126 127 #define KRB5_KDB_FLAGS_S4U ( KRB5_KDB_FLAG_PROTOCOL_TRANSITION | \ 128 KRB5_KDB_FLAG_CONSTRAINED_DELEGATION ) 129 130 /* KDB iteration flags */ 131 #define KRB5_DB_ITER_WRITE 0x00000001 132 #define KRB5_DB_ITER_REV 0x00000002 133 #define KRB5_DB_ITER_RECURSE 0x00000004 134 135 /* String attribute names recognized by krb5 */ 136 #define KRB5_KDB_SK_PAC_PRIVSVR_ENCTYPE "pac_privsvr_enctype" 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_check_transited_realms(krb5_context kcontext, 660 const krb5_data *tr_contents, 661 const krb5_data *client_realm, 662 const krb5_data *server_realm); 663 664 krb5_error_code krb5_db_check_policy_as(krb5_context kcontext, 665 krb5_kdc_req *request, 666 krb5_db_entry *client, 667 krb5_db_entry *server, 668 krb5_timestamp kdc_time, 669 const char **status, 670 krb5_pa_data ***e_data); 671 672 krb5_error_code krb5_db_check_policy_tgs(krb5_context kcontext, 673 krb5_kdc_req *request, 674 krb5_db_entry *server, 675 krb5_ticket *ticket, 676 const char **status, 677 krb5_pa_data ***e_data); 678 679 void krb5_db_audit_as_req(krb5_context kcontext, krb5_kdc_req *request, 680 const krb5_address *local_addr, 681 const krb5_address *remote_addr, 682 krb5_db_entry *client, krb5_db_entry *server, 683 krb5_timestamp authtime, krb5_error_code error_code); 684 685 void krb5_db_refresh_config(krb5_context kcontext); 686 687 krb5_error_code krb5_db_check_allowed_to_delegate(krb5_context kcontext, 688 krb5_const_principal client, 689 const krb5_db_entry *server, 690 krb5_const_principal proxy); 691 692 krb5_error_code krb5_db_get_s4u_x509_principal(krb5_context kcontext, 693 const krb5_data *client_cert, 694 krb5_const_principal in_princ, 695 unsigned int flags, 696 krb5_db_entry **entry); 697 698 krb5_error_code krb5_db_allowed_to_delegate_from(krb5_context context, 699 krb5_const_principal client, 700 krb5_const_principal server, 701 krb5_pac server_pac, 702 const krb5_db_entry *proxy); 703 704 /** 705 * Sort an array of @a krb5_key_data keys in descending order by their kvno. 706 * Key data order within a kvno is preserved. 707 * 708 * @param key_data 709 * The @a krb5_key_data array to sort. This is sorted in place so the 710 * array will be modified. 711 * @param key_data_length 712 * The length of @a key_data. 713 */ 714 void 715 krb5_dbe_sort_key_data(krb5_key_data *key_data, size_t key_data_length); 716 717 krb5_error_code 718 krb5_db_issue_pac(krb5_context context, unsigned int flags, 719 krb5_db_entry *client, krb5_keyblock *replaced_reply_key, 720 krb5_db_entry *server, krb5_db_entry *krbtgt, 721 krb5_timestamp authtime, krb5_pac old_pac, krb5_pac new_pac, 722 krb5_data ***auth_indicators); 723 724 /* default functions. Should not be directly called */ 725 /* 726 * Default functions prototype 727 */ 728 729 krb5_error_code 730 krb5_dbe_def_search_enctype( krb5_context kcontext, 731 krb5_db_entry *dbentp, 732 krb5_int32 *start, 733 krb5_int32 ktype, 734 krb5_int32 stype, 735 krb5_int32 kvno, 736 krb5_key_data **kdatap); 737 738 krb5_error_code 739 krb5_def_store_mkey_list( krb5_context context, 740 char *keyfile, 741 krb5_principal mname, 742 krb5_keylist_node *keylist, 743 char *master_pwd); 744 745 krb5_error_code 746 krb5_db_def_fetch_mkey( krb5_context context, 747 krb5_principal mname, 748 krb5_keyblock *key, 749 krb5_kvno *kvno, 750 char *db_args); 751 752 krb5_error_code 753 krb5_def_fetch_mkey_list( krb5_context context, 754 krb5_principal mprinc, 755 const krb5_keyblock *mkey, 756 krb5_keylist_node **mkeys_list); 757 758 krb5_error_code 759 krb5_dbe_def_cpw( krb5_context context, 760 krb5_keyblock * master_key, 761 krb5_key_salt_tuple * ks_tuple, 762 int ks_tuple_count, 763 char * passwd, 764 int new_kvno, 765 krb5_boolean keepold, 766 krb5_db_entry * db_entry); 767 768 krb5_error_code 769 krb5_dbe_def_decrypt_key_data( krb5_context context, 770 const krb5_keyblock * mkey, 771 const krb5_key_data * key_data, 772 krb5_keyblock * dbkey, 773 krb5_keysalt * keysalt); 774 775 krb5_error_code 776 krb5_dbe_def_encrypt_key_data( krb5_context context, 777 const krb5_keyblock * mkey, 778 const krb5_keyblock * dbkey, 779 const krb5_keysalt * keysalt, 780 int keyver, 781 krb5_key_data * key_data); 782 783 krb5_error_code 784 krb5_db_def_rename_principal( krb5_context kcontext, 785 krb5_const_principal source, 786 krb5_const_principal target); 787 788 krb5_error_code 789 krb5_db_create_policy( krb5_context kcontext, 790 osa_policy_ent_t policy); 791 792 krb5_error_code 793 krb5_db_get_policy ( krb5_context kcontext, 794 char *name, 795 osa_policy_ent_t *policy ); 796 797 krb5_error_code 798 krb5_db_put_policy( krb5_context kcontext, 799 osa_policy_ent_t policy); 800 801 krb5_error_code 802 krb5_db_iter_policy( krb5_context kcontext, 803 char *match_entry, 804 osa_adb_iter_policy_func func, 805 void *data); 806 807 krb5_error_code 808 krb5_db_delete_policy( krb5_context kcontext, 809 char *policy); 810 811 void 812 krb5_db_free_policy( krb5_context kcontext, 813 osa_policy_ent_t policy); 814 815 816 krb5_error_code 817 krb5_db_set_context(krb5_context, void *db_context); 818 819 krb5_error_code 820 krb5_db_get_context(krb5_context, void **db_context); 821 822 void 823 krb5_dbe_free_key_data_contents(krb5_context, krb5_key_data *); 824 825 void 826 krb5_dbe_free_key_list(krb5_context, krb5_keylist_node *); 827 828 void 829 krb5_dbe_free_actkvno_list(krb5_context, krb5_actkvno_node *); 830 831 void 832 krb5_dbe_free_mkey_aux_list(krb5_context, krb5_mkey_aux_node *); 833 834 void 835 krb5_dbe_free_tl_data(krb5_context, krb5_tl_data *); 836 837 void 838 krb5_dbe_free_strings(krb5_context, krb5_string_attr *, int count); 839 840 void 841 krb5_dbe_free_string(krb5_context, char *); 842 843 /* 844 * Register the KDB keytab type, allowing "KDB:" to be used as a keytab name. 845 * For this type to work, the context used for keytab operations must have an 846 * associated database handle (via krb5_db_open()). 847 */ 848 krb5_error_code krb5_db_register_keytab(krb5_context context); 849 850 #define KRB5_KDB_DEF_FLAGS 0 851 852 #define KDB_MAX_DB_NAME 128 853 #define KDB_REALM_SECTION "realms" 854 #define KDB_MODULE_POINTER "database_module" 855 #define KDB_MODULE_DEF_SECTION "dbdefaults" 856 #define KDB_MODULE_SECTION "dbmodules" 857 #define KDB_LIB_POINTER "db_library" 858 #define KDB_DATABASE_CONF_FILE DEFAULT_SECURE_PROFILE_PATH 859 #define KDB_DATABASE_ENV_PROF KDC_PROFILE_ENV 860 861 #define KRB5_KDB_OPEN_RW 0 862 #define KRB5_KDB_OPEN_RO 1 863 864 #define KRB5_KDB_OPT_SET_DB_NAME 0 865 #define KRB5_KDB_OPT_SET_LOCK_MODE 1 866 867 /* 868 * This number indicates the date of the last incompatible change to the DAL. 869 * The maj_ver field of the module's vtable structure must match this version. 870 */ 871 #define KRB5_KDB_DAL_MAJOR_VERSION 9 872 873 /* 874 * Note the following when converting a module to DAL version 9: 875 * 876 * - get_authdata_info() and sign_authdata() have been removed, and issue_pac() 877 * has been added. 878 * 879 * - check_allowed_to_delegate() must handle a null proxy argument, returning 880 * success if server has any authorized delegation targets in the traditional 881 * scheme. 882 * 883 * - allowed_to_delegate_from() accepts a krb5_pac parameter (in place 884 * server_ad_info) for the impersonator's PAC. 885 * 886 * - check_allowed_to_delegate() and allowed_to_delegate_from() must return 887 * KRB5KDC_ERR_BADOPTION on authorization failure. 888 * 889 * - the KRB5_KDB_FLAG_ISSUE_PAC and KRB5_FLAG_CLIENT_REFERRALS_ONLY flags have 890 * been combined into KRB5_KDB_FLAG_CLIENT. 891 * 892 * - the KRB5_KDB_FLAG_CANONICALIZE flag has been renamed to 893 * KRB5_KDB_FLAG_REFERRAL_OK, and is only passed to get_principal() when a 894 * realm referral is allowed (AS client and TGS server lookups, when the 895 * CANONICALIZE option is requested or, for AS requests, when the client is 896 * an enterprise principal). As of DAL version 8 the KDB module should 897 * always canonicalize aliases within a realm; the KDC will decide whether to 898 * use the original or canonical principal. 899 */ 900 901 /* 902 * A krb5_context can hold one database object. Modules should use 903 * krb5_db_set_context and krb5_db_get_context to store state associated with 904 * the database object. 905 * 906 * Some module functions are mandatory for KDC operation; others are optional 907 * or apply only to administrative operations. If a function is optional, a 908 * module can leave the function pointer as NULL. Alternatively, modules can 909 * return KRB5_PLUGIN_OP_NOTSUPP when asked to perform an inapplicable action. 910 * 911 * Some module functions have default implementations which will call back into 912 * the vtable interface. Leave these functions as NULL to use the default 913 * implementations. 914 * 915 * The documentation in these comments describes the DAL as it is currently 916 * implemented and used, not as it should be. So if anything seems off, that 917 * probably means the current state of things is off. 918 * 919 * Modules must allocate memory for principal entries, policy entries, and 920 * other structures using an allocator compatible with malloc() as seen by 921 * libkdb5 and libkrb5. Modules may link against libkdb5 and call 922 * krb5_db_alloc() to be certain that the same malloc implementation is used. 923 */ 924 925 typedef struct _kdb_vftabl { 926 short int maj_ver; 927 short int min_ver; 928 929 /* 930 * Mandatory: Invoked after the module library is loaded, when the first DB 931 * using the module is opened, across all contexts. 932 */ 933 krb5_error_code (*init_library)(void); 934 935 /* 936 * Mandatory: Invoked before the module library is unloaded, after the last 937 * DB using the module is closed, across all contexts. 938 */ 939 krb5_error_code (*fini_library)(void); 940 941 /* 942 * Mandatory: Initialize a database object. Profile settings should be 943 * read from conf_section inside KDB_MODULE_SECTION. db_args communicates 944 * command-line arguments for module-specific flags. mode will be one of 945 * KRB5_KDB_OPEN_{RW,RO} or'd with one of 946 * KRB5_KDB_SRV_TYPE_{KDC,ADMIN,PASSWD,OTHER}. 947 */ 948 krb5_error_code (*init_module)(krb5_context kcontext, char *conf_section, 949 char **db_args, int mode); 950 951 /* 952 * Mandatory: Finalize the database object contained in a context. Free 953 * any state contained in the db_context pointer and null it out. 954 */ 955 krb5_error_code (*fini_module)(krb5_context kcontext); 956 957 /* 958 * Optional: Initialize a database object while creating the underlying 959 * database. conf_section and db_args have the same meaning as in 960 * init_module. This function may return an error if the database already 961 * exists. Used by kdb5_util create. 962 * 963 * If db_args contains the value "temporary", the module should create an 964 * exclusively locked side copy of the database suitable for loading in a 965 * propagation from primary to replica. This side copy will later be 966 * promoted with promote_db, allowing complete updates of the DB with no 967 * loss in read availability. If the module cannot comply with this 968 * architecture, it should return an error. 969 */ 970 krb5_error_code (*create)(krb5_context kcontext, char *conf_section, 971 char **db_args); 972 973 /* 974 * Optional: Destroy a database. conf_section and db_args have the same 975 * meaning as in init_module. Used by kdb5_util destroy. In current 976 * usage, the database is destroyed while open, so the module should handle 977 * that. 978 */ 979 krb5_error_code (*destroy)(krb5_context kcontext, char *conf_section, 980 char **db_args); 981 982 /* 983 * Deprecated: No longer used as of krb5 1.10; can be removed in the next 984 * DAL revision. Modules should leave as NULL. 985 */ 986 krb5_error_code (*get_age)(krb5_context kcontext, char *db_name, 987 time_t *age); 988 989 /* 990 * Optional: Lock the database, with semantics depending on the mode 991 * argument: 992 * 993 * KRB5_DB_LOCKMODE_SHARED: Lock may coexist with other shared locks. 994 * KRB5_DB_LOCKMODE_EXCLUSIVE: Lock may not coexist with other locks. 995 * KRB5_DB_LOCKMODE_PERMANENT: Exclusive lock surviving process exit. 996 * 997 * Used by the "kadmin lock" command, incremental propagation, and 998 * kdb5_util dump. Incremental propagation support requires shared locks 999 * to operate. kdb5_util dump will continue unlocked if the module returns 1000 * KRB5_PLUGIN_OP_NOTSUPP. 1001 */ 1002 krb5_error_code (*lock)(krb5_context kcontext, int mode); 1003 1004 /* Optional: Release a lock created with db_lock. */ 1005 krb5_error_code (*unlock)(krb5_context kcontext); 1006 1007 /* 1008 * Mandatory: Set *entry to an allocated entry for the principal 1009 * search_for. If the principal is not found, return KRB5_KDB_NOENTRY. 1010 * 1011 * The meaning of flags are as follows: 1012 * 1013 * KRB5_KDB_FLAG_REFERRAL_OK: Set by the KDC when looking up entries for an 1014 * AS client with canonicalization requested or for an enterprise 1015 * principal, or for a TGS request server with canonicalization 1016 * requested. Determines whether the module should return out-of-realm 1017 * referrals. 1018 * 1019 * KRB5_KDB_FLAG_CLIENT: Set by the KDC when looking up a client principal 1020 * during an AS or TGS request. Affects how the module should return 1021 * out-of-realm referrals. 1022 * 1023 * KRB5_KDB_FLAG_MAP_PRINCIPALS: Set by the KDC when looking up the client 1024 * entry during TGS requests, except for S4U TGS requests and requests 1025 * where the server entry has the KRB5_KDB_NO_AUTH_DATA_REQUIRED 1026 * attribute. Indicates that the module should map foreign principals 1027 * to local principals if it supports doing so. 1028 * 1029 * KRB5_KDB_FLAG_PROTOCOL_TRANSITION: Set by the KDC when looking up the 1030 * client entry during an S4U2Self TGS request. This affects the PAC 1031 * information which should be included when authorization data is 1032 * generated; see the Microsoft S4U specification for details. 1033 * 1034 * KRB5_KDB_FLAG_CONSTRAINED_DELEGATION: Set by the KDC when looking up the 1035 * client entry during an S4U2Proxy TGS request. Also affects PAC 1036 * generation. 1037 * 1038 * KRB5_KDB_FLAG_CROSS_REALM: Set by the KDC after looking up a server 1039 * entry during a TGS request, if the header ticket was issued by a 1040 * different realm. 1041 * 1042 * KRB5_KDB_FLAG_ISSUING_REFERRAL: Set by the KDC after looking up a server 1043 * entry during a TGS request, if the requested server principal is not 1044 * part of the realm being served, and a referral or alternate TGT will 1045 * be issued instead. 1046 * 1047 * A module may return an in-realm alias by setting (*entry)->princ to the 1048 * canonical name. The KDC will decide based on the request whether to use 1049 * the requested name or the canonical name in the issued ticket. 1050 * 1051 * A module can return a referral to another realm if flags contains 1052 * KRB5_KDB_FLAG_REFERRAL_OK. If KRB5_KDB_FLAG_CLIENT is also set, the 1053 * module should return a referral by simply filling in an out-of-realm 1054 * name in (*entry)->princ and setting all other fields to NULL. 1055 * Otherwise, the module should return the entry for the cross-realm TGS of 1056 * the referred-to realm. 1057 */ 1058 krb5_error_code (*get_principal)(krb5_context kcontext, 1059 krb5_const_principal search_for, 1060 unsigned int flags, 1061 krb5_db_entry **entry); 1062 1063 /* 1064 * Optional: Create or modify a principal entry. db_args communicates 1065 * command-line arguments for module-specific flags. 1066 * 1067 * The mask field of an entry indicates the changed fields. Mask values 1068 * are defined in kadmin's admin.h header. If KADM5_PRINCIPAL is set in 1069 * the mask, the entry is new; otherwise it already exists. All fields of 1070 * an entry are expected to contain correct values, regardless of whether 1071 * they are specified in the mask, so it is acceptable for a module to 1072 * ignore the mask and update the entire entry. 1073 */ 1074 krb5_error_code (*put_principal)(krb5_context kcontext, 1075 krb5_db_entry *entry, char **db_args); 1076 1077 /* 1078 * Optional: Delete the entry for the principal search_for. If the 1079 * principal did not exist, return KRB5_KDB_NOENTRY. 1080 */ 1081 krb5_error_code (*delete_principal)(krb5_context kcontext, 1082 krb5_const_principal search_for); 1083 1084 /* 1085 * Optional with default: Rename a principal. If the source principal does 1086 * not exist, return KRB5_KDB_NOENTRY. If the target exists, return an 1087 * error. 1088 * 1089 * NOTE: If the module chooses to implement a custom function for renaming 1090 * a principal instead of using the default, then rename operations will 1091 * fail if iprop logging is enabled. 1092 */ 1093 krb5_error_code (*rename_principal)(krb5_context kcontext, 1094 krb5_const_principal source, 1095 krb5_const_principal target); 1096 1097 /* 1098 * Optional: For each principal entry in the database, invoke func with the 1099 * arguments func_arg and the entry data. If match_entry is specified, the 1100 * module may narrow the iteration to principal names matching that regular 1101 * expression; a module may alternatively ignore match_entry. 1102 */ 1103 krb5_error_code (*iterate)(krb5_context kcontext, 1104 char *match_entry, 1105 int (*func)(krb5_pointer, krb5_db_entry *), 1106 krb5_pointer func_arg, krb5_flags iterflags); 1107 1108 /* 1109 * Optional: Create a password policy entry. Return an error if the policy 1110 * already exists. 1111 */ 1112 krb5_error_code (*create_policy)(krb5_context kcontext, 1113 osa_policy_ent_t policy); 1114 1115 /* 1116 * Optional: Set *policy to the policy entry of the specified name. If the 1117 * entry does not exist, return KRB5_KDB_NOENTRY. 1118 */ 1119 krb5_error_code (*get_policy)(krb5_context kcontext, char *name, 1120 osa_policy_ent_t *policy); 1121 1122 /* 1123 * Optional: Modify an existing password policy entry to match the values 1124 * in policy. Return an error if the policy does not already exist. 1125 */ 1126 krb5_error_code (*put_policy)(krb5_context kcontext, 1127 osa_policy_ent_t policy); 1128 1129 /* 1130 * Optional: For each password policy entry in the database, invoke func 1131 * with the arguments data and the entry data. If match_entry is 1132 * specified, the module may narrow the iteration to policy names matching 1133 * that regular expression; a module may alternatively ignore match_entry. 1134 */ 1135 krb5_error_code (*iter_policy)(krb5_context kcontext, char *match_entry, 1136 osa_adb_iter_policy_func func, 1137 void *data); 1138 1139 /* 1140 * Optional: Delete the password policy entry with the name policy. Return 1141 * an error if the entry does not exist. 1142 */ 1143 krb5_error_code (*delete_policy)(krb5_context kcontext, char *policy); 1144 1145 /* 1146 * Optional with default: Retrieve a master keyblock from the stash file 1147 * db_args, filling in *key and *kvno. mname is the name of the master 1148 * principal for the realm. 1149 * 1150 * The default implementation reads the master keyblock from a keytab or 1151 * old-format stash file. 1152 */ 1153 krb5_error_code (*fetch_master_key)(krb5_context kcontext, 1154 krb5_principal mname, 1155 krb5_keyblock *key, krb5_kvno *kvno, 1156 char *db_args); 1157 1158 /* 1159 * Optional with default: Given a keyblock for some version of the 1160 * database's master key, fetch the decrypted master key values from the 1161 * database and store the list into *mkeys_list. The caller will free 1162 * *mkeys_list using a libkdb5 function which uses the standard free() 1163 * function, so the module must not use a custom allocator. 1164 * 1165 * The caller may not know the version number of the master key it has, in 1166 * which case it will pass IGNORE_VNO. 1167 * 1168 * The default implementation ignores kvno and tries the key against the 1169 * current master key data and all KRB5_TL_MKEY_AUX values, which contain 1170 * copies of the master keys encrypted with old master keys. 1171 */ 1172 krb5_error_code (*fetch_master_key_list)(krb5_context kcontext, 1173 krb5_principal mname, 1174 const krb5_keyblock *key, 1175 krb5_keylist_node **mkeys_list); 1176 1177 /* 1178 * Optional with default: Save a list of master keyblocks, obtained from 1179 * fetch_master_key_list, into the stash file db_arg. The caller will set 1180 * master_pwd to NULL, so the module should just ignore it. mname is the 1181 * name of the master principal for the realm. 1182 * 1183 * The default implementation saves the list of master keys in a 1184 * keytab-format file. 1185 */ 1186 krb5_error_code (*store_master_key_list)(krb5_context kcontext, 1187 char *db_arg, 1188 krb5_principal mname, 1189 krb5_keylist_node *keylist, 1190 char *master_pwd); 1191 1192 /* 1193 * Optional with default: Starting at position *start, scan the key data of 1194 * a database entry for a key matching the enctype ktype, the salt type 1195 * stype, and the version kvno. Store the resulting key into *kdatap and 1196 * set *start to the position after the key found. If ktype is negative, 1197 * match any enctype. If stype is negative, match any salt type. If kvno 1198 * is zero or negative, find the most recent key version satisfying the 1199 * other constraints. 1200 */ 1201 krb5_error_code (*dbe_search_enctype)(krb5_context kcontext, 1202 krb5_db_entry *dbentp, 1203 krb5_int32 *start, krb5_int32 ktype, 1204 krb5_int32 stype, krb5_int32 kvno, 1205 krb5_key_data **kdatap); 1206 1207 1208 /* 1209 * Optional with default: Change the key data for db_entry to include keys 1210 * derived from the password passwd in each of the specified key-salt 1211 * types, at version new_kvno. Discard the old key data if keepold is not 1212 * set. 1213 * 1214 * The default implementation uses the keyblock master_key to encrypt each 1215 * new key, via the function encrypt_key_data. 1216 */ 1217 krb5_error_code (*change_pwd)(krb5_context context, 1218 krb5_keyblock *master_key, 1219 krb5_key_salt_tuple *ks_tuple, 1220 int ks_tuple_count, char *passwd, 1221 int new_kvno, krb5_boolean keepold, 1222 krb5_db_entry *db_entry); 1223 1224 /* 1225 * Optional: Promote a temporary database to be the live one. context must 1226 * be initialized with an exclusively locked database created with the 1227 * "temporary" db_arg. On success, the database object contained in 1228 * context will be finalized. 1229 * 1230 * This method is used by kdb5_util load to replace the live database with 1231 * minimal loss of read availability. 1232 */ 1233 krb5_error_code (*promote_db)(krb5_context context, char *conf_section, 1234 char **db_args); 1235 1236 /* 1237 * Optional with default: Decrypt the key in key_data with master keyblock 1238 * mkey, placing the result into dbkey. Copy the salt from key_data, if 1239 * any, into keysalt. Either dbkey or keysalt may be left unmodified on 1240 * successful return if key_data does not contain key or salt information. 1241 * 1242 * The default implementation expects the encrypted key (in krb5_c_encrypt 1243 * format) to be stored in key_data_contents[0], with length given by 1244 * key_data_length[0]. If key_data_ver is 2, it expects the salt to be 1245 * stored, unencrypted, in key_data_contents[1], with length given by 1246 * key_data_length[1]. 1247 */ 1248 krb5_error_code (*decrypt_key_data)(krb5_context kcontext, 1249 const krb5_keyblock *mkey, 1250 const krb5_key_data *key_data, 1251 krb5_keyblock *dbkey, 1252 krb5_keysalt *keysalt); 1253 1254 /* 1255 * Optional with default: Encrypt dbkey with master keyblock mkey, placing 1256 * the result into key_data along with keysalt. 1257 * 1258 * The default implementation stores the encrypted key (in krb5_c_encrypt 1259 * format) in key_data_contents[0] and the length in key_data_length[0]. 1260 * If keysalt is specified, it sets key_data_ver to 2, and stores the salt 1261 * in key_data_contents[1] and its length in key_data_length[1]. If 1262 * keysalt is not specified, key_data_ver is set to 1. 1263 */ 1264 krb5_error_code (*encrypt_key_data)(krb5_context kcontext, 1265 const krb5_keyblock *mkey, 1266 const krb5_keyblock *dbkey, 1267 const krb5_keysalt *keysalt, 1268 int keyver, krb5_key_data *key_data); 1269 1270 /* 1271 * Optional: Perform a policy check on a cross-realm ticket's transited 1272 * field. Return 0 if the check authoritatively succeeds, 1273 * KRB5_PLUGIN_NO_HANDLE to use the core transited-checking mechanisms, or 1274 * another error (other than KRB5_PLUGIN_OP_NOTSUPP) if the check fails. 1275 */ 1276 krb5_error_code (*check_transited_realms)(krb5_context kcontext, 1277 const krb5_data *tr_contents, 1278 const krb5_data *client_realm, 1279 const krb5_data *server_realm); 1280 1281 /* 1282 * Optional: Perform a policy check on an AS request, in addition to the 1283 * standard policy checks. Return 0 if the AS request is allowed. If the 1284 * AS request is not allowed: 1285 * - Place a short string literal into *status. 1286 * - If desired, place data into e_data. Any data placed here will be 1287 * freed by the caller using the standard free function. 1288 * - Return an appropriate error (such as KRB5KDC_ERR_POLICY). 1289 */ 1290 krb5_error_code (*check_policy_as)(krb5_context kcontext, 1291 krb5_kdc_req *request, 1292 krb5_db_entry *client, 1293 krb5_db_entry *server, 1294 krb5_timestamp kdc_time, 1295 const char **status, 1296 krb5_pa_data ***e_data); 1297 1298 /* 1299 * Optional: Perform a policy check on a TGS request, in addition to the 1300 * standard policy checks. Return 0 if the TGS request is allowed. If the 1301 * TGS request is not allowed: 1302 * - Place a short string literal into *status. 1303 * - If desired, place data into e_data. Any data placed here will be 1304 * freed by the caller using the standard free function. 1305 * - Return an appropriate error (such as KRB5KDC_ERR_POLICY). 1306 * The input parameter ticket contains the TGT used in the TGS request. 1307 */ 1308 krb5_error_code (*check_policy_tgs)(krb5_context kcontext, 1309 krb5_kdc_req *request, 1310 krb5_db_entry *server, 1311 krb5_ticket *ticket, 1312 const char **status, 1313 krb5_pa_data ***e_data); 1314 1315 /* 1316 * Optional: This method informs the module of a successful or unsuccessful 1317 * AS request. 1318 */ 1319 void (*audit_as_req)(krb5_context kcontext, krb5_kdc_req *request, 1320 const krb5_address *local_addr, 1321 const krb5_address *remote_addr, 1322 krb5_db_entry *client, krb5_db_entry *server, 1323 krb5_timestamp authtime, krb5_error_code error_code); 1324 1325 /* Note: there is currently no method for auditing TGS requests. */ 1326 1327 /* 1328 * Optional: This method informs the module of a request to reload 1329 * configuration or other state (that is, the KDC received a SIGHUP). 1330 */ 1331 void (*refresh_config)(krb5_context kcontext); 1332 1333 /* 1334 * Optional: Perform a policy check on server being allowed to obtain 1335 * tickets from client to proxy. If proxy is NULL, check if server has any 1336 * authorized delegation targets (client will also be NULL in this case). 1337 * (Note that proxy is the target of the delegation, not the delegating 1338 * service; the term "proxy" is from the viewpoint of the delegating 1339 * service asking another service to perform some of its work in the 1340 * authentication context of the client. This terminology comes from the 1341 * Microsoft S4U protocol documentation.) Return 0 if policy allows 1342 * delegation to the specified target (or to any target if proxy is NULL), 1343 * or KRB5KDC_ERR_BADOPTION if not. If this method is not implemented, all 1344 * S4U2Proxy delegation requests will be rejected. 1345 */ 1346 krb5_error_code (*check_allowed_to_delegate)(krb5_context context, 1347 krb5_const_principal client, 1348 const krb5_db_entry *server, 1349 krb5_const_principal proxy); 1350 1351 /* 1352 * Optional: Free the e_data pointer of a database entry. If this method 1353 * is not implemented, the e_data pointer in principal entries will be 1354 * freed with free() as seen by libkdb5. 1355 */ 1356 void (*free_principal_e_data)(krb5_context kcontext, krb5_octet *e_data); 1357 1358 /* 1359 * Optional: get a client principal entry based on an X.509 certificate. 1360 * 1361 * If flags include KRB5_KDB_FLAG_REFERRAL_OK, the certificate was 1362 * presented in an AS request. princ->realm indicates the request realm, 1363 * but the data components should be ignored. The module can return an 1364 * out-of-realm client referral as it would for get_principal(). 1365 * 1366 * Otherwise, princ is from a TGS request. If it contains data components 1367 * (and not just a realm), the module should verify that it is the same as 1368 * the lookup result for client_cert. The module should not return a 1369 * referral. 1370 */ 1371 krb5_error_code (*get_s4u_x509_principal)(krb5_context kcontext, 1372 const krb5_data *client_cert, 1373 krb5_const_principal princ, 1374 unsigned int flags, 1375 krb5_db_entry **entry_out); 1376 1377 /* 1378 * Optional: Perform a policy check on server being allowed to obtain 1379 * tickets from client to proxy. This method is similar to 1380 * check_allowed_to_delegate, but it operates on the target server DB entry 1381 * (called "proxy" here as in Microsoft's protocol documentation) rather 1382 * than the intermediate server entry. server_pac is the verified PAC from 1383 * the authdata of the intermediate server. Return 0 if policy allows the 1384 * delegation, or KRB5KDC_ERR_BADOPTION if not. 1385 * 1386 * This method is called for S4U2Proxy requests and implements the 1387 * resource-based constrained delegation variant, which can support 1388 * cross-realm delegation. If this method is not implemented or if it 1389 * returns a policy error, the KDC will fall back to 1390 * check_allowed_to_delegate if the intermediate and target servers are in 1391 * the same realm and the evidence ticket is forwardable. 1392 */ 1393 krb5_error_code (*allowed_to_delegate_from)(krb5_context context, 1394 krb5_const_principal client, 1395 krb5_const_principal server, 1396 krb5_pac server_pac, 1397 const krb5_db_entry *proxy); 1398 1399 /* 1400 * Optional: Add buffers to new_pac using krb5_pac_add_buffer() before it 1401 * is signed. 1402 * 1403 * The caller will handle the following buffer types, so do not copy or add 1404 * them: 1405 * 1406 * KRB5_PAC_SERVER_CHECKSUM 1407 * KRB5_PAC_PRIVSVR_CHECKSUM 1408 * KRB5_PAC_TICKET_CHECKSUM 1409 * KRB5_PAC_CLIENT_INFO 1410 * KRB5_PAC_DELEGATION_INFO 1411 * 1412 * For TGS requests, old_pac is the PAC of the header ticket, except when 1413 * KRB5_KDB_FLAG_CONTRAINED_DELEGATION is present in flags, in which case 1414 * it is the PAC of the second ticket. If 1415 * KRB5_KDB_FLAG_PROTOCOL_TRANSITION is present in flags and client is not 1416 * NULL, old_pac is the PAC of the requesting service, not the subject of 1417 * the S4U2Self request, and its buffers should not be copied into new_pac. 1418 * The signatures and PAC_CLIENT_INFO of old_pac have been verified by the 1419 * caller. 1420 * 1421 * If replaced_reply_key is not null, the request is an AS request and the 1422 * reply key was replaced by a preauth mechanism such as PKINIT, meaning 1423 * the Kerberos password or long-term key was not used. The module may use 1424 * this key to encrypt a PAC_CREDENTIALS_INFO buffer containing credentials 1425 * (such as an NTLM hash) that the client would ordinarily derive from the 1426 * Kerberos password or long-term key. 1427 * 1428 * server is the database entry of the server the ticket will be issued to, 1429 * which may be a referral TGS. 1430 * 1431 * signing_krbtgt is the database entry of the krbtgt principal used to 1432 * verify old_pac (or null if old_pac is null). If 1433 * KRB5_KDB_FLAG_CROSS_REALM is present in flags, this entry will be an 1434 * incoming cross-realm TGS, and the PAC fields should undergo appropriate 1435 * filtering based on the trust level of the cross-realm relationship. 1436 * 1437 * auth_indicators points to NULL or a null-terminated list of krb5_data 1438 * pointers, each containing an authentication indicator (RFC 8129). The 1439 * method may modify this list, or free it and replace *auth_indicators 1440 * with NULL, to change which auth indicators will be included in the 1441 * ticket. 1442 */ 1443 krb5_error_code (*issue_pac)(krb5_context context, unsigned int flags, 1444 krb5_db_entry *client, 1445 krb5_keyblock *replaced_reply_key, 1446 krb5_db_entry *server, 1447 krb5_db_entry *signing_krbtgt, 1448 krb5_timestamp authtime, krb5_pac old_pac, 1449 krb5_pac new_pac, 1450 krb5_data ***auth_indicators); 1451 1452 /* End of minor version 0 for major version 9. */ 1453 } kdb_vftabl; 1454 1455 #endif /* !defined(_WIN32) */ 1456 1457 #endif /* KRB5_KDB5__ */ 1458