Debian Codegraph @

src/pwquality.h

raw
1 /*
2 * libpwquality main API code header
3 *
4 * Copyright (c) Red Hat, Inc, 2011
5 * Copyright (c) Tomas Mraz <[email protected]>, 2011
6 *
7 * See the end of the file for the License Information
8 */
9
10 #ifndef PWQUALITY_H
11 #define PWQUALITY_H
12
13 #include <sys/types.h>
14
15 #ifdef __cplusplus
16 extern "C" {
17 #endif
18
19 #define PWQ_SETTING_DIFF_OK 1
20 #define PWQ_SETTING_MIN_LENGTH 3
21 #define PWQ_SETTING_DIG_CREDIT 4
22 #define PWQ_SETTING_UP_CREDIT 5
23 #define PWQ_SETTING_LOW_CREDIT 6
24 #define PWQ_SETTING_OTH_CREDIT 7
25 #define PWQ_SETTING_MIN_CLASS 8
26 #define PWQ_SETTING_MAX_REPEAT 9
27 #define PWQ_SETTING_DICT_PATH 10
28 #define PWQ_SETTING_MAX_CLASS_REPEAT 11
29 #define PWQ_SETTING_GECOS_CHECK 12
30 #define PWQ_SETTING_BAD_WORDS 13
31 #define PWQ_SETTING_MAX_SEQUENCE 14
32 #define PWQ_SETTING_DICT_CHECK 15
33 #define PWQ_SETTING_USER_CHECK 16
34 #define PWQ_SETTING_ENFORCING 17
35 #define PWQ_SETTING_RETRY_TIMES 18
36 #define PWQ_SETTING_ENFORCE_ROOT 19
37 #define PWQ_SETTING_LOCAL_USERS 20
38 #define PWQ_SETTING_USER_SUBSTR 21
39
40 #define PWQ_MAX_ENTROPY_BITS 256
41 #define PWQ_MIN_ENTROPY_BITS 56
42
43 #define PWQ_MAX_ERROR_MESSAGE_LEN 256
44
45 #define PWQ_ERROR_SUCCESS 0 /* implicit, not used in the library code */
46 #define PWQ_ERROR_FATAL_FAILURE -1
47 #define PWQ_ERROR_INTEGER -2
48 #define PWQ_ERROR_CFGFILE_OPEN -3
49 #define PWQ_ERROR_CFGFILE_MALFORMED -4
50 #define PWQ_ERROR_UNKNOWN_SETTING -5
51 #define PWQ_ERROR_NON_INT_SETTING -6
52 #define PWQ_ERROR_NON_STR_SETTING -7
53 #define PWQ_ERROR_MEM_ALLOC -8
54 #define PWQ_ERROR_TOO_SIMILAR -9
55 #define PWQ_ERROR_MIN_DIGITS -10
56 #define PWQ_ERROR_MIN_UPPERS -11
57 #define PWQ_ERROR_MIN_LOWERS -12
58 #define PWQ_ERROR_MIN_OTHERS -13
59 #define PWQ_ERROR_MIN_LENGTH -14
60 #define PWQ_ERROR_PALINDROME -15
61 #define PWQ_ERROR_CASE_CHANGES_ONLY -16
62 #define PWQ_ERROR_ROTATED -17
63 #define PWQ_ERROR_MIN_CLASSES -18
64 #define PWQ_ERROR_MAX_CONSECUTIVE -19
65 #define PWQ_ERROR_EMPTY_PASSWORD -20
66 #define PWQ_ERROR_SAME_PASSWORD -21
67 #define PWQ_ERROR_CRACKLIB_CHECK -22
68 #define PWQ_ERROR_RNG -23
69 #define PWQ_ERROR_GENERATION_FAILED -24
70 #define PWQ_ERROR_USER_CHECK -25
71 #define PWQ_ERROR_GECOS_CHECK -26
72 #define PWQ_ERROR_MAX_CLASS_REPEAT -27
73 #define PWQ_ERROR_BAD_WORDS -28
74 #define PWQ_ERROR_MAX_SEQUENCE -29
75
76 typedef struct pwquality_settings pwquality_settings_t;
77
78 /* Return default pwquality settings to be used in other library calls. */
79 pwquality_settings_t *
80 pwquality_default_settings(void);
81
82 /* Free pwquality settings data. */
83 void
84 pwquality_free_settings(pwquality_settings_t *pwq);
85
86 /* Parse the configuration file (if cfgfile is NULL then the default one).
87 * If auxerror is not NULL it also possibly returns auxiliary error information
88 * that must be passed into pwquality_strerror() function.
89 * New in 1.3.0: First tries to parse all *.conf configuration files from
90 * <cfgfile>.d directory if it exists. Order of parsing determines what
91 values will be in effect - the latest wins. */
92 int
93 pwquality_read_config(pwquality_settings_t *pwq, const char *cfgfile,
94 void **auxerror);
95
96 /* Useful for setting the options as configured on a pam module
97 * command line in form of <opt>=<val> */
98 int
99 pwquality_set_option(pwquality_settings_t *pwq, const char *option);
100
101 /* Set value of an integer setting. */
102 int
103 pwquality_set_int_value(pwquality_settings_t *pwq, int setting, int value);
104
105 /* Set value of a string setting. */
106 int
107 pwquality_set_str_value(pwquality_settings_t *pwq, int setting,
108 const char *value);
109
110 /* Get value of an integer setting. */
111 int
112 pwquality_get_int_value(pwquality_settings_t *pwq, int setting, int *value);
113
114 /* Get value of a string setting.
115 * The caller must copy the string before another calls that can
116 * manipulate the pwq settings object.
117 */
118 int
119 pwquality_get_str_value(pwquality_settings_t *pwq, int setting, const char **value);
120
121 /* Generate a random password of entropy_bits entropy and check it according to
122 * the settings. */
123 int
124 pwquality_generate(pwquality_settings_t *pwq, int entropy_bits,
125 char **password);
126
127 /* Check the password according to the settings.
128 * It returns either score <0-100>, negative error number,
129 * and possibly also auxiliary error information that must be
130 * passed into pwquality_strerror() function.
131 * The old password is optional and can be NULL.
132 * The user is used for checking the password against user name
133 * and potentially other passwd information and can be NULL.
134 * The auxerror can be NULL - in that case the auxiliary error information
135 * is not returned.
136 * Not passing the *auxerror into pwquality_strerror() can lead to memory leaks.
137 * The score depends on PWQ_SETTING_MIN_LENGTH. If it is set higher,
138 * the score for the same passwords will be lower. */
139 int
140 pwquality_check(pwquality_settings_t *pwq, const char *password,
141 const char *oldpassword, const char *user, void **auxerror);
142
143 /* Translate the error code and auxiliary message into a localized
144 * text message.
145 * If buf is NULL it uses an internal static buffer which
146 * makes the function non-reentrant in that case.
147 * The returned pointer is not guaranteed to point to the buf. */
148 const char *
149 pwquality_strerror(char *buf, size_t len, int errcode, void *auxerror);
150
151 #ifdef __cplusplus
152 }
153 #endif
154
155 #endif /* PWQUALITY_H */
156
157 /*
158 * Redistribution and use in source and binary forms, with or without
159 * modification, are permitted provided that the following conditions
160 * are met:
161 * 1. Redistributions of source code must retain the above copyright
162 * notice, and the entire permission notice in its entirety,
163 * including the disclaimer of warranties.
164 * 2. Redistributions in binary form must reproduce the above copyright
165 * notice, this list of conditions and the following disclaimer in the
166 * documentation and/or other materials provided with the distribution.
167 * 3. The name of the author may not be used to endorse or promote
168 * products derived from this software without specific prior
169 * written permission.
170 *
171 * ALTERNATIVELY, this product may be distributed under the terms of
172 * the GNU General Public License version 2 or later, in which case the
173 * provisions of the GPL are required INSTEAD OF the above restrictions.
174 *
175 * THIS SOFTWARE IS PROVIDED `AS IS'' AND ANY EXPRESS OR IMPLIED
176 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
177 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
178 * DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
179 * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
180 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
181 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
182 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
183 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
184 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
185 * OF THE POSSIBILITY OF SUCH DAMAGE.
186 */