#reading file /usr/local/src/devel/IdM/pwReset/etc/pwReset-unclean.sys

progname = "pwReset"

version = 0.1

date = "2011-01-11"
<author>
   name  = "Peter Gietz" 
   org= "DAASI International GmbH"
   mail = "peter.gietz@daasi.de"
</author>

<copyright>
text1 = Copyright (c) 2005 DAASI International GmbH
text2 = This library is free software; you can redistribute it and/or \
modify it under the same terms as Perl itself.
</copyright>

progshortdescr = "Webtool for password reset"

<progdescription>
text1 ="pwReset is a simple webtool for password reset. It works as follows: \
When first started (status = 'none') it tests whether cookies are enabled \
(via redirect to status testcookie), and returns a respective message to the \
user if not, with a link to start all over again." 
text2 = "If the cookie is \
retrievable an Apache-session is established (information is stored in files \
on the server) and a mask is shown to the user, where she can input an ID \
(loginid, email address or TextGrid ID). If mode 'oneinputfield' is set in the \
configuration there is one input field for either of them, if not, there are \
three separate input fields."
text3 = "After pressing the \"verify me\" button the programm is called with \
'sendlink' status where the programm first checks whether the input values \
conform to configurable regular expressions \
(e.g. \".*\\@.*\" for email address), \
returns respective errors if they do not conform. If they do, the programm \
looks up the ID in the LDAP server and retrieves an email address from there \
(even if the ID was the mail address). \
If the ID was found a separate sessionid (not the ID in the cookie) is created \
and concatenated to an url that calls status 'printform' and that url is sent \
to the email address with some configurable text."
text4 = "If the user clicks on the url in that email, the sessionid in the \
query is compared with the respective id stored in the session and if they \
are identical a form to input the password (in two separate input fields) is \
displayed. After pressing the button \"reset password\" the program is \
restarted with the status 'modify'."
text5 = "In this last status again the matching of sessionid is checked, as \
well as the matching of password and retyped password. Then it is checked how \
often the session has been used (there is a counter for every access) and \
whether that number is less than a configurable maximum. The password value is \
then tested against the configurable regular expression that defines the \
password policy. If any of these checks fail a respective error message is \
displayed, otherwise the program looks up the entry and changes the password \
in the LDAP server."
text6 = "At any error state, the user either gets the last input screen (e.g. \
when wrong values have been inputted) or a link to restart the process (e.g. if \
session is not valid any more). A lot of things are configurable (see the \
single options below). HTTPS as well as TLS for the LDAP connection can be \
enforced. All activities can be logged. Configuration concerning input fields \
(labels, regExp, etc.) happens in a hash at the beginning of the source code. \
Everything else can be configured in a Apache style configuration file. All \
passwords needed (for LDAP access and for SMTP auth) are sored in a separate \
file."
text7= "If you start the program with status 'adminhelp' \
(/url/?status=adminhelp) this manpage is displayed in the browser. You can \
additionally specify one single configuration option to only have the help to \
that option displayed (e.g. /url/?status=adminhelp&helpfeature=emailconfig). \
The adminhelp feature can be turned off in the configuration."  

</progdescription>
 

<bugs>
text1 = "Please report bugs to peter.gietz@daasi.de"
text2 = "some todos are: "
text3 = "more than one regExp per inputfield"
text4 = "multilanguage support is already designed but needs gettext translations"
text5 = "configurable css file does not work properly yet"
</bugs>

<additions example>
text1 = "For getting this manpage: "
text2 = "   pwReset.pl -h"
text3 = " "
</additions>

<additions requirements>
text1 = "Following modules are required: "
text2 = "* Config::General"
text5 = "* File::Basename"
text6 = "* File::Copy"
text7 = "* File::Flock"
text8 = "* File::Temp"
text9 = "* Getopt::Std"
text10 = "* IO::Prompt"
text11 = "* Log::Log4perl"
text12 = "* LWP::Authen::Ntlm"
text13 = "* MIME::Base64"
text14 = "* Net::LDAP"
text15 = "* Net::SMTP"
text18 = "* Text::Wrap"
</additions>

<options loglevel>
        key = "l"
        must = 0
        description = "Loglevel for controlling logmessages."
	description_de = "Loglevel zur Kontrolle des Logging."
        arg = 1
        argtype = "skalar"
	values = "no, all, debug, info, warn, error, fatal" 
        default = "warn"
</options>

<options logfile>
        key = "L"
        must = 0
        description = "Name of the logfile with absolute or relative path. "
	description_de = "Name der Logdatei mit absolutem oder relativem Pfad." 
        arg = 1
        argtype = "filename_add_subdir_log"
        default = "pwReset.log"
</options>

<options debugmode>
        key = "d"
        must = 0
        description = "Sets debug mode to on."
        description_de = "Stellt den Debug-Modus an."
        arg = 0
</options>

<options verbose>
        key = "v"
        must = 0
        description = "Sets verbose mode which makes the program quite chatty."
        description_de = "Stellt den Verbose-Modus an, womit das Programm \
        gespraechiger wird."
        arg = 0
</options>

<options language>
        key = "G"
        must = 0
        description = "Sets the language for output like this one"
        description_de = "Setzt die Sprache fuer Ausgaben wie diese. "
        arg = 1
	default = en
	values = en, de
</options>

<options passwordfile>
        key = "p"
        description = "Name of the password file which contains the secrets \
		    the programm must know to connect to data bases etc. \
		    The format for all lines of this file must be: \
		    <token><blank><password> where <token> has to be the \
		    option label which defines the database such as e.g. \
                    \"outputuri\". "
        description_de = "Name einer Datei, welche die Passworte enthaelt, \
		    die das Programm wissen muss um Datenbanken zu \
		    kontaktieren etc. Das Format dieser Datei ist: \
		    <Token><Leerzeichen><Passwort> wobei <Token> ein \
		    Optionsname sein muss, welcher die Datenbank \
		    definiert wie z.B. \"outputuri\". "
        arg = 1
	default = "pwReset.secret"
        argtype = "filename_exist"
</options>

<options configfile>
        key = "c"
        must = 0
        description = Name of the user config file with absolute or \
		    relative path."
        description_de = Name der benutzerdefinierten Konfigurationsdatei \
		    mit absolutem oder relativem Pfad."
        arg = 1
        argtype = "filename_exist_subdir_etc"
        default = "./etc/pwReset.conf"
</options>


<options printhelp>
        key = "h"
        must = 0
        description = "prints out the manpage"
        description_de = "Druckt die Manpage aus"
        arg = 0
</options>


<options helpfeature>
        key = "H"
        must = 0
        description = "prints out description of the feature referenced by \
	    commandline flag or config file token. "
        description_de = "Druckt die Beschreibung der Option aus, die \
	    entweder ueber den Kommandozeilen- oder ueber den \
	    Konfigurationsdatei-Parameter spezifiziert wird."
        arg = 1
</options>


<options emailconfig>
        key = "e"
        must = 0
        description = "specifies the SMTP-communication of the program, in a \
	        string with token-value pairs, format: \
		\#token1=value1;\#token2=value; etc. \
		Following tokens are understood: \
		\#smtprelay sets the mailserver from which the mail should \
		be sent \
		\#from sets the from address of the mail to be sent. \
		\#to sets the mailaddress of the administrator to whom mails \
		should be sent. More than one address can be separated by \
		comma. \
		\#subjectpart sets a prefix that will be included in the \
		subject line.\n\
		\#hello sets the smtpclient name.\n\
		\#smtpuser sets the user name SMTP Auth authentication. \
 		In this case the corresponding password has to \
		be stored in the passwordfile (-p, default is \
		dbconnector.secret) behind the token smtpauth."
         description_de = "Spezifiziert das Mail-Interface des Programms \
	        wodurch in bestimmten Faellen automatische E-Mails an den \
		Administrator geschickt werden koennen. Das Format besteht \
		aus mit Semikolon getrennten Schluessel-Wert-Paaren, wobei \
		der Schluessel mit einem vorgestellten \# gekennzeichnet \
		wird: \n\
		\#token1=value1;\#token2=value; etc. \n\
		Folgende Tokens werden unterstuetzt: \n\
		\#smtprelay spezifiziert den Mailserver von welchem aus die \
		Mail geschickt werden soll.\n\
		\#from spezifiziert die Sender-E-Mail-Adresse.\n\
		\#to spezifiziert die Ziel-Adresse des Administratoren, an \
		den die automatischen Mails geschickt werden sollen. \
		Hierbei koennen mehrere mit Komma separierte Adressen \
		angegeben werden.\n\
		\#subjectpart setzt ein Praefix fuer die verschiedenen \
		Mail-Subjects.\n\
		\#hello setzt den smtpclient-Namen.\n\
		\#smtpuser setzt den User-Namen für SMTP \
		Auth-Authentifizierung. Wenn dieser gesetzt ist, muss \
 		das korrespondierende Passwort in der mit \
		passwordfile spezifizierten Datei (-p, Voreinstellung \
		ist dbconnector.secret) hinter dem Stichwort smtpauth \
		eingetragen sein."
        arg = 1
	argtype = token_emailinfo
        default = 0
</options>

<options cssfile>
        key = "C"
        must = 0
        description = "Name of the CSS file with absolute or \
		    relative path."
        description_de = "Name der CSS-Datei \
		    mit absolutem oder relativem Pfad."
        arg = 1
        argtype = "filename_exist_subdir_etc"
        default = "./etc/pwReset.css"
</options>

<options sessionpath>
        key = "s"
        must = 0
        description = "Path (relative or absolute) of the directory where to store session information."
        description_de = "Pfad (relativ oder absolut) zum Verzeichnis, in dem die Session-Informationen gespeichert werden."
        arg = 1
        argtype = "filename_dir"
        default = "./sessions"
</options>

<options sessionlockpath>
        key = "S"
        must = 0
        description = "Path (relative or absolute) of the directory where to store session lock information."
        description_de = "Pfad (relativ oder absolut) zum Verzeichnis, in dem die Session-Lock-Informationen gespeichert werden."
        arg = 1
        argtype = "filename_dir"
        default = "./locks"
</options>

<options sessiontime>
        key = "T"
        must = 0
        description = "Sets the duration of a cookie session. Format: +<number><unit>, where you can specify the following units:  s for seconds, m for minutes, h for hours, d for days, M for months, and y for years"
        description_de = "definiert die Lebensdauer einer cookie session. Format: +<Nummer><Einheit>, wobei Einheit s für Sekunden, m für Minuten, h für Stunden, d für Tage, M für Monate, und y für Jahre steht. "
        arg = 1
	default = "2d"
</options>


<options title>
        key = "t"
        must = 1
        description = "Sets the page title."
        description_de = "definiert den Seitentitel."
        arg = 1
	default = "Password Reset Tool"
</options>

<options charset>
        key = "X"
        must = 1
        description = "Sets the character set."
        description_de = "definiert die Zeichensatzkodierung."
        arg = 1
	default = "utf-8"
	values = "utf-8, iso5889" 
</options>

<options bgcolor>
        key = "b"
        must = 0
        description = "Sets the background color"
        description_de = "definiert die Hintergrundsfarbe."
        arg = 1
	default = "ffffff"
</options>

<options linkmail>
        key = "K"
        must = 0
        description = "Sets the text for the link mail"
        description_de = "Definiert die link mail"
        arg = 1
	default = "You receive this message, because someone (probably you) requested $ to reset your Password. $ You can do this with following link: %URL%"
</options>


<options meta>
        key = "M"
        must = 0
        description = "Sets the metatags. Format: name1:content1|name2:content2"
        description_de = "definiert die Meta-Tags. \
	 Format: name1:content1|name2:content2"
        arg = 1
	default = "Robots:noindex,nofollow"
</options>

<options ldapuri>
        key = "u"
        must = 1
        description = "URI for input of LDAP data. \n\
		    The format for the LDAP URI is (see RFC 4516): \
		    ldap://<host>[:<port>]/<basedn>?<attributes>?<scope>?\n\
		    <filter>?<extension> where <extension> can by now only \
		    be either bindname=<bindname> for authenticating to the \
		    server. In this case the corresponding password has to \
		    be stored in the passwordfile (-p, default is \
		    dbconnector.secret) behind the token inputuri. \
		    The second extension supported is \
		    config=<Slapd-configuration file>, which is only \
		    needed with inputformat _REPL."
        description_de = "URI fuer Eingabedaten aus einem LDAP-Server.\n\
		    Das Format fuer die LDAP-URI (siehe RFC 4516) ist: \
		    ldap://<host>[:<port>]/<basedn>?<attributes>?<scope>?\n\
		    <filter>?<extension> wobei als <extension> gegenwaertig \
		    folgende Erweiterungen unterstuetzt werden:\n\
		    bindname=<bindname> zur Authentifizierung am Server, \
		    wobei das korrespondierende Passwort in der mit \
		    passwordfile spezifizierten Datei (-p, Voreinstellung \
		    ist dbconnector.secret) hinter dem Stichwort inputuri \
		    eingetragen sein muss.\n\
		    config=<Slapd-configuration file>, womit die zu \
		    verwendende Open-LDAP-Konfigurationsdatei spezifiziert \
		    wird, was nur im Zusammenhang mit dem inputformat (-I) \
		    \"_REPL\" benoetigt wird."
        arg = 1
        argtype = "uri"
</options>

<options pwhash>
        key = "P"
        must = 1
        description = "Specifies the password hash algorithm"
        description_de = "definiert den Passwort-Hash-Algorhitmus"
        arg = 1
	default = "SSHA"
	values = "SSHA, MD5, CRYPT"
</options>

<options forcehttps>
        key = "f"
        must = 0
        description = "Forces https."
        description_de = "Erzwingt https."
        arg = 0
</options>

<options oneinputfield>
        key = "o"
        must = 0
        description = "Combines all ID-inputfields to one and creates a complex filter"
        description_de = "vereinigt alle ID-Eingabefelder in eins und baut entsprechende Filter auf"
        arg = 0
</options>

<options forcetls>
        key = "z"
        must = 0
        description = "Forces START_TLS in LDAP-connection"
        description_de = "Erzwingt START_TLS in LDAP-Verbindung"
        arg = 0
</options>

<options enableadminhelp>
        key = "a"
        must = 0
        description = "Allows display of adminhelp"
        description_de = "Erlaubt die Anzeige der Admin-Hilfe"
        arg = 0
</options>