_____ _________ ________ ___ ___ _________ ________ / __/ \_ ____/ \ ) | | | | \_ ____/ \ ) \__ \ | _)_ | __ _/ | | | | | _)_ | __ _/ ___\ \ | \ | | \ \ \ \_/ / | \ | | \ \ solutions \____/ /_____ / /_/ \ \ \ / /_____ / /_/ \ \ \/ \/ \_/ \/ \/ (c) Lada 'Ray' Lostak (c) Orcave (c) 2002-2005 Content: Central Boozing System simple suer manual History: 05/18/2002 Ray - initial version 1.0 Architecture ---------------- CBS is based on modules. Module is indepenend par of CBS. Module doesn't need to have anything common with other modules, but they can share some datas. CBS is based on own core library and Stlc which provides all necessary core function for auth, database accesses and others. Planned modules: Admin - allready done, required for administrating :o) Web - 'anonymous' user access (surfer) Mail - standard simple mail client + shared accounts (like support) Web Forums - forums, accesible from 'Web' module. Forum can be live or moderated Web News - 'News' for 'Web' module Stat - statistics for page access/links/crosslinks/click-outs/etc. Many objects (such as user/group) have 'Name' and 'Name ID'. What is difference ? NameId is system unique alais - consists of letters (A-Z a_z) numbers (0-9) and udnerscore (_). It have to start with letter. NameId is used for list, etc. because it is more readable than long name with national chars. Many object also have 'Id' (number). It is system unique ID. It is showed just for security/admin reasons and only in Admin module. Number itselfs it totally unimportant. 1.1 User managing ----------------- CBS admin part know 'user' and 'group'. Every user have some own properties (profile) such as real name, photo, etc. Every user can be member of 0 or more 'groups'. In other way, groups 'consits' of 0 or more users. There is one special user, initially called 'root' (can be renamed). This user have rights to do everything. This user ignores any access rights - it means, this users doesn't need to have assigned any rights but can do everything. 1.2 Access rigths ----------------- CBS uses ACL for assign access rights. ACL is Acces Control List - in other way, 'list' of access rights assigned to user or group. Nearly every action in CBS have corresponding access right, which tell system if user can process given action. If system can't lcoate access right for action and given user (rule doesn't exists), system denied access to user. WARNING: some modules/accesses have 'allow' by default. In this case, missing rule means 'access allowed'. Every ACL rule consits of: 1. ACL type (exported by modules) 2. ACL parametres (depenend on ACL type) 3. assigned groups/users for which given rule hold 1.2.1 ACL type -------------- Every module exports 0 or more ACL types. For example, Admin module exports right to 'administrate' users. Everyone, whoch have this rule (user/group) can do full administrating. ACL type is in dotted form. Becasuse some module will export a lott of rigths, it is more readable, when types creates 'tree'. Every node of this imaginary tree is represented as dotted identifier. For ex. modules.exec It meas 'exec' access right under 'moules' and similar. In CBS you can also see ACL type in full form module@acl_type. Module is in this case name of module, which exports given ACL type. Full ACL type is system unique. In addition, every rule includes description which explains what given ACL type is doing. After create database, or after adding module is required to 'build' type database. See Admin module for more informations. Once Type database is ready, ACL fully works. Every ACL type references some object type. For example 'module', or 'mail group' and others. See modules ACL for details about referenced object and tis properties. 1.2.2 ACL rule -------------- ACL rule is physical instance of ACL type. It means, it is assigned to physical users and also it holds settings/flags/validity districs. EVery ACL rule consists of: 1. ACL type link (ofcourse :o) 2. Rule result 3. Validity specification 4. Constraints/flags 5. Related user/group list (1) is clear. This can't be changed within rule. So, if you need to change rule type, you have to delete rule and create with new type. (2) rule result depends on rule type. Known types: allow - majority of rules uses 'Allow / denied' access. If access denied is selected, system doesn't allow user to process given action. Majority of modules/ACL types have denied as default, so, it is not necessary to explicitly block access by rule (3) Validity specification makes rule more exact. For example, for 'modules.exec' is specification physical module. Known standard types: modules - list of CBS modules users - system users groups - system groups ug - system user or groups Every module can export own specification. In all cases, specification is list of specs, divided into '2' - Allowed and Denined. By default, all is denied ofcourse. For details about validity see module description. (4) Every rule can have additional flags/constraints. It is similar to (3) - but instead of specification there are various flags/constraints. Every moduel can export own. Not all flags/constraints are valid for all ACL types. If they are not valid, they are not present in list. Standard ones: Ignore specs - ignore speficiations, valid for all (useful in combination with others) Owner - rule will hold onl if given user is OWNER of object, which is in center of concern - valid only for types, which referenced object, which are owned by someone (5) Physical users/group list. Rule is valid for all users/groups listed here 1.3 Data security ----------------- After user connects and sucesfully login (login can be anonymous/automatical) system creates SessionId. This session ID connect to database as 'admin' user. But after login, system switch to 'different' database user which doesn't have physcal access too all DB tables. Why ? Assume there is a BUG in system, which allow atacker unauthorized DB command execution, or increase his system rights. What will happend ? He can read all tables, etc. Every module exports for every rule 'list' of tables, with access (read/write). CBS allows admin to create more physical DB users with different physical access to tables. After login, CBS switch to different phsyical user. So, if attacker attacks 'normal' account (get password somewhere, key, whatever) and find bug in system, he have also break physical DB users, which is verry hard, until he will have access to other tables (datas). For example, if we have table 'PRIVATE' which hold our 'private' conversation, we can create 2 physical DB users: 1. normal 2. superuser Normal user will have read access to 'users' table (always required ofcurse), and other tables which he need (anonymous users doesn't need write access to anything at all). But 'superuser' will include read/write access to our 'PRIVATE' table. This increases a lott of security of whole system. It is required to find hard csecurity bug in 2 or 3 progreams, not in one. And in all at one time. In all cases, our system is 'secure' by itselfs, but the best way, hwo to make security is to count with internals defects. In real live, there will be probrably 'a lott of physical DB users'. Every CBS user have assigned just in the moment one DB user. Every module with table list and access rigths also export comment - what table means. It is up to administrator (user one, not system) to create proper access rules and DB users. Every rule contains 'table results' - list of tables and access rigths, like: USERS r LISTS r PROFILES w (tables which are niot liseted are not accessed in any form by user). Maybe this can be done automaticly, and CBS can create 'DB' user automaticly. I am planning to do this automaticly, but not right now. 1.4 Security ------------ General security is also very important. All users, which logs into system, to other modules than 'Web' should use HTTPS connection (required). Every user can user static or SAuth login (both). It is up to admin to divide VIP users and denied them static login and force using SAuth or keep them both, if they are enough clever to use SAuth and staic only if there is no-other way. Passwords.... PAssword need to be at least 7 chars long, it HAVE TO include small and BIG letter and also at least 2 chars from this list: !@#$%^&*(),.?/ It is also prohibited to use 'words' like sex, beer, names, etc. Password are not stored in database in text form, so, admin can't be sure, if users use lame password. For this reason, it is insitalled on system 'password' cracker which checks, if password can be cracked simple, and if yes, it required to use 'harder' password. Password for static logins should be changed every month. If attacker is going to guess password, system allows 4 times to try. Then it creats 'pause' between gueses. First time 4 seconds, then 8, 16, etc. up to one hour. After time timeout is end, user can 'try' again. It is enough for security (we don't need to lock/unlock account). On the second side, in this period, system doesn't accept ANY password (including valid one). So, it ispossible, if someone start password attack, that valid user can't log in. Valid user have to WAIT until attacker will stop his stupid tries (probably allready stops :) or ask admin to solve security trouble. This problem can't be solved by CBS admin but system (server) admins. After 15 minutes of 'not working' with system, system automaticly logout user. If user send request after this persion, system shows him error abotu timenout. After 1 hour of stop workng with CBS, system deletes user session (not only invaldiate, physically deleted) and show user different error - not timeout, but something abtu session ID and posisble crack, etc. So, be awarte of keeping 'openned' CBS windows without work with them. It is enoigh to press 'refresh'. CBS doesn't use cookies, session variables are crypted by 2 128bit keys, one unique for server, second unique per session, so, should be pretty hard to break into system and supply invalid inputs. System by detault doesn't show 'link' for action, which users doesn't have rights to do. For example, in user view can be visible 'delete user' link. But only if user have access to admin, link will be visible. So, there is 2 way protection: 1. system doesn't send link to sensitive operation (to send, attacker have to break 2 128 bit keys) 2. system checks accesses before processing given action too It increases a bit server load, but makes system more secure. 2.0 Modules ----------- Enought about 'common' things and let's look in details at physical modules. 2.1 Index --------- Small module, which allows user to 'select' which module will be processed. This module is required and can't be removed from system. If user doesn't have assigned any modules, module will end session. Some user can be logged automaticly and some module can be runned also automaticly. Typically 'Web' users login automaticly and 'Web' module is runned. So, after executing 'www.domain.com' everyone automaticly see web pages. But for CBS system, it is physical user and can be watched, etc etc. 2.2 Admin module ---------------- Module, which is small exception in system. It is not indepenend module, but this module shares with CBS core all inforomations - users/access rigths, etc. There is no next module, which is 'a part of core' at all. Modules goal is to administrate users/groups/access rights and other core things. Module is required and can't be removed from system. 2.2.1 User administration ------------------------- Allows to view users, search, etc. Nebudu popsiovat kazdou picovinu co jsem tam udelal :) User properties: Photo - need to be PNG (BIG can be also accepted). Max size is 32Kb Name - title, first name, middle and last Alias - user NameId (see CBS preface) Addresses - lsit of IP addreses, from which user can login in std form a.b.c.d/mask where mask is count of '1' bits in mask. If not given, 32 is used. To allow user login from anywhere put here 0.0.0.0/0 State flags - various flags, right now flags whcih allow user to login into system by passwd/sauth protocols. If none is included, user can't login into system (account is disabled) Groups - list of groups, which users is member 2.2.2 Group admin ----------------- Allows to add/delete/manage groups. Every group have followign attibutes: Name - name id Commnet - some wierd comment Memebrs - members list 2.2.3 Companies admin --------------------- Companies administratuion, nothing to add. All other modules, excpet admin, have stored all datas in separate tables. If user is present in more companies, after login, he have to select current. Every company have fully separated datas. Except users, etc. Addresses etc. will be used only for reports (stats, ...) 2.2.4 ACL admin --------------- There is nothing to add, everything was said before. "Update ACL" creates (updates) ACL type list. It is necessary to do only after initial DB creation or after adding some module. So, probbaly will be used only by system admin. View ACL types shows all current known types. It is just informatical table. View ACL shows table with all ACL's. Click to edit :) 2.3 Mail lists groups --------------------- Mail list module (ML) should allow managing fully automatical mail list. There are few types if mail list: 1. Public 2. Moderated 3. Private Mail list 'robot' which administrates it should be accesible from WEB and MAIL (both). Mail robot shoul be abble to do following things: 1. Add anyone to any 'mail group' (respecting access rights) 2. Remove anyone from mail groups 3. List all subscibed mail groups (public) Every 'subsriber' have following properties: 1. id (auto increment) 2. email (john@dee.com) 3. name (John Dee) 4. adding time 5. send_errors 6. disabled 7. disabled_time All mail lists properties are also stored as table. Record includes 'send_errors' column, which informs system about deliver error. When send_errors count reached some points, account is 'disabled'. Accounts older than some time are physically removed from database. Next table holds references beteen email lists and users. 1. list_id 2. user_id CBS users can use 'template' to send email to list. See chapter "Templates" for details. Note: template are used in many other parts, such as Mail client, Bugy bugy and others. 2.3.1. Mail robot/admin ----------------------- All should be based on 'mail' - no password will be used. If user will subscibe from web or mail, server will reply with 'acknowledge' email. Replying this email (with some generated ID to verify in subject) will process real (un)subscription. All text will be possible to assign to each separate mail list - throw 'codebook'. It means, some email lists can be in english, some on czech. This codebook will define all texts for robot. Robot should be accesible throw web and email. Email should be XXX@lists.orcave.com where XXX is list alias or "admin" for robot itselfs. Additionakl form should beL: subscribe-XXX@orcave.com (alias to 'subscribe xxx' command) unsubscribe-XXX@orcave.com (alias to 'unsubscribe xxx' command) Robot commands are given in SUBJECT. Robot should recognize these commands: info XXX subscribe XXX unsubscribe XXX list Info send info about email list XXX. (un)subscribe is clean. It sends text, which inform user about action, something like (fully editable for avery mail gorup list): Subject: Confirmation for subscribe XXX Someone (possibly you) has requested that your email address be added to the mailing list "XXX@lists.orcave.com". If you really want this action to be taken, please send the following commands (exactly as shown) back to "admin@lists.orcave.com": auth AAAAAAAA subscribe XXX YYYYYYYY For most emailing client is enough reply to this email. If you do not want this action to be taken, simply ignore this message and the request will be disregarded. If you have any questions about the list, please contact "XXX-info@lists.orcave.com". Thanks! admin@lists.orcave.com AAAAAAA=generated ID YYYYYYY=related email Similar for unsubscribe. Text are stored in database and can be reused between various lists. It is not important to sub-class these text for languages, because list is in "some langauge", so, one text per mail is enough. 2.3.2. List properties ---------------------- Every list include at least these properties: Alias - the most important thing Name - full list name Desc - list description (short) Info - list informations (used on web or send by XXX-info@lists) Type - private/moderated/public Text - alais for 'texts' (see above) Body type - text only (NO html possible) - any HTML tags are ripped our HTML (only base tags) - base tags are kept - all scripts etc. is removed HTML (as is) - whole body is kept (security hole for public lists) Body flags - flags: allow attachements - allows sending files throw mail list allow dangerous file types - allows sending all files throw email list (without this options are files like EXE, DLL, HTM(L) etc. ripped out) Max size - max of email (usually ~4-32 Kb) Approve - Approval points (0-100) >=100 -> email is sent Approve_list- List of ppl who 'sign' email (and its approval scale) ACL rules: send into email list (send to list) send into email list (send to list - 50 points) moderator/approval ('approve' emails to be sent) moderator/approval ('approve' emails to be sent - 50 points) history_view/search list (view/search history list) history_write access (modify, remove emails, ...) admin (add new users, change properties) add_new_list (add new lists - adding user become admin @ the list) admin (full lists aministration) 2.3.3. Security --------------- Sending files/html to email lsit is secure, robot wipe out HTML tags or dangerous files. For internal emails, this rescriction can be off. It is higly recomended to public lists remove possibility to send files and html bodies. CBS security. There is ACL rule 'send to email list' and '50' version. It means, if someone have '50' right, 2 ppl need to sign before email is sent to list (for highly sensitive groups). This should prevent typos, mistakes, etc. So, if user A send email to private list and user have access 'send into email list', email is immdediatelly send. If not, someone with at least 'half' ACL have to 'sign' email too. It is possible to add also other 'levels' of approval if required. 2.3.4. List functions --------------------- Public list: every one can send email to xxx@lists and this email will send to all subscribe users. Robot accepts only emails from ppl, who are subsribed. If anyone else send email to robot, robot reply with 'error' (text on server). See error err_not_subscriber. Private list: only valid CBS user may send emails to the list. See down how it should work. Moderated: If someone send email, valid CBS users with right ACL have to 'sign' email. When email is approved, robot send it to all users. 2.3.5. Texts ------------ Mail/Web interfaes uses smoe text to communicate with users. These text are stored and can be reused in more groups. THere are separate texts for: Subscription Example above Unsubscription Example above (very similar) Info "You requiested info about XXX mail list." Bye ! admin@lists.orcave.com Error Error text. Something like: "During processing your request following error occurs:" If you have any questions about the lists, please visit http://www.orcave.com/redir?dst=support.cbs.lists&src=cbs.list.msg Thanks! admin@lists.orcave.com When body of this text need to 'reference' something (such as author email, error text, security ID, etc.) it should use %tag_name% which will be replaced. Error text can be also defined. It is stored in separate database. Error texts can be also reused, byt they will be reused mainly on language. That's why they are separate from normal text. Error texts are stored in form: error_alias text_to_user details 2.3.6. Error codes ------------------ Known error codes: error_not_subscriber - "You are not subscriber of XXX mail group" "If you are not subscriber of XXX meail group, you can't send emails to the group. For subscription send email to admin@lists with "Subscribe XXX" in the body. NO other error yet defined... :) 2.3.7. Mail storing ------------------- All mails send to lists are stored in database. Emails in database are stored in ASCII encoding. If email was crypled with some MIME format, it is ENCODED before storing (for simple finding). Attachments are stored in separate database (performace reasons). So, we have 2 tables with datas: Mails: 1. Mail ID (auto increment) 2. Mail list 3. From 4. Body (ASCII coded) Attachments: 1. Mail ID 2. Binary attachment Before storing emails attachement should be wiped out 'standards' attachements, like "signature.asc" text version of HTML email and similar 'auto attchements'. Every list have separate table(s) for storing history (security reasons) 2.3.8. Templates ---------------- When user decides to send tempate to mail list, template can use following items: 1. email [edit field] - like: john@dee.com 2. name [edit field] - like: John Dee 2.3.9. Summary -------------- We have following tables: lists - all lists and their properties lists_users - all users subsribed in some email list lists_distribution - users & list references lists_erros - lists errors lists_txt - admin list related texts lists_history_XXX - list history lists_history_att_XXX - list history attachements 2.4. Templates -------------- Template is separate module, which allows to store 'template' with fields. Fields can be filled by user or can be filled automaticly. Every template have following properties: 1. ACL edit view/use 2. Alias (short name) 3. Full name 4. Editable items list 5. Body 6. Tree position Templates are associated in tree. CBS export all function needed for tree operations. Author of template can limit user, who can use/change given template. While creation of template, author creaed 'body' and 'item list'. Item is something, what user who is using template fills (or item is filled automatically). Body of template is valid 'template' engine. So, there can be used IF/ELSE if necessary or just simple reference 'item' values. When user is going to send template, it shows to him page with items to fill. In next step, user see 'generated' text and if he 'apply', email is sent/or ready for approving. Every item have following attributes: 1. Template ID to which it belongs 2. Order 3. Alias 4. Full name / help 5. Type 6. Type specific field (for list here is list of avilable items :) 7. data type Some items may be filled by users, other may be filled by module, which calls template. Supported items: 1. list - user selects from predefined values (combo box) 2. edit - user fills text 3. editlong - user fills text, but long one Supported types: 1. manual - user have to fill) 2. auto - module fill automaticly (by mail module or sending one) 3. date - item is filled with current date