Debian Codegraph @

doc/man/pwquality.3

raw
1 .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
2 .\"
3 .\" Standard preamble:
4 .\" ========================================================================
5 .de Sp \" Vertical space (when we can't use .PP)
6 .if t .sp .5v
7 .if n .sp
8 ..
9 .de Vb \" Begin verbatim text
10 .ft CW
11 .nf
12 .ne \\$1
13 ..
14 .de Ve \" End verbatim text
15 .ft R
16 .fi
17 ..
18 .\" Set up some character translations and predefined strings. \*(-- will
19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
20 .\" double quote, and \*(R" will give a right double quote. \*(C+ will
21 .\" give a nicer C++. Capital omega is used to do unbreakable dashes and
22 .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
23 .\" nothing in troff, for use with C<>.
24 .tr \(*W-
25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
26 .ie n \{\
27 . ds -- \(*W-
28 . ds PI pi
29 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
31 . ds L" ""
32 . ds R" ""
33 . ds C` ""
34 . ds C' ""
35 'br\}
36 .el\{\
37 . ds -- \|\(em\|
38 . ds PI \(*p
39 . ds L" ``
40 . ds R" ''
41 . ds C`
42 . ds C'
43 'br\}
44 .\"
45 .\" Escape single quotes in literal strings from groff's Unicode transform.
46 .ie \n(.g .ds Aq \(aq
47 .el .ds Aq '
48 .\"
49 .\" If the F register is >0, we'll generate index entries on stderr for
50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
51 .\" entries marked with X<> in POD. Of course, you'll have to process the
52 .\" output yourself in some meaningful fashion.
53 .\"
54 .\" Avoid warning from groff about undefined register 'F'.
55 .de IX
56 ..
57 .nr rF 0
58 .if \n(.g .if rF .nr rF 1
59 .if (\n(rF:(\n(.g==0)) \{\
60 . if \nF \{\
61 . de IX
62 . tm Index:\\$1\t\\n%\t"\\$2"
63 ..
64 . if !\nF==2 \{\
65 . nr % 0
66 . nr F 2
67 . \}
68 . \}
69 .\}
70 .rr rF
71 .\" ========================================================================
72 .\"
73 .IX Title "PWQUALITY 3"
74 .TH PWQUALITY 3 "2021-04-01" "Red Hat, Inc." "Libpwquality API Manual"
75 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
76 .\" way too many mistakes in technical documents.
77 .if n .ad l
78 .nh
79 .SH "NAME"
80 pwquality \- Documentation of the libpwquality API
81 .SH "SYNOPSIS"
82 .IX Header "SYNOPSIS"
83 .Vb 1
84 \& #include <pwquality.h>
85 \&
86 \& pwquality_settings_t *pwquality_default_settings(void);
87 \& void pwquality_free_settings(pwquality_settings_t *pwq);
88 \&
89 \& int pwquality_read_config(pwquality_settings_t *pwq, const char *cfgfile,
90 \& void **auxerror);
91 \&
92 \& int pwquality_set_option(pwquality_settings_t *pwq, const char *option);
93 \& int pwquality_set_int_value(pwquality_settings_t *pwq, int setting, int value);
94 \& int pwquality_set_str_value(pwquality_settings_t *pwq, int setting,
95 \& const char *value);
96 \& int pwquality_get_int_value(pwquality_settings_t *pwq, int setting, int *value);
97 \& int pwquality_get_str_value(pwquality_settings_t *pwq, int setting, const char **value);
98 \&
99 \& int pwquality_generate(pwquality_settings_t *pwq, int entropy_bits,
100 \& char **password);
101 \&
102 \& int pwquality_check(pwquality_settings_t *pwq, const char *password,
103 \& const char *oldpassword, const char *user, void **auxerror);
104 \&
105 \& const char *pwquality_strerror(char *buf, size_t len, int errcode, void *auxerror);
106 .Ve
107 .SH "DESCRIPTION"
108 .IX Header "DESCRIPTION"
109 Function \fBpwquality_default_settings()\fR allocates and returns default pwquality
110 settings to be used in other library calls. The allocated opaque structure has
111 to be freed with the \fBpwquality_free_settings()\fR call.
112 .PP
113 The \fBpwquality_read_config()\fR parses the configuration file (if \fIcfgfile\fR is
114 \&\s-1NULL\s0 then the default one). If \fIauxerror\fR is not \s-1NULL\s0 it also possibly returns
115 auxiliary error information that must be passed into \fBpwquality_strerror()\fR
116 function.
117 .IP "\fBNew in 1.3.0:\fR" 4
118 .IX Item "New in 1.3.0:"
119 The library first tries to parse all \fI*.conf\fR configuration files from
120 \&\fI<cfgfile>.d\fR directory if it exists. Order of parsing determines what
121 values will be in effect \- the latest wins.
122 .PP
123 Function \fBpwquality_set_option()\fR is useful for setting the options as configured
124 on a pam module command line in form of \fIopt\fR=\fIval\fR.
125 .PP
126 Getter and setter functions for the individual integer and string setting
127 values are: \fBpwquality_set_int_value()\fR, \fBpwquality_set_str_value()\fR,
128 \&\fBpwquality_get_int_value()\fR, and \fBpwquality_get_str_value()\fR. In case of the
129 string getter the caller must copy the string before another calls that can
130 manipulate the \fIpwq\fR settings object.
131 .PP
132 The \fBpwquality_generate()\fR function generates a random password of
133 \&\fIentropy_bits\fR entropy and checks it according to the settings. The
134 \&\fI*password\fR is allocated on the heap by the library. The \fIentropy_bits\fR
135 value is adjusted to fit within the \fB\s-1PWQ_MIN_ENTROPY_BITS\s0\fR and
136 \&\fB\s-1PWQ_MAX_ENTROPY_BITS\s0\fR range before generating a password.
137 .PP
138 The \fBpwquality_check()\fR function checks the \fIpassword\fR according to the
139 settings. It returns either score (value between 0 and 100), negative
140 error number, and possibly also auxiliary error information that must be
141 passed into the \fBpwquality_strerror()\fR function.
142 The \fIoldpassword\fR is optional and can be \s-1NULL.\s0 The \fIuser\fR is used for
143 checking the \fIpassword\fR against the user name and potentially other
144 \&\fBpasswd\fR\|(5) information and can be \s-1NULL.\s0 The \fIauxerror\fR can be \s-1NULL\s0 \- in
145 that case the auxiliary error information is not returned. However if it is
146 non-NULL not passing the returned \fI*auxerror\fR into \fBpwquality_strerror()\fR can
147 lead to memory leaks.
148 .PP
149 The score of a password depends on the value of the setting
150 \&\fB\s-1PWQ_SETTING_MIN_LENGTH\s0\fR. If it is set higher, the score for the same
151 passwords will be lower.
152 .PP
153 Function \fBpwquality_strerror()\fR translates the \fIerrcode\fR and \fIauxerror\fR
154 auxiliary data into a localized text message. If \fIbuf\fR is \s-1NULL\s0 the function
155 uses an internal static buffer which makes the function non-reentrant in that
156 case. The returned pointer is not guaranteed to point to the \fIbuf\fR. The
157 function deallocates eventual \fIauxerror\fR data passed into it, thus it must
158 not be called twice with the same \fIauxerror\fR data.
159 .SH "RETURN VALUES"
160 .IX Header "RETURN VALUES"
161 In general the functions which return \fBint\fR return 0 as success value and
162 negative values as concrete \fB\s-1PWQ_ERROR\s0\fR error code. \fBpwquality_strerror()\fR does
163 not allocate data and so it cannot fail.
164 .PP
165 The returned positive or zero score from \fBpwquality_check()\fR should not be
166 used for rejection of passwords, it should be used only as approximate
167 indicator of entropy present in the password with values such as 0\-30 being
168 low, 30\-60 medium, and 60\-100 high.
169 .SH "EXAMPLE"
170 .IX Header "EXAMPLE"
171 Typical use of the libpwquality \s-1API:\s0
172 .PP
173 .Vb 1
174 \& #include <pwquality.h>
175 \&
176 \& ...
177 \&
178 \& pwquality_settings_t *pwq;
179 \& int rv;
180 \& void *auxerror;
181 \& char buf[PWQ_MAX_ERROR_MESSAGE_LEN];
182 \&
183 \& pwq = pwquality_default_settings();
184 \& if (pwq == NULL) {
185 \& fprintf(stderr, "Error: %s\en", pwquality_strerror(buf, sizeof(buf), PWQ_ERROR_MEM_ALLOC, NULL));
186 \& return \-1;
187 \& }
188 \&
189 \& if ((rv=pwquality_read_config(pwq, NULL, &auxerror)) != 0) {
190 \& pwquality_free_settings(pwq);
191 \& fprintf(stderr, "Error: %s\en", pwquality_strerror(buf, sizeof(buf), rv, auxerror));
192 \& return \-1;
193 \& }
194 \&
195 \& rv = pwquality_check(pwq, buf, NULL, user, &auxerror);
196 \& pwquality_free_settings(pwq);
197 \&
198 \& if (rv >= 0) {
199 \& fprintf(stderr, "Password entropy score is: %d\en", rv);
200 \& } else {
201 \& fprintf(stderr, "Password is rejected with error: %s\en", pwquality_strerror(buf, sizeof(buf), rv, auxerror));
202 \& }
203 .Ve
204 .SH "SEE ALSO"
205 .IX Header "SEE ALSO"
206 \&\fBpwquality.conf\fR\|(5)
207 .SH "AUTHORS"
208 .IX Header "AUTHORS"
209 Tomas Mraz <[email protected]>