diff --git a/README.md b/README.md index 78413cd..638b88d 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,431 @@ # dev_endboard +Description + +endboard is a textboard, intented for the use as a small service on tor +or i2p. It was written with the goal of anonymity and security, both for +the users and the admin. +Some things work differently in the darknets, and the code needs +to reflect this. I developed endboard based on the codebase of smolBBS +(see below) for my site terminus.i2p. Basically I wanted something +lightweight* that would work on both tor and i2p and be easy +to setup (without an external database). I guess the big time of forums +and boards is over (making way for TikTok), anyway I couldn't find +anything that really suited me. +smolBBS came close at least in the approach, so I started from there. + +*lightweight in terms of ease of installation and maintenance. +Code minification was a target in the beginning, but I had to give it up +to make space for all the features I wanted. + + +For the users + +The textboard allows anonymous posting only, and it has no timestamps. +Only one sub is created automatically (main), others can be created by +giving a new name for the sub when posting in main. +An overboard lets you keep the overview over the latest postings. +Also, users can define their own multifeeds, including or excluding +subs of their choice. +There can be replies to posts, which bumps the original posts to the top +of the sub and the overboard (if enabled). +A (very simple) captcha can be used to protect from some spam. +Individual threads, subs or the whole board can be dumped to a json file. +The dump of the whole board can be reimported into other instances of +endboard, which will replicate all messages from the existing board +(the "save overboard" link actually dumps all posts on the board, +including those that are not actually displayed on the overboard). +A landing page provides an overview of the site and the subs, and it +lets the user choose between different display styles. +If enabled, users can make automated posts via a bot api. +A simple bbcode dialect can be used to display headlines, bold text, +underlined text, strikethrough text, spoilers and links. + + +For the admin + +All options can be configured in one config file (or two, if the +webserver counts). +After login, the admin has access to a panel in which posts and subs can +be deleted. Also, logs can be reviewed and messages imported +(from other instances of endboard). +The administration is fairly straightforward, like the user interface. +Be careful when deleting posts, and especially whole subs, as they +cannot be restored. +Data backup should be done on a regular basis, this can be achieved by +simply copying the database file. +For the use of the admin panel, no cookies are necessary. +Moderators can help with the administration. In contrast to the admin, +a message or sub deleted by a moderator is not actually deleted and can +be restored after. +The access to the admin panel and the moderators panel can be disabled +in the config file, if needed. +For sites which are actively targeted and want to maximize security, +the interface for users, the panel for the admin and the panel for the +moderators could listen on three different addresses, where only the one +for the users would be public and the other two would be kept secret. +A simple fail2ban mechanism can be used to restrict the number of +unsuccessful logins (if exceeded, the interface will sent +429 - too many requests). + + +Technical description + +endboard is written in php and works with the versions 7 and 8. The +modules used are php-mbstring, php-json, php-fpm and php-sqlite3. +All posts are stored in a single database file (the path of which can +be configured). +The webserver used is nginx. Other servers should work as well, provided +that they can perform server rewrites and the admin replicates the one +from nginx (provided with the config file). + +The php is (with the exception of the calls to sqlite3) procedural. All +php code is in two files: +index.php at the webroot and config.php in /etc. + +Paths were chosen according to recent Linux standards (config goes to /etc, +working files to /var, the actual website to /srv). +Custom paths can be used, but will need adaption of config file +and/or index.php. + +Release history: + +-0.63 : changed from hash() to password_hash() for passwords, thanks anon. +-0.64 : fixed a bug in destroy_token(), which would not log you out, + although claiming to do so +-0.65 : introduced new function filter(), to get rid of lenghty + substr(preg_replace constructions + fixed a bug in check_free_space() + minor optimizations (like empty instead of isset) +-0.66 : put in some additional safety for the admin & mod tokens_ +-0.67 : fixed two embarrassing bugs that prevented the admin and the mods + from logging in + +Other features of endboard: + +1) to have pretty urls (means: well readable), the request parameters + are parsed directly from $_SERVER['REQUEST_URI'], instead of using + the $GET array. + This leads to links like : http://terminus.i2p/s/main instead of + http://terminus.i2p/?s=main. + +2) treatment of bots: there are a lot of crawlers, spiders and scrapers + out there that don't respect robot.txt, this is just a fact of the + internet. There is no reason to make it easy on them, though. + In fact, I can think of a lot of reasons not to. Therefore, several + links which are not visible to the users are sprinkled over the site. + Garbage data is sent to any bot that follows. More garbage + data is fed to bots that even follow links on the garbage site + itself. Badly coded bots and scripts can crash under the number of + links that is sent to them. Stay off my site next time. + Bots can also be blocked from the site on the basis of the ips. + Obviously, this works better for i2p than for tor. + +3) endboard provides a shortform to view subs, based on the first match. + So, http://terminus.i2p/s/m will lead to the sub 'main', because this + is the first match. http://terminus.i2p/s/me will lead to 'meta'. + The shortform is casesensitive, so http://terminus.i2p/s/p will lead + to 'pr0n', but http://terminus.i2p/s/P will lead to 'PP'. + + +Opsec + + +Best practises that were followed in the coding of endboard: + +-all user input is checked and filtered before further use +-in particular, all tags are stripped from posted texts +-no javascript, no cookies, no tracking is used anywhere +-config file and database are not in webroot +-all passwords and keys are hashed with the bcrypt function used by php + password_hash(). + (except the keys for the bots, as those are not considered sensitive) +-all interactions with the db take place via prepared statements +-the panels for mods and admins can be disabled in the config file + + +Best practises that were _not_ followed in the coding of endboard: + +-the access to the admin and mod panels (after initial authentification + with name/password) is done via a server generated token which is + transmitted in part via links to GET requests. + As such, this is a bad practise because it could enable an attacker to + acquire this token and thus steal the admin session. To make this + harder, the token is very long (250 characters), so that it cannot be + memorized, and is not fully displayed in the address bar. Also, each + token has a limited lifetime (that can be set in the config file) and is + deleted once the admin or mod logs out. + On top of that, the token is regenerated after each transaction, so that + even if an attacker could get hold of an existing token, it would only + be valid until the next activity of the admin or mod. If an attacker + was able to steal the token and use it successfully, the admin or mod + would notice with their next click (which would generate an error message + on account of their own (now invalidated) token). + The reason for all this is that I did not want the admin of the board + to have to have cookies enabled, which would be the normal way of + dealing with this (or to give credentials for each activity, like it + was in earlier versions). + There are risks implied with this new approach, but it is better than + cookies imo. Another implication of this is that endboard absolutely + needs end-to-end encryption to be provided by the underlying network, + like it is the case with tor and i2p. On clearnet, it would be trivial + to steal a token for any machine between client and server (like it + used to be with pop and ftp passwords, remember?). + On the darknets, this approach should work fine, though, and you don't + have to worry about cookies identifying you as the admin of an + infamous textboard :-). + + +Changes from smolBBS + +Almost no original code is left from smolBBS, the leftovers are the +captcha generation and a part of the spam check. I also stayed with the +idea of having different modes of the site to structure the code +(although there are a lot more now). +All in all, endboard has a lot more features today, and is not really +comparable any longer. Thanks go to sandlind for the initial inspiration + to make a board that is just simple and working. + + +Installation instructions + +The following instructions use debian, because I'm lazy. Adapt to your +system if needed. The setup of a tor hidden service or an eepsite is not +part of the instructions, as these topics are covered in countless other +instructions already. +The same for securing your server and making sure it doesn't blab. + + +Update your system and install needed components: + +# apt update && apt upgrade -y +# apt install -y php php-json php-mbstring php-sqlite3 php-fpm nginx + +Make directories: + +# mkdir -p /srv/endboard /etc/opt/endboard /var/opt/endboard + +Distribute files to webroot (from directory of the endboard archive): + +# cp -rv ./srv/* /srv/endboard/ + +Distribute config file to etc (from directory of the endboard archive): + +# cp -v ./etc/config.php /etc/opt/endboard/ + +Give ownership of working directory to webserver: + +# chown -R www-data:www-data /var/opt/endboard + +Copy config file for nginx (from directory of the endboard archive): + +# cp ./etc/endboard /etc/nginx/sites-available/ + +Edit the two config files according to your needs (at the very least, +define the landing page and the name of the admin account). + +Enable the site: + +# ln -s /etc/nginx/sites-available/endboard /etc/nginx/sites-enabled/ + +Then, test and restart web server: + +# nginx -t && systemctl reload nginx + + +First use + +Before you publish your servers address anywhere, open your browser and +go to http://youraddress.i2p/aa (or locally to http://127.0.0.1/aa). + +If everything went well, this will take you to a form where you can set +your admin password. Be sure to do that first. + +You will need the admin token generated by the server, you can get it +like this: + +# tail -n 1 /var/opt/endboard/admin_$name_token.txt + +(where $name is the name you have defined for the admin account). + +Then, put the name of the admin as defined in the config-file, the token +that you obtained, and a suitable password. Passwords need to be 10 +characters at least, must contain at least one letter, and cannot +consist of only one letter. + +After this procedure, you can disable the admin interface in the config +file, if you want, and only enable it when needed. + +Moderators + +If enabled in the config file (take_applications), users can apply to be +moderators under: + +http://youraddress.i2p/ap + +The form requires a name and an email address (although a phonenumber or +other kind of contact could be put here as well). + +The admin can enable, disable and delete moderators accounts from +the admin panel. + +For normal moderation, a moderators account is enough and should be used +in the day-to-day work. The admin account is only needed to view logs, +change the status of moderators accounts, import messages or delete +posts from the db (whereas the moderators can only hide posts so that +they are not displayed any longer). + + + +Risks when using endboard: + +-bugs in the code of endboard, this is still the beta version +-if you run a public server somewhere on the internet, you are + responsible for the content that is posted. Although it is quite + unlikely that you can/will be held accountable (if you do the setup + right), it is still advisable to delete content that is illegal in your + jurisdiction in a reasonable timeframe. + If you don't do that, this is on you. + + +Limits of the endboard software + + +Admin + +Currently, there is only one admin account, the name of which is defined +in the config file. If the password is lost, it cannot be reset. +Instead, the name of the admin account needs to be changed. +In future versions, other admin accounts can be defined. +Setting the password of the admin account during first use requires +knowledge of the name that is defined in the config file, as well as a +token generated by the server (in /var). +In theory, an attacker could send a flood of requests with guessed names +and tokens before the admin was able to set their password. +Because of the length of the token this approach is very unlikely +to succeed. + + +Network + +endboard relies on being on a darknet that provides full end-to-end +encryption between client and server (which is the case for both tor +and i2p). While endboard will run on the clearnet or on a Lan just fine +(for the users), the panels for the admin and the moderators are not +secured against attackers that are able to read the traffic between the +browser and the server. ssl could probably be used for this, but +clearnet is not the usecase anyway, so I will put no work into it. + + +Traffic + +The php and database components of endboard are able to manage a lot of +traffic, by darknet standards. Using sqlite3 is faster than using a +separate db engine, at least when it comes to read requests. +When it comes to concurrent write requests, sqlite3 is slower in +managing them, but still fast enough (I guess...). +Several posts arriving at the exactly the same point in time will be +treated one after another, without dropping any of them (according to +some testing, this should work with up to 46 posts per second +and possibly more). +Chances are that the latency of the connections and the network +resources play a larger role than the potential waiting time +(but no precise measurements have been done yet). + + +Captcha + +The captcha is simple, and its parameters can be read directly from the +source of the page. A moderately skilled attacker could write a bot that +cracks it and spam the board. +Since captcha systems provide little protection in general, it is not +used by default. +A postform can still be only used once, and for a limited time, +since it is preloaded with a token. + + +Log files + +endboard logs events like deletions, imports, authorization failures and +others to the db. The logs can be viewed on the admin panel, although +the view is not very sophisticated. This needs more work. +Another option would be to log to /var/log or syslog. Maybe in future +versions. + + +Display on mobile screens + +For some reason the display on small screens sucks. There is stuff in +the css I have not fully understood yet. I will come to it, but it is of +lower priority to me. + + +Number of posts, number of subs + +The theoretical maximum number of rows in a table is 2^64 +(18446744073709551616 or about 1.8e+19). This limit is unreachable since +the maximum database size of 140 terabytes will be reached first. +A 140 terabytes database can hold no more than approximately 1e+13 rows, +and then only if there are no indices and if each row contains very +little data. (http://stackoverflow.com/questions/1546947/ddg#9456705) + +I'm not sure what this means for the users of endboard, but I'm pretty +confident that nobody will post more content than a terabyte to a board +like this. A terabyte of text only, that's an assload of posts. +That's as precise as it gets for now. + + +Changes from earlier versions + +The code has been almost completely rewritten. A lot of features have +been added, and a lot of bugs were fixed. +The most notable change is that endboard uses sqlite3 now instead of +storing the messages in json files. +All features that resided in other php files in earlier versions have +been put in index.php, this file has grown a lot as a result +(but the code is much better organized and consistent now). + +Licence stuff + +* The writing of the code of endboard started some time ago with another +* software called smolBBS. Although there is almost no original code +* left now, I still regard endboard as a fork of smolBBS. +* The author of smolBBS has required that the following text be +* distributed with any redistribution, so here it goes. +* The license and other conditions apply to endboard as well. +* +* IRC: *dulm @ irc.rizon.net +* +* Copyright (C) 2020 sandlind +* +* Redistribution and use in source and binary forms, with or without +* modification, are permitted provided that the following conditions are +* met: +* +* (1) Redistributions of source code must retain the above copyright +* notice, this list of conditions and the following disclaimer. +* +* (2) Redistributions in binary form must reproduce the above copyright +* notice, this list of conditions and the following disclaimer in +* the documentation and/or other materials provided with the +* distribution. +* +* (3)The name of the author may not be used to +* endorse or promote products derived from this software without +* specific prior written permission. +* +* THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +* IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +* WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +* DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, +* INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES +* (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +* SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +* STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING +* IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +* POSSIBILITY OF SUCH DAMAGE. + + + The source of terminus.i2p \ No newline at end of file