.\" Copyright (c) 2021 Dmitry V. Levin .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .Dd March 19, 2021 .Dt LIBPASSWDQC 3 .Os "Openwall Project" .Sh NAME .Nm passwdqc_params_reset , .Nm passwdqc_params_load , .Nm passwdqc_params_parse , .Nm passwdqc_params_free , .Nm passwdqc_check , .Nm passwdqc_random .Nd password strength checking functions .Sh LIBRARY Password strength checking library .Pq libpasswdqc, -lpasswdqc .Sh SYNOPSIS .In passwdqc.h .Bd -literal typedef struct { passwdqc_params_qc_t qc; passwdqc_params_pam_t pam; } passwdqc_params_t; .Ed .Ft void .Fn passwdqc_params_reset "passwdqc_params_t *params" .Ft int .Fo passwdqc_params_load .Fa "passwdqc_params_t *params" .Fa "char **reason" .Fa "const char *pathname" .Fc .Ft int .Fo passwdqc_params_parse .Fa "passwdqc_params_t *params" .Fa "char **reason" .Fa "int argc" .Fa "const char *const *argv" .Fc .Ft void .Fn passwdqc_params_free "passwdqc_params_t *params" .Ft const char * .Fo passwdqc_check .Fa "const passwdqc_params_qc_t *params" .Fa "const char *newpass" .Fa "const char *oldpass" .Fa "const struct passwd *pw" .Fc .Ft char * .Fn passwdqc_random "const passwdqc_params_qc_t *params" .Sh DESCRIPTION The .Fn passwdqc_params_reset function initializes the passwdqc_params_t structure specified by .Fa params argument to compile-time defaults. .Pp The .Fn passwdqc_params_load function fills in the passwdqc_params_t structure specified by .Fa params argument according to the configuration options listed in the file specified by .Fa pathname argument. When the passwdqc_params_t structure is no longer needed, the memory allocated by this function should be released using .Fn passwdqc_params_free . .Pp The .Fn passwdqc_params_parse function fills in the passwdqc_params_t structure specified by .Fa params argument according to the configuration options specified by .Fa argc and .Fa argv arguments. When the passwdqc_params_t structure is no longer needed, the memory allocated by this function should be released using .Fn passwdqc_params_free . .Pp The .Fn passwdqc_params_free function frees the memory allocated by .Fn passwdqc_params_load and .Fn passwdqc_params_parse functions when filling in the passwdqc_params_t structure specified by .Fa params argument. .Pp The .Fn passwdqc_check function checks the quality of the passphrase specified by .Fa newpass argument according to the configuration specified by .Fa params argument. If an optional old passphrase is specified by .Fa oldpass argument, .Fa newpass is additionally checked against .Fa oldpass for similarity. If an optional passwd record is specified by .Fa pw argument, .Fa newpass is additionally checked whether it is based on the personal login information in the passwd record. .Pp The .Fn passwdqc_random function generates a random passphrase according to the configuration specified by .Fa params argument. .Sh RETURN VALUES The .Fn passwdqc_params_reset and .Fn passwdqc_params_free functions do not return a value. .Pp Upon successful completion the .Fn passwdqc_params_load and .Fn passwdqc_params_parse functions return 0. Otherwise, -1 is returned and a pointer to dynamically allocated memory containing the error string is assigned to .Fa *reason . This memory should be released using free(3) when no longer needed. .Pp Upon successful completion the .Fn 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. .Pp Upon successful completion the .Fn 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. .Sh FILES .Pa /etc/passwdqc.conf (not read unless this suggested file location is specified with the .Ar pathname argument or with .Cm config Ns = Ns Ar /etc/passwdqc.conf configuration option). .Sh EXAMPLES The following example shows how to use the libpasswdqc library with system configuration options to check a passphrase. .Bd -literal -offset 2n #include #include #include #include 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(¶ms); if (passwdqc_params_load(¶ms, &parse_reason, config)) { fprintf(stderr, "passwdqc_params_load: %s\en", parse_reason ? parse_reason : "Out of memory"); free(parse_reason); goto out; } check_result = passwdqc_check(¶ms.qc, newpass, oldpass, pw); if (check_result) fprintf(stderr, "passwdqc_check: %s\en", check_result); out: passwdqc_params_free(¶ms); return !check_result; } .Ed .Sh SEE ALSO .Xr passwdqc.conf 5 , .Xr pwqcheck 1 , .Xr pwqgen 1 , .Xr pam_passwdqc 8 . .Pp https://www.openwall.com/passwdqc/ .Sh 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 .Fn passwdqc_params_free function was added in version 2.0.0 by Solar Designer. .Sh AUTHORS This manual page was written by Dmitry V. Levin.