---
name: "libpasswdqc"
section: "3"
platform: "linux"
package: "libpasswdqc-dev"
version: "2.0.3-2+b1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/libpasswdqc"
---

# libpasswdqc(3)

password strength checking functions

## 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;
```

*void*\

**passwdqc\_params\_reset**(*passwdqc\_params\_t \*params*);

*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*);

*const* *char* *\**\

**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

The **passwdqc\_params\_reset**() function initializes the passwdqc\_params\_t structure specified by *params* argument to compile-time defaults.

The **passwdqc\_params\_load**() function fills in the passwdqc\_params\_t structure specified by *params* argument according to the configuration options listed in the file specified by *pathname* argument.  When the passwdqc\_params\_t structure is no longer needed, the memory allocated by this function should be released using **passwdqc\_params\_free**().

The **passwdqc\_params\_parse**() function fills in the passwdqc\_params\_t structure specified by *params* argument according to the configuration options specified by *argc* and *argv* arguments.  When the passwdqc\_params\_t structure is no longer needed, the memory allocated by this function should be released using **passwdqc\_params\_free**().

The **passwdqc\_params\_free**() function frees the memory allocated by **passwdqc\_params\_load**() and **passwdqc\_params\_parse**() functions when filling in the passwdqc\_params\_t structure specified by *params* argument.

The **passwdqc\_check**() function checks the quality of the passphrase specified by *newpass* argument according to the configuration specified by *params* argument.  If an optional old passphrase is specified by *oldpass* argument, *newpass* is additionally checked against *oldpass* for similarity.  If an optional passwd record is specified by *pw* argument, *newpass* is additionally checked whether it is based on the personal login information in the passwd record.

The **passwdqc\_random**() function generates a random passphrase according to the configuration specified by *params* argument.

## RETURN VALUES

The **passwdqc\_params\_reset**() and **passwdqc\_params\_free**() functions do not return a value.

Upon successful completion the **passwdqc\_params\_load**() and **passwdqc\_params\_parse**() functions return 0.  Otherwise, -1 is returned and a pointer to dynamically allocated memory containing the error string is assigned to *\*reason*. This memory should be released using [free(3)](/free/3.md) when no longer needed.

Upon successful completion the **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 **passwdqc\_random**() function returns a dynamically allocated string containing the generated passphrase.  Otherwise, NULL is returned.  The string should be released using [free(3)](/free/3.md) 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: %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)](/passwdqc.conf/5.md), [pwqcheck(1)](/pwqcheck/1.md), [pwqgen(1)](/pwqgen/1.md), [pam\_passwdqc(8)](/pam_passwdqc/8.md).

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/\*/Linux by Dmitry V. Levin, reusing code from pam\_passwdqc. The **passwdqc\_params\_free**() function was added in version 2.0.0 by Solar Designer.

## AUTHORS

This manual page was written by Dmitry V. Levin.