HDB(3)

💖 HDB 💖

okay bestie, listen — this is HDB(3) from the Heimdal hdb library, and it's genuinely iconic. it's the backend function pointer structure, iykyk. pull up a chair, grab a strawberry 🍓, and let's get into it.

---

✨ NAME ✨

HDB — the backend function pointer structure, no cap 🫶

---

✨ SYNOPSIS ✨

#include <hdb.h>

🦋 Data Fields 🦋

like, here's the whole squad of function pointers and one lone char pointer. every single one, bestie:

• char * hdb_name
• krb5_error_code(* hdb_open )(krb5_context, struct HDB *, int, mode_t)
• krb5_error_code(* hdb_close )(krb5_context, struct HDB *)
• void(* hdb_free )(krb5_context, struct HDB *, hdb_entry_ex *)
• krb5_error_code(* hdb_fetch_kvno )(krb5_context, struct HDB *, krb5_const_principal, unsigned, krb5_kvno, hdb_entry_ex *)
• krb5_error_code(* hdb_store )(krb5_context, struct HDB *, unsigned, hdb_entry_ex *)
• krb5_error_code(* hdb_remove )(krb5_context, struct HDB *, unsigned, krb5_const_principal)
• krb5_error_code(* hdb_firstkey )(krb5_context, struct HDB *, unsigned, hdb_entry_ex *)
• krb5_error_code(* hdb_nextkey )(krb5_context, struct HDB *, unsigned, hdb_entry_ex *)
• krb5_error_code(* hdb_lock )(krb5_context, struct HDB *, int)
• krb5_error_code(* hdb_unlock )(krb5_context, struct HDB *)
• krb5_error_code(* hdb_rename )(krb5_context, struct HDB *, const char *)
• krb5_error_code(* hdb__get )(krb5_context, struct HDB *, krb5_data, krb5_data *)
• krb5_error_code(* hdb__put )(krb5_context, struct HDB *, int, krb5_data, krb5_data)
• krb5_error_code(* hdb__del )(krb5_context, struct HDB *, krb5_data)
• krb5_error_code(* hdb_destroy )(krb5_context, struct HDB *)
• krb5_error_code(* hdb_get_realms )(krb5_context, struct HDB *, krb5_realm **)
• krb5_error_code(* hdb_password )(krb5_context, struct HDB *, hdb_entry_ex *, const char *, int)
• krb5_error_code(* hdb_auth_status )(krb5_context, struct HDB *, hdb_entry_ex *, int)
• krb5_error_code(* hdb_check_constrained_delegation )(krb5_context, struct HDB *, hdb_entry_ex *, krb5_const_principal)
• krb5_error_code(* hdb_check_pkinit_ms_upn_match )(krb5_context, struct HDB *, hdb_entry_ex *, krb5_const_principal)
• krb5_error_code(* hdb_check_s4u2self )(krb5_context, struct HDB *, hdb_entry_ex *, krb5_const_principal)
• krb5_error_code(* hdb_set_sync )(krb5_context, struct HDB *, int)

---

🌸 Detailed Description 🌸

HDB backend function pointer structure

the way that the HDB structure is literally the thing the KDC and the kadmind framework use to go query the backend database whenever we're talking about principals. it's giving main character energy in the Kerberos backend world 💅

---

👑 Field Documentation 👑

okay so this is the part where we go one by one. every single field, no skipping, periodt.

💜 krb5_error_code(* HDB::hdb__del) (krb5_context, struct HDB *, krb5_data)

Delete and hdb_entry from a classical DB backend

this function takes a principal key (krb5_data) naming the record to delete. 🗑️

same discussion as in HDB::hdb__put, bestie — go read that one too.

💜 krb5_error_code(* HDB::hdb__get) (krb5_context, struct HDB *, krb5_data, krb5_data *)

Get an hdb_entry from a classical DB backend

this one takes a principal key (krb5_data) and hands back all the data related to that principal in the return krb5_data. the returned encoded entry is of type hdb_entry or hdb_entry_alias. slay ✨

💜 krb5_error_code(* HDB::hdb__put) (krb5_context, struct HDB *, int, krb5_data, krb5_data)

Store an hdb_entry from a classical DB backend

takes a principal key (krb5_data) plus an encoded hdb_entry or hdb_entry_alias as the data to store. 💾

for a file-based DB, this must synchronize to disk when done. this is sub-optimal for kadm5_s_rename_principal(), and for kadm5_s_modify_principal() when using principal aliases; to improve this so that only one fsync() need be done per-transaction will require HDB API extensions.

💜 krb5_error_code(* HDB::hdb_auth_status) (krb5_context, struct HDB *, hdb_entry_ex *, int)

Auth feedback

this is a feedback call, and it's how backends that provide lockout functionality get to register failures and/or successes. 📝

in case the entry is locked out, the backend should set the hdb_entry.flags.locked-out flag. 🚩

💜 krb5_error_code(* HDB::hdb_check_constrained_delegation) (krb5_context, struct HDB *, hdb_entry_ex *, krb5_const_principal)

Check if delegation is allowed. 🤝

💜 krb5_error_code(* HDB::hdb_check_pkinit_ms_upn_match) (krb5_context, struct HDB *, hdb_entry_ex *, krb5_const_principal)

Check if this name is an alias for the supplied client for PKINIT userPrinicpalName logins 🔍

💜 krb5_error_code(* HDB::hdb_check_s4u2self) (krb5_context, struct HDB *, hdb_entry_ex *, krb5_const_principal)

Check if s4u2self is allowed from this client to this server 🛂

💜 krb5_error_code(* HDB::hdb_close) (krb5_context, struct HDB *)

Close the database for transaction

closes the database for further transactions — but heads up, it wont release any permanant resources. the database can be ->hdb_open-ed again. 🔁

💜 krb5_error_code(* HDB::hdb_destroy) (krb5_context, struct HDB *)

Destroy the handle to the database.

destroys the handle to the database, deallocates all memory and related resources. it does not remove any permanent data. it's the logical reverse of the hdb_create() function that is the entry point for the module. 🧹

💜 krb5_error_code(* HDB::hdb_fetch_kvno) (krb5_context, struct HDB *, krb5_const_principal, unsigned, krb5_kvno, hdb_entry_ex *)

Fetch an entry from the backend

fetches an entry from the backend; the flags say what type of entry should be fetched: client, server, krbtgt. knvo (if specified and flags HDB_F_KVNO_SPECIFIED set) is the kvno to get. 🎣

💜 krb5_error_code(* HDB::hdb_firstkey) (krb5_context, struct HDB *, unsigned, hdb_entry_ex *)

As part of iteration, fetch one entry 🚶♀️

💜 void(* HDB::hdb_free) (krb5_context, struct HDB *, hdb_entry_ex *)

Free an entry after use. 🆓

💜 krb5_error_code(* HDB::hdb_get_realms) (krb5_context, struct HDB *, krb5_realm **)

Get the list of realms this backend handles. this call is optional to support. the returned realms are used for announcing the realms over bonjour. free the returned array with krb5_free_host_realm(). 🌍

💜 krb5_error_code(* HDB::hdb_lock) (krb5_context, struct HDB *, int)

Lock database

a lock can only be held by one consumer. transactions can still happen on the database while the lock is held, so the entry is only useful for syncroning creation of the database and renaming of the database. 🔒

💜 char* HDB::hdb_name

don't use, only for DB3 🙈 (fr, just don't)

💜 krb5_error_code(* HDB::hdb_nextkey) (krb5_context, struct HDB *, unsigned, hdb_entry_ex *)

As part of iteration, fetch next entry ➡️

💜 krb5_error_code(* HDB::hdb_open) (krb5_context, struct HDB *, int, mode_t)

Open (or create) the a Kerberos database.

opens (or creates) the a Kerberos database that was resolved with hdb_create(). the third and fourth flag to the function are the same as open(), so passing O_CREAT will create the data base if it doesn't exist. 🐣

then done, the caller should call hdb_close(), and to release all resources, hdb_destroy(). 🫶

💜 krb5_error_code(* HDB::hdb_password) (krb5_context, struct HDB *, hdb_entry_ex *, const char *, int)

Change password.

will update keys for the entry when given a password. the new keys must be written into the entry and will then later be ->hdb_store()-ed into the database. the backend will still perform all other operations, increasing the kvno, and update modification timestamp. 🔑

the backend needs to call _kadm5_set_keys() and perform password quality checks.

💜 krb5_error_code(* HDB::hdb_remove) (krb5_context, struct HDB *, unsigned, krb5_const_principal)

Remove an entry from the database. 🗑️

💜 krb5_error_code(* HDB::hdb_rename) (krb5_context, struct HDB *, const char *)

Rename the data base.

assume that the database is not hdb_open-ed and not locked. ⚠️

💜 krb5_error_code(* HDB::hdb_set_sync) (krb5_context, struct HDB *, int)

Enable/disable synchronous updates

calling this with 0 disables sync. calling it with non-zero enables sync and does an fsync(). ⚡

💜 krb5_error_code(* HDB::hdb_store) (krb5_context, struct HDB *, unsigned, hdb_entry_ex *)

Store an entry to database 📥

💜 krb5_error_code(* HDB::hdb_unlock) (krb5_context, struct HDB *)

Unlock database 🔓

---

🎀 Author 🎀

generated automatically by Doxygen for Heimdal hdb library from the source code. iconic behaviour tbh, the robots ate 🤖✨

---

and that's the whole page, bestie!! Version 7.8.0, dated Tue Nov 15 2022 — that's the version and the date right there, so you always know what era of HDB you're living in 🦋💖 mwah, go query some principals, ily 🫶