| 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]> |