www.LinuxHowtos.org

LIBPASSWDQC

Section: C Library Functions (3)
Index Return to Main Contents

BSD mandoc
Openwall Project

NAME

passwdqc_params_reset passwdqc_params_load passwdqc_params_parse passwdqc_params_free passwdqc_check passwdqc_random - password strength checking functions

LIBRARY

Password strength checking library (libpasswdqc,-lpasswdqc)

SYNOPSIS

In passwdqc.h

typedef struct {
        passwdqc_params_qc_t qc;
        passwdqc_params_pam_t pam;
} passwdqc_params_t;

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

DESCRIPTION

The Fn passwdqc_params_reset function initializes the passwdqc_params_t structure specified by Fa params argument to compil-time defaults.

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 .

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 .

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.

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.

The Fn passwdqc_random function generates a random passphrase according to the configuration specified by Fa params argument.

RETURN VALUES

The Fn passwdqc_params_reset and Fn passwdqc_params_free functions do not return a value.

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.

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.

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.

FILES

/etc/passwdqc.conf (not read unless this suggested file location is specified with the pathname argument or with config = /etc/passwdqc.conf configuration option).

EXAMPLES

The following example shows how to use the libpasswdqc library with system configuration options to check a passphrase.

#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: %sn",
      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: %sn", check_result);
out:
  passwdqc_params_free(&params);
  return !check_result;
}

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.

AUTHORS

This manual page was written by Dmitry V. Levin.