1PWQUALITY(3)                Libpwquality API Manual               PWQUALITY(3)
2
3
4

NAME

6       pwquality - Documentation of the libpwquality API
7

SYNOPSIS

9        #include <pwquality.h>
10
11        pwquality_settings_t *pwquality_default_settings(void);
12        void pwquality_free_settings(pwquality_settings_t *pwq);
13
14        int pwquality_read_config(pwquality_settings_t *pwq, const char *cfgfile,
15               void **auxerror);
16
17        int pwquality_set_option(pwquality_settings_t *pwq, const char *option);
18        int pwquality_set_int_value(pwquality_settings_t *pwq, int setting, int value);
19        int pwquality_set_str_value(pwquality_settings_t *pwq, int setting,
20               const char *value);
21        int pwquality_get_int_value(pwquality_settings_t *pwq, int setting, int *value);
22        int pwquality_get_str_value(pwquality_settings_t *pwq, int setting, const char **value);
23
24        int pwquality_generate(pwquality_settings_t *pwq, int entropy_bits,
25               char **password);
26
27        int pwquality_check(pwquality_settings_t *pwq, const char *password,
28               const char *oldpassword, const char *user, void **auxerror);
29
30        const char *pwquality_strerror(char *buf, size_t len, int errcode, void *auxerror);
31

DESCRIPTION

33       Function pwquality_default_settings() allocates and returns default
34       pwquality settings to be used in other library calls. The allocated
35       opaque structure has to be freed with the pwquality_free_settings()
36       call.
37
38       The pwquality_read_config() parses the configuration file (if cfgfile
39       is NULL then the default one). If auxerror is not NULL it also possibly
40       returns auxiliary error information that must be passed into
41       pwquality_strerror() function.
42
43       New in 1.3.0:
44           The library first tries to parse all *.conf configuration files
45           from <cfgfile>.d directory if it exists. Order of parsing
46           determines what values will be in effect - the latest wins.
47
48       Function pwquality_set_option() is useful for setting the options as
49       configured on a pam module command line in form of opt=val.
50
51       Getter and setter functions for the individual integer and string
52       setting values are: pwquality_set_int_value(),
53       pwquality_set_str_value(), pwquality_get_int_value(), and
54       pwquality_get_str_value(). In case of the string getter the caller must
55       copy the string before another calls that can manipulate the pwq
56       settings object.
57
58       The pwquality_generate() function generates a random password of
59       entropy_bits entropy and checks it according to the settings. The
60       *password is allocated on the heap by the library. The entropy_bits
61       value is adjusted to fit within the PWQ_MIN_ENTROPY_BITS and
62       PWQ_MAX_ENTROPY_BITS range before generating a password.
63
64       The pwquality_check() function checks the password according to the
65       settings. It returns either score (value between 0 and 100), negative
66       error number, and possibly also auxiliary error information that must
67       be passed into the pwquality_strerror() function.  The oldpassword is
68       optional and can be NULL. The user is used for checking the password
69       against the user name and potentially other passwd(5) information and
70       can be NULL. The auxerror can be NULL - in that case the auxiliary
71       error information is not returned. However if it is non-NULL not
72       passing the returned *auxerror into pwquality_strerror() can lead to
73       memory leaks.
74
75       The score of a password depends on the value of the setting
76       PWQ_SETTING_MIN_LENGTH. If it is set higher, the score for the same
77       passwords will be lower.
78
79       Function pwquality_strerror() translates the errcode and auxerror
80       auxiliary data into a localized text message. If buf is NULL the
81       function uses an internal static buffer which makes the function non-
82       reentrant in that case. The returned pointer is not guaranteed to point
83       to the buf. The function deallocates eventual auxerror data passed into
84       it, thus it must not be called twice with the same auxerror data.
85

RETURN VALUES

87       In general the functions which return int return 0 as success value and
88       negative values as concrete PWQ_ERROR error code. pwquality_strerror()
89       does not allocate data and so it cannot fail.
90
91       The returned positive or zero score from pwquality_check() should not
92       be used for rejection of passwords, it should be used only as
93       approximate indicator of entropy present in the password with values
94       such as 0-30 being low, 30-60 medium, and 60-100 high.
95

EXAMPLE

97       Typical use of the libpwquality API:
98
99        #include <pwquality.h>
100
101        ...
102
103               pwquality_settings_t *pwq;
104               int rv;
105               void *auxerror;
106               char buf[PWQ_MAX_ERROR_MESSAGE_LEN];
107
108               pwq = pwquality_default_settings();
109               if (pwq == NULL) {
110                       fprintf(stderr, "Error: %s\n", pwquality_strerror(buf, sizeof(buf), PWQ_ERROR_MEM_ALLOC, NULL));
111                       return -1;
112               }
113
114               if ((rv=pwquality_read_config(pwq, NULL, &auxerror)) != 0) {
115                       pwquality_free_settings(pwq);
116                       fprintf(stderr, "Error: %s\n", pwquality_strerror(buf, sizeof(buf), rv, auxerror));
117                       return -1;
118               }
119
120               rv = pwquality_check(pwq, buf, NULL, user, &auxerror);
121               pwquality_free_settings(pwq);
122
123               if (rv >= 0) {
124                       fprintf(stderr, "Password entropy score is: %d\n", rv);
125               } else {
126                       fprintf(stderr, "Password is rejected with error: %s\n", pwquality_strerror(buf, sizeof(buf), rv, auxerror));
127               }
128

SEE ALSO

130       pwquality.conf(5)
131

AUTHORS

133       Tomas Mraz <tmraz@redhat.com>
134
135
136
137Red Hat, Inc.                     2021-04-01                      PWQUALITY(3)
Impressum