.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Required to disable full justification in groff 1.23.0. .if n .ds AD l .\" ======================================================================== .\" .IX Title "PWQUALITY 3" .TH PWQUALITY 3 2025-12-14 "Red Hat, Inc." "Libpwquality API Manual" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME pwquality \- Documentation of the libpwquality API .SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 1 \& #include \& \& pwquality_settings_t *pwquality_default_settings(void); \& void pwquality_free_settings(pwquality_settings_t *pwq); \& \& int pwquality_read_config(pwquality_settings_t *pwq, const char *cfgfile, \& void **auxerror); \& \& int pwquality_set_option(pwquality_settings_t *pwq, const char *option); \& int pwquality_set_int_value(pwquality_settings_t *pwq, int setting, int value); \& int pwquality_set_str_value(pwquality_settings_t *pwq, int setting, \& const char *value); \& int pwquality_get_int_value(pwquality_settings_t *pwq, int setting, int *value); \& int pwquality_get_str_value(pwquality_settings_t *pwq, int setting, const char **value); \& \& int pwquality_generate(pwquality_settings_t *pwq, int entropy_bits, \& char **password); \& \& int pwquality_check(pwquality_settings_t *pwq, const char *password, \& const char *oldpassword, const char *user, void **auxerror); \& \& const char *pwquality_strerror(char *buf, size_t len, int errcode, void *auxerror); .Ve .SH DESCRIPTION .IX Header "DESCRIPTION" Function \fBpwquality_default_settings()\fR allocates and returns default pwquality settings to be used in other library calls. The allocated opaque structure has to be freed with the \fBpwquality_free_settings()\fR call. .PP The \fBpwquality_read_config()\fR parses the configuration file (if \fIcfgfile\fR is NULL then the default one). If \fIauxerror\fR is not NULL it also possibly returns auxiliary error information that must be passed into \fBpwquality_strerror()\fR function. .IP "\fBNew in 1.3.0:\fR" 4 .IX Item "New in 1.3.0:" The library first tries to parse all \fI*.conf\fR configuration files from \&\fI.d\fR directory if it exists. Order of parsing determines what values will be in effect \- the latest wins. .PP Function \fBpwquality_set_option()\fR is useful for setting the options as configured on a pam module command line in form of \fIopt\fR=\fIval\fR. .PP Getter and setter functions for the individual integer and string setting values are: \fBpwquality_set_int_value()\fR, \fBpwquality_set_str_value()\fR, \&\fBpwquality_get_int_value()\fR, and \fBpwquality_get_str_value()\fR. In case of the string getter the caller must copy the string before another calls that can manipulate the \fIpwq\fR settings object. .PP The \fBpwquality_generate()\fR function generates a random password of \&\fIentropy_bits\fR entropy and checks it according to the settings. The \&\fI*password\fR is allocated on the heap by the library. The \fIentropy_bits\fR value is adjusted to fit within the \fBPWQ_MIN_ENTROPY_BITS\fR and \&\fBPWQ_MAX_ENTROPY_BITS\fR range before generating a password. .PP The \fBpwquality_check()\fR function checks the \fIpassword\fR according to the settings. It returns either score (value between 0 and 100), negative error number, and possibly also auxiliary error information that must be passed into the \fBpwquality_strerror()\fR function. The \fIoldpassword\fR is optional and can be NULL. The \fIuser\fR is used for checking the \fIpassword\fR against the user name and potentially other \&\fBpasswd\fR\|(5) information and can be NULL. The \fIauxerror\fR can be NULL \- in that case the auxiliary error information is not returned. However if it is non\-NULL not passing the returned \fI*auxerror\fR into \fBpwquality_strerror()\fR can lead to memory leaks. .PP The score of a password depends on the value of the setting \&\fBPWQ_SETTING_MIN_LENGTH\fR. If it is set higher, the score for the same passwords will be lower. .PP Function \fBpwquality_strerror()\fR translates the \fIerrcode\fR and \fIauxerror\fR auxiliary data into a localized text message. If \fIbuf\fR is NULL the function uses an internal static buffer which makes the function non\-reentrant in that case. The returned pointer is not guaranteed to point to the \fIbuf\fR. The function deallocates eventual \fIauxerror\fR data passed into it, thus it must not be called twice with the same \fIauxerror\fR data. .SH "RETURN VALUES" .IX Header "RETURN VALUES" In general the functions which return \fBint\fR return 0 as success value and negative values as concrete \fBPWQ_ERROR\fR error code. \fBpwquality_strerror()\fR does not allocate data and so it cannot fail. .PP The returned positive or zero score from \fBpwquality_check()\fR should not be used for rejection of passwords, it should be used only as approximate indicator of entropy present in the password with values such as 0\-30 being low, 30\-60 medium, and 60\-100 high. .SH EXAMPLE .IX Header "EXAMPLE" Typical use of the libpwquality API: .PP .Vb 1 \& #include \& \& ... \& \& pwquality_settings_t *pwq; \& int rv; \& void *auxerror; \& char buf[PWQ_MAX_ERROR_MESSAGE_LEN]; \& \& pwq = pwquality_default_settings(); \& if (pwq == NULL) { \& fprintf(stderr, "Error: %s\en", pwquality_strerror(buf, sizeof(buf), PWQ_ERROR_MEM_ALLOC, NULL)); \& return \-1; \& } \& \& if ((rv=pwquality_read_config(pwq, NULL, &auxerror)) != 0) { \& pwquality_free_settings(pwq); \& fprintf(stderr, "Error: %s\en", pwquality_strerror(buf, sizeof(buf), rv, auxerror)); \& return \-1; \& } \& \& rv = pwquality_check(pwq, buf, NULL, user, &auxerror); \& pwquality_free_settings(pwq); \& \& if (rv >= 0) { \& fprintf(stderr, "Password entropy score is: %d\en", rv); \& } else { \& fprintf(stderr, "Password is rejected with error: %s\en", pwquality_strerror(buf, sizeof(buf), rv, auxerror)); \& } .Ve .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBpwquality.conf\fR\|(5) .SH AUTHORS .IX Header "AUTHORS" Tomas Mraz