Debian Codegraph @

doc/man/pwquality.3.pod

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