Fano CSRF Application

Example web application that demonstrates how to use CSRF protection in Fano Framework.

This project is generated using Fano CLI command line tools to help scaffolding web application using Fano Framework.

Requirement

• Free Pascal >= 3.0
• Apache with mod_fcgid
• Fano Web Framework

Clone this repository

$ git clone git@github.com:fanofamework/fano-csrf.git --recursive

--recursive is needed so git also pull Fano repository.

If you are missing --recursive when you clone, you may find that vendor/fano directory is empty. In this case run

$ git submodule update --init

Change directory to fano-csrf as all commands below assumes you are inside it.

Copy configuration

$ ./tools/config.setup.sh

Generate secret key

Edit value of secretKey inside config/config.json file with your own secret key. You can generate secret key with Fano CLI or with other tools. To generate secret key with Fano CLI, run

$ fanocli --key

Create directory for sessions

$ mkdir -p storages/sessions
$ chmod 775 storages/sessions
$ sudo chown [your user name]:[user where web server run] storages/sessions

Replace [your user name] and [user where web server run] with actual value. For example Apache in Debian by default using www-data. You need to make sure that application can write to storage/sessions.

Build

Compile application.

$ ./build.sh

Run

Run with a webserver

If you have Fano CLI installed, run

$ sudo fanocli --deploy-fcgid=fano-csrf.fano

Otherwise you need to set virtual host manually. Please consult documentation of web server you use.

For example on Apache,

<VirtualHost *:80>
     ServerName fano-csrf.fano
     DocumentRoot /home/fano-csrf/public

     <Directory "/home/fano-csrf/public">
         Options +ExecCGI
         AllowOverride FileInfo
         Require all granted
         DirectoryIndex app.cgi
         AddHandler fcgid-script .cgi
     </Directory>
</VirtualHost>

On Apache, you will need to enable mod_fcgid. For example, on Debian, this will enable mod_fcgid module.

$ sudo a2enmod fcgid
$ sudo systemctl restart apache2

Depending on your server setup, for example, if you use .htaccess, add following code:

<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteRule ^(.*)$ app.cgi [L]
</IfModule>

and put .htaccess file in same directory as app.cgi file (i.e., in public directory).

Content of .htaccess basically tells Apache to serve existing files/directories directly. For any non-existing files/directories, pass them to our application.

Deployment

You need to deploy only executable binary and any supporting files such as HTML templates, images, css stylesheets, application config. Any pas or inc files or shell scripts is not needed in deployment machine in order application to run.

So for this repository, you will need to copy public, Templates, config and storages directories to your deployment machine. make sure that storages directory is writable by web server.

Known Issues

Issue with GNU Linker

When running build.sh script, you may encounter following warning:

/usr/bin/ld: warning: public/link.res contains output sections; did you forget -T?

This is known issue between Free Pascal 3.0.4 and GNU Linker. See FAQ: link.res syntax error, or "did you forget -T?"

However, this warning is minor and can be ignored. It does not affect output executable. To remedy, upgrade Free Pascal to version 3.2.

Issue with unsynchronized compiled unit with unit source

Sometime Free Pascal can not compile your code because, for example, you deleted a unit source code (.pas) but old generated unit (.ppu, .o, .a files) still there or when you switch between git branches. Solution is to remove those files.

By default, generated compiled units are in bin/unit directory. But do not delete README.md file inside this directory, as it is not being ignored by git.

$ rm bin/unit/*.ppu
$ rm bin/unit/*.o
$ rm bin/unit/*.rsj
$ rm bin/unit/*.a

Following shell command will remove all files inside bin/unit directory except README.md file.

$ find bin/unit ! -name 'README.md' -type f -exec rm -f {} +

tools/clean.sh script is provided to simplify this task.

Windows user

Free Pascal supports Windows as target operating system, however, this repository is not yet tested on Windows. To target Windows, in build.cfg replace compiler switch -Tlinux with -Twin64 and uncomment line #-WC to become -WC.

Lazarus user

While you can use Lazarus IDE, it is not mandatory tool. Any text editor for code editing (Atom, Visual Studio Code, Sublime, Vim etc) should suffice.