1PWQUALITY(5) Libpwquality API Manual PWQUALITY(5)
2
3
4
6 pwquality - Documentation of the libpwquality API
7
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
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 check it according to the settings. The
60 *password is allocated on heap by the library.
61
62 The pwquality_check() function checks the password according to the
63 settings. It returns either score <0-100>, negative error number, and
64 possibly also auxiliary error information that must be passed into
65 pwquality_strerror() function. The oldpassword is optional and can be
66 NULL. The user is used for checking the password against the user name
67 and potentially other passwd(5) information and can be NULL. The
68 auxerror can be NULL - in that case the auxiliary error information is
69 not returned. However if it is non-NULL not passing the returned
70 *auxerror into pwquality_strerror() can lead to memory leaks. The
71 score depends on value of the setting PWQ_SETTING_MIN_LENGTH. If it is
72 set higher, the score for the same passwords will be lower.
73
74 Function pwquality_strerror() translates the errcode and auxerror
75 auxiliary data into localized text message. If buf is NULL the function
76 uses an internal static buffer which makes the function non-reentrant
77 in that case. The returned pointer is not guaranteed to point to the
78 buf.
79
81 In general the functions which return int return 0 as success value and
82 negative values as concrete PWQ_ERROR error code. pwquality_strerror()
83 does not allocate data and so it cannot fail.
84
85 The returned positive or zero score from pwquality_check() should not
86 be used for rejection of passwords, it should be used only as
87 approximate indicator of entropy present in the password with values
88 such as 0-30 being low, 30-60 medium, and 60-100 high.
89
91 Typical use of the libpwquality API:
92
93 #include <pwquality.h>
94
95 ...
96
97 pwquality_settings_t *pwq;
98 int rv;
99 void *auxerror;
100 char buf[1024];
101
102 pwq = pwquality_default_settings();
103 if (pwq == NULL) {
104 fprintf(stderr, "Error: %s\n", pwquality_strerror(buf, sizeof(buf), PWQ_ERROR_MEM_ALLOC, NULL));
105 return -1;
106 }
107
108 if ((rv=pwquality_read_config(pwq, NULL, &auxerror)) != 0) {
109 pwquality_free_settings(pwq);
110 fprintf(stderr, "Error: %s\n", pwquality_strerror(buf, sizeof(buf), rv, auxerror));
111 return -1;
112 }
113
114 rv = pwquality_check(pwq, buf, NULL, user, &auxerror);
115 pwquality_free_settings(pwq);
116
117 if (rv >= 0) {
118 fprintf(stderr, "Password entropy score is: %d\n", rv);
119 } else {
120 fprintf(stderr, "Password is rejected with error: %s\n", pwquality_strerror(buf, sizeof(buf), rv, auxerror));
121 }
122
124 pwquality.conf(5)
125
127 Tomas Mraz <tmraz@redhat.com>
128
129
130
131Red Hat, Inc. 2017-02-10 PWQUALITY(5)