LIBPASSWDQC(3)

💖 LIBPASSWDQC 💖

okay bestie, sit down, hydrate, because we're about to talk about the libpasswdqc library functions manual and honestly? it's giving security queen energy 🔥 this whole page lives in section 3 of the manual, it's all about password strength checking functions, and yes it ate. no cap.

---

✨ NAME ✨

passwdqc_params_reset, passwdqc_params_load, passwdqc_params_parse, passwdqc_params_free, passwdqc_check, passwdqc_random — password strength checking functions

like… six whole functions. one friend group. iconic. 👑

---

🌈 LIBRARY 🌈

Password strength checking library (libpasswdqc, -lpasswdqc)

so when you're linking, you link -lpasswdqc and the lib is literally called libpasswdqc. that's it, that's the vibe. 💅

---

🎀 SYNOPSIS 🎀

okay here's the whole cast list, exactly as written, no edits:

#include <passwdqc.h>

typedef struct {
        passwdqc_params_qc_t qc;
        passwdqc_params_pam_t pam;
} passwdqc_params_t;

void
passwdqc_params_reset(passwdqc_params_t *params);

int
passwdqc_params_load(passwdqc_params_t *params, char **reason,
    const char *pathname);

int
passwdqc_params_parse(passwdqc_params_t *params, char **reason,
    int argc, const char *const *argv);

void
passwdqc_params_free(passwdqc_params_t *params);

const char *
passwdqc_check(const passwdqc_params_qc_t *params, const char *newpass,
    const char *oldpass, const struct passwd *pw);

char *
passwdqc_random(const passwdqc_params_qc_t *params);

look at that struct. passwdqc_params_t is just a qc and a pam holding hands. main character energy fr fr. 🫶

---

🌸 DESCRIPTION 🌸

so like, here's what everybody does:

passwdqc_params_reset() — this one sets up the passwdqc_params_t structure you point at with the params argument, and it fills it with the compile-time defaults. it's the "start fresh, bestie" function. 🧚

passwdqc_params_load() — this one fills in the passwdqc_params_t structure named by the params argument, based on the configuration options it finds listed in the file named by the pathname argument. and listen — when you're done with that passwdqc_params_t structure, you have to release the memory this function allocated by calling passwdqc_params_free(). do not ghost your malloc'd memory. that's rude. 😭

passwdqc_params_parse() — same deal but instead of a file it fills in the passwdqc_params_t structure named by params according to the configuration options handed over in the argc and argv arguments. and again: when the structure's no longer needed, free that memory with passwdqc_params_free(). ✨

passwdqc_params_free() — the cleanup queen 👑 she frees the memory that passwdqc_params_load() and passwdqc_params_parse() allocated while filling in the passwdqc_params_t structure named by the params argument. she's the friend who helps you move out of the apartment.

passwdqc_check() — okay so this one checks the quality of the passphrase in the newpass argument, according to the config in the params argument. if you also pass an optional old passphrase in oldpass, then newpass gets additionally checked against oldpass for similarity (so you can't just change one letter, we see you 👀). and if you pass an optional passwd record in pw, then newpass is additionally checked to see whether it's based on the personal login information inside that passwd record. like no, you cannot make your password your own username. not today.

passwdqc_random() — generates a random passphrase according to the configuration in the params argument. free password generator, literally. 🎲

---

💀 RETURN VALUES 💀

passwdqc_params_reset() and passwdqc_params_free() — they do not return a value. they said "we're above that". 💅

passwdqc_params_load() and passwdqc_params_parse() — when everything goes right they return 0. otherwise they return -1, and a pointer to dynamically allocated memory holding the error string gets assigned to *reason. that memory should be released using free(3) once you don't need it anymore. don't forget. i'm serious.

passwdqc_check() — on success it returns NULL. otherwise you get back a string describing the error. heads up: that returned string is statically allocated and stays valid for the lifetime of the program, so don't you dare free() it. 🙈

passwdqc_random() — on success it returns a dynamically allocated string containing the generated passphrase. otherwise NULL. and you should release that string using free(3) when you're done with it.

⚠️ bestie the pattern here is: dynamically allocated = you free it. statically allocated = you do NOT. mixing those up is a whole horror movie. 😭

---

🦋 FILES 🦋

• /etc/passwdqc.conf (not read unless this suggested file location is specified with the pathname argument or with config=/etc/passwdqc.conf configuration option).

so yeah, she's not reading that file unless you literally tell her to. no unsolicited file reads. boundaries. ✨

---

🍓 EXAMPLES 🍓

here's how you use the libpasswdqc library with system configuration options to check a passphrase — verbatim, so copy it exactly:

#include <passwdqc.h>
#include <stdbool.h>
#include <stdlib.h>
#include <stdio.h>

bool
check(const char *newpass, const char *oldpass, const struct passwd *pw)
{
  static const char config[] = "/etc/passwdqc.conf";
  char *parse_reason;
  const char *check_result = "";
  passwdqc_params_t params;
  passwdqc_params_reset(&params);
  if (passwdqc_params_load(&params, &parse_reason, config)) {
    fprintf(stderr, "passwdqc_params_load: %s\n",
      parse_reason ? parse_reason : "Out of memory");
    free(parse_reason);
    goto out;
  }
  check_result = passwdqc_check(&params.qc, newpass, oldpass, pw);
  if (check_result)
    fprintf(stderr, "passwdqc_check: %s\n", check_result);
out:
  passwdqc_params_free(&params);
  return !check_result;
}

see how she resets → loads → checks → frees? that's the whole cycle. the way that goto out handles cleanup is honestly so valid. 🌟

---

💜 SEE ALSO 💜

• passwdqc.conf(5), pwqcheck(1), pwqgen(1), pam_passwdqc(8).
• https://www.openwall.com/passwdqc/

go read those too, i'm not kidding, expand your horizons. 🌈

---

🔥 HISTORY 🔥

so the lore is: the pam_passwdqc module was written for Openwall GNU//Linux by Solar Designer. the libpasswdqc library was originally written for ALT GNU//Linux by Dmitry V. Levin, reusing code from pam_passwdqc. and the passwdqc_params_free() function was added in version 2.0.0 by Solar Designer. ✨ the way that function joined the group chat in 2.0.0… we love a late arrival who slays. 🎀

---

🌟 AUTHORS 🌟

This manual page was written by Dmitry V. Levin.

---

and that's the whole page, bestie!! 💖 this manual came to you from the Openwall Project, dated March 19, 2021, living in section LIBPASSWDQC(3) — now go free your memory and protect your passwords. mwah 🫶✨