source4/heimdal/lib/hdb/hdb.h

   1 /*
   2  * Copyright (c) 1997 - 2007 Kungliga Tekniska Högskolan
   3  * (Royal Institute of Technology, Stockholm, Sweden).
   4  * All rights reserved.
   5  *
   6  * Redistribution and use in source and binary forms, with or without
   7  * modification, are permitted provided that the following conditions
   8  * are met:
   9  *
  10  * 1. Redistributions of source code must retain the above copyright
  11  *    notice, this list of conditions and the following disclaimer.
  12  *
  13  * 2. Redistributions in binary form must reproduce the above copyright
  14  *    notice, this list of conditions and the following disclaimer in the
  15  *    documentation and/or other materials provided with the distribution.
  16  *
  17  * 3. Neither the name of the Institute nor the names of its contributors
  18  *    may be used to endorse or promote products derived from this software
  19  *    without specific prior written permission.
  20  *
  21  * THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
  22  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  23  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  24  * ARE DISCLAIMED.  IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
  25  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  26  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  27  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  28  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  29  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  30  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  31  * SUCH DAMAGE.
  32  */
  33
  34 /* $Id$ */
  35
  36 #ifndef __HDB_H__
  37 #define __HDB_H__
  38
  39 #include <stdio.h>
  40
  41 #include <krb5.h>
  42
  43 #include <hdb_err.h>
  44
  45 #include <heim_asn1.h>
  46 #include <hdb_asn1.h>
  47 typedef HDB_keyset hdb_keyset;
  48 typedef HDB_entry hdb_entry;
  49 typedef HDB_entry_alias hdb_entry_alias;
  50
  51 struct hdb_dbinfo;
  52
  53 enum hdb_lockop{ HDB_RLOCK, HDB_WLOCK };
  54
  55 /* flags for various functions */
  56 #define HDB_F_DECRYPT           1       /* decrypt keys */
  57 #define HDB_F_REPLACE           2       /* replace entry */
  58 #define HDB_F_GET_CLIENT        4       /* fetch client */
  59 #define HDB_F_GET_SERVER        8       /* fetch server */
  60 #define HDB_F_GET_KRBTGT        16      /* fetch krbtgt */
  61 #define HDB_F_GET_ANY           28      /* fetch any of client,server,krbtgt */
  62 #define HDB_F_CANON             32      /* want canonicalition */
  63 #define HDB_F_ADMIN_DATA        64      /* want data that kdc don't use  */
  64 #define HDB_F_KVNO_SPECIFIED    128     /* we want a particular KVNO */
  65 #define HDB_F_CURRENT_KVNO      256     /* we want the current KVNO */
  66 #define HDB_F_LIVE_CLNT_KVNOS   512     /* we want all live keys for pre-auth */
  67 #define HDB_F_LIVE_SVC_KVNOS    1024    /* we want all live keys for tix */
  68 #define HDB_F_ALL_KVNOS         2048    /* we want all the keys, live or not */
  69 #define HDB_F_FOR_AS_REQ        4096    /* fetch is for a AS REQ */
  70 #define HDB_F_FOR_TGS_REQ       8192    /* fetch is for a TGS REQ */
  71 #define HDB_F_PRECHECK          16384   /* check that the operation would succeed */
  72 #define HDB_F_DELAY_NEW_KEYS    32768   /* apply [hdb] new_service_key_delay */
  73 #define HDB_F_SYNTHETIC_OK      65536   /* synthetic principal for PKINIT or GSS preauth OK */
  74 #define HDB_F_GET_FAST_COOKIE  131072   /* fetch the FX-COOKIE key (not a normal principal) */
  75
  76 /* hdb_capability_flags */
  77 #define HDB_CAP_F_HANDLE_ENTERPRISE_PRINCIPAL 1
  78 #define HDB_CAP_F_HANDLE_PASSWORDS      2
  79 #define HDB_CAP_F_PASSWORD_UPDATE_KEYS  4
  80 #define HDB_CAP_F_SHARED_DIRECTORY      8
  81
  82 /* auth status values */
  83
  84 /*
  85  * Un-initialised value, not permitted, used to indicate that a value
  86  * wasn't set for the benifit of logic in the caller, must not be
  87  * passed to hdb_auth_status()
  88  */
  89
  90 #define HDB_AUTHSTATUS_INVALID                  0
  91
  92 /*
  93  * A ticket was issued after authorization was successfully completed
  94  * (eg flags on the entry and expiry times were checked)
  95  */
  96 #define HDB_AUTHSTATUS_AUTHORIZATION_SUCCESS    1
  97
  98 /*
  99  * The user supplied the wrong password to a password-based
 100  * authentication mechanism (eg ENC-TS, ENC-CHAL)
 101  *
 102  * The HDB backend might increment a bad password count.
 103  */
 104 #define HDB_AUTHSTATUS_WRONG_PASSWORD           2
 105
 106 /*
 107  * The user supplied a correct password to a password-based
 108  * authentication mechanism (eg ENC-TS, ENC-CHAL)
 109  *
 110  * The HDB backend might reset a bad password count.
 111  */
 112 #define HDB_AUTHSTATUS_CORRECT_PASSWORD         3
 113
 114 /*
 115  * Attempted authenticaton with an unknown user
 116  */
 117 #define HDB_AUTHSTATUS_CLIENT_UNKNOWN           4
 118
 119 /*
 120  * Attempted authenticaton with an known user that is already locked
 121  * out.
 122  */
 123 #define HDB_AUTHSTATUS_CLIENT_LOCKED_OUT        5
 124
 125 /*
 126  * Successful authentication with a pre-authentication mechanism
 127  */
 128 #define HDB_AUTHSTATUS_GENERIC_SUCCESS          6
 129
 130 /*
 131  * Failed authentication with a pre-authentication mechanism
 132  */
 133 #define HDB_AUTHSTATUS_GENERIC_FAILURE          7
 134
 135 /*
 136  * Successful pre-authentication with PKINIT (smart card login etc)
 137  */
 138 #define HDB_AUTHSTATUS_PKINIT_SUCCESS           8
 139
 140 /*
 141  * Failed pre-authentication with PKINIT (smart card login etc)
 142  */
 143 #define HDB_AUTHSTATUS_PKINIT_FAILURE           9
 144
 145 /*
 146  * Successful pre-authentication with GSS pre-authentication
 147  */
 148 #define HDB_AUTHSTATUS_GSS_SUCCESS              10
 149
 150 /*
 151  * Failed pre-authentication with GSS pre-authentication
 152  */
 153 #define HDB_AUTHSTATUS_GSS_FAILURE              11
 154
 155 /* key usage for master key */
 156 #define HDB_KU_MKEY     0x484442
 157
 158 /*
 159  * Second component of WELLKNOWN namespace principals, the third component is
 160  * the common DNS suffix of the implied virtual hosts.
 161  */
 162 #define HDB_WK_NAMESPACE "HOSTBASED-NAMESPACE"
 163
 164 typedef struct hdb_master_key_data *hdb_master_key;
 165
 166 /**
 167  * hdb_entry_ex is a wrapper structure around the hdb_entry structure
 168  * that allows backends to keep a pointer to the backing store, ie in
 169  * ->hdb_fetch_kvno(), so that we the kadmin/kpasswd backend gets around to
 170  * ->hdb_store(), the backend doesn't need to lookup the entry again.
 171  */
 172
 173 typedef struct hdb_entry_ex {
 174     void *ctx;
 175     hdb_entry entry;
 176     void (*free_entry)(krb5_context, struct hdb_entry_ex *);
 177 } hdb_entry_ex;
 178
 179
 180 /**
 181  * HDB backend function pointer structure
 182  *
 183  * The HDB structure is what the KDC and kadmind framework uses to
 184  * query the backend database when talking about principals.
 185  */
 186
 187 typedef struct HDB {
 188     void *hdb_db;
 189     void *hdb_dbc; /** don't use, only for DB3 */
 190     const char *hdb_method_name;
 191     char *hdb_name;
 192     int hdb_master_key_set;
 193     hdb_master_key hdb_master_key;
 194     int hdb_openp;
 195     int hdb_capability_flags;
 196     int lock_count;
 197     int lock_type;
 198     /*
 199      * These fields cache config values.
 200      *
 201      * XXX Move these into a structure that we point to so that we
 202      * don't need to break the ABI every time we add a field.
 203      */
 204     int enable_virtual_hostbased_princs;
 205     size_t virtual_hostbased_princ_ndots;   /* Min. # of .s in hostname */
 206     size_t virtual_hostbased_princ_maxdots; /* Max. # of .s in namespace */
 207     char **virtual_hostbased_princ_svcs;    /* Which svcs are not wildcarded */
 208     time_t new_service_key_delay;           /* Delay for new keys */
 209     /**
 210      * Open (or create) the a Kerberos database.
 211      *
 212      * Open (or create) the a Kerberos database that was resolved with
 213      * hdb_create(). The third and fourth flag to the function are the
 214      * same as open(), thus passing O_CREAT will create the data base
 215      * if it doesn't exists.
 216      *
 217      * Then done the caller should call hdb_close(), and to release
 218      * all resources hdb_destroy().
 219      */
 220     krb5_error_code (*hdb_open)(krb5_context, struct HDB*, int, mode_t);
 221     /**
 222      * Close the database for transaction
 223      *
 224      * Closes the database for further transactions, wont release any
 225      * permanant resources. the database can be ->hdb_open-ed again.
 226      */
 227     krb5_error_code (*hdb_close)(krb5_context, struct HDB*);
 228     /**
 229      * Free an entry after use.
 230      */
 231     void            (*hdb_free)(krb5_context, struct HDB*, hdb_entry_ex*);
 232     /**
 233      * Fetch an entry from the backend
 234      *
 235      * Fetch an entry from the backend, flags are what type of entry
 236      * should be fetch: client, server, krbtgt.
 237      * knvo (if specified and flags HDB_F_KVNO_SPECIFIED set) is the kvno to get
 238      */
 239     krb5_error_code (*hdb_fetch_kvno)(krb5_context, struct HDB*,
 240                                       krb5_const_principal, unsigned, krb5_kvno,
 241                                       hdb_entry_ex*);
 242     /**
 243      * Store an entry to database
 244      */
 245     krb5_error_code (*hdb_store)(krb5_context, struct HDB*,
 246                                  unsigned, hdb_entry_ex*);
 247     /**
 248      * Remove an entry from the database.
 249      */
 250     krb5_error_code (*hdb_remove)(krb5_context, struct HDB*,
 251                                   unsigned, krb5_const_principal);
 252     /**
 253      * As part of iteration, fetch one entry
 254      */
 255     krb5_error_code (*hdb_firstkey)(krb5_context, struct HDB*,
 256                                     unsigned, hdb_entry_ex*);
 257     /**
 258      * As part of iteration, fetch next entry
 259      */
 260     krb5_error_code (*hdb_nextkey)(krb5_context, struct HDB*,
 261                                    unsigned, hdb_entry_ex*);
 262     /**
 263      * Lock database
 264      *
 265      * A lock can only be held by one consumers. Transaction can still
 266      * happen on the database while the lock is held, so the entry is
 267      * only useful for syncroning creation of the database and renaming of the database.
 268      */
 269     krb5_error_code (*hdb_lock)(krb5_context, struct HDB*, int);
 270     /**
 271      * Unlock database
 272      */
 273     krb5_error_code (*hdb_unlock)(krb5_context, struct HDB*);
 274     /**
 275      * Rename the data base.
 276      *
 277      * Assume that the database is not hdb_open'ed and not locked.
 278      */
 279     krb5_error_code (*hdb_rename)(krb5_context, struct HDB*, const char*);
 280     /**
 281      * Get an hdb_entry from a classical DB backend
 282      *
 283      * This function takes a principal key (krb5_data) and returns all
 284      * data related to principal in the return krb5_data. The returned
 285      * encoded entry is of type hdb_entry or hdb_entry_alias.
 286      */
 287     krb5_error_code (*hdb__get)(krb5_context, struct HDB*,
 288                                 krb5_data, krb5_data*);
 289     /**
 290      * Store an hdb_entry from a classical DB backend
 291      *
 292      * This function takes a principal key (krb5_data) and encoded
 293      * hdb_entry or hdb_entry_alias as the data to store.
 294      *
 295      * For a file-based DB, this must synchronize to disk when done.
 296      * This is sub-optimal for kadm5_s_rename_principal(), and for
 297      * kadm5_s_modify_principal() when using principal aliases; to
 298      * improve this so that only one fsync() need be done
 299      * per-transaction will require HDB API extensions.
 300      */
 301     krb5_error_code (*hdb__put)(krb5_context, struct HDB*, int,
 302                                 krb5_data, krb5_data);
 303     /**
 304      * Delete and hdb_entry from a classical DB backend
 305      *
 306      * This function takes a principal key (krb5_data) naming the record
 307      * to delete.
 308      *
 309      * Same discussion as in @ref HDB::hdb__put
 310      */
 311     krb5_error_code (*hdb__del)(krb5_context, struct HDB*, krb5_data);
 312     /**
 313      * Destroy the handle to the database.
 314      *
 315      * Destroy the handle to the database, deallocate all memory and
 316      * related resources. Does not remove any permanent data. Its the
 317      * logical reverse of hdb_create() function that is the entry
 318      * point for the module.
 319      */
 320     krb5_error_code (*hdb_destroy)(krb5_context, struct HDB*);
 321     /**
 322      * Get the list of realms this backend handles.
 323      * This call is optional to support. The returned realms are used
 324      * for announcing the realms over bonjour. Free returned array
 325      * with krb5_free_host_realm().
 326      */
 327     krb5_error_code (*hdb_get_realms)(krb5_context, struct HDB *, krb5_realm **);
 328     /**
 329      * Change password.
 330      *
 331      * Will update keys for the entry when given password.  The new
 332      * keys must be written into the entry and will then later be
 333      * ->hdb_store() into the database. The backend will still perform
 334      * all other operations, increasing the kvno, and update
 335      * modification timestamp.
 336      *
 337      * The backend needs to call _kadm5_set_keys() and perform password
 338      * quality checks.
 339      */
 340     krb5_error_code (*hdb_password)(krb5_context, struct HDB*, hdb_entry_ex*, const char *, int);
 341
 342     /**
 343      * Auth feedback
 344      *
 345      * This is a feedback call that allows backends that provides
 346      * lockout functionality to register failure and/or successes.
 347      *
 348      * In case the entry is locked out, the backend should set the
 349      * hdb_entry.flags.locked-out flag.
 350      */
 351     krb5_error_code (*hdb_auth_status)(krb5_context,
 352                                        struct HDB *,
 353                                        hdb_entry_ex *,
 354                                        const struct timeval *start_time,
 355                                        const struct sockaddr *from_addr,
 356                                        const char *original_client_name,
 357                                        int auth_type,
 358                                        const char *auth_details,
 359                                        const char *pa_type);
 360     /**
 361      * Check if delegation is allowed.
 362      */
 363     krb5_error_code (*hdb_check_constrained_delegation)(krb5_context, struct HDB *, hdb_entry_ex *, krb5_const_principal);
 364
 365     /**
 366      * Check if this name is an alias for the supplied client for PKINIT userPrinicpalName logins
 367      */
 368     krb5_error_code (*hdb_check_pkinit_ms_upn_match)(krb5_context, struct HDB *, hdb_entry_ex *, krb5_const_principal);
 369
 370     /**
 371      * Check if s4u2self is allowed from this client to this server or the SPN is a valid SPN of this client (for user2user)
 372      */
 373     krb5_error_code (*hdb_check_client_matches_target_service)(krb5_context, struct HDB *, hdb_entry_ex *, hdb_entry_ex *);
 374
 375     /**
 376      * Enable/disable synchronous updates
 377      *
 378      * Calling this with 0 disables sync.  Calling it with non-zero enables
 379      * sync and does an fsync().
 380      */
 381     krb5_error_code (*hdb_set_sync)(krb5_context, struct HDB *, int);
 382 }HDB;
 383
 384 #define HDB_INTERFACE_VERSION   11
 385
 386 struct hdb_method {
 387     int                 version;
 388     unsigned int        is_file_based:1;
 389     unsigned int        can_taste:1;
 390     krb5_error_code     (*init)(krb5_context, void **);
 391     void                (*fini)(void *);
 392     const char *prefix;
 393     krb5_error_code (*create)(krb5_context, HDB **, const char *filename);
 394 };
 395
 396 /* dump entry format, for hdb_print_entry() */
 397 typedef enum hdb_dump_format {
 398     HDB_DUMP_HEIMDAL = 0,
 399     HDB_DUMP_MIT = 1,
 400 } hdb_dump_format_t;
 401
 402 struct hdb_print_entry_arg {
 403     FILE *out;
 404     hdb_dump_format_t fmt;
 405 };
 406
 407 typedef krb5_error_code (*hdb_foreach_func_t)(krb5_context, HDB*,
 408                                               hdb_entry_ex*, void*);
 409 extern krb5_kt_ops hdb_kt_ops;
 410 extern krb5_kt_ops hdb_get_kt_ops;
 411
 412 extern const int hdb_interface_version;
 413
 414 #include <hdb-protos.h>
 415
 416 #endif /* __HDB_H__ */