Skip to content

Commit 127ae1f

Browse files
ldv-altsolardiz
ldv-alt
authored and
solardiz
committed
Add libpasswdqc(3) manual page
1 parent 4f43142 commit 127ae1f

File tree

5 files changed

+213
-0
lines changed

5 files changed

+213
-0
lines changed

‎Makefile

+5
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ SHLIBMODE = 755
1919
HEADER = passwdqc.h
2020
INCMODE = 644
2121
MAN1 = pwqgen.1 pwqcheck.1 pwqfilter.1
22+
MAN3 = libpasswdqc.3
2223
MAN5 = passwdqc.conf.5
2324
MAN8 = $(TITLE).8
2425
MANMODE = 644
@@ -199,6 +200,9 @@ install_lib_wrapped:
199200
$(MKDIR) $(DESTDIR)$(INCLUDEDIR)
200201
$(INSTALL) -m $(INCMODE) $(HEADER) $(DESTDIR)$(INCLUDEDIR)/
201202

203+
$(MKDIR) $(DESTDIR)$(MANDIR)/man3
204+
$(INSTALL) -m $(MANMODE) $(MAN3) $(DESTDIR)$(MANDIR)/man3/
205+
202206
$(MKDIR) $(DESTDIR)$(MANDIR)/man5
203207
$(INSTALL) -m $(MANMODE) $(MAN5) $(DESTDIR)$(MANDIR)/man5/
204208

@@ -255,6 +259,7 @@ remove_utils_wrapped:
255259

256260
remove_lib_wrapped:
257261
for f in $(MAN5); do $(RM) $(DESTDIR)$(MANDIR)/man5/$$f; done
262+
for f in $(MAN3); do $(RM) $(DESTDIR)$(MANDIR)/man3/$$f; done
258263
for f in $(HEADER); do $(RM) $(DESTDIR)$(INCLUDEDIR)/$$f; done
259264
for f in $(DEVEL_LIB); do $(RM) $(DESTDIR)$(DEVEL_LIBDIR)/$$f; done
260265
for f in $(SHARED_LIB); do $(RM) $(DESTDIR)$(SHARED_LIBDIR)/$$f; done

‎libpasswdqc.3

+205
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,205 @@
1+
.\" Copyright (c) 2021 Dmitry V. Levin
2+
.\" All rights reserved.
3+
.\"
4+
.\" Redistribution and use in source and binary forms, with or without
5+
.\" modification, are permitted.
6+
.\"
7+
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
8+
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
9+
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
10+
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
11+
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
12+
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
13+
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
14+
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
15+
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
16+
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
17+
.\" SUCH DAMAGE.
18+
.\"
19+
.Dd March 19, 2021
20+
.Dt LIBPASSWDQC 3
21+
.Os "Openwall Project"
22+
.Sh NAME
23+
.Nm passwdqc_params_reset ,
24+
.Nm passwdqc_params_load ,
25+
.Nm passwdqc_params_parse ,
26+
.Nm passwdqc_params_free ,
27+
.Nm passwdqc_check ,
28+
.Nm passwdqc_random
29+
.Nd password strength checking functions
30+
.Sh LIBRARY
31+
Password strength checking library
32+
.Pq libpasswdqc, -lpasswdqc
33+
.Sh SYNOPSIS
34+
.In passwdqc.h
35+
.Ft void
36+
.Fn passwdqc_params_reset "passwdqc_params_t *params"
37+
.Ft int
38+
.Fo passwdqc_params_load
39+
.Fa "passwdqc_params_t *params"
40+
.Fa "char **reason"
41+
.Fa "const char *pathname"
42+
.Fc
43+
.Ft int
44+
.Fo passwdqc_params_parse
45+
.Fa "passwdqc_params_t *params"
46+
.Fa "char **reason"
47+
.Fa "int argc"
48+
.Fa "const char *const *argv"
49+
.Fc
50+
.Ft void
51+
.Fn passwdqc_params_free "passwdqc_params_t *params"
52+
.Ft const char *
53+
.Fo passwdqc_check
54+
.Fa "const passwdqc_params_qc_t *params"
55+
.Fa "const char *newpass"
56+
.Fa "const char *oldpass"
57+
.Fa "const struct passwd *pw"
58+
.Fc
59+
.Ft char *
60+
.Fn passwdqc_random "const passwdqc_params_qc_t *params"
61+
.Sh DESCRIPTION
62+
The
63+
.Fn passwdqc_params_reset
64+
function initializes the passwdqc_params_t structure specified by
65+
.Fa params
66+
argument to compile-time defaults.
67+
.Pp
68+
The
69+
.Fn passwdqc_params_load
70+
function fills in the passwdqc_params_t structure specified by
71+
.Fa params
72+
argument according to the configuration options listed in the file specified by
73+
.Fa pathname
74+
argument. When the passwdqc_params_t structure is no longer needed,
75+
the memory allocated by this function should be released using
76+
.Fn passwdqc_params_free .
77+
.Pp
78+
The
79+
.Fn passwdqc_params_parse
80+
function fills in the passwdqc_params_t structure specified by
81+
.Fa params
82+
argument according to the configuration options specified by
83+
.Fa argc
84+
and
85+
.Fa argv
86+
arguments. When the passwdqc_params_t structure is no longer needed,
87+
the memory allocated by this function should be released using
88+
.Fn passwdqc_params_free .
89+
.Pp
90+
The
91+
.Fn passwdqc_params_free
92+
function frees the memory allocated by
93+
.Fn passwdqc_params_load
94+
and
95+
.Fn passwdqc_params_parse
96+
functions when filling in the passwdqc_params_t structure specified by
97+
.Fa params
98+
argument.
99+
.Pp
100+
The
101+
.Fn passwdqc_check
102+
function checks the quality of the passphrase specified by
103+
.Fa newpass
104+
argument according to the configuration specified by
105+
.Fa params
106+
argument. If an optional old passphrase is specified by
107+
.Fa oldpass
108+
argument,
109+
.Fa newpass
110+
is additionally checked against
111+
.Fa oldpass
112+
for similarity. If an optional passwd record is specified by
113+
.Fa pw
114+
argument,
115+
.Fa newpass
116+
is additionally checked whether it is based on the personal login information
117+
in the passwd record.
118+
.Pp
119+
The
120+
.Fn passwdqc_random
121+
function generates a random passphrase according to the configuration
122+
specified by
123+
.Fa params
124+
argument.
125+
.Sh RETURN VALUES
126+
The
127+
.Fn passwdqc_params_reset
128+
and
129+
.Fn passwdqc_params_free
130+
functions do not return a value.
131+
.Pp
132+
Upon successful completion the
133+
.Fn passwdqc_params_load
134+
and
135+
.Fn passwdqc_params_parse
136+
functions return 0. Otherwise, -1 is returned and a pointer to dynamically
137+
allocated memory containing the error string is assigned to
138+
.Fa *reason .
139+
This memory should be released using free(3) when no longer needed.
140+
.Pp
141+
Upon successful completion the
142+
.Fn passwdqc_check
143+
function returns NULL. Otherwise, a string describing the error is returned.
144+
The returned string is statically allocated and valid for the lifetime of the
145+
program.
146+
.Pp
147+
Upon successful completion the
148+
.Fn passwdqc_random
149+
function returns a dynamically allocated string containing the generated
150+
passphrase. Otherwise, NULL is returned. The string should be released using
151+
free(3) when no longer needed.
152+
.Sh FILES
153+
.Pa /etc/passwdqc.conf
154+
(not read unless this suggested file location is specified with the
155+
.Ar pathname
156+
argument or with
157+
.Cm config Ns = Ns Ar /etc/passwdqc.conf
158+
configuration option).
159+
.Sh EXAMPLES
160+
The following example shows how to use the libpasswdqc library with system
161+
configuration options to check a passphrase.
162+
.Bd -literal -offset 2n
163+
#include <passwdqc.h>
164+
#include <stdbool.h>
165+
#include <stdlib.h>
166+
#include <stdio.h>
167+
168+
bool
169+
check(const char *newpass, const char *oldpass, const struct passwd *pw)
170+
{
171+
static const char config[] = "/etc/passwdqc.conf";
172+
char *parse_reason;
173+
const char *check_result = "";
174+
passwdqc_params_t params;
175+
passwdqc_params_reset(&params);
176+
if (passwdqc_params_load(&params, &parse_reason, config)) {
177+
fprintf(stderr, "passwdqc_params_load: %s\en",
178+
parse_reason ? parse_reason : "Out of memory");
179+
free(parse_reason);
180+
goto out;
181+
}
182+
check_result = passwdqc_check(&params.qc, newpass, oldpass, pw);
183+
if (check_result)
184+
fprintf(stderr, "passwdqc_check: %s\en", check_result);
185+
out:
186+
passwdqc_params_free(&params);
187+
return !check_result;
188+
}
189+
.Ed
190+
.Sh SEE ALSO
191+
.Xr passwdqc.conf 5 ,
192+
.Xr pwqcheck 1 ,
193+
.Xr pwqgen 1 ,
194+
.Xr pam_passwdqc 8 .
195+
.Pp
196+
https://www.openwall.com/passwdqc/
197+
.Sh HISTORY
198+
The pam_passwdqc module was written for Openwall GNU/*/Linux by Solar Designer.
199+
The libpasswdqc library was originally written for ALT GNU/*/Linux
200+
by Dmitry V. Levin, reusing code from pam_passwdqc.
201+
The
202+
.Fn passwdqc_params_free
203+
function was added in version 2.0.0 by Solar Designer.
204+
.Sh AUTHORS
205+
This manual page was written by Dmitry V. Levin.

‎passwdqc.conf.5

+1
Original file line numberDiff line numberDiff line change
@@ -286,6 +286,7 @@ logging.
286286
option).
287287
.Sh SEE ALSO
288288
.Xr getpwnam 3 ,
289+
.Xr libpasswdqc 3 ,
289290
.Xr pam_passwdqc 8 .
290291
.Pp
291292
https://www.openwall.com/passwdqc/

‎pwqcheck.1

+1
Original file line numberDiff line numberDiff line change
@@ -253,6 +253,7 @@ also exits with non-zero status when it detects a weak passphrase.
253253
option).
254254
.Sh SEE ALSO
255255
.Xr pwqgen 1 ,
256+
.Xr libpasswdqc 3 ,
256257
.Xr passwd 5 ,
257258
.Xr passwdqc.conf 5 ,
258259
.Xr pam_passwdqc 8 .

‎pwqgen.1

+1
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,7 @@ randomness, and in any case when it fails to generate a passphrase.
7171
option).
7272
.Sh SEE ALSO
7373
.Xr pwqcheck 1 ,
74+
.Xr libpasswdqc 3 ,
7475
.Xr urandom 4 ,
7576
.Xr passwdqc.conf 5 ,
7677
.Xr pam_passwdqc 8 .

0 commit comments

Comments
 (0)