<!--
   $FML: restriction.sgml,v 1.1 2005/07/27 12:21:37 fukachan Exp $
-->


<chapter id="restriction">
	<title>
	Restrict Input Data
	</title>

<para>
&fml8; checks the input by regular expression FML::Restriction class
provides.
</para>


<sect1 id="restriction.overview">
	<title>
	Overview: Checks Of Input Data
	</title>

<sect2>
	<title>
	Restriction For Article Posting
	</title>

<para>
Restrictions for article are ambiguous or too restrictive. In fact
FML::Restriction class does not provide restriction rules for article
posting.
</para>

<para>
Instead FML::Filter filter system checks each line of content.
</para>

</sect2>


<sect2>
	<title>
	Restrictions For Command Mail
	</title>

<para>
FML::Process::Command class parses each line of the command mail and
checks the input by regular expressions FML::Restriction::Command
provides.  If the check is passed, &fml8; calls
FML::Command::{User,Admin}::COMMAND at the next step.
</para>

</sect2>


<sect2>
	<title>
	CGI
	</title>

<para>
CGI programs can receive the input from HTTP via only safe_param_XXX()
method.
</para>

<para>
It is expected that
safe_param_*()
and
try_cgi_*() 
returns the safe value.
</para>

<para>
These safe_param_XXX() functions checks the input by regular
expressions FML::Restriction::CGI provides (FML::Restriction::CGI
inherits FML::Restriction::Base).
</para>

</sect2>


<sect2>
	<title>
	makefml / fml
	</title>

<para>
CUI runs on the shell. 
It means he/she who runs CUI has priviledge to log in the mailing list
server.
So it does not check the input.
</para>

<para>
Each module checks the input independetly in that case
though no checks by FML::Restriction at the entrance.
For example, "adduser" module checks whether the input address
is valid or not even in the case of CUI.
These restrictions are dependent command specific modules.
These are applied even in the case of CUI.
</para>

</sect2>

</sect1>


<sect1 id="restriction.class">
	<title>
	FML::Restriction Class
	</title>

<para>
ACLs for the input data and commands are found at FML::Restriction
class.
</para>

<para>
For example, CGI modules use FML::Restriction::CGI class to check 
if the input data matches the proper regular expression.
</para>

<para>
Though FML::Restriction inherits FML::Restriction::Base class,
fundamentally each module should use FML::Restriction as object
composition. For example, use in the following way:
<screen>
use FML::Restriction::CGI;
$safe = new FML::Restriction::CGI;
my $allowed_regexp = $safe->param_regexp();

if ($value =~ /^$allowed_regexp{$key}$) { ... ok, do something ... ;}
</screen>
</para>

</sect1>


<sect1 id="restrictioncgi.input.data">
	<title>
	How CGI Restricts The Input
	</title>

<para>
CGI checks the input data by using FML::Restriction::CGI class.
</para>

<para>
The input should be restricted by FML::Restriction class.
We should not use param() method provided by perl's CGI class.
Instead use safe_param_xxx() method always to get value.
</para>

<para>
The following use may be allowed
<screen>
for my $dirty_buf (param()) {
   ... check ...
}
</screen>
but we should not use raw param() call.
<screen>
param($dirtty_buf)
</screen>
Instead, use safe_param_key().
<screen>
for my $key (param()) {
   ... check ...

   if (key eq $key) {
       value = safe_param_key()
   }
}
</screen>
</para>

</sect1>


<sect1>
	<title>
	Discussion: FML::Restriction Is Too Restrictive ?
	</title>

<para>
FML::Restriction class allows a subset of RFC defined expression.
</para>

<para>
RRC definition is too large. 
It is too difficult to implement it ;-)
We restrict the expression a little.
</para>

<para>
FML::Restriction::Command may be more granular but more granular
version is not implemented.
</para>

</sect1>


</chapter>
