1 /* 2 * libpwquality main API code header 3 * 4 * Copyright (c) Red Hat, Inc, 2011 5 * Copyright (c) Tomas Mraz <tm@t8m.info>, 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 */ 187