passwdqc_params_free(3)

1LIBPASSWDQC(3)           BSD Library Functions Manual           LIBPASSWDQC(3)
2

NAME

4     passwdqc_params_reset, passwdqc_params_load, passwdqc_params_parse,
5     passwdqc_params_free, passwdqc_check, passwdqc_random — password strength
6     checking functions
7

LIBRARY

9     Password strength checking library (libpasswdqc, -lpasswdqc)
10

SYNOPSIS

12     #include <passwdqc.h>
13
14     typedef struct {
15             passwdqc_params_qc_t qc;
16             passwdqc_params_pam_t pam;
17     } passwdqc_params_t;
18
19     void
20     passwdqc_params_reset(passwdqc_params_t *params);
21
22     int
23     passwdqc_params_load(passwdqc_params_t *params, char **reason,
24         const char *pathname);
25
26     int
27     passwdqc_params_parse(passwdqc_params_t *params, char **reason, int argc,
28         const char *const *argv);
29
30     void
31     passwdqc_params_free(passwdqc_params_t *params);
32
33     const char *
34     passwdqc_check(const passwdqc_params_qc_t *params, const char *newpass,
35         const char *oldpass, const struct passwd *pw);
36
37     char *
38     passwdqc_random(const passwdqc_params_qc_t *params);
39

DESCRIPTION

41     The passwdqc_params_reset() function initializes the passwdqc_params_t
42     structure specified by params argument to compile-time defaults.
43
44     The passwdqc_params_load() function fills in the passwdqc_params_t struc‐
45     ture specified by params argument according to the configuration options
46     listed in the file specified by pathname argument.  When the pass‐
47     wdqc_params_t structure is no longer needed, the memory allocated by this
48     function should be released using passwdqc_params_free().
49
50     The passwdqc_params_parse() function fills in the passwdqc_params_t
51     structure specified by params argument according to the configuration op‐
52     tions specified by argc and argv arguments.  When the passwdqc_params_t
53     structure is no longer needed, the memory allocated by this function
54     should be released using passwdqc_params_free().
55
56     The passwdqc_params_free() function frees the memory allocated by
57     passwdqc_params_load() and passwdqc_params_parse() functions when filling
58     in the passwdqc_params_t structure specified by params argument.
59
60     The passwdqc_check() function checks the quality of the passphrase speci‐
61     fied by newpass argument according to the configuration specified by
62     params argument.  If an optional old passphrase is specified by oldpass
63     argument, newpass is additionally checked against oldpass for similarity.
64     If an optional passwd record is specified by pw argument, newpass is ad‐
65     ditionally checked whether it is based on the personal login information
66     in the passwd record.
67
68     The passwdqc_random() function generates a random passphrase according to
69     the configuration specified by params argument.
70

RETURN VALUES

72     The passwdqc_params_reset() and passwdqc_params_free() functions do not
73     return a value.
74
75     Upon successful completion the passwdqc_params_load() and
76     passwdqc_params_parse() functions return 0.  Otherwise, -1 is returned
77     and a pointer to dynamically allocated memory containing the error string
78     is assigned to *reason.  This memory should be released using free(3)
79     when no longer needed.
80
81     Upon successful completion the passwdqc_check() function returns NULL.
82     Otherwise, a string describing the error is returned.  The returned
83     string is statically allocated and valid for the lifetime of the program.
84
85     Upon successful completion the passwdqc_random() function returns a dy‐
86     namically allocated string containing the generated passphrase.  Other‐
87     wise, NULL is returned.  The string should be released using free(3) when
88     no longer needed.
89

FILES

91     /etc/passwdqc.conf (not read unless this suggested file location is spec‐
92     ified with the pathname argument or with config=/etc/passwdqc.conf con‐
93     figuration option).
94

EXAMPLES

96     The following example shows how to use the libpasswdqc library with sys‐
97     tem configuration options to check a passphrase.
98
99       #include <passwdqc.h>
100       #include <stdbool.h>
101       #include <stdlib.h>
102       #include <stdio.h>
103
104       bool
105       check(const char *newpass, const char *oldpass, const struct passwd *pw)
106       {
107         static const char config[] = "/etc/passwdqc.conf";
108         char *parse_reason;
109         const char *check_result = "";
110         passwdqc_params_t params;
111         passwdqc_params_reset(&params);
112         if (passwdqc_params_load(&params, &parse_reason, config)) {
113           fprintf(stderr, "passwdqc_params_load: %s\n",
114             parse_reason ? parse_reason : "Out of memory");
115           free(parse_reason);
116           goto out;
117         }
118         check_result = passwdqc_check(&params.qc, newpass, oldpass, pw);
119         if (check_result)
120           fprintf(stderr, "passwdqc_check: %s\n", check_result);
121       out:
122         passwdqc_params_free(&params);
123         return !check_result;
124       }
125

HISTORY

132     The pam_passwdqc module was written for Openwall GNU/*/Linux by Solar De‐
133     signer.  The libpasswdqc library was originally written for ALT
134     GNU/*/Linux by Dmitry V. Levin, reusing code from pam_passwdqc.  The
135     passwdqc_params_free() function was added in version 2.0.0 by Solar De‐
136     signer.
137

AUTHORS

139     This manual page was written by Dmitry V. Levin.
140
141Openwall Project                March 19, 2021                Openwall Project