*
* $Id: README,v 1.3 1998/05/12 02:55:45 jbourne Exp $
* 
* Based on code written by an anonymous software socialist.
* 
* modified for use in CGI's by James Bourne <jbourne@hardrock.org>
* May 9, 1998.  See the file COPYING for more information on Copyright
*
*   
*   Copyright (C) 1998  James Bourne <jbourne@hardrock.org>
*
*   This program is free software; you can redistribute it and/or modify
*   it under the terms of the GNU General Public License as published by
*   the Free Software Foundation; either version 2 of the License, or
*   (at your option) any later version.
*
*   This program is distributed in the hope that it will be useful,
*   but WITHOUT ANY WARRANTY; without even the implied warranty of
*   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
*   GNU General Public License for more details.
*
*   You should have received a copy of the GNU General Public License
*   along with this program; if not, write to the Free Software
*   Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

libcgiupl will decode multitype forms therefore allowing simple integration
of file uploads to be added into existing or new CGI's.  The original code
was slightly more then difficult to deal with.  One could not easily decode
the information submitted and store it in a non-volitile memory space where
it could be reused later in the CGI or passed to other functions.  

The dentry structure and integer return value are based on NCSA parsing
routines which I have used in the past and which are integrated into
libcgip.a, for parsing standard forms.

Once libcgiupl.a functions decode stdin, name/value pairs are placed in the
dentry structure.  Access to these name/value pairs is done by referencing
the array containing the structures (ie data[0].name, data[0].val,
data[0].type).  In the case of the type member, the integer values defined
in cgiupl.h can be used to determine if the value is a filename or other
form data.  The function check_dserror can be used as a simple interface to
the library error messages, using the same format as strerror(errno).

SECURITY NOTES
There are a few things you will NEED to check for security reasons. 

Remember, you are completely braindead if you WWW server runs as root, and
you are just asking for comprimises this way.

- File Permissions/ownerships/directories:  All files uploaded should be
created mode 600 owned by the WWW server user or the uid of an suid binary. 
The library will try to catch filenames with ../.. in them and turn the /
into _ (if it can exist after the server parses the form).  Be *VERY*
carefull with this if you are suiding a binary as root, an easy DOS would be
to somehow make the cgi accept an upload file of passwd and try to set the
dir to be /etc.  Bang, you have a wrecked password file or even worse, root
without a password!

- value parsing/execution of shells:  No checking for shell escapes is done
in the library, YOU HAVE TO DO THIS YOURSELF.  If you use some of the form
data for a system, exec, or popen call, you might want to be very dilegent
about parsing it first.  Yes, the WWW server will do some escaping by
default but, do you want to trust it to catch everything?  I know I
wouldn't.

Please send question/comments/bugs to James Bourne <jbourne@island.net>

