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¶

#include<passwdqc.h>

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

int
passwdqc_params_load(passwdqc_params_t *params,char **reason,const char *pathname);

int
passwdqc_params_parse(passwdqc_params_t *params,char **reason,int argc,const char *const *argv);

void
passwdqc_params_free(passwdqc_params_t *params);

constchar*
passwdqc_check(const passwdqc_params_qc_t *params,const char *newpass,const char *oldpass,const struct passwd *pw);

char*
passwdqc_random(const passwdqc_params_qc_t *params);

DESCRIPTION¶

Thepasswdqc_params_reset()function initializes the passwdqc_params_t structure specified byparamsargument to compile-time defaults.

Thepasswdqc_params_load()function fills in the passwdqc_params_t structure specified byparamsargument according to the configuration options listed in the file specified bypathnameargument. When the passwdqc_params_t structure is no longer needed,the memory allocated by this function should be released usingpasswdqc_params_free().

Thepasswdqc_params_parse()function fills in the passwdqc_params_t structure specified byparamsargument according to the configuration options specified byargcandargvarguments. When the passwdqc_params_t structure is no longer needed,the memory allocated by this function should be released usingpasswdqc_params_free().

Thepasswdqc_params_free()function frees the memory allocated bypasswdqc_params_load()andpasswdqc_params_parse()functions when filling in the passwdqc_params_t structure specified byparamsargument.

Thepasswdqc_check()function checks the quality of the passphrase specified bynewpassargument according to the configuration specified byparamsargument. If an optional old passphrase is specified byoldpassargument,newpassis additionally checked againstoldpassfor similarity. If an optional passwd record is specified bypwargument,newpassis additionally checked whether it is based on the personal login informationin the passwd record.

Thepasswdqc_random()function generates a random passphrase according to the configurationspecified byparamsargument.

RETURN VALUES¶

Thepasswdqc_params_reset()andpasswdqc_params_free()functions do not return a value.

Upon successful completion thepasswdqc_params_load()andpasswdqc_params_parse()functions return 0. Otherwise, -1 is returned and a pointer to dynamicallyallocated memory containing the error string is assigned to*reason.This memory should be released using free(3) when no longer needed.

Upon successful completion thepasswdqc_check()function returns NULL. Otherwise, a string describing the error is returned.The returned string is statically allocated and valid for the lifetime of theprogram.

Upon successful completion thepasswdqc_random()function returns a dynamically allocated string containing the generatedpassphrase. Otherwise, NULL is returned. The string should be released usingfree(3) when no longer needed.

FILES¶

/etc/passwdqc.conf(not read unless this suggested file location is specified with thepathnameargument or withconfig=/etc/passwdqc.confconfiguration option).

EXAMPLES¶

The following example shows how to use the libpasswdqc library with systemconfiguration 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: %s\n",
      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\n", check_result);
out:
  passwdqc_params_free(&params);
  return !check_result;
}

SEE ALSO¶

passwdqc.conf(5),pwqcheck(1),pwqgen(1),pam_passwdqc(8).

https://www.openwall.com/passwdqc/

HISTORY¶

The pam_passwdqc module was written for Openwall GNU/*/Linux by Solar Designer.The libpasswdqc library was originally written for ALT GNU/*/Linuxby Dmitry V. Levin, reusing code from pam_passwdqc.Thepasswdqc_params_free()function was added in version 2.0.0 by Solar Designer.

AUTHORS¶

This manual page was written by Dmitry V. Levin.