.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" 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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    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
.\" ========================================================================
.\"
.IX Title "PWQUALITY 3"
.TH PWQUALITY 3 "2021-04-01" "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.h>
\&
\& 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
\&\s-1NULL\s0 then the default one). If \fIauxerror\fR is not \s-1NULL\s0 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<cfgfile>.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 \fB\s-1PWQ_MIN_ENTROPY_BITS\s0\fR and
\&\fB\s-1PWQ_MAX_ENTROPY_BITS\s0\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 \s-1NULL.\s0 The \fIuser\fR is used for
checking the \fIpassword\fR against the user name and potentially other
\&\fBpasswd\fR\|(5) information and can be \s-1NULL.\s0 The \fIauxerror\fR can be \s-1NULL\s0 \- 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
\&\fB\s-1PWQ_SETTING_MIN_LENGTH\s0\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 \s-1NULL\s0 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 \fB\s-1PWQ_ERROR\s0\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 \s-1API:\s0
.PP
.Vb 1
\& #include <pwquality.h>
\&
\& ...
\&
\&        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 <tmraz@redhat.com>