| blob | 8cddb08b9ef410fb453ffd700e54d8602f201b0e |
2 <HTML>
4 <HEAD>
9 </HEAD>
11 <BODY>
15 </H1>
17 <UL>
18 <P>
23 </P>
25 <P>
27 <UL>
49 </UL>
51 </P>
53 </UL>
57 <P>
58 CGIscriptor merges plain ASCII HTML files transparantly and safely
59 with CGI variables, in-line PERL code, shell commands, and executable
60 scripts in many languages (on-line and real-time). It combines the
61 "ease of use" of HTML files with the versatillity of specialized
62 scripts and PERL programs. It hides all the specifics and
63 idiosyncrasies of correct output and CGI coding and naming. Scripts
64 do not have to be aware of HTML, HTTP, or CGI conventions just as HTML
65 files can be ignorant of scripts and the associated values. CGIscriptor
66 complies with the W3C HTML 4.0 recommendations.
67 </P>
69 <P>
70 In addition to its use as a WWW embeded CGI processor, it can
71 be used as a command-line document preprocessor (text-filter).
72 </P>
76 <P>
77 The aim of CGIscriptor is to execute "plain" scripts inside a text file
78 using any required CGIparameters and environment variables. It
79 is optimized to transparantly process HTML files inside a WWW server.
80 The native language is Perl, but many other scripting languages
81 can be used.
82 </P>
84 <P>
85 CGIscriptor reads text files from the requested input file (i.e., from
87 requesting the service) preceded by the obligatory
89 (except for "raw" files which supply their own Content-type message
90 and only if the SERVER_PROTOCOL contains HTTP, FTP, GOPHER, MAIL, or MIME).
91 </P>
93 <P>
94 When CGIscriptor encounters an embedded script, indicated by an HTML4 tag
95 </P>
97 <PRE>
99 PERL script
101 </PRE>
103 or
105 <PRE>
107 OS Shell script
109 </PRE>
111 <P>
112 construct (anything between []-brackets is optional, other MIME-types are
113 supported), the embedded script is removed and both the contents of the
114 source file (i.e., "do 'ScriptSource'") AND the script are evaluated as a
115 PERL program (i.e., by eval()), a shell script (i.e., by a "safe" version
116 of `Command`, qx) or an external interpreter. The output of the eval()
118 construct in the output string. Any CGI parameters declared by the CGI
119 attribute are available as simple perl variables, and can subsequently
120 be made available as variables to other scripting languages (e.g., bash,
121 python, or lisp).
122 </P>
124 <P>
125 Example: printing "Hello World"
126 </P>
128 <PRE>
133 </PRE>
135 <P>
136 Save this in a file, hello.html, in the directory you indicated with
137 $YOUR_HTML_FILES and access http://your_server/SHTML/hello.html
138 (or to whatever name you use as an alias for CGIscriptor.pl).
139 This is realy ALL you need to do to get going.
140 </P>
142 <P>
143 You can use any values that are delivered in CGI-compliant form (i.e.,
145 in your scripts IFF you have declared them in a META or SCRIPT tag before e.g.:
146 </P>
148 <PRE>
151 </PRE>
152 or
153 <PRE>
155 [SRC='ScriptSource']>
156 </PRE>
158 <P>
159 After such a 'CGI' attribute, you can use $name as an ordinary PERL variable
160 (the ScriptSource file is immediately evaluated with "do 'ScriptSource'").
161 The CGIscriptor script allows you to write ordinary HTML files which will
162 include dynamic CGI aware (run time) features, such as on-line answers
163 to specific CGI requests, queries, or the results of calculations.
164 </P>
166 <P>
167 For example, if you wanted to answer questions of clients, you could write
169 that prints out the answer to requests given as arguments. You then write
170 a HTML page "Respond.html" containing the following fragment:
171 </P>
173 <hr>
174 <PRE>
176 The Answer to your question
179 is
181 AnswerQuestion($Question);
188 </PRE>
189 <hr>
191 <P>
192 The output could look like the following (in HTML-speak):
193 </P>
195 <hr>
196 <PRE>
197 <CENTER>
198 The Answer to your question
200 is
202 </CENTER>
206 </PRE>
207 <hr>
209 <P>
210 Note that the function "Answer.pl" does know nothing about CGI or HTML,
211 it just prints out answers to arguments. Likewise, the text has no
212 provisions for scripts or CGI like constructs. Also, it is completely
214 to call up other information or pictures/sounds. The final text never
215 shows any cue as to what the original "source" looked like, i.e.,
216 where you store your scripts and how they are called.
217 </P>
219 <P>
220 There are some extra's. The argument of the files called in a SRC= tag
221 can access the CGI variables declared in the preceding META tag from
222 the @ARGV array. Executable files are called as:
223 `file '$ARGV[0]' ... ` (e.g., `Answer.pl \'$Question\'`;)
224 The files called from SRC can even be (CGIscriptor) html files which are
225 processed in-line. Furthermore, the SRC= tag can contain a perl block
226 that is evaluated. That is,
227 </P>
229 <PRE>
231 </PRE>
233 <P>
234 will result in the evaluation of "print do {$Question};" and the VALUE
235 of $Question will be printed. Note that these "SRC-blocks" can be
236 preceded and followed by other file names, but only a single block is
237 allowed in a SRC= tag.
238 </P>
240 <p>
241 One of the major hassles of dynamic WWW pages is the fact that several
242 mutually incompatible browsers and platforms must be supported. For example,
243 the way sound is played automatically is different for Netscape and
244 Internet Explorer, and for each browser it is different again on
245 Unix, MacOS, and Windows. Realy dangerous is processing user-supplied
246 (form-) values to construct email addresses, file names, or database
247 queries. All Apache WWW-server exploits reported in the media are
248 based on faulty CGI-scripts that didn't check their user-data properly.
249 </p>
251 <p>
252 There is no panacee for these problems, but a lot of work and problems
253 can be safed by allowing easy and transparent control over which
255 supplies such a method in the form of a pair of attributes:
256 IF='...condition..' and UNLESS='...condition...'. When added to a
257 script tag, the whole block (including the SRC attribute) will be
258 ignored if the condition is false (IF) or true (UNLESS).
259 For example, the following block will NOT be evaluated if the value
260 of the CGI variable FILENAME is NOT a valid filename:
261 </p>
263 <pre>
265 .....
267 </pre>
269 <p>
270 (the function CGIsafeFileName(String) returns an empty string ("")
271 if the String argument is not a valid filename).
272 The UNLESS attribute is the mirror image of IF.
273 </p>
275 <P>
276 A user manual follows the HTML 4 and security paragraphs below.
277 </P>
282 <P>
283 In general, CGIscriptor.pl complies with the HTML 4 recommendations of
284 the W3C. This means that any software to manage Web sites will be able
285 to handle CGIscriptor files, as will web agents.
286 </P>
288 <P>
291 feature is ignored, and a SRC feature is implemented. All CGI specific
292 features are delegated to the CGI attribute.
293 </P>
295 <P>
296 However, the behavior deviates from the W3C recommendations at some
297 points. Most notably:
298 </P>
300 <DL>
302 client (i.e., the browser)
305 when a SRC feature is present.
311 (i.e., deleted from the output).
314 document.
318 and their \-slashed combinations: \'\', \"\", \`\`, \(\),
319 \{\}, \[\].
323 rendered with new-lines.
325 (i.e., no content is processed)
326 </DL>
328 <P>
329 The reasons for these choices are:
330 </P>
332 <P>
333 You can still write completely HTML4 compliant documents. CGIscriptor
334 will not force you to write "deviant" code. However, it allows you to
335 do so (which is, in fact, just as bad). The prime design principle
336 was to allow users to include plain Perl code. The code itself should
337 be "enhancement free". Therefore, extra features were needed to
338 supply easy access to CGI and Web site components. For security
339 reasons these have to be declared explicitly. The SRC feature
340 transparently manages access to external files, especially the safe
341 use of executable files.
342 </P>
344 <P>
345 The CGI attribute handles the declarations of external (CGI) variables
346 in the SCRIPT and META tag's.<BR>
347 EVERYTHING THE CGI ATTRIBUTE AND THE META TAG DO CAN BE DONE INSIDE
349 </P>
351 <P>
352 The reason for the IF, UNLESS, and SRC attributes (and its Perl code evaluation)
353 were build into the META and SCRIPT tags is part laziness, part security. The SRC
354 blocks allows more compact documents and easier debugging. The values of the
355 CGI variables can be immediately screened for security by IF or UNLESS
356 conditions, and even SRC attributes (e.g., email addresses and file names), and
357 a few commands can be called without having to add another Perl TAG pair.
358 This is especially important for documents that require the use of other
359 (restricted) "scripting" languages that lag transparent control structures.
360 </P>
365 <P>
366 Your WWW site is a few keystrokes away from a few hundred million internet
367 users. A fair percentage of these users knows more about your computer
368 than you do. And some of these just might have bad intentions.
369 </P>
371 <P>
372 To ensure uncompromized operation of your server and platform, several
373 features are incorporated in CGIscriptor.pl to enhance security.
374 First of all, you should check the source of this program. No security
375 measures will help you when you download programs from anonymous sources.
376 If you want to use THIS file, please make sure that it is uncompromized.
377 The best way to do this is to contact the source and try to determine
378 whether s/he is reliable (and accountable).
379 </P>
381 <P>
382 BE AWARE THAT ANY PROGRAMMER CAN CHANGE THIS PROGRAM IN SUCH A WAY THAT
383 IT WILL SET THE DOORS TO YOUR SYSTEM WIDE OPEN
384 </P>
386 <P>
387 I would like to ask any user who finds bugs that could compromise
388 security to report them to me (and any other bug too,
389 Email: R.J.J.H.vanSon@uva.nl or ifa@hum.uva.nl).
390 </P>
394 <dl>
396 <dd>The inner workings of the HTML source files are completely hidden
397 from the client. Only the HTTP header and the ever changing content
398 of the output distinguish it from the output of a plain, fixed HTML
399 file. Names, structures, and arguments of the "embedded" scripts
400 are invisible to the client. Error output is suppressed except
401 during debugging (user configurable).
404 <dd>Directories containing Inline text and script files can reside on
405 separate trees, distinct from those of the HTTP server. This means
406 that NEITHER the text files, NOR the script files can be read by
407 clients other than through CGIscriptor.pl, UNLESS they are
408 EXPLICITELY made available.
411 <dd>All client supplied values are used as literal values (''-quoted).
412 Client supplied ''-quotes are ALWAYS removed. Therefore, as long as the
413 embedded scripts do NOT themselves evaluate these values, clients CANNOT
414 supply executable commands. Be sure to AVOID scripts like:
416 <PRE>
419 </PRE>
421 <P>
422 These are a recipe for disaster. However, the following quoted
423 form should be save (but is still not adviced):
424 </P>
426 <PRE>
428 </PRE>
430 <P>
431 A special function, SAFEqx(), will automatically do exactly this,
433 with $UserValue interpolated. I recommend to use SAFEqx() instead
434 of backticks whenever you can. The OS shell scripts inside
435 </P>
437 <PRE>
439 </PRE>
441 <P>
442 are handeld by SAFEqx and automatically ''-quoted.
443 </P>
446 <dd>All requests can be logged separate from the Host server. The level of
447 detail is user configurable: Including or excluding the actual queries.
448 This allows for the inspection of (im-) proper use.
451 <dd>The Remote addresses can be checked against a list of authorized
452 (i.e., accepted) or non-authorized (i.e., rejected) clients. Both
453 REMOTE_HOST and REMOTE_ADDR are tested so clients without a proper
454 HOST name can be (in-) excluded by their IP-address. Client patterns
455 containing all numbers and dots are considered IP-addresses, all others
456 domain names. No wild-cards or regexp's are allowed, only partial
457 addresses.<br>
458 Matching of names is done from the back to the front (domain first,
459 i.e., $REMOTE_HOST =~ /\Q$pattern\E$/is), so including ".edu" will
460 accept or reject all clients from the domain EDU. Matching of
461 IP-addresses is done from the front to the back (domain first, i.e.,
462 $REMOTE_ADDR =~ /^\Q$pattern\E/is), so including "128." will (in-)
463 exclude all clients whose IP-address starts with 128.
465 matches ALL HOSTS/clients.<br>
467 <P>
468 For those needing more expressional power, lines starting with
469 "-e" are evaluated by the perl eval() function. E.g.,
470 '-e $REMOTE_HOST =~ /\.edu$/is;' will accept/reject clients from the
471 domain '.edu'.
472 </P>
475 <dd>In principle, CGIscriptor could read ANY file in the directory
476 tree as discussed in 1. However, for security reasons this is
477 restricted to text files. It can be made more restricted by entering
478 a global file pattern (e.g., ".html"). This is done by default.
479 For each client requesting access, the file pattern(s) can be made
480 more restrictive than the global pattern by entering client specific
481 file patterns in the Access Control files (see 5).
482 For example: if the ACCEPT file contained the lines
484 <PRE>
485 * DEMO
486 .hum.uva.nl LET
487 145.18.230.
488 </PRE>
490 <P>
492 "/my/demo/file.html" ($PATH_INFO =~ /\Q$pattern\E/), Clients from
495 145.18.230.[0-9]+ could access ALL files.
496 Again, for those needing more expressional power, lines starting with
498 '-e $REMOTE_HOST =~ /\.edu$/is && $PATH_INFO =~ m@/DEMO/@is;' <br />
500 clients from the domain '.edu'.
501 </P>
502 <p>
503 <dt>7 Access control: Server side session tickets
504 <dd>Specific paths can be controlled by Session Tickets which must be
505 present as a SESSIONTICKET=<value> CGI variable in the request. These paths
506 are defined in %TicketRequiredPatterns as pairs of:<br />
507 ('regexp' => 'SessionPath\tPasswordPath\tLogin.html\tExpiration').<br />
508 Session Tickets are stored in a separate directory (SessionPath, e.g.,
510 The following is an example:
511 <pre>
512 Type: SESSION
513 IPaddress: 127.0.0.1
514 AllowedPaths: ^/Private/Name/
515 Expires: +3600
516 Username: test
517 ...
518 </pre>
519 Other content can follow. <br />
520 <br />
521 It is adviced that Session Tickets should be deleted
522 after some (idle) time. The IP address should be the IP number at login, and
523 the SESSIONTICKET will be rejected if it is presented from another IP address.
524 AllowedPaths is a perl regexp. Be careful how they match. Make sure to delimit
527 time the ticket will remain valid after creation (file ctime). Time can be given
529 None of these need be present, but the Ticket must have a non-zero size.<br />
530 <br />
531 Next to Session Tickets, there are two other type of ticket files:<br />
532 - LOGIN tickets store information about a current login request<br />
533 - PASSWORD ticket store account information to authorize login requests<br />
534 </p>
535 <P>
536 <dt>8 Query length limiting
537 <dd>The length of the Query string can be limited. If CONTENT_LENGTH is larger
538 than this limit, the request is rejected. The combined length of the
539 Query string and the POST input is checked before any processing is done.
540 This will prevent clients from overloading the scripts.
541 The actual, combined, Query Size is accessible as a variable through
542 $CGI_Content_Length.
543 </P>
545 <P>
546 <dt>9 Illegal filenames, paths, and protected directories
547 <dd>One of the primary security concerns in handling CGI-scripts is the
549 malicious commands. Examples are inserting ';', null bytes, or <newline> characters
550 in URL's and filenames, followed by executable commands. A special
551 variable $FileAllowedChars stores a string of all allowed characters.
552 Any request that translates to a filename with a character OUTSIDE
553 this set will be rejected.<br>
554 In general, all (readable files) in the ServerRoot tree are accessible.
555 This might not be what you want. For instance, your ServerRoot directory
556 might be the working directory of a CVS project and contain sensitive
557 information (e.g., the password to get to the repository). You can block
558 access to these subdirectories by adding the corresponding patterns to
559 the $BlockPathAccess variable. For instance, $BlockPathAccess = '/CVS/'
560 will block any request that contains '/CVS/' or:<br>
561 <pre>
562 die if $BlockPathAccess && $ENV{'PATH_INFO'} =~ m@$BlockPathAccess@;
563 </pre>
564 </P>
566 <P>
567 <dt>10 The execution of code blocks can be controlled in a transparent way
568 by adding IF or UNLESS conditions in the tags themselves.
569 <dd>That is, a simple check of the validity of filenames or email
570 addresses can be done before any code is executed.
571 </p>
573 </dl>
575 <hr>
579 <UL>
600 </UL>
604 <P>
605 CGIscriptor removes embedded scripts, indicated by an HTML 4 type
606 <SCRIPT TYPE='text/ssperl'> </SCRIPT> or <SCRIPT TYPE='text/osshell'>
607 </SCRIPT> constructs. The contents of the directive are executed by
608 the PERL eval() and `` functions (in a separate name space). The
609 result of the eval() function replaces the <SCRIPT> </SCRIPT> construct
610 in the output file. You can use the values that are delivered in
613 defined in a <META> or <SCRIPT> tag.
615 subsequent <SCRIPT> and <META> results (including the defining
616 tag) will also be pushed onto a stack: @CGIscriptorResults. This list
617 behaves like any other, ordinary list and can be manipulated.
618 </P>
620 <P>
621 Both GET and POST requests are accepted. These two methods are treated
622 equal. Variables, i.e., those values that are determined when a file is
623 processed, are indicated in the CGI attribute by $<name> or
624 $<name>=<default> in which <name> is the name of the
625 variable and <default> is the value used when there is NO current CGI
626 value for <name> (you can use white-spaces in
627 $<name>=<default> but really DO make sure that the default
628 value is followed by white space or is quoted). Names can contain any
629 alphanumeric characters and _ (i.e., names match /[\w]+/).<br>
630 If the <i>Content-type:</i> is 'multipart/*', the input is treated as a
631 MIME multipart message and automatically delimited. CGI variables get the
633 </P>
635 <P>
636 Variables can be CGI variables, i.e., those from the QUERY_STRING,
637 environment variables, e.g., REMOTE_USER, REMOTE_HOST, or REMOTE_ADDR,
638 or predefined values, e.g., CGI_Decoded_QS (The complete, decoded,
639 query string), CGI_Content_Length (the length of the decoded query
640 string), CGI_Year, CGI_Month, CGI_Time, and CGI_Hour (the current
641 date and time).
642 </P>
644 <P>
645 All these are available when defined in a CGI attribute. All environment
646 variables are accessible as $ENV{'name'}. So, to access the REMOTE_HOST
647 and the REMOTE_USER, use, e.g.:
648 </P>
650 <PRE>
651 <SCRIPT TYPE='text/ssperl'>
653 </SCRIPT>
654 </PRE>
656 <P>
658 Another way to do this is:
659 </P>
661 <PRE>
664 </PRE>
666 or
668 <PRE>
671 </PRE>
673 <P>
674 This is possible because ALL environment variables are available as
675 CGI variables. The environment variables take precedence over CGI
677 </P>
679 <PRE>
681 </PRE>
683 <P>
684 Will print the current HOME directory (environment) irrespective whether
685 there is a CGI variable from the query
687 THIS IS A SECURITY FEATURE. It prevents clients from changing
688 the values of defined environment variables (e.g., by supplying
689 a bogus $REMOTE_ADDR). Although $ENV{} is not changed by the META tags,
690 it would make the use of declared variables insecure. You can still
691 access CGI variables after a name clash with
692 CGIscriptor::CGIparseValue(<name>).
693 </P>
695 <P>
696 Some CGI variables are present several times in the query string
697 (e.g., from multiple selections). These should be defined as
698 @VARIABLENAME=default in the CGI attribute. The list @VARIABLENAME
699 will contain ALL VARIABLENAME values from the query, or a single
700 default value. If there is an ENVIRONMENT variable of the
701 same name, it will be used instead of the default AND the query
702 values. The corresponding function is
703 CGIscriptor::CGIparseValueList(<name>)
704 </P>
706 <P>
707 CGI variables collected in a @VARIABLENAME list are unordered.
708 When more structured variables are needed, a hash table can be used.
709 A variable defined as %VARIABLE=default will collect all
710 CGI-parameter values whose name start with 'VARIABLE' in a hash table
711 with the remainder of the name as a key. For instance, %PERSON will
712 collect PERSONname='John Doe', PERSONbirthdate='01 Jan 00', and
713 PERSONspouse='Alice' into a hash table %PERSON such that
714 $PERSON{'spouse'} equals 'Alice'. Any default value or environment
716 variable of the same name, it will be used instead of the default
717 AND the query values. The corresponding function is
718 CGIscriptor::CGIparseValueHash(<name>)
719 </P>
721 <P>
722 This method of first declaring your environment and CGI variables
723 before being able to use them in the scripts might seem somewhat
724 clumsy, but it protects you from inadvertedly printing out the values of
725 system environment variables when their names coincide with those used
727 values for your private variables.
728 THIS IS A SECURITY FEATURE!
729 </P>
733 <P>
735 message before anything is printed. This has been extended to include
736 plain text (.txt) files, for which the Content-type (MIME type)
737 'text/plain' is printed. In all other respects, text files are treated as
738 HTML files (this can be switched off by removing '.txt' from the
739 $FilePattern variable). When the content type should be something else,
740 e.g., with multipart files, use the $RawFilePattern (.xmr, see also next
741 item). CGIscriptor will not print a Content-type message for this file type
742 (which must supply its OWN Content-type message). Raw files must still
743 conform to the <SCRIPT></SCRIPT> and <META> tag
744 specifications.
745 </P>
749 <P>
750 CGIscriptor is intended to process HTML and text files only. You can
752 with the .xmr extension. However, CGIscriptor will not process binary files
753 of any type, e.g., pictures or sounds. Given the sheer number of formats, I
754 do not have any intention to do so. However, an escape route has been
755 provided. You can construct a genuine raw (.xmr) text file that contains
756 the perl code to service any file type you want. If the global
757 $BinaryMapFile variable contains the path to this file (e.g.,
758 /BinaryMapFile.xmr), this file will be called whenever an unsupported
759 (non-HTML) file type is requested. The path to the requested binary file
760 is stored in $ENV('CGI_BINARY_FILE') and can be used like any other
761 CGI-variable. Servicing binary files then becomes supplying the correct
763 file and writing it to STDOUT (e.g., using sysread() and syswrite()).
764 </P>
768 <P>
769 All attributes of a META tag are ignored, except the
771 inside the quotes following the CONTENT= indication (white-space is
772 ignored, "'` (){}[]-quotes are allowed, plus their \ versions) MUST
773 start with any of the CGIscriptor mime-types (e.g.: text/ssperl or
774 text/osshell) and a comma or semicolon.
775 The quoted string following CGI= contains a white-space separated list
776 of declarations of the CGI (and Environment) values and default values
777 used when no CGI values are supplied by the query string.
778 </P>
780 <P>
781 If the default value is a longer string containing special characters,
782 possibly spanning several lines, the string must be enclosed in quotes.
783 You may use any pair of quotes or brackets from the list '', "", ``, (),
784 [], or {} to distinguish default values (or preceded by \, e.g., \(...\)
785 is different from (...)). The outermost pair will always be used and any
786 other quotes inside the string are considered to be part of the string
787 value, e.g.,
788 </P>
790 <PRE>
791 $Value = {['this'
792 "and" (this)]}
793 </PRE>
795 <P>
796 will result in $Value getting the default value
797 </P>
799 <PRE>
800 ['this'
801 "and" (this)]
802 </PRE>
804 <P>
805 (NOTE that the newline is part of the default value!).
806 </P>
808 <P>
809 Internally, for defining and initializing CGI (ENV) values, the META
810 and SCRIPT tags use the function "defineCGIvariable($name, $default)"
811 (scalars) and "defineCGIvariableList($name, $default)" (lists).
812 These functions can be used inside scripts as
813 "CGIscriptor::defineCGIvariable($name, $default)" and
814 "CGIscriptor::defineCGIvariableList($name, $default)".
815 </P>
817 <P>
818 The CGI attribute will be processed exactly identical when used inside
820 HTML 4.0 specifications of the W3C.
821 </P>
825 <P>
826 There is a problem when constructing html files containing
827 server-side perl scripts with standard HTML tools. These
828 tools will refuse to process any text between
830 tags. This is quite annoying when you want to use large
831 HTML templates where you will fill in values.
832 </P>
834 <P>
835 For this purpose, CGIscriptor will read the neutral
838 tag (in Cascading Style Sheet manner) Note that "varname" has
839 NO '$' before it, it is a bare name. Any text between
842 to '$varname' as is (e.g., as a literal). No
843 processing or interpolation will be performed.
844 There is also NO nesting possible. Do NOT nest
846 Moreover, DIV tags do NOT ensure a block structure in
847 the final rendering (i.e., no empty lines).
848 </P>
850 <P>
852 is handled the XML way. No content is processed,
853 but varname is defined, and any SRC directives are
854 processed.
855 </P>
857 <P>
858 You can use $varname like any other variable name.
859 However, $varname is NOT a CGI variable and will be
860 completely internal to your script. There is NO
861 interaction between $varname and the outside world.
862 </P>
864 <P>
865 To interpolate a DIV derived text, you can use:
866 <pre>
867 $varname =~ s/([\]])/\\\1/g; # Mark ']'-quotes
868 $varname = eval("qq[$varname]"); # Interpolate all values
869 </pre>
870 </P>
872 <p>
873 The DIV tag will process IF, UNLESS, CGI and SRC attributes.
874 The SRC files will be pre-pended to the body
875 text of the tag.
876 </p>
879 CONDITIONAL PROCESSING: THE 'IF' AND 'UNLESS' ATTRIBUTES
880 </H2></A>
882 <p>
883 It is often necessary to include code-blocks that should be executed
884 conditionally, e.g., only for certain browsers or operating system.
885 Furthermore, quite often sanity and security checks are necessary
886 before user (form) data can be processed, e.g., with respect to
887 email addresses and filenames.
888 </p>
890 <p>
891 Checks added to the code are often difficult to find, interpret or
892 maintain and in general mess up the code flow. This kind of confussion
893 is dangerous. Also, for many of the supported "foreign" scripting
894 languages, adding these checks is cumbersome or even impossible.
895 </p>
897 <p>
898 As a uniform method for asserting the correctness of "context", two
899 attributes are added to all supported tags: IF and UNLESS.
900 They both evaluate their value and block execution when the
903 the backslash in the '\>' is removed and only used to differentiate
905 backslash in '\<' is also removed. Inside these conditionals,
906 ~/ and ./ are expanded to their respective directory root paths.
907 </p>
909 <p>
910 For example, the following tag will be ignored when the filename is
911 invalid:
912 </p>
914 <pre>
915 <SCRIPT TYPE='text/ssperl' CGI='$FILENAME'
916 IF='CGIscriptor::CGIsafeFileName($FILENAME);'>
917 ...
919 </pre>
921 <p>
922 The IF and UNLESS values must be quoted. The same quotes are supported
923 as with the other attributes. The SRC attribute is ignored when IF and
924 UNLESS block execution.
925 </p>
928 THE MAGIC SOURCE ATTRIBUTE (SRC=)</H2></A>
930 <P>
931 The SRC attribute inside tags accepts a list of filenames and URL's
933 </P>
935 <P>
936 ALL the variable values defined in the CGI attribute are available in
937 @ARGV as if the file was executed from the command line, in
938 the exact order in which they were declared in the preceding CGI
939 attribute.
940 </P>
942 <P>
943 First, a SRC={}-block will be evaluated as if the code inside the
945 "print do { code };'';" or `code` (i.e., SAFEqx('code)).
946 Only a single block is evaluated. Note that this is processed less
948 depends on the content-type: Perl for text/ssperl and OS shell for
949 text/osshell. For other mime types (scripting languages), anything in
950 the source block is put in front of the code block "inside" the tag.
951 </P>
953 <P>
954 Second, executable files (i.e., -x filename != 0) are evaluated as:
956 That is, you can actually call executables savely from the SRC tag.
957 </P>
959 <P>
960 Third, text files that match the file pattern, used by CGIscriptor to
961 check whether files should be processed ($FilePattern), are
962 processed in-line (i.e., recursively) by CGIscriptor as if the code
963 was inserted in the original source file. Recursions, i.e., calling
964 a file inside itself, are blocked. If you need them, you have to code
965 them explicitely using "main::ProcessFile($file_path)".
966 </P>
968 <P>
969 Fourth, Perl text files (i.e., -T filename != 0) are evaluated as:
970 "do FileName;'';".
971 </P>
973 <P>
974 Last, URL's (i.e., starting with 'HTTP://', 'FTP://', 'GOPHER://', 'TELNET://',
976 and document header is done by main::GET_URL($URL [, 0]). You can enter your own
979 </P>
981 <P>
982 There are two pseudo-file names: PREFIX and POSTFIX. These implement
983 a switch from prefixing the SRC code/files (PREFIX, default) before the content of
984 the tag to appending the code after the content of the tag (POSTFIX). The switches
985 are done in the order in which the PREFIX and POSTFIX labels are encountered.
986 You can mix PREFIX and POSTFIX labels in any order with the SRC files.
987 Note that the ORDER of file execution is determined for prefixed and
988 postfixed files seperately.
989 <P>
991 <P>
992 File paths can be preceded by the URL protocol prefix "file://". This
993 is simply STRIPPED from the name.
994 </P>
996 <P>
997 Example:
998 </P>
1000 <P>
1001 The request
1002 "http://cgi-bin/Action_Forms.pl/Statistics/Sign_Test.html?positive=8&negative=22
1005 </P>
1007 <P>
1008 on encountering the lines:
1009 </P>
1011 <PRE>
1014 </SCRIPT></b><p>"
1015 </PRE>
1017 This line will be processed as:
1019 <PRE>
1020 "<b>`${SS_SCRIPT}/Statistics/SignTest.pl '8' '22'`</b><p>"
1021 </PRE>
1023 <P>
1024 In which "${SS_SCRIPT}/Statistics/SignTest.pl" is an executable script,
1025 This line will end up printed as:
1026 </P>
1028 <PRE>
1029 "<b>p <= 0.0161</b><p>"
1030 </PRE>
1032 <P>
1033 Note that the META tag itself will never be printed, and is invisible to
1034 the outside world.
1035 </P>
1037 <P>
1038 The SRC files in a DIV/INS tag will be added (pre-pended) to the body
1040 </P>
1044 <P>
1047 public directories can be accessed without direct reference to the
1048 actual paths. Filepaths starting with "./" are replaced by
1049 "$YOUR_SCRIPTS/" and this should only be used for scripts.
1050 The "$YOUR_SCRIPTS" directory is added to @INC so, e.g., the
1051 'require' command will load from the "$YOUR_SCRIPTS" directory.
1052 </P>
1054 <P>
1056 out for constructs like $a =~ s/aap\./noot./g, use
1057 $a =~ s@aap\.@noot.@g instead.
1058 </P>
1060 <P>
1061 CGIscriptor.pl will assign the values of $SS_PUB and $SS_SCRIPT
1062 (i.e., $YOUR_HTML_FILES and $YOUR_SCRIPTS) to the environment variables
1063 $SS_PUB and $SS_SCRIPT. These can be accessed by the scripts that are
1064 executed. The "$SS_SCRIPT" ($YOUR_SCRIPTS) directory is added to
1065 @INC so, e.g., the 'require' command will load from the "$SS_SCRIPT"
1066 directory.<br>
1067 Values not preceded by $, ~/, or ./ are used as literals
1068 </P>
1070 <A NAME="OSSHELL"><H2 ALIGN="CENTER">OS SHELL SCRIPT EVALUATION (CONTENT-TYPE=TEXT/OSSHELL)</H2></A>
1072 <P>
1073 OS scripts are executed by a "safe" version of the `` operator (i.e.,
1074 SAFEqx(), see also below) and any output is printed. CGIscriptor will
1075 interpolate the script and replace all user-supplied CGI-variables by
1076 their ''-quoted values (actually, all variables defined in CGI attributes are
1077 quoted). Other Perl variables are interpolated in a simple fasion, i.e.,
1078 $scalar by their value, @list by join(' ', @list), and %hash by their
1079 name=value pairs. Complex references, e.g., @$variable, are all
1080 evaluated in a scalar context. Quotes should be used with care.
1081 NOTE: the results of the shell script evaluation will appear in the
1082 @CGIscriptorResults stack just as any other result.
1083 </P>
1085 <P>
1086 All occurrences of $@% that should NOT be interpolated must be
1087 preceeded by a "\". Interpolation can be switched off completely by
1088 setting $CGIscriptor::NoShellScriptInterpolation = 1
1089 (set to 0 or undef to switch interpolation on again)
1090 i.e.,
1091 </P>
1093 <PRE>
1095 $CGIscriptor::NoShellScriptInterpolation = 1;
1097 </PRE>
1102 <p>
1103 Allows general and global conversions of files using Regular Expressions.
1104 Very handy (but costly) to rewrite legacy pages to a new format.
1105 Select files to use it on with <br>
1106 my $TranslationPaths = 'filepattern';<br>
1107 This is costly. For efficiency, define:<br>
1108 $TranslationPaths = ''; when not using translations.<br>
1109 Accepts general regular expressions: [$pattern, $replacement]
1110 </p>
1112 <p>
1113 Define:</p>
1114 <pre>
1115 my $TranslationPaths = 'filepattern'; # Pattern matching PATH_INFO
1117 push(@TranslationTable, ['pattern', 'replacement']);
1118 # e.g. (for Ruby Rails):
1122 # Runs:
1123 my $currentRegExp;
1124 foreach $currentRegExp (@TranslationTable)
1125 {
1126 my ($pattern, $replacement) = @$currentRegExp;
1127 $$text =~ s!$pattern!$replacement!msg;
1128 };
1129 </pre>
1133 </A>
1135 <P>
1136 Adding a MIME-type and an interpreter command to
1137 %ScriptingLanguages automatically will catch any other
1138 scripting language in the standard
1140 E.g., adding: $ScriptingLanguages{'text/sspython'} = 'python';
1141 will actually execute the folowing code in an HTML page
1142 (ignore 'REMOTE_HOST' for the moment):
1143 </P>
1145 <PRE>
1147 # A Python script
1151 </PRE>
1153 <P>
1154 The script code is NOT interpolated by perl, EXCEPT for those
1155 interpreters that cannot handle variables themselves.
1156 Currently, several interpreters are pre-installed:
1157 </P>
1159 <PRE>
1166 # "| egrep -v '> |^rep. |^nil\\\$'",
1176 "rebol --quiet|egrep -v '^[> ]* == '|sed 's/^\s*\[> \]* //g'",
1178 (psql)
1179 </PRE>
1181 <P>
1182 Note that the "value" of $ScriptingLanguages{mime} must be a command
1183 that reads Standard Input and writes to standard output. Any extra
1184 output of interactive interpreters (banners, echo's, prompts)
1185 should be removed by piping the output through 'tail', 'grep',
1186 'sed', or even 'awk' or 'perl'.
1187 </P>
1189 <P>
1190 For access to CGI variables there is a special hashtable:
1191 %ScriptingCGIvariables.
1192 CGI variables can be accessed in three ways.
1193 <dl>
1195 nothing is done and the script itself should parse the relevant
1196 environment variables.
1198 value is empty, e.g., $ScriptingCGIvariables{"text/sspraat"} = '';,
1199 the script text is interpolated by perl. That is, all $var, @array,
1200 %hash, and \-slashes are replaced by their respective values.
1202 in front of the script according to the format stored in
1203 %ScriptingCGIvariables. That is, the following (pseudo-)code is
1204 executed for each CGI- or Environment variable defined in the CGI-tag:
1205 printf(INTERPRETER, $ScriptingCGIvariables{$mime}, $CGI_NAME, $CGI_VALUE);
1206 </dl>
1207 </P>
1209 <P>
1212 (note that these definitions are not save, the real ones contain '-quotes).
1213 </P>
1215 <P>
1216 THIS WILL NOT WORK FOR @VARIABLES, the (empty) $VARIABLES will be used
1217 instead.
1218 </P>
1220 <P>
1221 The $CGI_VALUE parameters are "shrubed" of all control characters
1222 and quotes (by &shrubCGIparameter($CGI_VALUE)). Control characters
1226 if a client would supply the string value (in standard perl)
1227 </P>
1229 <P>
1231 it would be processed as
1233 (e.g., sh or bash would process the latter more according to your
1234 intentions).<br>
1235 If your intepreter requires different protection measures, you will
1236 have to supply these in %main::SHRUBcharacterTR (string => translation),
1237 e.g.,
1239 <PRE>
1241 </PRE>
1242 </P>
1244 <P>
1245 Currently, the following definitions are used:
1246 </P>
1248 <PRE>
1249 %ScriptingCGIvariables = (
1267 );
1268 </PRE>
1270 <P>
1271 Four tables allow fine-tuning of interpreter with code that should be
1272 added before and after each code block:
1273 </P>
1275 <P>
1276 Code added before each script block
1277 </P>
1279 <PRE>
1280 %ScriptingPrefix = (
1283 );
1284 </PRE>
1286 <P>
1287 Code added at the end of each script block
1288 </P>
1290 <PRE>
1291 %ScriptingPostfix = (
1294 );
1295 </PRE>
1297 <P>
1298 Initialization code, inserted directly after opening (NEVER interpolated)
1299 </P>
1301 <PRE>
1302 %ScriptingInitialization = (
1307 );
1308 </PRE>
1310 <P>
1311 Cleanup code, inserted before closing (NEVER interpolated)
1312 </P>
1314 <PRE>
1315 %ScriptingCleanup = (
1321 );
1322 </PRE>
1324 <P>
1325 The SRC attribute is NOT magical for these interpreters. In short,
1326 all code inside a source file or {} block is written verbattim
1327 to the interpreter. No (pre-)processing or executional magic is done.
1328 </P>
1330 <P>
1331 A serious shortcomming of the described mechanism for handling other
1332 (scripting) languages, with respect to standard perl scripts
1333 (i.e., 'text/ssperl'), is that the code is only executed when
1334 the pipe to the interpreter is closed. So the pipe has to be
1335 closed at the end of each block. This means that the state of the
1336 interpreter (e.g., all variable values) is lost after the closing of
1338 all values and definitions.
1339 </P>
1344 <P>
1345 To ease some important auxilliary functions from within the
1346 html pages I have added them as MIME types. This uses
1347 the mechanism that is also used for the evaluation of
1348 other scripting languages, with interpolation of CGI
1349 parameters (and perl-variables). Actually, these are
1350 defined exactly like any other "scripting language".
1351 </P>
1353 <dl>
1354 <dt>text/ssdisplay:
1355 <dd>display some (HTML) text with interpolated
1356 variables (uses `cat`).
1357 <dt>text/sslogfile:
1358 <dd>write (append) the interpolated block to the file
1359 mentioned on the first, non-empty line
1360 (the filename can be preceded by 'File: ',
1361 note the space after the ':',
1363 <dt>text/ssmailto:
1364 <dd>send email directly from within the script block.
1365 The first line of the body must contain
1366 To:Name@Valid.Email.Address
1367 (note: NO space between 'To:' and the email adres)
1368 For other options see the mailto man pages.
1369 It works by directly sending the (interpolated)
1370 content of the text block to a pipe into the
1371 Linux program 'mailto'.
1372 </dl>
1374 <P>
1375 In these script blocks, all Perl variables will be
1376 replaced by their values. All CGI variables are cleaned before
1377 they are used. These CGI variables must be redefined with a
1378 CGI attribute to restore their original values.
1379 In general, this will be more secure than constructing
1380 e.g., your own email command lines. For instance, Mailto will
1381 not execute any odd (forged) email address, but just stops
1382 when the email address is invalid and awk will construct
1384 as a "valid" UNIX filename). Note that it will also gladly
1385 store this file anywhere (/../../../etc/passwd will work!).
1386 Use the CGIscriptor::CGIsafeFileName() function to clean the
1387 filename.
1388 </P>
1392 <P>
1393 If a shell script starts with the UNIX style "#! <shell command> \n"
1394 line, the rest of the shell script is piped into the indicated command,
1395 i.e.,
1396 open(COMMAND, "| command");print COMMAND $RestOfScript;
1397 </P>
1399 <P>
1400 In many ways this is equivalent to the MIME-type profiling for
1401 evaluating other scripting languages as discussed above. The
1402 difference breaks down to convenience. Shell script piping is a
1403 "raw" implementation. It allows you to control all aspects of
1404 execution. Using the MIME-type profiling is easier, but has a
1405 lot of defaults built in that might get in the way. Another
1406 difference is that shell script piping uses the SAFEqx() function,
1407 and MIME-type profiling does not.
1408 </P>
1410 <P>
1411 Execution of shell scripts is under the control of the Perl Script blocks
1412 in the document. The MIME-type triggered execution of <SCRIPT></SCRIPT>
1413 blocks can be simulated easily. You can switch to a different shell, e.g. tcl,
1414 completely by executing the following Perl commands inside your document:
1415 </P>
1417 <PRE>
1419 $main::ShellScriptContentType = "text/ssTcl"; # Yes, you can do this
1420 CGIscriptor::RedirectShellScript('/usr/bin/tcl'); # Pipe to Tcl
1421 $CGIscriptor::NoShellScriptInterpolation = 1;
1423 </PRE>
1425 <P>
1426 After this script is executed, CGIscriptor will parse scripts of
1428 WITHOUT interpolation (i.e., NO substitution of Perl variables).
1429 The crucial function is :
1430 </P>
1432 <PRE>
1433 CGIscriptor::RedirectShellScript('/usr/bin/tcl')
1434 </PRE>
1436 <P>
1437 After executing this function, all shell scripts AND all
1438 calls to SAFEqx()) are piped into '|/usr/bin/tcl'. If the argument
1439 of RedirectShellScript is empty, e.g., '', the original (default)
1440 value is reset.
1441 </P>
1443 <P>
1444 The standard output, STDOUT, of any pipe is send to the client.
1445 Currently, you should be carefull with quotes in such a piped script.
1446 The results of a pipe is NOT put on the @CGIscriptorResults stack.
1447 As a result, you do not have access to the output of any piped (#!)
1448 process! If you want such access, execute
1449 </P>
1451 <PRE>
1453 </PRE>
1455 <P>
1456 or
1457 </P>
1459 <PRE>
1461 $resultvar = SAFEqx('echo "script"|command');
1463 </PRE>
1465 <P>
1466 Safety is never complete. Although SAFEqx() prevents some of the
1467 most obvious forms of attacks and security slips, it cannot prevent
1468 them all. Especially, complex combinations of quotes and intricate
1469 variable references cannot be handled safely by SAFEqx. So be on
1470 guard.
1471 </P>
1475 <P>
1476 All PERL scripts are evaluated inside a PERL package. This package
1477 has a separate name space. This isolated name space protects the
1478 CGIscriptor.pl program against interference from user code. However,
1479 some variables, e.g., $_, are global and cannot be protected. You are
1480 advised NOT to use such global variable names. You CAN write
1481 directives that directly access the variables in the main program.
1482 You do so at your own risk (there is definitely enough rope available
1483 to hang yourself). The behavior of CGIscriptor becomes undefined if
1484 you change its private variables during run time. The PERL code
1485 directives are used as in:
1486 </P>
1488 <PRE>
1489 $Result = eval($directive); print $Result;'';
1490 </PRE>
1492 <P>
1495 the result is treated as a scalar. To prevent the VALUE of the code
1496 block from appearing on the client's screen, end the directive with
1498 eval(), blocks, and subroutines, but only as a scalar.
1499 </P>
1501 <P>
1504 (e.g., for "my $var;" declarations). This means that values assigned
1505 to a PERL variable can be used throughout the document unless they
1506 were declared with "my". The following will actually work as intended
1507 (note that the ``-quotes in this example are NOT evaluated, but used
1508 as simple quotes):
1509 </P>
1511 <PRE>
1513 anything ...
1515 anything ...
1517 </PRE>
1519 <P>
1522 construct will print the elements of $String separated by commas, leaving
1523 out the first element, i.e., $List[0].
1524 </P>
1526 <p>
1527 Another warning: './' and '~/' are ALWAYS replaced by the values of
1528 $YOUR_SCRIPTS and $YOUR_HTML_FILES, respectively . This can interfere
1529 with pattern matching, e.g., $a =~ s/aap\./noot\./g will result in the
1530 evaluations of $a =~ s/aap\\${YOUR_SCRIPTS}noot\./g. Use
1532 </p>
1534 <A NAME="SESSIONTICKETS"><H2 ALIGN="CENTER">SERVER SIDE SESSIONS AND ACCESS CONTROL (LOGIN)</H2></A>
1535 <p>
1536 An infrastructure for user acount authorization and file access control
1537 is available. Each request is matched against a list of URL path patterns.
1538 If the request matches, a Session Ticket is required to access the URL.
1539 This Session Ticket should be present as a CGI parameter:
1540 </p>
1542 <p>
1543 The example implementation stores Session Tickets as files in a local
1544 directory. To create Session Tickets, a Login request must be given
1546 password. The user name and (singly hashed) password are stored in a
1547 PASSWORD ticket with the same name as the user account (name cleaned up
1548 for security).
1549 </p>
1550 <p>
1551 The example session model implements 3 functions:
1552 <ol>
1554 The password is hashed with the server side salt, and then hashed with
1555 a Random salt. Client and Server both perform these actions and the
1556 Server only grants access if restults are the same. The server side only
1557 stores the password hashed with the
1558 server side salt. Neither the plain password, nor the hashed password is
1559 ever exchanged. Only values hashed with the one-time salt are exchanged.
1560 </li>
1562 For every access to a restricted URL, the Session Ticket is checked before
1563 access is granted. There are two session modes. The first uses a fixed
1564 Session Ticket that is stored as a cookie value in the browser. The second
1565 is a Challenge mode, where the client has to calculate the value of the
1566 one-time Session Ticket from a value derived from the password and
1567 a random string.
1568 </li>
1570 A new password is hashed with the server side salt, and then encrypted
1571 (XORed)
1572 with the old password hashed with the salt. That value is exchanged
1573 and XORed with the stored old hashed(salt+password). Again, the
1574 stored password value is never exchanged unencrypted.
1575 </li>
1576 </ol>
1577 </p>
1579 <p>
1580 The session authentication mechanism is based on the exchange of ticket
1581 identifiers. A ticket identifier is just a string of characters, a name
1582 or a random 40 character hexadecimal string. There are four types of
1583 tickets:
1584 <ul>
1589 </ul>
1590 All tickets can have an expiration date in the form of a time duration
1592 An absolute time can be given in seconds since the epoch of the server host.
1593 </p>
1594 <p>
1595 A Login page should create a LOGIN ticket file locally and send a
1596 server specific SALT, a Random salt, and a LOGIN ticket
1597 identifier. The server side compares the username and hashed password,
1598 actually hashed(Random salt+hashed(SALT+password)) from the client with
1599 the values it calculates from the stored Random salt from the LOGIN
1600 ticket and the hashed(SALT+password) from the PASSWORD ticket. If
1601 successful, a new SESSION ticket is generated as a hash sum of the LOGIN
1602 ticket and the stored password. This SESSION ticket should also be
1603 generated by the client and stored as a cookie value. The Username, IP
1604 address and Path are available as $LoginUsername, $LoginIPaddress, and
1605 $LoginPath, respectively.
1606 </p>
1607 <p>
1608 In the current example implementation, all random values are created as
1610 /dev/urandom.
1611 </p>
1614 <p>
1615 For strong security, please use end-to-end encryption. This can be
1616 achieved using a VPN (Virtual Private Network), SSH tunnel, or a HTTPS
1617 capable server with OpenSSL. The session ticket system of CGIscriptor.pl
1618 is intended to be used as a simple authentication mechanism WITHOUT
1619 END-TO-END ENCRYPTION. The authenticating mechanism tries to use some
1620 simple means to protect the authentication process from eavesdropping.
1621 For this it uses a secure hash function, SHA1. For all practial purposes,
1622 it is impossible to "decrypt" a SHA1 sum.
1623 </p>
1624 <p>
1625 Humans tend to reuse passwords. A compromise of a site running
1626 CGIscriptor.pl could therefore lead to a compromise of user accounts at
1627 other sites. Therefore, plain text passwords are never stored, used, or
1628 even exchanged. Instead, a server site SALT value is "encrypted" with
1629 the plain password, actually, both are hashed with a one-way secure hash
1630 function (SHA1) into a single string. Whenever the word "password" is
1631 used, this hash sum is meant.
1632 </p>
1633 <p>
1634 For the authentication and a change of password, the (old) password
1635 is used to "encrypt" a random one-time token or the new password,
1636 respectively. For authentication, decryption is not needed, so a secure
1637 hash function (SHA1) is used to create a one-way hash sum "encryption".
1638 A new password must be decrypted. New passwords are encryped by XORing
1639 them with the old password.
1640 </p>
1644 <P>
1645 A CGIscriptor package is attached to the bottom of this file. With
1646 this package you can personalize your version of CGIscriptor by
1647 including often used perl routines. These subroutines can be
1648 accessed by prefixing their names with CGIscriptor::, e.g.,
1649 </P>
1651 <PRE>
1653 CGIscriptor::ListDocs("/Books/*") # List all documents in /Books
1655 </PRE>
1657 <P>
1658 It already contains some useful subroutines for Document Management.
1659 As it is a separate package, it has its own namespace, isolated from
1660 both the evaluator and the main program. To access variables from
1662 </P>
1664 <P>
1665 Currently, the following functions are implemented
1666 (precede them with CGIscriptor::, see below for more information)
1667 </P>
1669 <UL>
1671 Is used by text/osshell Shell scripts. Protects all CGI
1672 (client-supplied) values with single quotes before executing the
1673 commands (one of the few functions that also works WITHOUT CGIscriptor::
1674 in front)
1676 failure/success)<br>
1677 Is used by the META tag to define and initialize CGI and ENV
1678 name/value pairs. Tries to obtain an initializing value from (in
1679 order):<br>
1680 $ENV{$name}<br>
1681 The Query string<br>
1682 The default value given (if any)<br>
1683 (one of the few functions that also works WITHOUT CGIscriptor::
1684 in front)
1686 Check a string against the Allowed File Characters (and ../ /..).
1687 Returns an empty string for unsafe filenames.
1689 Check a string against correct email address pattern.
1690 Returns an empty string for unsafe addresses.
1692 Open a named PIPE for SAFEqx to receive ALL shell scripts
1696 Extract the value of a CGI variable from the global or a private
1697 URL-encoded query (multipart POST raw, NOT decoded)
1698 <li>CGIparseValueList (ValueName [, URL_encoded_QueryString])
1700 As CGIparseValue, but now assembles ALL values of ValueName into a list.
1702 Extract the header of a multipart CGI variable from the global or a private
1703 URL-encoded query ("" when not a multipart variable or absent)
1705 Decode the complete global URL-encoded query or a private
1706 URL-encoded query
1708 Returns the page from URL (with added base tag, both FTP and HTTP)
1709 Uses main::GET_URL(URL, 1) to get at the command to read the URL.
1710 <LI>BrowseDirs(RootDirectory [, Pattern, Startdir, CGIname]) # print browsable directories
1711 <LI>ListDocs(Pattern [,ListType]) # Prints a nested HTML directory listing of
1713 <LI>HTMLdocTree(Pattern [,ListType]) # Prints a nested HTML listing of all
1714 local links starting from a given document, e.g.,
1716 </UL>
1720 <P>
1721 If the pseudo-variable "$CGIscriptorResults" has been defined in a
1722 META tag, all subsequent SCRIPT and META results are pushed
1723 on the @CGIscriptorResults stack. This list is just another
1724 Perl variable and can be used and manipulated like any other list.
1725 $CGIscriptorResults[-1] is always the last result.
1726 This is only of limited use, e.g., to use the results of an OS shell
1727 script inside a Perl script. Will NOT contain the results of Pipes
1728 or code from MIME-profiling.
1729 </P>
1731 <A NAME="CGIPREDEFINED"><H2 ALIGN="CENTER">USEFULL CGI PREDEFINED VARIABLES (DO NOT ASSIGN TO THESE)</H2></A>
1733 <ul>
1734 <li>$CGI_HOME - The ServerRoot directory
1735 <li>$CGI_Decoded_QS - The complete decoded Query String
1736 <li>$CGI_Content_Length - The ACTUAL length of the Query String
1737 <li>$CGI_Date - Current date and time
1738 <li>$CGI_Year $CGI_Month $CGI_Day $CGI_WeekDay - Current Date
1739 <li>$CGI_Time - Current Time
1740 <li>$CGI_Hour $CGI_Minutes $CGI_Seconds - Current Time, split
1741 GMT Date/Time:
1742 <li>$CGI_GMTYear $CGI_GMTMonth $CGI_GMTDay $CGI_GMTWeekDay $CGI_GMTYearDay
1743 <li>$CGI_GMTHour $CGI_GMTMinutes $CGI_GMTSeconds $CGI_GMTisdst
1744 </ul>
1748 <P>
1749 Variables accessible (in APACHE) as $ENV{"<name>"}
1750 (see: "http://hoohoo.ncsa.uiuc.edu/cgi/env.html"):
1751 </P>
1753 <UL>
1754 <LI>QUERY_STRING - The query part of URL, that is, everything that follows the
1755 question mark.
1756 <LI>PATH_INFO - Extra path information given after the script name
1757 <LI>PATH_TRANSLATED - Extra pathinfo translated through the rule system.
1758 (This doesn't always make sense.)
1759 <LI>REMOTE_USER - If the server supports user authentication, and the script is
1760 protected, this is the username they have authenticated as.
1761 <LI>REMOTE_HOST - The hostname making the request. If the server does not have
1762 this information, it should set REMOTE_ADDR and leave this unset
1763 <LI>REMOTE_ADDR - The IP address of the remote host making the request.
1765 variable will be set to the remote user name retrieved from
1766 the server. Usage of this variable should be limited to logging
1767 only.
1768 <LI>AUTH_TYPE - If the server supports user authentication, and the script
1769 is protected, this is the protocol-specific authentication
1770 method used to validate the user.
1771 <LI>CONTENT_TYPE - For queries which have attached information, such as HTTP
1772 POST and PUT, this is the content type of the data.
1773 <LI>CONTENT_LENGTH - The length of the said content as given by the client.
1774 <LI>SERVER_SOFTWARE - The name and version of the information server software
1775 answering the request (and running the gateway).
1776 Format: name/version
1777 <LI>SERVER_NAME - The server's hostname, DNS alias, or IP address as it
1778 would appear in self-referencing URLs
1779 <LI>GATEWAY_INTERFACE - The revision of the CGI specification to which this
1780 server complies. Format: CGI/revision
1781 <LI>SERVER_PROTOCOL - The name and revision of the information protocol this
1782 request came in with. Format: protocol/revision
1783 <LI>SERVER_PORT - The port number to which the request was sent.
1784 <LI>REQUEST_METHOD - The method with which the request was made. For HTTP,
1786 <LI>SCRIPT_NAME - A virtual path to the script being executed, used for
1787 self-referencing URLs.
1788 <LI>HTTP_ACCEPT - The MIME types which the client will accept, as given by
1789 HTTP headers. Other protocols may need to get this
1790 information from elsewhere. Each item in this list should
1791 be separated by commas as per the HTTP spec.
1792 Format: type/subtype, type/subtype
1793 <LI>HTTP_USER_AGENT - The browser the client is using to send the request.
1794 General format: software/version library/version.
1795 </UL>
1799 <P>
1800 CGIscriptor.pl will run on any WWW server that runs Perl scripts,
1801 just add a line like the following to your srm.conf file
1802 (Apache example):
1803 </P>
1805 <pre>
1806 ScriptAlias /SHTML/ /real-path/CGIscriptor.pl/
1807 </pre>
1809 <p>
1810 URL's that refer to http://www.your.address/SHTML/... will now be handled
1811 by CGIscriptor.pl, which can use a private directory tree (default is the
1812 DOCUMENT_ROOT directory tree, but it can be anywhere, see manual).
1813 </P>
1815 <p>
1816 If your hosting ISP won't let you add ScriptAlias lines you can use
1818 (from Gerd Franke)
1819 </P>
1821 <pre>
1822 RewriteEngine On
1823 RewriteBase /
1824 RewriteCond %{REQUEST_FILENAME} .html$
1825 RewriteCond %{SCRIPT_FILENAME} !cgiscriptor.pl$
1826 RewriteCond %{REQUEST_FILENAME} -f
1827 RewriteRule ^(.*)$ /cgi-bin/cgiscriptor.pl/$1?%{QUERY_STRING}
1828 </Pre>
1830 <p>
1832 in the url and where the file "path/filename.html" exists is redirected
1833 to "/cgi.bin/cgiscriptor.pl/path/filename.html?query".
1834 The user configuration should get the same path-level as the
1835 .htaccess-file:
1836 </P>
1838 <pre>
1839 # Just enter your own directory path here
1840 $YOUR_HTML_FILES = "$ENV{'DOCUMENT_ROOT'}";
1841 # use DOCUMENT_ROOT only, if .htaccess lies in the root-directory.
1842 </Pre>
1844 <p>
1845 If this .htaccess goes in a specific directory, the path to this
1846 directory must be added to $ENV{'DOCUMENT_ROOT'}.
1847 </p>
1849 <p>
1850 The CGIscriptor file contains all documentation as comments. These comments
1851 can be removed to speed up loading (e.g., `egrep -v '^#' CGIscriptor.pl` >
1852 leanScriptor.pl). A bare bones version of CGIscriptor.pl, lacking
1853 documentation, most comments, access control, example functions etc.
1854 (but still with the copyright notice and some minimal documentation)
1855 can be obtained by calling CGIscriptor.pl on the command line with the
1856 '-slim' command line argument, e.g.,
1857 </p>
1859 <PRE>
1861 </PRE>
1863 <P>
1866 'do CGIscriptor.pl' after setting $ENV{PATH_INFO} and $ENV{QUERY_STRING},
1867 or CGIscriptor.pl can be loaded with 'require "/real-path/CGIscriptor.pl"'.
1868 In the latter case, requests are processed by 'Handle_Request();'
1869 (again after setting $ENV{PATH_INFO} and $ENV{QUERY_STRING}).
1870 </P>
1872 <p>
1873 The --help command line switch will print the manual.
1874 </p>
1876 <P>
1877 Using the command line execution option, CGIscriptor.pl can be used as a document
1878 (meta-)preprocessor. If the first argument is '-', STDIN will be read. For example:
1879 </P>
1881 <PRE>
1883 </PRE>
1885 <P>
1886 This command line will produce a STATIC file with the DYNAMIC content of
1887 MyDocument.html "interpolated". This option would be very dangerous when
1888 available over the internet. If someone could sneak a
1889 'http://www.your.domain/-' URL past your server, CGIscriptor could EXECUTE
1890 any POSTED contend. Therefore, for security reasons, STDIN will NOT
1891 be read if ANY of the HTTP server environment variables is set (e.g., SERVER_PORT,
1892 SERVER_PROTOCOL, SERVER_NAME, SERVER_SOFTWARE, HTTP_USER_AGENT,
1893 REMOTE_ADDR).<br>
1894 This block on processing STDIN on HTTP requests can be lifted by setting
1895 <pre>
1896 $BLOCK_STDIN_HTTP_REQUEST = 0;
1897 </pre>
1898 In the security configuration. But be carefull when doing this.
1899 It can be very dangerous.
1900 </P>
1902 <P>
1903 Running demo's and more information can be found at
1904 http://www.fon.hum.uva.nl/~rob/OSS/OSS.html
1905 </P>
1907 <P>
1908 A pocket-size HTTP daemon, CGIservlet.pl, is available from my web site
1909 or CPAN that can use CGIscriptor.pl as the base of a µWWW server and
1910 demonstrates its use.
1911 </P>
1915 <P>
1916 CGIscriptor.pl was mainly developed and tested on UNIX. However, as I
1917 coded part of the time on an Apple Macintosh under MacPerl, I made sure
1918 CGIscriptor did run under MacPerl (with command line options). But only as
1919 an independend script, not as part of a HTTP server. I have used it
1920 under Apache in Windows XP.
1921 </P>
1925 <P>
1926 This program is free software; you can redistribute it and/or
1927 modify it under the terms of the GNU General Public License
1928 as published by the Free Software Foundation; either version 2
1929 of the License, or (at your option) any later version.
1930 </P>
1932 <P>
1933 This program is distributed in the hope that it will be useful,
1934 but WITHOUT ANY WARRANTY; without even the implied warranty of
1935 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
1936 GNU General Public License for more details.
1937 </P>
1939 <P>
1940 You should have received a copy of the GNU General Public License
1941 along with this program; if not, write to the Free Software
1944 </P>
1946 <PRE>
1947 Author: Rob van Son
1948 email:
1949 R.J.J.H.vanSon@uva.nl
1950 University of Amsterdam
1953 Ver: 2.0
1954 Env: Perl 5.002
1955 </PRE>
1956 </BODY>
1958 </HTML>