From 1f9071ba75c3f2b0e76a42217ff38f58ccc505e0 Mon Sep 17 00:00:00 2001 From: Tomas Mraz Date: Wed, 22 Jul 2015 18:53:42 +0200 Subject: Add API manual page. --- doc/man/Makefile.am | 9 ++-- doc/man/pwquality.3.pod | 133 ++++++++++++++++++++++++++++++++++++++++++++++++ po/es.po | 53 ++++++++++++------- 3 files changed, 174 insertions(+), 21 deletions(-) create mode 100644 doc/man/pwquality.3.pod diff --git a/doc/man/Makefile.am b/doc/man/Makefile.am index 07da8fa..117d12b 100644 --- a/doc/man/Makefile.am +++ b/doc/man/Makefile.am @@ -1,10 +1,10 @@ -dist_man_MANS = pwmake.1 pwscore.1 pwquality.conf.5 +dist_man_MANS = pwmake.1 pwscore.1 pwquality.conf.5 pwquality.3 if HAVE_PAM dist_man_MANS += pam_pwquality.8 endif -EXTRA_DIST=pam_pwquality.8.pod pwmake.1.pod pwscore.1.pod pwquality.conf.5.pod +EXTRA_DIST=pam_pwquality.8.pod pwmake.1.pod pwscore.1.pod pwquality.conf.5.pod pwquality.3.pod %.8: %.8.pod bash -c 'declare -u ucname=$*; pod2man --utf8 --name="$$ucname" --section=8 --center="Linux-PAM Manual" --release="Red Hat, Inc." $< $@' @@ -15,5 +15,8 @@ EXTRA_DIST=pam_pwquality.8.pod pwmake.1.pod pwscore.1.pod pwquality.conf.5.pod %.5: %.5.pod bash -c 'declare -u ucname=$*; pod2man --utf8 --name="$$ucname" --section=5 --center="File Formats Manual" --release="Red Hat, Inc." $< $@' +%.3: %.3.pod + bash -c 'declare -u ucname=$*; pod2man --utf8 --name="$$ucname" --section=5 --center="Libpwquality API Manual" --release="Red Hat, Inc." $< $@' + manclean: - rm *.8 *.1 *.5 + rm *.8 *.1 *.5 *.3 diff --git a/doc/man/pwquality.3.pod b/doc/man/pwquality.3.pod new file mode 100644 index 0000000..79e97a3 --- /dev/null +++ b/doc/man/pwquality.3.pod @@ -0,0 +1,133 @@ +=pod + +=head1 NAME + +pwquality - Documentation of the libpwquality API + +=head1 SYNOPSIS + + #include + + 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); + +=head1 DESCRIPTION + +Function I allocates and returns default pwquality settings +to be used in other library calls. The allocated opaque structure has to be freed +with the I call. + +The I parses the configuration file (if B is NULL +then the default one). If B is not NULL it also possibly returns auxiliary +error information that must be passed into I function. + +=over 4 + +=item B + +The library first tries to parse all F<*.conf> configuration files from +F<< .d >> directory if it exists. Order of parsing determines what values will +be in effect - the latest wins. + +=back + +Function I is useful for setting the options as configured +on a pam module command line in form of =. + +Getter and setter functions for the individual integer and string setting values are: +I, I, +I, and I. In case of the +string getter the caller must copy the string before another calls that can +manipulate the B settings object. + +The I function generates a random password of B entropy +and check it according to the settings. The B<*password> is allocated on heap by the +library. + +The I function checks the B according to the settings. It +returns either score <0-100>, negative error number, and possibly also auxiliary error +information that must be passed into I function. +The B is optional and can be NULL. +The B is used for checking the B against the user name +and potentially other L information and can be NULL. +The B can be NULL - in that case the auxiliary error information +is not returned. +However if it is non-NULL not passing the returned B<*auxerror> into +I can lead to memory leaks. +The score depends on value of the setting B. If it is +set higher, the score for the same passwords will be lower. + +Function I translates the B and B auxiliary +data into localized text message. If B is NULL the function uses an internal static +buffer which makes the function non-reentrant in that case. The returned pointer is not +guaranteed to point to the B. + +=head1 RETURN VALUES + +In general the functions which return B return 0 as success value and negative values +as concrete B error code. I does not allocate data +and so it cannot fail. + +The returned positive or zero score from I should not be used for +rejection of passwords, it should be used only as approximate indicator of entropy present +in the password with values such as 0-30 being low, 30-60 medium, and 60-100 high. + +=head1 EXAMPLE + +Typical use of the libpwquality API: + + #include + + ... + + pwquality_settings_t *pwq; + int rv; + void *auxerror; + char buf[1024]; + + 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)); + } + +=head1 SEE ALSO + +L + +=head1 AUTHORS + +Tomas Mraz diff --git a/po/es.po b/po/es.po index 358e2a8..61a4450 100644 --- a/po/es.po +++ b/po/es.po @@ -1,7 +1,7 @@ # SOME DESCRIPTIVE TITLE. # Copyright (C) YEAR libpwquality project # This file is distributed under the same license as the PACKAGE package. -# +# # Translators: # Adolfo Jayme Barrientos, 2015 # Claudio Rodrigo Pereyra Diaz , 2011 @@ -16,11 +16,12 @@ msgstr "" "POT-Creation-Date: 2014-08-06 16:45+0200\n" "PO-Revision-Date: 2015-02-01 00:56+0000\n" "Last-Translator: Adolfo Jayme Barrientos\n" -"Language-Team: Spanish (http://www.transifex.com/projects/p/libpwquality/language/es/)\n" +"Language-Team: Spanish (http://www.transifex.com/projects/p/libpwquality/" +"language/es/)\n" +"Language: es\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" -"Language: es\n" "Plural-Forms: nplurals=2; plural=(n != 1);\n" #: src/pam_pwquality.c:25 @@ -50,9 +51,10 @@ msgstr "Uso: %s [usuario]\n" #: src/pwscore.c:23 #, c-format msgid "" -" The command reads the password to be scored from the standard " -"input.\n" -msgstr " La orden lee la contraseña que se valorará a partir de la entrada estándar.\n" +" The command reads the password to be scored from the standard input.\n" +msgstr "" +" La orden lee la contraseña que se valorará a partir de la entrada " +"estándar.\n" #: src/pwscore.c:51 src/pwscore.c:59 src/pwscore.c:65 #, c-format @@ -68,7 +70,9 @@ msgstr "No se pudo obtener la contraseña que se valorará" msgid "" "Password quality check failed:\n" " %s\n" -msgstr "Falló la comprobación de calidad de la contraseña:\n %s\n" +msgstr "" +"Falló la comprobación de calidad de la contraseña:\n" +" %s\n" #: src/pwmake.c:22 #, c-format @@ -104,9 +108,10 @@ msgid "The password contains the user name in some form" msgstr "De alguna manera, en la contraseña se lee el nombre del usuario " #: src/error.c:47 -msgid "" -"The password contains words from the real name of the user in some form" -msgstr "De alguna manera, en la contraseña existen palabras del nombre real del usuario" +msgid "The password contains words from the real name of the user in some form" +msgstr "" +"De alguna manera, en la contraseña existen palabras del nombre real del " +"usuario" #: src/error.c:49 msgid "The password contains forbidden words in some form" @@ -168,37 +173,47 @@ msgstr "La contraseña contiene menos de %ld clases de caracteres" #: src/error.c:87 msgid "The password does not contain enough character classes" -msgstr "La contraseña no contiene la suficiente cantidad de clases de caracteres" +msgstr "" +"La contraseña no contiene la suficiente cantidad de clases de caracteres" #: src/error.c:90 #, c-format msgid "The password contains more than %ld same characters consecutively" -msgstr "La contraseña contiene más de %ld caracteres iguales en forma consecutiva" +msgstr "" +"La contraseña contiene más de %ld caracteres iguales en forma consecutiva" #: src/error.c:93 msgid "The password contains too many same characters consecutively" -msgstr "La contraseña contiene en forma consecutiva demasiados caracteres iguales" +msgstr "" +"La contraseña contiene en forma consecutiva demasiados caracteres iguales" #: src/error.c:96 #, c-format msgid "" "The password contains more than %ld characters of the same class " "consecutively" -msgstr "La contraseña contiene m ás de %ld caracteres de la misma clase en forma consecutiva" +msgstr "" +"La contraseña contiene m ás de %ld caracteres de la misma clase en forma " +"consecutiva" #: src/error.c:99 msgid "" "The password contains too many characters of the same class consecutively" -msgstr "La contraseña contiene en forma consecutiva demasiados caracteres de la misma clase" +msgstr "" +"La contraseña contiene en forma consecutiva demasiados caracteres de la " +"misma clase" #: src/error.c:102 #, c-format msgid "The password contains monotonic sequence longer than %ld characters" -msgstr "La contraseña contiene una secuencia monotónica mayor de %ld caracteres" +msgstr "" +"La contraseña contiene una secuencia monotónica mayor de %ld caracteres" #: src/error.c:105 msgid "The password contains too long of a monotonic character sequence" -msgstr "La contraseña contiene una secuencia de caracteres monotónica demasiado extensa" +msgstr "" +"La contraseña contiene una secuencia de caracteres monotónica demasiado " +"extensa" #: src/error.c:107 msgid "No password supplied" @@ -210,7 +225,9 @@ msgstr "No es posible obtener números aleatorios desde el dispositivo RNG" #: src/error.c:111 msgid "Password generation failed - required entropy too low for settings" -msgstr "Falló la creación de la contraseña - es necesaria una entropía demasiado pequeña para las configuraciones" +msgstr "" +"Falló la creación de la contraseña - es necesaria una entropía demasiado " +"pequeña para las configuraciones" #: src/error.c:114 src/error.c:117 msgid "The password fails the dictionary check" -- cgit v1.2.1