src/include/kdb.h

   1 /* -*- mode: c; c-basic-offset: 4; indent-tabs-mode: nil -*- */
   2 /*
   3  * Copyright 1990,1991 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 6
  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
 102 /* Creation flags */
 103 #define KRB5_KDB_CREATE_BTREE           0x00000001
 104 #define KRB5_KDB_CREATE_HASH            0x00000002
 105
 106 /* Private flag used to indicate principal is local TGS */
 107 #define KRB5_KDB_TICKET_GRANTING_SERVICE        0x01000000
 108 /* Private flag used to indicate xrealm relationship  is non-transitive */
 109 #define KRB5_KDB_XREALM_NON_TRANSITIVE          0x02000000
 110
 111 /* Entry get flags */
 112 /* Name canonicalization requested */
 113 #define KRB5_KDB_FLAG_CANONICALIZE              0x00000010
 114 /* Include authorization data generated by backend */
 115 #define KRB5_KDB_FLAG_INCLUDE_PAC               0x00000020
 116 /* Is AS-REQ (client referrals only) */
 117 #define KRB5_KDB_FLAG_CLIENT_REFERRALS_ONLY     0x00000040
 118 /* Map cross-realm principals */
 119 #define KRB5_KDB_FLAG_MAP_PRINCIPALS            0x00000080
 120 /* Protocol transition */
 121 #define KRB5_KDB_FLAG_PROTOCOL_TRANSITION       0x00000100
 122 /* Constrained delegation */
 123 #define KRB5_KDB_FLAG_CONSTRAINED_DELEGATION    0x00000200
 124 /* User-to-user */
 125 #define KRB5_KDB_FLAG_USER_TO_USER              0x00000800
 126 /* Cross-realm */
 127 #define KRB5_KDB_FLAG_CROSS_REALM               0x00001000
 128 /* Allow in-realm aliases */
 129 #define KRB5_KDB_FLAG_ALIAS_OK                  0x00002000
 130
 131 #define KRB5_KDB_FLAGS_S4U                      ( KRB5_KDB_FLAG_PROTOCOL_TRANSITION | \
 132                                                   KRB5_KDB_FLAG_CONSTRAINED_DELEGATION )
 133
 134 #if !defined(_WIN32)
 135
 136 /*
 137  * Note --- these structures cannot be modified without changing the
 138  * database version number in libkdb.a, but should be expandable by
 139  * adding new tl_data types.
 140  */
 141 typedef struct _krb5_tl_data {
 142     struct _krb5_tl_data* tl_data_next;         /* NOT saved */
 143     krb5_int16            tl_data_type;
 144     krb5_ui_2             tl_data_length;
 145     krb5_octet          * tl_data_contents;
 146 } krb5_tl_data;
 147
 148 /* String attributes (currently stored inside tl-data) map C string keys to
 149  * values.  They can be set via kadmin and consumed by KDC plugins. */
 150 typedef struct krb5_string_attr_st {
 151     char *key;
 152     char *value;
 153 } krb5_string_attr;
 154
 155 /*
 156  * If this ever changes up the version number and make the arrays be as
 157  * big as necessary.
 158  *
 159  * Currently the first type is the enctype and the second is the salt type.
 160  */
 161 typedef struct _krb5_key_data {
 162     krb5_int16            key_data_ver;         /* Version */
 163     krb5_int16            key_data_kvno;        /* Key Version */
 164     krb5_int16            key_data_type[2];     /* Array of types */
 165     krb5_ui_2             key_data_length[2];   /* Array of lengths */
 166     krb5_octet          * key_data_contents[2]; /* Array of pointers */
 167 } krb5_key_data;
 168
 169 #define KRB5_KDB_V1_KEY_DATA_ARRAY      2       /* # of array elements */
 170
 171 typedef struct _krb5_keysalt {
 172     krb5_int16            type;
 173     krb5_data             data;                 /* Length, data */
 174 } krb5_keysalt;
 175
 176 /*
 177  * A principal database entry.  Extensions to this structure currently use the
 178  * tl_data list.  The e_data and e_length fields are not used by any calling
 179  * code except kdb5_util dump and load, which marshal and unmarshal the array
 180  * in the dump record.  KDB modules may use these fields internally as long as
 181  * they set e_length appropriately (non-zero if the data should be marshalled
 182  * across dump and load, zero if not) and handle null e_data values in
 183  * caller-constructed principal entries.
 184  */
 185 typedef struct _krb5_db_entry_new {
 186     krb5_magic            magic;                /* NOT saved */
 187     krb5_ui_2             len;
 188     krb5_ui_4             mask;                 /* members currently changed/set */
 189     krb5_flags            attributes;
 190     krb5_deltat           max_life;
 191     krb5_deltat           max_renewable_life;
 192     krb5_timestamp        expiration;           /* When the client expires */
 193     krb5_timestamp        pw_expiration;        /* When its passwd expires */
 194     krb5_timestamp        last_success;         /* Last successful passwd */
 195     krb5_timestamp        last_failed;          /* Last failed passwd attempt */
 196     krb5_kvno             fail_auth_count;      /* # of failed passwd attempt */
 197     krb5_int16            n_tl_data;
 198     krb5_int16            n_key_data;
 199     krb5_ui_2             e_length;             /* Length of extra data */
 200     krb5_octet          * e_data;               /* Extra data to be saved */
 201
 202     krb5_principal        princ;                /* Length, data */
 203     krb5_tl_data        * tl_data;              /* Linked list */
 204     krb5_key_data       * key_data;             /* Array */
 205 } krb5_db_entry;
 206
 207 typedef struct _osa_policy_ent_t {
 208     int               version;
 209     char      *name;
 210     krb5_ui_4       pw_min_life;
 211     krb5_ui_4       pw_max_life;
 212     krb5_ui_4       pw_min_length;
 213     krb5_ui_4       pw_min_classes;
 214     krb5_ui_4       pw_history_num;
 215     krb5_ui_4       policy_refcnt;
 216     /* Only valid if version > 1 */
 217     krb5_ui_4       pw_max_fail;                /* pwdMaxFailure */
 218     krb5_ui_4       pw_failcnt_interval;        /* pwdFailureCountInterval */
 219     krb5_ui_4       pw_lockout_duration;        /* pwdLockoutDuration */
 220 } osa_policy_ent_rec, *osa_policy_ent_t;
 221
 222 typedef       void    (*osa_adb_iter_policy_func) (void *, osa_policy_ent_t);
 223
 224 typedef struct __krb5_key_salt_tuple {
 225     krb5_enctype        ks_enctype;
 226     krb5_int32          ks_salttype;
 227 } krb5_key_salt_tuple;
 228
 229 #define KRB5_KDB_MAGIC_NUMBER           0xdbdbdbdb
 230 #define KRB5_KDB_V1_BASE_LENGTH         38
 231
 232 #define KRB5_TL_LAST_PWD_CHANGE         0x0001
 233 #define KRB5_TL_MOD_PRINC               0x0002
 234 #define KRB5_TL_KADM_DATA               0x0003
 235 #define KRB5_TL_KADM5_E_DATA            0x0004
 236 #define KRB5_TL_RB1_CHALLENGE           0x0005
 237 #ifdef SECURID
 238 #define KRB5_TL_SECURID_STATE           0x0006
 239 #endif /* SECURID */
 240 #define KRB5_TL_USER_CERTIFICATE        0x0007
 241 #define KRB5_TL_MKVNO                   0x0008
 242 #define KRB5_TL_ACTKVNO                 0x0009
 243 #define KRB5_TL_MKEY_AUX                0x000a
 244
 245 /* String attributes may not always be represented in tl-data.  kadmin clients
 246  * must use the get_strings and set_string RPCs. */
 247 #define KRB5_TL_STRING_ATTRS            0x000b
 248
 249 #define KRB5_TL_PAC_LOGON_INFO          0x0100 /* NDR encoded validation info */
 250 #define KRB5_TL_SERVER_REFERRAL         0x0200 /* ASN.1 encoded ServerReferralInfo */
 251 #define KRB5_TL_SVR_REFERRAL_DATA       0x0300 /* ASN.1 encoded PA-SVR-REFERRAL-DATA */
 252 #define KRB5_TL_CONSTRAINED_DELEGATION_ACL 0x0400 /* Each entry is a permitted SPN */
 253 #define KRB5_TL_LM_KEY                  0x0500 /* LM OWF */
 254 #define KRB5_TL_X509_SUBJECT_ISSUER_NAME 0x0600 /* <I>IssuerDN<S>SubjectDN */
 255 #define KRB5_TL_LAST_ADMIN_UNLOCK       0x0700 /* Timestamp of admin unlock */
 256
 257 #define KRB5_TL_DB_ARGS                 0x7fff
 258
 259 /* version number for KRB5_TL_ACTKVNO data */
 260 #define KRB5_TL_ACTKVNO_VER     1
 261
 262 /* version number for KRB5_TL_MKEY_AUX data */
 263 #define KRB5_TL_MKEY_AUX_VER    1
 264
 265 typedef struct _krb5_actkvno_node {
 266     struct _krb5_actkvno_node *next;
 267     krb5_kvno      act_kvno;
 268     krb5_timestamp act_time;
 269 } krb5_actkvno_node;
 270
 271 typedef struct _krb5_mkey_aux_node {
 272     struct _krb5_mkey_aux_node *next;
 273     krb5_kvno        mkey_kvno; /* kvno of mkey protecting the latest_mkey */
 274     krb5_key_data    latest_mkey; /* most recent mkey */
 275 } krb5_mkey_aux_node;
 276
 277 typedef struct _krb5_keylist_node {
 278     krb5_keyblock keyblock;
 279     krb5_kvno     kvno;
 280     struct _krb5_keylist_node *next;
 281 } krb5_keylist_node;
 282
 283 /*
 284  * Determines the number of failed KDC requests before DISALLOW_ALL_TIX is set
 285  * on the principal.
 286  */
 287 #define KRB5_MAX_FAIL_COUNT             5
 288
 289 /* XXX depends on knowledge of krb5_parse_name() formats */
 290 #define KRB5_KDB_M_NAME         "K/M"   /* Kerberos/Master */
 291
 292 /* prompts used by default when reading the KDC password from the keyboard. */
 293 #define KRB5_KDC_MKEY_1 "Enter KDC database master key"
 294 #define KRB5_KDC_MKEY_2 "Re-enter KDC database master key to verify"
 295
 296
 297 extern char *krb5_mkey_pwd_prompt1;
 298 extern char *krb5_mkey_pwd_prompt2;
 299
 300 /*
 301  * These macros specify the encoding of data within the database.
 302  *
 303  * Data encoding is little-endian.
 304  */
 305 #ifdef _KRB5_INT_H
 306 #include "k5-platform.h"
 307 #define krb5_kdb_decode_int16(cp, i16)          \
 308     *((krb5_int16 *) &(i16)) = load_16_le(cp)
 309 #define krb5_kdb_decode_int32(cp, i32)          \
 310     *((krb5_int32 *) &(i32)) = load_32_le(cp)
 311 #define krb5_kdb_encode_int16(i16, cp)  store_16_le(i16, cp)
 312 #define krb5_kdb_encode_int32(i32, cp)  store_32_le(i32, cp)
 313 #endif /* _KRB5_INT_H */
 314
 315 #define KRB5_KDB_OPEN_RW                0
 316 #define KRB5_KDB_OPEN_RO                1
 317
 318 #ifndef KRB5_KDB_SRV_TYPE_KDC
 319 #define KRB5_KDB_SRV_TYPE_KDC           0x0100
 320 #endif
 321
 322 #ifndef KRB5_KDB_SRV_TYPE_ADMIN
 323 #define KRB5_KDB_SRV_TYPE_ADMIN         0x0200
 324 #endif
 325
 326 #ifndef KRB5_KDB_SRV_TYPE_PASSWD
 327 #define KRB5_KDB_SRV_TYPE_PASSWD        0x0300
 328 #endif
 329
 330 #ifndef KRB5_KDB_SRV_TYPE_OTHER
 331 #define KRB5_KDB_SRV_TYPE_OTHER         0x0400
 332 #endif
 333
 334 #define KRB5_KDB_OPT_SET_DB_NAME        0
 335 #define KRB5_KDB_OPT_SET_LOCK_MODE      1
 336
 337 #define KRB5_DB_LOCKMODE_SHARED       0x0001
 338 #define KRB5_DB_LOCKMODE_EXCLUSIVE    0x0002
 339 #define KRB5_DB_LOCKMODE_DONTBLOCK    0x0004
 340 #define KRB5_DB_LOCKMODE_PERMANENT    0x0008
 341
 342 /* libkdb.spec */
 343 krb5_error_code krb5_db_setup_lib_handle(krb5_context kcontext);
 344 krb5_error_code krb5_db_open( krb5_context kcontext, char **db_args, int mode );
 345 krb5_error_code krb5_db_init  ( krb5_context kcontext );
 346 krb5_error_code krb5_db_create ( krb5_context kcontext, char **db_args );
 347 krb5_error_code krb5_db_inited  ( krb5_context kcontext );
 348 krb5_error_code kdb5_db_create ( krb5_context kcontext, char **db_args );
 349 krb5_error_code krb5_db_fini ( krb5_context kcontext );
 350 const char * krb5_db_errcode2string ( krb5_context kcontext, long err_code );
 351 krb5_error_code krb5_db_destroy ( krb5_context kcontext, char **db_args );
 352 krb5_error_code krb5_db_promote ( krb5_context kcontext, char **db_args );
 353 krb5_error_code krb5_db_get_age ( krb5_context kcontext, char *db_name, time_t *t );
 354 krb5_error_code krb5_db_lock ( krb5_context kcontext, int lock_mode );
 355 krb5_error_code krb5_db_unlock ( krb5_context kcontext );
 356 krb5_error_code krb5_db_get_principal ( krb5_context kcontext,
 357                                         krb5_const_principal search_for,
 358                                         unsigned int flags,
 359                                         krb5_db_entry **entry );
 360 void krb5_db_free_principal ( krb5_context kcontext, krb5_db_entry *entry );
 361 krb5_error_code krb5_db_put_principal ( krb5_context kcontext,
 362                                         krb5_db_entry *entry );
 363 krb5_error_code krb5_db_delete_principal ( krb5_context kcontext,
 364                                            krb5_principal search_for );
 365 krb5_error_code krb5_db_iterate ( krb5_context kcontext,
 366                                   char *match_entry,
 367                                   int (*func) (krb5_pointer, krb5_db_entry *),
 368                                   krb5_pointer func_arg );
 369
 370
 371 krb5_error_code krb5_db_store_master_key  ( krb5_context kcontext,
 372                                             char *keyfile,
 373                                             krb5_principal mname,
 374                                             krb5_kvno kvno,
 375                                             krb5_keyblock *key,
 376                                             char *master_pwd);
 377 krb5_error_code krb5_db_store_master_key_list  ( krb5_context kcontext,
 378                                                  char *keyfile,
 379                                                  krb5_principal mname,
 380                                                  char *master_pwd);
 381 krb5_error_code krb5_db_fetch_mkey  ( krb5_context   context,
 382                                       krb5_principal mname,
 383                                       krb5_enctype   etype,
 384                                       krb5_boolean   fromkeyboard,
 385                                       krb5_boolean   twice,
 386                                       char          *db_args,
 387                                       krb5_kvno     *kvno,
 388                                       krb5_data     *salt,
 389                                       krb5_keyblock *key);
 390 krb5_error_code
 391 krb5_db_fetch_mkey_list( krb5_context    context,
 392                          krb5_principal  mname,
 393                          const krb5_keyblock * mkey );
 394
 395 krb5_error_code
 396 krb5_dbe_find_enctype( krb5_context     kcontext,
 397                        krb5_db_entry    *dbentp,
 398                        krb5_int32               ktype,
 399                        krb5_int32               stype,
 400                        krb5_int32               kvno,
 401                        krb5_key_data    **kdatap);
 402
 403
 404 krb5_error_code krb5_dbe_search_enctype ( krb5_context kcontext,
 405                                           krb5_db_entry *dbentp,
 406                                           krb5_int32 *start,
 407                                           krb5_int32 ktype,
 408                                           krb5_int32 stype,
 409                                           krb5_int32 kvno,
 410                                           krb5_key_data **kdatap);
 411
 412 krb5_error_code
 413 krb5_db_setup_mkey_name ( krb5_context context,
 414                           const char *keyname,
 415                           const char *realm,
 416                           char **fullname,
 417                           krb5_principal *principal);
 418
 419 /**
 420  * Decrypts the key given in @@a key_data. If @a mkey is specified, that
 421  * master key is used. If @a mkey is NULL, then all master keys are tried.
 422  */
 423 krb5_error_code
 424 krb5_dbe_decrypt_key_data( krb5_context         context,
 425                            const krb5_keyblock        * mkey,
 426                            const krb5_key_data        * key_data,
 427                            krb5_keyblock      * dbkey,
 428                            krb5_keysalt       * keysalt);
 429
 430 krb5_error_code
 431 krb5_dbe_encrypt_key_data( krb5_context                 context,
 432                            const krb5_keyblock        * mkey,
 433                            const krb5_keyblock        * dbkey,
 434                            const krb5_keysalt         * keysalt,
 435                            int                          keyver,
 436                            krb5_key_data              * key_data);
 437
 438 krb5_error_code
 439 krb5_dbe_fetch_act_key_list(krb5_context          context,
 440                             krb5_principal       princ,
 441                             krb5_actkvno_node  **act_key_list);
 442
 443 krb5_error_code
 444 krb5_dbe_find_act_mkey( krb5_context          context,
 445                         krb5_actkvno_node   * act_mkey_list,
 446                         krb5_kvno           * act_kvno,
 447                         krb5_keyblock      ** act_mkey);
 448
 449 krb5_error_code
 450 krb5_dbe_find_mkey( krb5_context         context,
 451                     krb5_db_entry      * entry,
 452                     krb5_keyblock      ** mkey);
 453
 454 /* Set *mkvno to mkvno in entry tl_data, or 0 if not present. */
 455 krb5_error_code
 456 krb5_dbe_lookup_mkvno( krb5_context    context,
 457                        krb5_db_entry * entry,
 458                        krb5_kvno     * mkvno);
 459
 460 krb5_keylist_node *
 461 krb5_db_mkey_list_alias( krb5_context kcontext );
 462
 463 /* Set *mkvno to mkvno in entry tl_data, or minimum value from mkey_list. */
 464 krb5_error_code
 465 krb5_dbe_get_mkvno( krb5_context        context,
 466                     krb5_db_entry     * entry,
 467                     krb5_kvno         * mkvno);
 468
 469 krb5_error_code
 470 krb5_dbe_lookup_mod_princ_data( krb5_context          context,
 471                                 krb5_db_entry       * entry,
 472                                 krb5_timestamp      * mod_time,
 473                                 krb5_principal      * mod_princ);
 474
 475 krb5_error_code
 476 krb5_dbe_lookup_mkey_aux( krb5_context         context,
 477                           krb5_db_entry      * entry,
 478                           krb5_mkey_aux_node ** mkey_aux_data_list);
 479 krb5_error_code
 480 krb5_dbe_update_mkvno( krb5_context    context,
 481                        krb5_db_entry * entry,
 482                        krb5_kvno       mkvno);
 483
 484 krb5_error_code
 485 krb5_dbe_lookup_actkvno( krb5_context         context,
 486                          krb5_db_entry      * entry,
 487                          krb5_actkvno_node ** actkvno_list);
 488
 489 krb5_error_code
 490 krb5_dbe_update_mkey_aux( krb5_context          context,
 491                           krb5_db_entry       * entry,
 492                           krb5_mkey_aux_node  * mkey_aux_data_list);
 493
 494 krb5_error_code
 495 krb5_dbe_update_actkvno(krb5_context    context,
 496                         krb5_db_entry * entry,
 497                         const krb5_actkvno_node *actkvno_list);
 498
 499 krb5_error_code
 500 krb5_dbe_update_last_pwd_change( krb5_context     context,
 501                                  krb5_db_entry  * entry,
 502                                  krb5_timestamp   stamp);
 503
 504 krb5_error_code
 505 krb5_dbe_update_last_admin_unlock( krb5_context     context,
 506                                    krb5_db_entry  * entry,
 507                                    krb5_timestamp   stamp);
 508
 509 krb5_error_code
 510 krb5_dbe_lookup_tl_data( krb5_context          context,
 511                          krb5_db_entry       * entry,
 512                          krb5_tl_data        * ret_tl_data);
 513
 514 krb5_error_code
 515 krb5_dbe_create_key_data( krb5_context          context,
 516                           krb5_db_entry       * entry);
 517
 518
 519 krb5_error_code
 520 krb5_dbe_update_mod_princ_data( krb5_context          context,
 521                                 krb5_db_entry       * entry,
 522                                 krb5_timestamp        mod_date,
 523                                 krb5_const_principal  mod_princ);
 524
 525 void *krb5_db_alloc( krb5_context kcontext,
 526                      void *ptr,
 527                      size_t size );
 528
 529 void krb5_db_free( krb5_context kcontext,
 530                    void *ptr);
 531
 532
 533 krb5_error_code
 534 krb5_dbe_lookup_last_pwd_change( krb5_context          context,
 535                                  krb5_db_entry       * entry,
 536                                  krb5_timestamp      * stamp);
 537
 538 krb5_error_code
 539 krb5_dbe_lookup_last_admin_unlock( krb5_context          context,
 540                                    krb5_db_entry       * entry,
 541                                    krb5_timestamp      * stamp);
 542
 543 /* Retrieve the set of string attributes in entry, in no particular order.
 544  * Free *strings_out with krb5_dbe_free_strings when done. */
 545 krb5_error_code
 546 krb5_dbe_get_strings(krb5_context context, krb5_db_entry *entry,
 547                      krb5_string_attr **strings_out, int *count_out);
 548
 549 /* Retrieve a single string attribute from entry, or NULL if there is no
 550  * attribute for key.  Free *value_out with krb5_dbe_free_string when done. */
 551 krb5_error_code
 552 krb5_dbe_get_string(krb5_context context, krb5_db_entry *entry,
 553                     const char *key, char **value_out);
 554
 555 /* Change or add a string attribute in entry, or delete it if value is NULL. */
 556 krb5_error_code
 557 krb5_dbe_set_string(krb5_context context, krb5_db_entry *entry,
 558                     const char *key, const char *value);
 559
 560 krb5_error_code
 561 krb5_dbe_delete_tl_data( krb5_context    context,
 562                          krb5_db_entry * entry,
 563                          krb5_int16      tl_data_type);
 564
 565 krb5_error_code
 566 krb5_dbe_update_tl_data( krb5_context          context,
 567                          krb5_db_entry       * entry,
 568                          krb5_tl_data        * new_tl_data);
 569
 570 /* Compute the salt for a key data entry given the corresponding principal. */
 571 krb5_error_code
 572 krb5_dbe_compute_salt(krb5_context context, const krb5_key_data *key,
 573                       krb5_const_principal princ, krb5_int16 *salttype_out,
 574                       krb5_data **salt_out);
 575
 576 krb5_error_code
 577 krb5_dbe_cpw( krb5_context        kcontext,
 578               krb5_keyblock       * master_key,
 579               krb5_key_salt_tuple       * ks_tuple,
 580               int                         ks_tuple_count,
 581               char              * passwd,
 582               int                         new_kvno,
 583               krb5_boolean        keepold,
 584               krb5_db_entry     * db_entry);
 585
 586
 587 krb5_error_code
 588 krb5_dbe_ark( krb5_context        context,
 589               krb5_keyblock       * master_key,
 590               krb5_key_salt_tuple       * ks_tuple,
 591               int                         ks_tuple_count,
 592               krb5_db_entry     * db_entry);
 593
 594 krb5_error_code
 595 krb5_dbe_crk( krb5_context        context,
 596               krb5_keyblock       * master_key,
 597               krb5_key_salt_tuple       * ks_tuple,
 598               int                         ks_tuple_count,
 599               krb5_boolean        keepold,
 600               krb5_db_entry     * db_entry);
 601
 602 krb5_error_code
 603 krb5_dbe_apw( krb5_context        context,
 604               krb5_keyblock       * master_key,
 605               krb5_key_salt_tuple       * ks_tuple,
 606               int                         ks_tuple_count,
 607               char              * passwd,
 608               krb5_db_entry     * db_entry);
 609
 610 int
 611 krb5_db_get_key_data_kvno( krb5_context    context,
 612                            int             count,
 613                            krb5_key_data * data);
 614
 615 krb5_error_code krb5_db_sign_authdata(krb5_context kcontext,
 616                                       unsigned int flags,
 617                                       krb5_const_principal client_princ,
 618                                       krb5_db_entry *client,
 619                                       krb5_db_entry *server,
 620                                       krb5_db_entry *krbtgt,
 621                                       krb5_keyblock *client_key,
 622                                       krb5_keyblock *server_key,
 623                                       krb5_keyblock *krbtgt_key,
 624                                       krb5_keyblock *session_key,
 625                                       krb5_timestamp authtime,
 626                                       krb5_authdata **tgt_auth_data,
 627                                       krb5_authdata ***signed_auth_data);
 628
 629 krb5_error_code krb5_db_check_transited_realms(krb5_context kcontext,
 630                                                const krb5_data *tr_contents,
 631                                                const krb5_data *client_realm,
 632                                                const krb5_data *server_realm);
 633
 634 krb5_error_code krb5_db_check_policy_as(krb5_context kcontext,
 635                                         krb5_kdc_req *request,
 636                                         krb5_db_entry *client,
 637                                         krb5_db_entry *server,
 638                                         krb5_timestamp kdc_time,
 639                                         const char **status,
 640                                         krb5_pa_data ***e_data);
 641
 642 krb5_error_code krb5_db_check_policy_tgs(krb5_context kcontext,
 643                                          krb5_kdc_req *request,
 644                                          krb5_db_entry *server,
 645                                          krb5_ticket *ticket,
 646                                          const char **status,
 647                                          krb5_pa_data ***e_data);
 648
 649 void krb5_db_audit_as_req(krb5_context kcontext, krb5_kdc_req *request,
 650                           krb5_db_entry *client, krb5_db_entry *server,
 651                           krb5_timestamp authtime, krb5_error_code error_code);
 652
 653 void krb5_db_refresh_config(krb5_context kcontext);
 654
 655 krb5_error_code krb5_db_check_allowed_to_delegate(krb5_context kcontext,
 656                                                   krb5_const_principal client,
 657                                                   const krb5_db_entry *server,
 658                                                   krb5_const_principal proxy);
 659
 660 /* default functions. Should not be directly called */
 661 /*
 662  *   Default functions prototype
 663  */
 664
 665 krb5_error_code
 666 krb5_dbe_def_search_enctype( krb5_context kcontext,
 667                              krb5_db_entry *dbentp,
 668                              krb5_int32 *start,
 669                              krb5_int32 ktype,
 670                              krb5_int32 stype,
 671                              krb5_int32 kvno,
 672                              krb5_key_data **kdatap);
 673
 674 krb5_error_code
 675 krb5_def_store_mkey_list( krb5_context context,
 676                           char *keyfile,
 677                           krb5_principal mname,
 678                           krb5_keylist_node *keylist,
 679                           char *master_pwd);
 680
 681 krb5_error_code
 682 krb5_db_def_fetch_mkey( krb5_context   context,
 683                         krb5_principal mname,
 684                         krb5_keyblock *key,
 685                         krb5_kvno     *kvno,
 686                         char          *db_args);
 687
 688 krb5_error_code
 689 krb5_def_fetch_mkey_list( krb5_context            context,
 690                           krb5_principal        mprinc,
 691                           const krb5_keyblock  *mkey,
 692                           krb5_keylist_node  **mkeys_list);
 693
 694 krb5_error_code
 695 krb5_dbe_def_cpw( krb5_context    context,
 696                   krb5_keyblock       * master_key,
 697                   krb5_key_salt_tuple   * ks_tuple,
 698                   int                     ks_tuple_count,
 699                   char          * passwd,
 700                   int                     new_kvno,
 701                   krb5_boolean    keepold,
 702                   krb5_db_entry * db_entry);
 703
 704 krb5_error_code
 705 krb5_dbe_def_decrypt_key_data( krb5_context             context,
 706                                const krb5_keyblock    * mkey,
 707                                const krb5_key_data    * key_data,
 708                                krb5_keyblock          * dbkey,
 709                                krb5_keysalt           * keysalt);
 710
 711 krb5_error_code
 712 krb5_dbe_def_encrypt_key_data( krb5_context             context,
 713                                const krb5_keyblock    * mkey,
 714                                const krb5_keyblock    * dbkey,
 715                                const krb5_keysalt     * keysalt,
 716                                int                      keyver,
 717                                krb5_key_data          * key_data);
 718
 719 krb5_error_code
 720 krb5_db_create_policy( krb5_context kcontext,
 721                        osa_policy_ent_t policy);
 722
 723 krb5_error_code
 724 krb5_db_get_policy ( krb5_context kcontext,
 725                      char *name,
 726                      osa_policy_ent_t *policy );
 727
 728 krb5_error_code
 729 krb5_db_put_policy( krb5_context kcontext,
 730                     osa_policy_ent_t policy);
 731
 732 krb5_error_code
 733 krb5_db_iter_policy( krb5_context kcontext,
 734                      char *match_entry,
 735                      osa_adb_iter_policy_func func,
 736                      void *data);
 737
 738 krb5_error_code
 739 krb5_db_delete_policy( krb5_context kcontext,
 740                        char *policy);
 741
 742 void
 743 krb5_db_free_policy( krb5_context kcontext,
 744                      osa_policy_ent_t policy);
 745
 746
 747 krb5_error_code
 748 krb5_db_set_context(krb5_context, void *db_context);
 749
 750 krb5_error_code
 751 krb5_db_get_context(krb5_context, void **db_context);
 752
 753 void
 754 krb5_dbe_free_key_data_contents(krb5_context, krb5_key_data *);
 755
 756 void
 757 krb5_dbe_free_key_list(krb5_context, krb5_keylist_node *);
 758
 759 void
 760 krb5_dbe_free_actkvno_list(krb5_context, krb5_actkvno_node *);
 761
 762 void
 763 krb5_dbe_free_mkey_aux_list(krb5_context, krb5_mkey_aux_node *);
 764
 765 void
 766 krb5_dbe_free_tl_data(krb5_context, krb5_tl_data *);
 767
 768 void
 769 krb5_dbe_free_strings(krb5_context, krb5_string_attr *, int count);
 770
 771 void
 772 krb5_dbe_free_string(krb5_context, char *);
 773
 774 #define KRB5_KDB_DEF_FLAGS      0
 775
 776 #define KDB_MAX_DB_NAME                 128
 777 #define KDB_REALM_SECTION               "realms"
 778 #define KDB_MODULE_POINTER              "database_module"
 779 #define KDB_MODULE_DEF_SECTION          "dbdefaults"
 780 #define KDB_MODULE_SECTION              "dbmodules"
 781 #define KDB_LIB_POINTER                 "db_library"
 782 #define KDB_DATABASE_CONF_FILE          DEFAULT_SECURE_PROFILE_PATH
 783 #define KDB_DATABASE_ENV_PROF           KDC_PROFILE_ENV
 784
 785 #define KRB5_KDB_OPEN_RW                0
 786 #define KRB5_KDB_OPEN_RO                1
 787
 788 #define KRB5_KDB_OPT_SET_DB_NAME        0
 789 #define KRB5_KDB_OPT_SET_LOCK_MODE      1
 790
 791 /*
 792  * This number indicates the date of the last incompatible change to the DAL.
 793  * The maj_ver field of the module's vtable structure must match this version.
 794  */
 795 #define KRB5_KDB_DAL_MAJOR_VERSION 3
 796
 797 /*
 798  * A krb5_context can hold one database object.  Modules should use
 799  * krb5_db_set_context and krb5_db_get_context to store state associated with
 800  * the database object.
 801  *
 802  * Some module functions are mandatory for KDC operation; others are optional
 803  * or apply only to administrative operations.  If a function is optional, a
 804  * module can leave the function pointer as NULL.  Alternatively, modules can
 805  * return KRB5_PLUGIN_OP_NOTSUPP when asked to perform an inapplicable action.
 806  *
 807  * Some module functions have default implementations which will call back into
 808  * the vtable interface.  Leave these functions as NULL to use the default
 809  * implementations.
 810  *
 811  * The documentation in these comments describes the DAL as it is currently
 812  * implemented and used, not as it should be.  So if anything seems off, that
 813  * probably means the current state of things is off.
 814  */
 815
 816 typedef struct _kdb_vftabl {
 817     short int maj_ver;
 818     short int min_ver;
 819
 820     /*
 821      * Mandatory: Invoked after the module library is loaded, when the first DB
 822      * using the module is opened, across all contexts.
 823      */
 824     krb5_error_code (*init_library)(void);
 825
 826     /*
 827      * Mandatory: Invoked before the module library is unloaded, after the last
 828      * DB using the module is closed, across all contexts.
 829      */
 830     krb5_error_code (*fini_library)(void);
 831
 832     /*
 833      * Mandatory: Initialize a database object.  Profile settings should be
 834      * read from conf_section inside KDB_MODULE_SECTION.  db_args communicates
 835      * command-line arguments for module-specific flags.  mode will be one of
 836      * KRB5_KDB_OPEN_{RW,RO} or'd with one of
 837      * KRB5_KDB_SRV_TYPE_{KDC,ADMIN,PASSWD,OTHER}.
 838      */
 839     krb5_error_code (*init_module)(krb5_context kcontext, char *conf_section,
 840                                    char **db_args, int mode);
 841
 842     /*
 843      * Mandatory: Finalize the database object contained in a context.  Free
 844      * any state contained in the db_context pointer and null it out.
 845      */
 846     krb5_error_code (*fini_module)(krb5_context kcontext);
 847
 848     /*
 849      * Optional: Initialize a database object while creating the underlying
 850      * database.  conf_section and db_args have the same meaning as in
 851      * init_module.  This function may return an error if the database already
 852      * exists.  Used by kdb5_util create.
 853      *
 854      * If db_args contains the value "temporary", the module should create an
 855      * exclusively locked side copy of the database suitable for loading in a
 856      * propagation from master to slave.  This side copy will later be promoted
 857      * with promote_db, allowing complete updates of the DB with no loss in
 858      * read availability.  If the module cannot comply with this architecture,
 859      * it should return an error.
 860      */
 861     krb5_error_code (*create)(krb5_context kcontext, char *conf_section,
 862                               char **db_args);
 863
 864     /*
 865      * Optional: Destroy a database.  conf_section and db_args have the same
 866      * meaning as in init_module.  Used by kdb5_util destroy.  In current
 867      * usage, the database is destroyed while open, so the module should handle
 868      * that.
 869      */
 870     krb5_error_code (*destroy)(krb5_context kcontext, char *conf_section,
 871                                char **db_args);
 872
 873     /*
 874      * Deprecated: No longer used as of krb5 1.10; can be removed in the next
 875      * DAL revision.  Modules should leave as NULL.
 876      */
 877     krb5_error_code (*get_age)(krb5_context kcontext, char *db_name,
 878                                time_t *age);
 879
 880     /*
 881      * Optional: Lock the database, with semantics depending on the mode
 882      * argument:
 883      *
 884      * KRB5_DB_LOCKMODE_SHARED: Lock may coexist with other shared locks.
 885      * KRB5_DB_LOCKMODE_EXCLUSIVE: Lock may not coexist with other locks.
 886      * KRB5_DB_LOCKMODE_PERMANENT: Exclusive lock surviving process exit.
 887      * (KRB5_DB_LOCKMODE_DONTBLOCK is unused and unimplemented.)
 888      *
 889      * Used by the "kadmin lock" command, incremental propagation, and
 890      * kdb5_util dump.  Incremental propagation support requires shared locks
 891      * to operate.  kdb5_util dump will continue unlocked if the module returns
 892      * KRB5_PLUGIN_OP_NOTSUPP.
 893      */
 894     krb5_error_code (*lock)(krb5_context kcontext, int mode);
 895
 896     /* Optional: Release a lock created with db_lock. */
 897     krb5_error_code (*unlock)(krb5_context kcontext);
 898
 899     /*
 900      * Mandatory: Set *entry to an allocated entry for the principal
 901      * search_for.  If the principal is not found, return KRB5_KDB_NOENTRY.
 902      *
 903      * The meaning of flags are as follows:
 904      *
 905      * KRB5_KDB_FLAG_CANONICALIZE: Set by the KDC when looking up entries for
 906      *     an AS or TGS request with canonicalization requested.  Determines
 907      *     whether the module should return out-of-realm referrals.
 908      *
 909      * KRB5_KDB_FLAG_INCLUDE_PAC: Set by the KDC during an AS request when the
 910      *     client requested PAC information during padata, and during most TGS
 911      *     requests.  Indicates that the module should include PAC information
 912      *     when its sign_authdata method is invoked.
 913      *
 914      * KRB5_KDB_FLAG_CLIENT_REFERRALS_ONLY: Set by the KDC when looking up the
 915      *     client entry in an AS request.  Affects how the module should return
 916      *     out-of-realm referrals.
 917      *
 918      * KRB5_KDB_FLAG_MAP_PRINCIPALS: Set by the KDC when looking up the client
 919      *     entry during TGS requests, except for S4U TGS requests and requests
 920      *     where the server entry has the KRB5_KDB_NO_AUTH_DATA_REQUIRED
 921      *     attribute.  Indicates that the module should map foreign principals
 922      *     to local principals if it supports doing so.
 923      *
 924      * KRB5_KDB_FLAG_PROTOCOL_TRANSITION: Set by the KDC when looking up the
 925      *     client entry during an S4U2Self TGS request.  This affects the PAC
 926      *     information which should be included when authorization data is
 927      *     generated; see the Microsoft S4U specification for details.
 928      *
 929      * KRB5_KDB_FLAG_CONSTRAINED_DELEGATION: Set by the KDC when looking up the
 930      *     client entry during an S4U2Proxy TGS request.  Also affects PAC
 931      *     generation.
 932      *
 933      * KRB5_KDB_FLAG_CROSS_REALM: Set by the KDC when looking up a client entry
 934      *     during a TGS request, if the client principal is not part of the
 935      *     realm being served.
 936      *
 937      * KRB5_KDB_FLAG_ALIAS_OK: Set by the KDC for server principal lookups and
 938      *     for AS request client principal lookups with canonicalization
 939      *     requested; also set by the admin interface.  Determines whether the
 940      *     module should return in-realm aliases.
 941      *
 942      * A module can return in-realm aliases if KRB5_KDB_FLAG_ALIAS_OK is set.
 943      * To return an in-realm alias, fill in a different value for
 944      * entries->princ than the one requested.
 945      *
 946      * A module can return out-of-realm referrals if KRB5_KDB_FLAG_CANONICALIZE
 947      * is set.  For AS request clients (KRB5_KDB_FLAG_CLIENT_REFERRALS_ONLY is
 948      * also set), the module should do so by simply filling in an out-of-realm
 949      * name in entries->princ and setting all other fields to NULL.  Otherwise,
 950      * the module should return the entry for the cross-realm TGS of the
 951      * referred-to realm.  For TGS referals, the module can also include
 952      * tl-data of type KRB5_TL_SERVER_REFERRAL containing ASN.1-encoded Windows
 953      * referral data as documented in draft-ietf-krb-wg-kerberos-referrals-11
 954      * appendix A; this will be returned to the client as encrypted padata.
 955      */
 956     krb5_error_code (*get_principal)(krb5_context kcontext,
 957                                      krb5_const_principal search_for,
 958                                      unsigned int flags,
 959                                      krb5_db_entry **entry);
 960
 961     /*
 962      * Mandatory: Free a database entry.  The entry may have been constructed
 963      * by the caller (using the db_alloc function to allocate associated
 964      * memory); thus, a plugin must allocate each field of a principal entry
 965      * separately.
 966      */
 967     void (*free_principal)(krb5_context kcontext, krb5_db_entry *entry);
 968
 969     /*
 970      * Optional: Create or modify a principal entry.  db_args communicates
 971      * command-line arguments for module-specific flags.
 972      *
 973      * The mask field of an entry indicates the changed fields.  Mask values
 974      * are defined in kadmin's admin.h header.  If KADM5_PRINCIPAL is set in
 975      * the mask, the entry is new; otherwise it already exists.  All fields of
 976      * an entry are expected to contain correct values, regardless of whether
 977      * they are specified in the mask, so it is acceptable for a module to
 978      * ignore the mask and update the entire entry.
 979      */
 980     krb5_error_code (*put_principal)(krb5_context kcontext,
 981                                      krb5_db_entry *entry, char **db_args);
 982
 983     /*
 984      * Optional: Delete the entry for the principal search_for.  If the
 985      * principal did not exist, return KRB5_KDB_NOENTRY.
 986      */
 987     krb5_error_code (*delete_principal)(krb5_context kcontext,
 988                                         krb5_const_principal search_for);
 989
 990     /*
 991      * Optional: For each principal entry in the database, invoke func with the
 992      * argments func_arg and the entry data.  If match_entry is specified, the
 993      * module may narrow the iteration to principal names matching that regular
 994      * expression; a module may alternatively ignore match_entry.
 995      */
 996     krb5_error_code (*iterate)(krb5_context kcontext,
 997                                char *match_entry,
 998                                int (*func)(krb5_pointer, krb5_db_entry *),
 999                                krb5_pointer func_arg);
1000
1001     /*
1002      * Optional: Create a password policy entry.  Return an error if the policy
1003      * already exists.
1004      */
1005     krb5_error_code (*create_policy)(krb5_context kcontext,
1006                                      osa_policy_ent_t policy);
1007
1008     /*
1009      * Optional: Set *policy to the policy entry of the specified name.  If the
1010      * entry does not exist, return KRB5_KDB_NOENTRY.
1011      */
1012     krb5_error_code (*get_policy)(krb5_context kcontext, char *name,
1013                                   osa_policy_ent_t *policy);
1014
1015     /*
1016      * Optional: Modify an existing password policy entry to match the values
1017      * in policy.  Return an error if the policy does not already exist.
1018      */
1019     krb5_error_code (*put_policy)(krb5_context kcontext,
1020                                   osa_policy_ent_t policy);
1021
1022     /*
1023      * Optional: For each password policy entry in the database, invoke func
1024      * with the argments data and the entry data.  If match_entry is specified,
1025      * the module may narrow the iteration to policy names matching that
1026      * regular expression; a module may alternatively ignore match_entry.
1027      */
1028     krb5_error_code (*iter_policy)(krb5_context kcontext, char *match_entry,
1029                                    osa_adb_iter_policy_func func,
1030                                    void *data);
1031
1032     /*
1033      * Optional: Delete the password policy entry with the name policy.  Return
1034      * an error if the entry does not exist.
1035      */
1036     krb5_error_code (*delete_policy)(krb5_context kcontext, char *policy);
1037
1038     /* Optional: Free a policy entry returned by db_get_policy. */
1039     void (*free_policy)(krb5_context kcontext, osa_policy_ent_t val);
1040
1041     /*
1042      * Mandatory: Has the semantics of realloc(ptr, size).  Callers use this to
1043      * allocate memory for new or changed principal entries, so the module
1044      * should expect to potentially see this memory in db_free_principal.
1045      */
1046     void *(*alloc)(krb5_context kcontext, void *ptr, size_t size);
1047
1048     /*
1049      * Mandatory: Has the semantics of free(ptr).  Callers use this to free
1050      * fields from a principal entry (such as key data) before changing it in
1051      * place, and in some cases to free data they allocated with db_alloc.
1052      */
1053     void (*free)(krb5_context kcontext, void *ptr);
1054
1055     /*
1056      * Optional with default: Retrieve a master keyblock from the stash file
1057      * db_args, filling in *key and *kvno.  mname is the name of the master
1058      * principal for the realm.
1059      *
1060      * The default implementation reads the master keyblock from a keytab or
1061      * old-format stash file.
1062      */
1063     krb5_error_code (*fetch_master_key)(krb5_context kcontext,
1064                                         krb5_principal mname,
1065                                         krb5_keyblock *key, krb5_kvno *kvno,
1066                                         char *db_args);
1067
1068     /*
1069      * Optional with default: Given a keyblock for some version of the
1070      * database's master key, fetch the decrypted master key values from the
1071      * database and store the list into *mkeys_list.  The caller will free
1072      * *mkeys_list using a libkdb5 function which uses the standard free()
1073      * function, so the module must not use a custom allocator.
1074      *
1075      * The caller may not know the version number of the master key it has, in
1076      * which case it will pass IGNORE_VNO.
1077      *
1078      * The default implementation ignores kvno and tries the key against the
1079      * current master key data and all KRB5_TL_MKEY_AUX values, which contain
1080      * copies of the master keys encrypted with old master keys.
1081      */
1082     krb5_error_code (*fetch_master_key_list)(krb5_context kcontext,
1083                                              krb5_principal mname,
1084                                              const krb5_keyblock *key,
1085                                              krb5_keylist_node **mkeys_list);
1086
1087     /*
1088      * Optional with default: Save a list of master keyblocks, obtained from
1089      * fetch_master_key_list, into the stash file db_arg.  The caller will set
1090      * master_pwd to NULL, so the module should just ignore it.  mname is the
1091      * name of the master principal for the realm.
1092      *
1093      * The default implementation saves the list of master keys in a
1094      * keytab-format file.
1095      */
1096     krb5_error_code (*store_master_key_list)(krb5_context kcontext,
1097                                              char *db_arg,
1098                                              krb5_principal mname,
1099                                              krb5_keylist_node *keylist,
1100                                              char *master_pwd);
1101
1102     /*
1103      * Optional with default: Starting at position *start, scan the key data of
1104      * a database entry for a key matching the enctype ktype, the salt type
1105      * stype, and the version kvno.  Store the resulting key into *kdatap and
1106      * set *start to the position after the key found.  If ktype is negative,
1107      * match any enctype.  If stype is negative, match any salt type.  If kvno
1108      * is zero or negative, find the most recent key version satisfying the
1109      * other constraints.
1110      */
1111     krb5_error_code (*dbe_search_enctype)(krb5_context kcontext,
1112                                           krb5_db_entry *dbentp,
1113                                           krb5_int32 *start, krb5_int32 ktype,
1114                                           krb5_int32 stype, krb5_int32 kvno,
1115                                           krb5_key_data **kdatap);
1116
1117
1118     /*
1119      * Optional with default: Change the key data for db_entry to include keys
1120      * derived from the password passwd in each of the specified key-salt
1121      * types, at version new_kvno.  Discard the old key data if keepold is not
1122      * set.
1123      *
1124      * The default implementation uses the keyblock master_key to encrypt each
1125      * new key, via the function encrypt_key_data.
1126      */
1127     krb5_error_code (*change_pwd)(krb5_context context,
1128                                   krb5_keyblock *master_key,
1129                                   krb5_key_salt_tuple *ks_tuple,
1130                                   int ks_tuple_count, char *passwd,
1131                                   int new_kvno, krb5_boolean keepold,
1132                                   krb5_db_entry *db_entry);
1133
1134     /*
1135      * Optional: Promote a temporary database to be the live one.  context must
1136      * be initialized with an exclusively locked database created with the
1137      * "temporary" db_arg.  On success, the database object contained in
1138      * context will be finalized.
1139      *
1140      * This method is used by kdb5_util load to replace the live database with
1141      * minimal loss of read availability.
1142      */
1143     krb5_error_code (*promote_db)(krb5_context context, char *conf_section,
1144                                   char **db_args);
1145
1146     /*
1147      * Optional with default: Decrypt the key in key_data with master keyblock
1148      * mkey, placing the result into dbkey.  Copy the salt from key_data, if
1149      * any, into keysalt.  Either dbkey or keysalt may be left unmodified on
1150      * successful return if key_data does not contain key or salt information.
1151      *
1152      * The default implementation expects the encrypted key (in krb5_c_encrypt
1153      * format) to be stored in key_data_contents[0], with length given by
1154      * key_data_length[0].  If key_data_ver is 2, it expects the salt to be
1155      * stored, unencrypted, in key_data_contents[1], with length given by
1156      * key_data_length[1].
1157      */
1158     krb5_error_code (*decrypt_key_data)(krb5_context kcontext,
1159                                         const krb5_keyblock *mkey,
1160                                         const krb5_key_data *key_data,
1161                                         krb5_keyblock *dbkey,
1162                                         krb5_keysalt *keysalt);
1163
1164     /*
1165      * Optional with default: Encrypt dbkey with master keyblock mkey, placing
1166      * the result into key_data along with keysalt.
1167      *
1168      * The default implementation stores the encrypted key (in krb5_c_encrypt
1169      * format) in key_data_contents[0] and the length in key_data_length[0].
1170      * If keysalt is specified, it sets key_data_ver to 2, and stores the salt
1171      * in key_data_contents[1] and its length in key_data_length[1].  If
1172      * keysalt is not specified, key_data_ver is set to 1.
1173      */
1174     krb5_error_code (*encrypt_key_data)(krb5_context kcontext,
1175                                         const krb5_keyblock *mkey,
1176                                         const krb5_keyblock *dbkey,
1177                                         const krb5_keysalt *keysalt,
1178                                         int keyver, krb5_key_data *key_data);
1179
1180     /*
1181      * Optional: Generate signed authorization data, such as a Windows PAC, for
1182      * the ticket to be returned to the client.  Place the signed authorization
1183      * data, if any, in *signed_auth_data.  This function will be invoked for
1184      * an AS request if the client included padata requesting a PAC.  This
1185      * function will be invoked for a TGS request if there is authorization
1186      * data in the TGT, if the client is from another realm, or if the TGS
1187      * request is an S4U2Self or S4U2Proxy request.  This function will not be
1188      * invoked during TGS requests if the server principal has the
1189      * no_auth_data_required attribute set.  Input parameters are:
1190      *
1191      *   flags: The flags used to look up the client principal.
1192      *
1193      *   client_princ: For S4U2Proxy TGS requests, the client principal
1194      *     requested by the service; for regular TGS requests, the
1195      *     possibly-canonicalized client principal.
1196      *
1197      *   client: The DB entry of the client.  For S4U2Self, this will be the DB
1198      *     entry for the client principal requested by the service).
1199      *
1200      *   server: The DB entry of the service principal.
1201      *
1202      *   krbtgt: For TGS requests, the DB entry of the (possibly foreign)
1203      *     ticket granting service of the TGT.  For AS requests, the DB entry
1204      *     of the service principal.
1205      *
1206      *   client_key: The reply key for the KDC request, before any FAST armor
1207      *     is applied.  For AS requests, this may be the client's long-term key
1208      *     or a key chosen by a preauth mechanism.  For TGS requests, this may
1209      *     be the subkey found in the AP-REQ or the session key of the TGT.
1210      *
1211      *   server_key: The server key used to encrypt the returned ticket.
1212      *
1213      *   krbtgt_key: For TGS requests, the key of the (possibly foreign) ticket
1214      *     granting service of the TGT.  for AS requests, the service
1215      *     principal's key.
1216      *
1217      *   session_key: The session key of the ticket being granted to the
1218      *     requestor.
1219      *
1220      *   authtime: The timestamp of the original client authentication time.
1221      *     For AS requests, this is the current time.  For TGS requests, this
1222      *     is the authtime of the subject ticket (TGT or S4U2Proxy evidence
1223      *     ticket).
1224      *
1225      *   tgt_auth_data: For TGS requests, the authorization data present in the
1226      *     subject ticket.  For AS requests, NULL.
1227      */
1228     krb5_error_code (*sign_authdata)(krb5_context kcontext,
1229                                      unsigned int flags,
1230                                      krb5_const_principal client_princ,
1231                                      krb5_db_entry *client,
1232                                      krb5_db_entry *server,
1233                                      krb5_db_entry *krbtgt,
1234                                      krb5_keyblock *client_key,
1235                                      krb5_keyblock *server_key,
1236                                      krb5_keyblock *krbtgt_key,
1237                                      krb5_keyblock *session_key,
1238                                      krb5_timestamp authtime,
1239                                      krb5_authdata **tgt_auth_data,
1240                                      krb5_authdata ***signed_auth_data);
1241
1242     /*
1243      * Optional: Perform a policy check on a cross-realm ticket's transited
1244      * field and return an error (other than KRB5_PLUGIN_OP_NOTSUPP) if the
1245      * check fails.
1246      */
1247     krb5_error_code (*check_transited_realms)(krb5_context kcontext,
1248                                               const krb5_data *tr_contents,
1249                                               const krb5_data *client_realm,
1250                                               const krb5_data *server_realm);
1251
1252     /*
1253      * Optional: Perform a policy check on an AS request, in addition to the
1254      * standard policy checks.  Return 0 if the AS request is allowed.  If the
1255      * AS request is not allowed:
1256      *   - Place a short string literal into *status.
1257      *   - If desired, place data into e_data.  Any data placed here will be
1258      *     freed by the caller using the standard free function.
1259      *   - Return an appropriate error (such as KDC_ERR_POLICY).
1260      */
1261     krb5_error_code (*check_policy_as)(krb5_context kcontext,
1262                                        krb5_kdc_req *request,
1263                                        krb5_db_entry *client,
1264                                        krb5_db_entry *server,
1265                                        krb5_timestamp kdc_time,
1266                                        const char **status,
1267                                        krb5_pa_data ***e_data);
1268
1269     /*
1270      * Optional: Perform a policy check on a TGS request, in addition to the
1271      * standard policy checks.  Return 0 if the TGS request is allowed.  If the
1272      * TGS request is not allowed:
1273      *   - Place a short string literal into *status.
1274      *   - If desired, place data into e_data.  Any data placed here will be
1275      *     freed by the caller using the standard free function.
1276      *   - Return an appropriate error (such as KDC_ERR_POLICY).
1277      * The input parameter ticket contains the TGT used in the TGS request.
1278      */
1279     krb5_error_code (*check_policy_tgs)(krb5_context kcontext,
1280                                         krb5_kdc_req *request,
1281                                         krb5_db_entry *server,
1282                                         krb5_ticket *ticket,
1283                                         const char **status,
1284                                         krb5_pa_data ***e_data);
1285
1286     /*
1287      * Optional: This method informs the module of a successful or unsuccessful
1288      * AS request.
1289      */
1290     void (*audit_as_req)(krb5_context kcontext, krb5_kdc_req *request,
1291                          krb5_db_entry *client, krb5_db_entry *server,
1292                          krb5_timestamp authtime, krb5_error_code error_code);
1293
1294     /* Note: there is currently no method for auditing TGS requests. */
1295
1296     /*
1297      * Optional: This method informs the module of a request to reload
1298      * configuration or other state (that is, the KDC received a SIGHUP).
1299      */
1300     void (*refresh_config)(krb5_context kcontext);
1301
1302     /*
1303      * Optional: Perform a policy check on server being allowed to obtain
1304      * tickets from client to proxy.  (Note that proxy is the target of the
1305      * delegation, not the delegating service; the term "proxy" is from the
1306      * viewpoint of the delegating service asking another service to perform
1307      * some of its work in the authentication context of the client.  This
1308      * terminology comes from the Microsoft S4U protocol documentation.)
1309      * Return 0 if policy allows it, or an appropriate error (such as
1310      * KRB5KDC_ERR_POLICY) if not.  If this method is not implemented, all
1311      * S4U2Proxy delegation requests will be rejected.
1312      */
1313     krb5_error_code (*check_allowed_to_delegate)(krb5_context context,
1314                                                  krb5_const_principal client,
1315                                                  const krb5_db_entry *server,
1316                                                  krb5_const_principal proxy);
1317 } kdb_vftabl;
1318
1319 #endif /* !defined(_WIN32) */
1320
1321 #endif /* KRB5_KDB5__ */