diff options
Diffstat (limited to 'contrib/pam_modules/pam_passwdqc/libpasswdqc.3')
| -rw-r--r-- | contrib/pam_modules/pam_passwdqc/libpasswdqc.3 | 211 |
1 files changed, 211 insertions, 0 deletions
diff --git a/contrib/pam_modules/pam_passwdqc/libpasswdqc.3 b/contrib/pam_modules/pam_passwdqc/libpasswdqc.3 new file mode 100644 index 000000000000..197ea4d49ff4 --- /dev/null +++ b/contrib/pam_modules/pam_passwdqc/libpasswdqc.3 @@ -0,0 +1,211 @@ +.\" 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 <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(¶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. |