Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
PWQUALITY(3)		     Libpwquality API Manual		    PWQUALITY(3)

NAME
     pwquality - Documentation of the libpwquality API

SYNOPSIS
      #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);

DESCRIPTION
     Function pwquality_default_settings() allocates and returns default pwqual-
     ity settings to be used in other library calls. The allocated opaque struc-
     ture has to be freed with the pwquality_free_settings() call.

     The  pwquality_read_config()  parses  the configuration file (if cfgfile is
     NULL then the default one). If auxerror is not NULL it  also  possibly  re-
     turns  auxiliary  error information that must be passed into pwquality_str-
     error() function.

     New in 1.3.0:
	 The library first tries to parse all *.conf  configuration  files  from
	 <cfgfile>.d  directory  if  it exists. Order of parsing determines what
	 values will be in effect - the latest wins.

     Function pwquality_set_option() is useful for setting the options	as  con-
     figured on a pam module command line in form of opt=val.

     Getter  and  setter functions for the individual integer and string setting
     values are: pwquality_set_int_value(),  pwquality_set_str_value(),  pwqual-
     ity_get_int_value(),  and	pwquality_get_str_value(). In case of the string
     getter the caller must copy the string before another calls that can manip-
     ulate the pwq settings object.

     The pwquality_generate()  function  generates  a  random  password  of  en-
     tropy_bits  entropy  and checks it according to the settings. The *password
     is allocated on the heap by the library. The entropy_bits value is adjusted
     to fit within the PWQ_MIN_ENTROPY_BITS and PWQ_MAX_ENTROPY_BITS  range  be-
     fore generating a password.

     The  pwquality_check()  function  checks the password according to the set-
     tings. It returns either score (value between 0 and  100),  negative  error
     number,  and  possibly also auxiliary error information that must be passed
     into the pwquality_strerror() function.  The oldpassword  is  optional  and
     can  be  NULL.  The user is used for checking the password against the user
     name and potentially other passwd(5) information and can be NULL. The  aux-
     error can be NULL - in that case the auxiliary error information is not re-
     turned.  However  if it is non-NULL not passing the returned *auxerror into
     pwquality_strerror() can lead to memory leaks.

     The score of a password depends  on  the  value  of  the  setting	PWQ_SET-
     TING_MIN_LENGTH. If it is set higher, the score for the same passwords will
     be lower.

     Function pwquality_strerror() translates the errcode and auxerror auxiliary
     data into a localized text message. If buf is NULL the function uses an in-
     ternal  static  buffer which makes the function non-reentrant in that case.
     The returned pointer is not guaranteed to point to the  buf.  The	function
     deallocates  eventual  auxerror  data  passed  into it, thus it must not be
     called twice with the same auxerror data.

RETURN VALUES
     In general the functions which return int return 0  as  success  value  and
     negative values as concrete PWQ_ERROR error code. pwquality_strerror() does
     not allocate data and so it cannot fail.

     The  returned  positive  or zero score from pwquality_check() should not be
     used for rejection of passwords, it should be used only as approximate  in-
     dicator  of  entropy present in the password with values such as 0-30 being
     low, 30-60 medium, and 60-100 high.

EXAMPLE
     Typical use of the libpwquality API:

      #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\n", 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\n", 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\n", rv);
	     } else {
		     fprintf(stderr, "Password is rejected with error: %s\n", pwquality_strerror(buf, sizeof(buf), rv, auxerror));
	     }

SEE ALSO
     pwquality.conf(5)

AUTHORS
     Tomas Mraz <tmraz@redhat.com>

Red Hat, Inc.			   2021-04-01			    PWQUALITY(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=pwquality&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>

home | help