<section> DBAF::Safe.pm

<function> CheckNameOccupied
<description> Check wether given name is occupied by other user
<accepts>
<1> class from DBAF or DBAF::Safe
<2> system name (aka login)
<3> uid
<returns>
<failure> undef; sets ERROR entry in object called on
<succes> 0 if name not occupied or occupied by given uid, 1 if encountered in stop_words not by uid, 2 if occupied by another user as primary login, 3 if occupied by another user as service name
<note> One can check wether name is occupied at all by supplying zero uid
</function>

<function> GetUidFromEmail
<description> test wether user with given email exist
<accepts>
<1> class from DBAF or DBAF::Safe
<2> email to search for
<returns>
<failure> undef; sets ERROR entry in object called on
<succes> 0 if no uid registered for this email, uid corresponding for given email if found
<note> Can be changed in future version t0 return array of uids
</function>

<function> CheckUserEna
<description> checks ena field for given uid in accounts
<accepts>
<1> class from DBAF or DBAF::Safe
<2> uid
<returns>
<failure> undef; sets ERROR entry in object called on
<succes> returns ena field value or undef if no entry found
</function>

<function> GenNewSession
<description> generate new session for given uid always with sid 8
<accepts>
<1> class from DBAF or DBAF::Safe
<2> uid
<3> choice of paranoia level
<returns>
<failure> undef; sets ERROR entry in object called on
<succes> new session key
<note> Session generated is always for sid 8 with corresponding suid
</function>

<function> GetUidFromSession
<description> function for diggin uid from session
<accepts>
<1> class from DBAF or DBAF::Safe
<2> session key
<returns>
<failure> undef; sets ERROR entry in object called on
<succes> uid or 0 if no session exists with given key
<note> If session with given key exists it's last_acces filed is updated
</function>

<function> DeleteSession
<description> function for removing session
<accepts>
<1> class from DBAF or DBAF::Safe
<2> session key
<returns>
<failure> undef; sets ERROR entry in object called on
<succes> result of deletion
</function>

<function> UpdateSession
<description> updates session
<accepts>
<1> class from DBAF or DBAF::Safe
<2> session key
<3> choice of paranoia level
<returns>
<failure> undef; sets ERROR entry in object called on
<succes> session key
<note> mainly for purpose of setting new paranoia mode
</function>

<function> GetActiveServices
<description> Obtains list of active services for given uid
<accepts>
<1> class from DBAF or DBAF::Safe
<2> uid
<returns>
<failure> undef; sets ERROR entry in object called on
<succes> hash ref; format is following: $hashref->{sid} = ['login', suid]
<note> for the sake of perfomance resulting hash is remebered inside of DBAF::Safe object. Unless it is invalidated by some other function all succesive calls will actualy return same hashref for this uid. Calling function fith another uid will actualy store info for this new uid.
</function>

<function> GetUserInfo
<description> obtains full user info for give uid
<accepts>
<1> class from DBAF or DBAF::Safe
<2> uid
<returns>
<failure> undef; sets ERROR entry in object called on
<succes> hash ref; format is following: <code>
$info->{'login'} = accounts.login;
$info->{'passwd'} = accounts.passwd;
$info->{'passwd2'} = accounts.passwd;
$info->{'uid'} = $uid;
($info->{'fname'},
$info->{'iname'},
$info->{'oname'}) = split(/\s/,account_info.fio);
$info->{'sex'} = account_info.sex;
($info->{'byear'},
$info->{'bmonth'},
$info->{'bday'}) = split(/\-/,account_info.birth_date);
$info->{'xcountry'} = account_info.country;
$info->{'region'} = account_info.region;
$info->{'city'} = account_info.city;
$info->{'charset'} = account_info.charset;
$info->{'fmail'} = account_info.mail_format;
$info->{'icq'} = account_info.icq;
$info->{'email'} = account_info.email;
$info->{'nick'} = account_info.nickname;
$info->{'hintq'} = account_info.hintq;
$info->{'hinta'} = account_info.hinta;
</code>
<note> This function is rather heavy overhead so use it only when indo from both accounts and accoun_info is needed
</function>

<function> GetInfoForCookies
<description> obtains full user info for give uid
<accepts>
<1> class from DBAF or DBAF::Safe
<2> uid
<returns>
<failure> undef; sets ERROR entry in object called on
<succes> hash ref; format is following: <code>
$info->{'login'} = accounts.login;
$info->{'fio'} = account_info.fio;
$info->{'nick'} = account_info.nickname;
$info->{'email'} = subscription.login where sid=2;
</code>
<note> This function is otherwise useless except for cookie info digup at authorization time
</function>

<function> GetAccountInfo
<description> obtains account info for user
<accepts>
<1> class from DBAF or DBAF::Safe
<2> uid
<returns>
<failure> undef; sets ERROR entry in object called on
<succes> hashref; format is following <code>
$info->{'login'} = accounts.login;
$info->{'passwd'} = accounts.passwd;
</code>
<note> hash will be empty if no record found
</function>

<function> GetProjLogin
<description> obtains service login name by given sid
<accepts>
<1> class from DBAF or DBAF::Safe
<2> uid
<3> sid
<returns>
<failure> undef; sets ERROR entry in object called on
<succes> service login name or undef if no name found
<note> if returned undef check error in class called on
</function>

<function> InsertUserInfo
<description> inserting user information into accounts, account_info and
subscription with sid; default paranoia level is 1
<accepts>
<1> class from DBAF or DBAF::Safe
<2> hashref with user information; hash format is following: <code>

</code>
<returns>
<failure> undef; sets ERROR entry in object called on
<succes> new uid
<note> insertion is subdivided into three phases: 1. creation of accounts 
record, 2. creation of record in account_info and 3. creation of record in
subscription with sid 8. While at some phase insertion can failed previous
phases wount be rolled back. Check error log for information what phase did
failed.
</function>

<function> InsertMailInfo
<description> inserts info into safeguard neccessary for mail subscribtio
<accepts>
<1> class from DBAF or DBAF::Safe
<2> uid
<3> Hash ref containing login, passwd, fname, iname and optionaly oname
<returns>
<failure> undef; sets ERROR entry in object called on
<succes> new suid
<note> to bypass check for mail and narod subscription existance feed forth
parameter that must be in this case of true value
</function>

<function> InsertDZInfo
<description> Inserts into safeguard info regarding DZ subscription
<accepts>
<1> class from DBAF or DBAF::Safe
<2> uid
<3> user info hashref containing login and passwd
<returns>
<failure> undef; sets ERROR entry in object called on
<succes> new suid
</function>

<function> UpdatePassword
<description> Updates password in accounts table
<accepts>
<1> class from DBAF or DBAF::Safe
<2> uid
<3> new password
<returns>
<failure> undef; sets ERROR entry in object called on
<succes> 'ok'
</function>

<function> UpdateAccountInfo
<description> updates user account info
<accepts>
<1> class from DBAF or DBAF::Safe
<2> uid
<3> hashref containing user info - replaced as is
<returns>
<failure> undef; sets ERROR entry in object called on
<succes> 1
<note> unlike previous version of passport this version wount modify anything
in supplied hash
</function>

<function> DeleteUser
<description> deletes records from accounts, account_info and subscription
with sid=8 by given uid
<accepts>
<1> class from DBAF or DBAF::Safe
<2> uid
<returns>
<failure> undef; sets ERROR entry in object called on
<succes> 1
<note> All subscription records with this uid and sid!=8 wount be removed
</function>

<function> UpdateLogin
<description> Updates login fields in accounts and subscription with sid=8
<accepts>
<1> class from DBAF or DBAF::Safe
<2> uid
<3> new login
<returns>
<failure> undef; sets ERROR entry in object called on
<succes> 1
<note> In subscription login field modified only for sid=8. See
UpdateServiceLogin for project dependant login changes.
</function>

<function> UpdateServiceLogin
<description> updates per project login fields in subscription
<accepts>
<1> class from DBAF or DBAF::Safe
<2> uid
<3> new login
<4> sid
<returns>
<failure> undef; sets ERROR entry in object called on
<succes> 1
<note> Login updated only for given sid. No other project modification for
project dependant tables performed. Exception is mail (sid=2). Old login is
moved to stop_words with uid and sid and timed stamp
</function>

<function> DeleteServiceLogin
<description> Removes record from subscription by given uid and sid
<accepts>
<1> class from DBAF or DBAF::Safe
<2> uid
<3> sid
<returns>
<failure> undef; sets ERROR entry in object called on
<succes> 1 on deletion, 0E0 (zero but true) if no record exists for sid=2
<note> Record deleted only for given sid. No other project modification for
project dependant tables performed. Exception is mail (sid=2). Old login is
moved to stop_words with uid and sid and timed stamp
</function>

<function> GetUidFromLogin
<description> returns nonzero uid if user can log in with this login and
password
<accepts>
<1> class from DBAF or DBAF::Safe
<2> login
<3> passwd
<returns>
<failure> undef; sets ERROR entry in object called on
<succes> 0 if login/passwd pair isn't valid, uid otherwise
<note> This version implements algorythm sensetive to passwd case
</function>

<function> GetAccessChoice
<description> Obtains user's choice of access mode
<accepts>
<1> class from DBAF or DBAF::Safe
<2> uid
<returns>
<failure> undef; sets ERROR entry in object called on
<succes> user choice
<note> Choice is the login_rule in subscription record with sid=8
</function>

<function> SetAccessChoice
<description> Sets user's access choice
<accepts>
<1> class from DBAF or DBAF::Safe
<2> uid
<3> choice of paranoia level
<returns>
<failure> undef; sets ERROR entry in object called on
<succes> 1
<note> Choice is the login_rule in subscription record with sid=8
</function>

<function> InsertVictym
<description> inserts record into victym table for user to be able to confirm
subscription
<accepts>
<1> class from DBAF or DBAF::Safe
<2> uid
<3> hash ref that it waits to contain some of two entries: getnews and
announce
<returns>
<failure> undef; sets ERROR entry in object called on
<succes> unique key
</function>

<function> GetVirtualId
<description> Obtains VirtualId by given uid & name
<accepts>
<1> class from DBAF or DBAF::Safe
<2> uid
<3> name of site (login in subscription(4))
<returns>
<failure> undef; sets ERROR entry in object called on
<succes> virtual id if found, undef otherwise
<note> returned field host_number from table hosts of safeguard
</function>

<function> ConstructName
<description> Constructs available name when proposed login is already
occupied
<accepts>
<1> class from DBAF or DBAF::Safe
<2> hashref to AllVals; for effective funtioning need login, iname and fname present
<returns>
<failure> undef; sets ERROR entry in object called on
<succes> hashref to array of free names condtructed of data in AllVals
<note> Look inside code for princips of name constructioning


Описание реализации секьюрной (платёжной) авторизации.

Поскольку пользователь не может использовать платёжную авторизацию без общей
авторизации на портале, все необходимые данные о пользователе уже должны
находиться в таблицах safeguarddb::accounts и safeguarddb::account_info. Поэтому дополнительный
платёжный пароль реализован как особого рода "сервис" и вписан в таблицу
safeguarddb::services 

При заведении пользователем платёжного пароля
добавляется запись в таблицу safeguarddb::subscription ; логин пользователя
берётся такой же, как и логин портала; от пароля берётся MD5-hash, который и
заносится в таблицу. 

При авторизации пользователя сравниваются MD5-hash введённого пользователем
пароля и пароля, хранящегося в safeguarddb::subscription .

sid сервиса "платёжный пароль" = 15 .

Соответствующие функции модификации, добавления и проверки платёжного пароля
добавлены в Safe.pm
