libpasswdqc.3

.\" Copyright (c) 2021 Dmitry V. Levin
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd March 19, 2021
.Dt LIBPASSWDQC 3
.Os "Openwall Project"
.Sh NAME
.Nm passwdqc_params_reset ,
.Nm passwdqc_params_load ,
.Nm passwdqc_params_parse ,
.Nm passwdqc_params_free ,
.Nm passwdqc_check ,
.Nm passwdqc_random
.Nd password strength checking functions
.Sh LIBRARY
Password strength checking library
.Pq libpasswdqc, -lpasswdqc
.Sh SYNOPSIS
.In passwdqc.h
.Bd -literal
typedef struct {
	passwdqc_params_qc_t qc;
	passwdqc_params_pam_t pam;
} passwdqc_params_t;
.Ed
.Ft void
.Fn passwdqc_params_reset "passwdqc_params_t *params"
.Ft int
.Fo passwdqc_params_load
.Fa "passwdqc_params_t *params"
.Fa "char **reason"
.Fa "const char *pathname"
.Fc
.Ft int
.Fo passwdqc_params_parse
.Fa "passwdqc_params_t *params"
.Fa "char **reason"
.Fa "int argc"
.Fa "const char *const *argv"
.Fc
.Ft void
.Fn passwdqc_params_free "passwdqc_params_t *params"
.Ft const char *
.Fo passwdqc_check
.Fa "const passwdqc_params_qc_t *params"
.Fa "const char *newpass"
.Fa "const char *oldpass"
.Fa "const struct passwd *pw"
.Fc
.Ft char *
.Fn passwdqc_random "const passwdqc_params_qc_t *params"
.Sh DESCRIPTION
The
.Fn passwdqc_params_reset
function initializes the passwdqc_params_t structure specified by
.Fa params
argument to compile-time defaults.
.Pp
The
.Fn passwdqc_params_load
function fills in the passwdqc_params_t structure specified by
.Fa params
argument according to the configuration options listed in the file specified by
.Fa pathname
argument.  When the passwdqc_params_t structure is no longer needed,
the memory allocated by this function should be released using
.Fn passwdqc_params_free .
.Pp
The
.Fn passwdqc_params_parse
function fills in the passwdqc_params_t structure specified by
.Fa params
argument according to the configuration options specified by
.Fa argc
and
.Fa argv
arguments.  When the passwdqc_params_t structure is no longer needed,
the memory allocated by this function should be released using
.Fn passwdqc_params_free .
.Pp
The
.Fn passwdqc_params_free
function frees the memory allocated by
.Fn passwdqc_params_load
and
.Fn passwdqc_params_parse
functions when filling in the passwdqc_params_t structure specified by
.Fa params
argument.
.Pp
The
.Fn passwdqc_check
function checks the quality of the passphrase specified by
.Fa newpass
argument according to the configuration specified by
.Fa params
argument.  If an optional old passphrase is specified by
.Fa oldpass
argument,
.Fa newpass
is additionally checked against
.Fa oldpass
for similarity.  If an optional passwd record is specified by
.Fa pw
argument,
.Fa newpass
is additionally checked whether it is based on the personal login information
in the passwd record.
.Pp
The
.Fn passwdqc_random
function generates a random passphrase according to the configuration
specified by
.Fa params
argument.
.Sh RETURN VALUES
The
.Fn passwdqc_params_reset
and
.Fn passwdqc_params_free
functions do not return a value.
.Pp
Upon successful completion the
.Fn passwdqc_params_load
and
.Fn passwdqc_params_parse
functions return 0.  Otherwise, -1 is returned and a pointer to dynamically
allocated memory containing the error string is assigned to
.Fa *reason .
This memory should be released using free(3) when no longer needed.
.Pp
Upon successful completion the
.Fn passwdqc_check
function returns NULL.  Otherwise, a string describing the error is returned.
The returned string is statically allocated and valid for the lifetime of the
program.
.Pp
Upon successful completion the
.Fn passwdqc_random
function returns a dynamically allocated string containing the generated
passphrase.  Otherwise, NULL is returned.  The string should be released using
free(3) when no longer needed.
.Sh FILES
.Pa /etc/passwdqc.conf
(not read unless this suggested file location is specified with the
.Ar pathname
argument or with
.Cm config Ns = Ns Ar /etc/passwdqc.conf
configuration option).
.Sh EXAMPLES
The following example shows how to use the libpasswdqc library with system
configuration options to check a passphrase.
.Bd -literal -offset 2n
#include <passwdqc.h>
#include <stdbool.h>
#include <stdlib.h>
#include <stdio.h>

bool
check(const char *newpass, const char *oldpass, const struct passwd *pw)
{
  static const char config[] = "/etc/passwdqc.conf";
  char *parse_reason;
  const char *check_result = "";
  passwdqc_params_t params;
  passwdqc_params_reset(&params);
  if (passwdqc_params_load(&params, &parse_reason, config)) {
    fprintf(stderr, "passwdqc_params_load: %s\en",
      parse_reason ? parse_reason : "Out of memory");
    free(parse_reason);
    goto out;
  }
  check_result = passwdqc_check(&params.qc, newpass, oldpass, pw);
  if (check_result)
    fprintf(stderr, "passwdqc_check: %s\en", check_result);
out:
  passwdqc_params_free(&params);
  return !check_result;
}
.Ed
.Sh SEE ALSO
.Xr passwdqc.conf 5 ,
.Xr pwqcheck 1 ,
.Xr pwqgen 1 ,
.Xr pam_passwdqc 8 .
.Pp
https://www.openwall.com/passwdqc/
.Sh HISTORY
The pam_passwdqc module was written for Openwall GNU/*/Linux by Solar Designer.
The libpasswdqc library was originally written for ALT GNU/*/Linux
by Dmitry V. Levin, reusing code from pam_passwdqc.
The
.Fn passwdqc_params_free
function was added in version 2.0.0 by Solar Designer.
.Sh AUTHORS
This manual page was written by Dmitry V. Levin.