NAME

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

LIBRARY

     Password strength checking library (libpasswdqc, -lpasswdqc)

SYNOPSIS

     #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);

DESCRIPTION

     The passwdqc_params_reset() function initializes the passwdqc_params_t structure specified
     by params argument to compile-time defaults.

     The passwdqc_params_load() function fills in the passwdqc_params_t structure specified by
     params argument according to the configuration options listed in the file specified by
     pathname argument.  When the passwdqc_params_t structure is no longer needed, the memory
     allocated by this function should be released using passwdqc_params_free().

     The passwdqc_params_parse() function fills in the passwdqc_params_t structure specified by
     params argument according to the configuration options specified by argc and argv arguments.
     When the passwdqc_params_t structure is no longer needed, the memory allocated by this
     function should be released using passwdqc_params_free().

     The passwdqc_params_free() function frees the memory allocated by passwdqc_params_load() and
     passwdqc_params_parse() functions when filling in the passwdqc_params_t structure specified
     by params argument.

     The passwdqc_check() function checks the quality of the passphrase specified by newpass
     argument according to the configuration specified by params argument.  If an optional old
     passphrase is specified by oldpass argument, newpass is additionally checked against oldpass
     for similarity.  If an optional passwd record is specified by pw argument, newpass is
     additionally checked whether it is based on the personal login information in the passwd
     record.

     The passwdqc_random() function generates a random passphrase according to the configuration
     specified by params argument.

RETURN VALUES

     The passwdqc_params_reset() and passwdqc_params_free() functions do not return a value.

     Upon successful completion the passwdqc_params_load() and passwdqc_params_parse() functions
     return 0.  Otherwise, -1 is returned and a pointer to dynamically allocated memory
     containing the error string is assigned to *reason.  This memory should be released using
     free(3) when no longer needed.

     Upon successful completion the passwdqc_check() function returns NULL.  Otherwise, a string
     describing the error is returned.  The returned string is statically allocated and valid for
     the lifetime of the program.

     Upon successful completion the passwdqc_random() function returns a dynamically allocated
     string containing the generated passphrase.  Otherwise, NULL is returned.  The string should
     be released using free(3) when no longer needed.

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).

EXAMPLES

     The following example shows how to use the libpasswdqc library with system configuration
     options to check a passphrase.

       #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 ALSO

     passwdqc.conf(5), pwqcheck(1), pwqgen(1), pam_passwdqc(8).

     https://www.openwall.com/passwdqc/

HISTORY

     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.  The passwdqc_params_free() function was added in version 2.0.0 by
     Solar Designer.

AUTHORS

     This manual page was written by Dmitry V. Levin.