1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
|
=pod
=head1 NAME
pwquality - Documentation of the libpwquality API
=head1 SYNOPSIS
#include <pwquality.h>
pwquality_settings_t *pwquality_default_settings(void);
void pwquality_free_settings(pwquality_settings_t *pwq);
int pwquality_read_config(pwquality_settings_t *pwq, const char *cfgfile,
void **auxerror);
int pwquality_set_option(pwquality_settings_t *pwq, const char *option);
int pwquality_set_int_value(pwquality_settings_t *pwq, int setting, int value);
int pwquality_set_str_value(pwquality_settings_t *pwq, int setting,
const char *value);
int pwquality_get_int_value(pwquality_settings_t *pwq, int setting, int *value);
int pwquality_get_str_value(pwquality_settings_t *pwq, int setting, const char **value);
int pwquality_generate(pwquality_settings_t *pwq, int entropy_bits,
char **password);
int pwquality_check(pwquality_settings_t *pwq, const char *password,
const char *oldpassword, const char *user, void **auxerror);
const char *pwquality_strerror(char *buf, size_t len, int errcode, void *auxerror);
=head1 DESCRIPTION
Function pwquality_default_settings() allocates and returns default pwquality
settings to be used in other library calls. The allocated opaque structure has
to be freed with the pwquality_free_settings() call.
The pwquality_read_config() parses the configuration file (if I<cfgfile> is
NULL then the default one). If I<auxerror> is not NULL it also possibly returns
auxiliary error information that must be passed into pwquality_strerror()
function.
=over 4
=item B<New in 1.3.0:>
The library first tries to parse all F<*.conf> configuration files from
F<< <cfgfile>.d >> directory if it exists. Order of parsing determines what
values will be in effect - the latest wins.
=back
Function pwquality_set_option() is useful for setting the options as configured
on a pam module command line in form of I<opt>=I<val>.
Getter and setter functions for the individual integer and string setting
values are: pwquality_set_int_value(), pwquality_set_str_value(),
pwquality_get_int_value(), and pwquality_get_str_value(). In case of the
string getter the caller must copy the string before another calls that can
manipulate the I<pwq> settings object.
The pwquality_generate() function generates a random password of
I<entropy_bits> entropy and checks it according to the settings. The
I<*password> is allocated on the heap by the library. The I<entropy_bits>
value is adjusted to fit within the B<PWQ_MIN_ENTROPY_BITS> and
B<PWQ_MAX_ENTROPY_BITS> range before generating a password.
The pwquality_check() function checks the I<password> according to the
settings. It returns either score (value between 0 and 100), negative
error number, and possibly also auxiliary error information that must be
passed into the pwquality_strerror() function.
The I<oldpassword> is optional and can be NULL. The I<user> is used for
checking the I<password> against the user name and potentially other
L<passwd(5)> information and can be NULL. The I<auxerror> can be NULL - in
that case the auxiliary error information is not returned. However if it is
non-NULL not passing the returned I<*auxerror> into pwquality_strerror() can
lead to memory leaks.
The score of a password depends on the value of the setting
B<PWQ_SETTING_MIN_LENGTH>. If it is set higher, the score for the same
passwords will be lower.
Function pwquality_strerror() translates the I<errcode> and I<auxerror>
auxiliary data into a localized text message. If I<buf> is NULL the function
uses an internal static buffer which makes the function non-reentrant in that
case. The returned pointer is not guaranteed to point to the I<buf>. The
function deallocates eventual I<auxerror> data passed into it, thus it must
not be called twice with the same I<auxerror> data.
=head1 RETURN VALUES
In general the functions which return B<int> return 0 as success value and
negative values as concrete B<PWQ_ERROR> error code. pwquality_strerror() does
not allocate data and so it cannot fail.
The returned positive or zero score from pwquality_check() should not be
used for rejection of passwords, it should be used only as approximate
indicator of entropy present in the password with values such as 0-30 being
low, 30-60 medium, and 60-100 high.
=head1 EXAMPLE
Typical use of the libpwquality API:
#include <pwquality.h>
...
pwquality_settings_t *pwq;
int rv;
void *auxerror;
char buf[PWQ_MAX_ERROR_MESSAGE_LEN];
pwq = pwquality_default_settings();
if (pwq == NULL) {
fprintf(stderr, "Error: %s\n", pwquality_strerror(buf, sizeof(buf), PWQ_ERROR_MEM_ALLOC, NULL));
return -1;
}
if ((rv=pwquality_read_config(pwq, NULL, &auxerror)) != 0) {
pwquality_free_settings(pwq);
fprintf(stderr, "Error: %s\n", pwquality_strerror(buf, sizeof(buf), rv, auxerror));
return -1;
}
rv = pwquality_check(pwq, buf, NULL, user, &auxerror);
pwquality_free_settings(pwq);
if (rv >= 0) {
fprintf(stderr, "Password entropy score is: %d\n", rv);
} else {
fprintf(stderr, "Password is rejected with error: %s\n", pwquality_strerror(buf, sizeof(buf), rv, auxerror));
}
=head1 SEE ALSO
L<pwquality.conf(5)>
=head1 AUTHORS
Tomas Mraz <tmraz@redhat.com>
|
