| blob | d2bfad17decd3e52c5f17a827d73cb0eaa3e3a9d |
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 four other type of ticket files:<br />
532 - LOGIN tickets store information about a current login request<br />
533 - PASSWORD tickets store account information to authorize login requests<br />
534 - IPADDRESS tickets for IP address only checks<br />
535 - CHALLENGE tickets for challenge tasks for every request<br />
536 </p>
537 <P>
538 <dt>8 Query length limiting
539 <dd>The length of the Query string can be limited. If CONTENT_LENGTH is larger
540 than this limit, the request is rejected. The combined length of the
541 Query string and the POST input is checked before any processing is done.
542 This will prevent clients from overloading the scripts.
543 The actual, combined, Query Size is accessible as a variable through
544 $CGI_Content_Length.
545 </P>
547 <P>
548 <dt>9 Illegal filenames, paths, and protected directories
549 <dd>One of the primary security concerns in handling CGI-scripts is the
551 malicious commands. Examples are inserting ';', null bytes, or <newline> characters
552 in URL's and filenames, followed by executable commands. A special
553 variable $FileAllowedChars stores a string of all allowed characters.
554 Any request that translates to a filename with a character OUTSIDE
555 this set will be rejected.<br>
556 In general, all (readable files) in the ServerRoot tree are accessible.
557 This might not be what you want. For instance, your ServerRoot directory
558 might be the working directory of a CVS project and contain sensitive
559 information (e.g., the password to get to the repository). You can block
560 access to these subdirectories by adding the corresponding patterns to
561 the $BlockPathAccess variable. For instance, $BlockPathAccess = '/CVS/'
562 will block any request that contains '/CVS/' or:<br>
563 <pre>
564 die if $BlockPathAccess && $ENV{'PATH_INFO'} =~ m@$BlockPathAccess@;
565 </pre>
566 </P>
568 <P>
569 <dt>10 The execution of code blocks can be controlled in a transparent way
570 by adding IF or UNLESS conditions in the tags themselves.
571 <dd>That is, a simple check of the validity of filenames or email
572 addresses can be done before any code is executed.
573 </p>
575 </dl>
577 <hr>
581 <UL>
602 </UL>
606 <P>
607 CGIscriptor removes embedded scripts, indicated by an HTML 4 type
608 <SCRIPT TYPE='text/ssperl'> </SCRIPT> or <SCRIPT TYPE='text/osshell'>
609 </SCRIPT> constructs. The contents of the directive are executed by
610 the PERL eval() and `` functions (in a separate name space). The
611 result of the eval() function replaces the <SCRIPT> </SCRIPT> construct
612 in the output file. You can use the values that are delivered in
615 defined in a <META> or <SCRIPT> tag.
617 subsequent <SCRIPT> and <META> results (including the defining
618 tag) will also be pushed onto a stack: @CGIscriptorResults. This list
619 behaves like any other, ordinary list and can be manipulated.
620 </P>
622 <P>
623 Both GET and POST requests are accepted. These two methods are treated
624 equal. Variables, i.e., those values that are determined when a file is
625 processed, are indicated in the CGI attribute by $<name> or
626 $<name>=<default> in which <name> is the name of the
627 variable and <default> is the value used when there is NO current CGI
628 value for <name> (you can use white-spaces in
629 $<name>=<default> but really DO make sure that the default
630 value is followed by white space or is quoted). Names can contain any
631 alphanumeric characters and _ (i.e., names match /[\w]+/).<br>
632 If the <i>Content-type:</i> is 'multipart/*', the input is treated as a
633 MIME multipart message and automatically delimited. CGI variables get the
635 </P>
637 <P>
638 Variables can be CGI variables, i.e., those from the QUERY_STRING,
639 environment variables, e.g., REMOTE_USER, REMOTE_HOST, or REMOTE_ADDR,
640 or predefined values, e.g., CGI_Decoded_QS (The complete, decoded,
641 query string), CGI_Content_Length (the length of the decoded query
642 string), CGI_Year, CGI_Month, CGI_Time, and CGI_Hour (the current
643 date and time).
644 </P>
646 <P>
647 All these are available when defined in a CGI attribute. All environment
648 variables are accessible as $ENV{'name'}. So, to access the REMOTE_HOST
649 and the REMOTE_USER, use, e.g.:
650 </P>
652 <PRE>
653 <SCRIPT TYPE='text/ssperl'>
655 </SCRIPT>
656 </PRE>
658 <P>
660 Another way to do this is:
661 </P>
663 <PRE>
666 </PRE>
668 or
670 <PRE>
673 </PRE>
675 <P>
676 This is possible because ALL environment variables are available as
677 CGI variables. The environment variables take precedence over CGI
679 </P>
681 <PRE>
683 </PRE>
685 <P>
686 Will print the current HOME directory (environment) irrespective whether
687 there is a CGI variable from the query
689 THIS IS A SECURITY FEATURE. It prevents clients from changing
690 the values of defined environment variables (e.g., by supplying
691 a bogus $REMOTE_ADDR). Although $ENV{} is not changed by the META tags,
692 it would make the use of declared variables insecure. You can still
693 access CGI variables after a name clash with
694 CGIscriptor::CGIparseValue(<name>).
695 </P>
697 <P>
698 Some CGI variables are present several times in the query string
699 (e.g., from multiple selections). These should be defined as
700 @VARIABLENAME=default in the CGI attribute. The list @VARIABLENAME
701 will contain ALL VARIABLENAME values from the query, or a single
702 default value. If there is an ENVIRONMENT variable of the
703 same name, it will be used instead of the default AND the query
704 values. The corresponding function is
705 CGIscriptor::CGIparseValueList(<name>)
706 </P>
708 <P>
709 CGI variables collected in a @VARIABLENAME list are unordered.
710 When more structured variables are needed, a hash table can be used.
711 A variable defined as %VARIABLE=default will collect all
712 CGI-parameter values whose name start with 'VARIABLE' in a hash table
713 with the remainder of the name as a key. For instance, %PERSON will
714 collect PERSONname='John Doe', PERSONbirthdate='01 Jan 00', and
715 PERSONspouse='Alice' into a hash table %PERSON such that
716 $PERSON{'spouse'} equals 'Alice'. Any default value or environment
718 variable of the same name, it will be used instead of the default
719 AND the query values. The corresponding function is
720 CGIscriptor::CGIparseValueHash(<name>)
721 </P>
723 <P>
724 This method of first declaring your environment and CGI variables
725 before being able to use them in the scripts might seem somewhat
726 clumsy, but it protects you from inadvertedly printing out the values of
727 system environment variables when their names coincide with those used
729 values for your private variables.
730 THIS IS A SECURITY FEATURE!
731 </P>
735 <P>
737 message before anything is printed. This has been extended to include
738 plain text (.txt) files, for which the Content-type (MIME type)
739 'text/plain' is printed. In all other respects, text files are treated as
740 HTML files (this can be switched off by removing '.txt' from the
741 $FilePattern variable). When the content type should be something else,
742 e.g., with multipart files, use the $RawFilePattern (.xmr, see also next
743 item). CGIscriptor will not print a Content-type message for this file type
744 (which must supply its OWN Content-type message). Raw files must still
745 conform to the <SCRIPT></SCRIPT> and <META> tag
746 specifications.
747 </P>
751 <P>
752 CGIscriptor is intended to process HTML and text files only. You can
754 with the .xmr extension. However, CGIscriptor will not process binary files
755 of any type, e.g., pictures or sounds. Given the sheer number of formats, I
756 do not have any intention to do so. However, an escape route has been
757 provided. You can construct a genuine raw (.xmr) text file that contains
758 the perl code to service any file type you want. If the global
759 $BinaryMapFile variable contains the path to this file (e.g.,
760 /BinaryMapFile.xmr), this file will be called whenever an unsupported
761 (non-HTML) file type is requested. The path to the requested binary file
762 is stored in $ENV('CGI_BINARY_FILE') and can be used like any other
763 CGI-variable. Servicing binary files then becomes supplying the correct
765 file and writing it to STDOUT (e.g., using sysread() and syswrite()).
766 </P>
770 <P>
771 All attributes of a META tag are ignored, except the
773 inside the quotes following the CONTENT= indication (white-space is
774 ignored, "'` (){}[]-quotes are allowed, plus their \ versions) MUST
775 start with any of the CGIscriptor mime-types (e.g.: text/ssperl or
776 text/osshell) and a comma or semicolon.
777 The quoted string following CGI= contains a white-space separated list
778 of declarations of the CGI (and Environment) values and default values
779 used when no CGI values are supplied by the query string.
780 </P>
782 <P>
783 If the default value is a longer string containing special characters,
784 possibly spanning several lines, the string must be enclosed in quotes.
785 You may use any pair of quotes or brackets from the list '', "", ``, (),
786 [], or {} to distinguish default values (or preceded by \, e.g., \(...\)
787 is different from (...)). The outermost pair will always be used and any
788 other quotes inside the string are considered to be part of the string
789 value, e.g.,
790 </P>
792 <PRE>
793 $Value = {['this'
794 "and" (this)]}
795 </PRE>
797 <P>
798 will result in $Value getting the default value
799 </P>
801 <PRE>
802 ['this'
803 "and" (this)]
804 </PRE>
806 <P>
807 (NOTE that the newline is part of the default value!).
808 </P>
810 <P>
811 Internally, for defining and initializing CGI (ENV) values, the META
812 and SCRIPT tags use the function "defineCGIvariable($name, $default)"
813 (scalars) and "defineCGIvariableList($name, $default)" (lists).
814 These functions can be used inside scripts as
815 "CGIscriptor::defineCGIvariable($name, $default)" and
816 "CGIscriptor::defineCGIvariableList($name, $default)".
817 </P>
819 <P>
820 The CGI attribute will be processed exactly identical when used inside
822 HTML 4.0 specifications of the W3C.
823 </P>
827 <P>
828 There is a problem when constructing html files containing
829 server-side perl scripts with standard HTML tools. These
830 tools will refuse to process any text between
832 tags. This is quite annoying when you want to use large
833 HTML templates where you will fill in values.
834 </P>
836 <P>
837 For this purpose, CGIscriptor will read the neutral
840 tag (in Cascading Style Sheet manner) Note that "varname" has
841 NO '$' before it, it is a bare name. Any text between
844 to '$varname' as is (e.g., as a literal). No
845 processing or interpolation will be performed.
846 There is also NO nesting possible. Do NOT nest
848 Moreover, DIV tags do NOT ensure a block structure in
849 the final rendering (i.e., no empty lines).
850 </P>
852 <P>
854 is handled the XML way. No content is processed,
855 but varname is defined, and any SRC directives are
856 processed.
857 </P>
859 <P>
860 You can use $varname like any other variable name.
861 However, $varname is NOT a CGI variable and will be
862 completely internal to your script. There is NO
863 interaction between $varname and the outside world.
864 </P>
866 <P>
867 To interpolate a DIV derived text, you can use:
868 <pre>
869 $varname =~ s/([\]])/\\\1/g; # Mark ']'-quotes
870 $varname = eval("qq[$varname]"); # Interpolate all values
871 </pre>
872 </P>
874 <p>
875 The DIV tag will process IF, UNLESS, CGI and SRC attributes.
876 The SRC files will be pre-pended to the body
877 text of the tag.
878 </p>
881 CONDITIONAL PROCESSING: THE 'IF' AND 'UNLESS' ATTRIBUTES
882 </H2></A>
884 <p>
885 It is often necessary to include code-blocks that should be executed
886 conditionally, e.g., only for certain browsers or operating system.
887 Furthermore, quite often sanity and security checks are necessary
888 before user (form) data can be processed, e.g., with respect to
889 email addresses and filenames.
890 </p>
892 <p>
893 Checks added to the code are often difficult to find, interpret or
894 maintain and in general mess up the code flow. This kind of confussion
895 is dangerous. Also, for many of the supported "foreign" scripting
896 languages, adding these checks is cumbersome or even impossible.
897 </p>
899 <p>
900 As a uniform method for asserting the correctness of "context", two
901 attributes are added to all supported tags: IF and UNLESS.
902 They both evaluate their value and block execution when the
905 the backslash in the '\>' is removed and only used to differentiate
907 backslash in '\<' is also removed. Inside these conditionals,
908 ~/ and ./ are expanded to their respective directory root paths.
909 </p>
911 <p>
912 For example, the following tag will be ignored when the filename is
913 invalid:
914 </p>
916 <pre>
917 <SCRIPT TYPE='text/ssperl' CGI='$FILENAME'
918 IF='CGIscriptor::CGIsafeFileName($FILENAME);'>
919 ...
921 </pre>
923 <p>
924 The IF and UNLESS values must be quoted. The same quotes are supported
925 as with the other attributes. The SRC attribute is ignored when IF and
926 UNLESS block execution.
927 </p>
930 THE MAGIC SOURCE ATTRIBUTE (SRC=)</H2></A>
932 <P>
933 The SRC attribute inside tags accepts a list of filenames and URL's
935 </P>
937 <P>
938 ALL the variable values defined in the CGI attribute are available in
939 @ARGV as if the file was executed from the command line, in
940 the exact order in which they were declared in the preceding CGI
941 attribute.
942 </P>
944 <P>
945 First, a SRC={}-block will be evaluated as if the code inside the
947 "print do { code };'';" or `code` (i.e., SAFEqx('code)).
948 Only a single block is evaluated. Note that this is processed less
950 depends on the content-type: Perl for text/ssperl and OS shell for
951 text/osshell. For other mime types (scripting languages), anything in
952 the source block is put in front of the code block "inside" the tag.
953 </P>
955 <P>
956 Second, executable files (i.e., -x filename != 0) are evaluated as:
958 That is, you can actually call executables savely from the SRC tag.
959 </P>
961 <P>
962 Third, text files that match the file pattern, used by CGIscriptor to
963 check whether files should be processed ($FilePattern), are
964 processed in-line (i.e., recursively) by CGIscriptor as if the code
965 was inserted in the original source file. Recursions, i.e., calling
966 a file inside itself, are blocked. If you need them, you have to code
967 them explicitely using "main::ProcessFile($file_path)".
968 </P>
970 <P>
971 Fourth, Perl text files (i.e., -T filename != 0) are evaluated as:
972 "do FileName;'';".
973 </P>
975 <P>
976 Last, URL's (i.e., starting with 'HTTP://', 'FTP://', 'GOPHER://', 'TELNET://',
978 and document header is done by main::GET_URL($URL [, 0]). You can enter your own
981 </P>
983 <P>
984 There are two pseudo-file names: PREFIX and POSTFIX. These implement
985 a switch from prefixing the SRC code/files (PREFIX, default) before the content of
986 the tag to appending the code after the content of the tag (POSTFIX). The switches
987 are done in the order in which the PREFIX and POSTFIX labels are encountered.
988 You can mix PREFIX and POSTFIX labels in any order with the SRC files.
989 Note that the ORDER of file execution is determined for prefixed and
990 postfixed files seperately.
991 <P>
993 <P>
994 File paths can be preceded by the URL protocol prefix "file://". This
995 is simply STRIPPED from the name.
996 </P>
998 <P>
999 Example:
1000 </P>
1002 <P>
1003 The request
1004 "http://cgi-bin/Action_Forms.pl/Statistics/Sign_Test.html?positive=8&negative=22
1007 </P>
1009 <P>
1010 on encountering the lines:
1011 </P>
1013 <PRE>
1016 </SCRIPT></b><p>"
1017 </PRE>
1019 This line will be processed as:
1021 <PRE>
1022 "<b>`${SS_SCRIPT}/Statistics/SignTest.pl '8' '22'`</b><p>"
1023 </PRE>
1025 <P>
1026 In which "${SS_SCRIPT}/Statistics/SignTest.pl" is an executable script,
1027 This line will end up printed as:
1028 </P>
1030 <PRE>
1031 "<b>p <= 0.0161</b><p>"
1032 </PRE>
1034 <P>
1035 Note that the META tag itself will never be printed, and is invisible to
1036 the outside world.
1037 </P>
1039 <P>
1040 The SRC files in a DIV/INS tag will be added (pre-pended) to the body
1042 </P>
1046 <P>
1049 public directories can be accessed without direct reference to the
1050 actual paths. Filepaths starting with "./" are replaced by
1051 "$YOUR_SCRIPTS/" and this should only be used for scripts.
1052 The "$YOUR_SCRIPTS" directory is added to @INC so, e.g., the
1053 'require' command will load from the "$YOUR_SCRIPTS" directory.
1054 </P>
1056 <P>
1058 out for constructs like $a =~ s/aap\./noot./g, use
1059 $a =~ s@aap\.@noot.@g instead.
1060 </P>
1062 <P>
1063 CGIscriptor.pl will assign the values of $SS_PUB and $SS_SCRIPT
1064 (i.e., $YOUR_HTML_FILES and $YOUR_SCRIPTS) to the environment variables
1065 $SS_PUB and $SS_SCRIPT. These can be accessed by the scripts that are
1066 executed. The "$SS_SCRIPT" ($YOUR_SCRIPTS) directory is added to
1067 @INC so, e.g., the 'require' command will load from the "$SS_SCRIPT"
1068 directory.<br>
1069 Values not preceded by $, ~/, or ./ are used as literals
1070 </P>
1072 <A NAME="OSSHELL"><H2 ALIGN="CENTER">OS SHELL SCRIPT EVALUATION (CONTENT-TYPE=TEXT/OSSHELL)</H2></A>
1074 <P>
1075 OS scripts are executed by a "safe" version of the `` operator (i.e.,
1076 SAFEqx(), see also below) and any output is printed. CGIscriptor will
1077 interpolate the script and replace all user-supplied CGI-variables by
1078 their ''-quoted values (actually, all variables defined in CGI attributes are
1079 quoted). Other Perl variables are interpolated in a simple fasion, i.e.,
1080 $scalar by their value, @list by join(' ', @list), and %hash by their
1081 name=value pairs. Complex references, e.g., @$variable, are all
1082 evaluated in a scalar context. Quotes should be used with care.
1083 NOTE: the results of the shell script evaluation will appear in the
1084 @CGIscriptorResults stack just as any other result.
1085 </P>
1087 <P>
1088 All occurrences of $@% that should NOT be interpolated must be
1089 preceeded by a "\". Interpolation can be switched off completely by
1090 setting $CGIscriptor::NoShellScriptInterpolation = 1
1091 (set to 0 or undef to switch interpolation on again)
1092 i.e.,
1093 </P>
1095 <PRE>
1097 $CGIscriptor::NoShellScriptInterpolation = 1;
1099 </PRE>
1104 <p>
1105 Allows general and global conversions of files using Regular Expressions.
1106 Very handy (but costly) to rewrite legacy pages to a new format.
1107 Select files to use it on with <br>
1108 my $TranslationPaths = 'filepattern';<br>
1109 This is costly. For efficiency, define:<br>
1110 $TranslationPaths = ''; when not using translations.<br>
1111 Accepts general regular expressions: [$pattern, $replacement]
1112 </p>
1114 <p>
1115 Define:</p>
1116 <pre>
1117 my $TranslationPaths = 'filepattern'; # Pattern matching PATH_INFO
1119 push(@TranslationTable, ['pattern', 'replacement']);
1120 # e.g. (for Ruby Rails):
1124 # Runs:
1125 my $currentRegExp;
1126 foreach $currentRegExp (@TranslationTable)
1127 {
1128 my ($pattern, $replacement) = @$currentRegExp;
1129 $$text =~ s!$pattern!$replacement!msg;
1130 };
1131 </pre>
1135 </A>
1137 <P>
1138 Adding a MIME-type and an interpreter command to
1139 %ScriptingLanguages automatically will catch any other
1140 scripting language in the standard
1142 E.g., adding: $ScriptingLanguages{'text/sspython'} = 'python';
1143 will actually execute the folowing code in an HTML page
1144 (ignore 'REMOTE_HOST' for the moment):
1145 </P>
1147 <PRE>
1149 # A Python script
1153 </PRE>
1155 <P>
1156 The script code is NOT interpolated by perl, EXCEPT for those
1157 interpreters that cannot handle variables themselves.
1158 Currently, several interpreters are pre-installed:
1159 </P>
1161 <PRE>
1168 # "| egrep -v '> |^rep. |^nil\\\$'",
1178 "rebol --quiet|egrep -v '^[> ]* == '|sed 's/^\s*\[> \]* //g'",
1180 (psql)
1181 </PRE>
1183 <P>
1184 Note that the "value" of $ScriptingLanguages{mime} must be a command
1185 that reads Standard Input and writes to standard output. Any extra
1186 output of interactive interpreters (banners, echo's, prompts)
1187 should be removed by piping the output through 'tail', 'grep',
1188 'sed', or even 'awk' or 'perl'.
1189 </P>
1191 <P>
1192 For access to CGI variables there is a special hashtable:
1193 %ScriptingCGIvariables.
1194 CGI variables can be accessed in three ways.
1195 <dl>
1197 nothing is done and the script itself should parse the relevant
1198 environment variables.
1200 value is empty, e.g., $ScriptingCGIvariables{"text/sspraat"} = '';,
1201 the script text is interpolated by perl. That is, all $var, @array,
1202 %hash, and \-slashes are replaced by their respective values.
1204 in front of the script according to the format stored in
1205 %ScriptingCGIvariables. That is, the following (pseudo-)code is
1206 executed for each CGI- or Environment variable defined in the CGI-tag:
1207 printf(INTERPRETER, $ScriptingCGIvariables{$mime}, $CGI_NAME, $CGI_VALUE);
1208 </dl>
1209 </P>
1211 <P>
1214 (note that these definitions are not save, the real ones contain '-quotes).
1215 </P>
1217 <P>
1218 THIS WILL NOT WORK FOR @VARIABLES, the (empty) $VARIABLES will be used
1219 instead.
1220 </P>
1222 <P>
1223 The $CGI_VALUE parameters are "shrubed" of all control characters
1224 and quotes (by &shrubCGIparameter($CGI_VALUE)). Control characters
1228 if a client would supply the string value (in standard perl)
1229 </P>
1231 <P>
1233 it would be processed as
1235 (e.g., sh or bash would process the latter more according to your
1236 intentions).<br>
1237 If your intepreter requires different protection measures, you will
1238 have to supply these in %main::SHRUBcharacterTR (string => translation),
1239 e.g.,
1241 <PRE>
1243 </PRE>
1244 </P>
1246 <P>
1247 Currently, the following definitions are used:
1248 </P>
1250 <PRE>
1251 %ScriptingCGIvariables = (
1269 );
1270 </PRE>
1272 <P>
1273 Four tables allow fine-tuning of interpreter with code that should be
1274 added before and after each code block:
1275 </P>
1277 <P>
1278 Code added before each script block
1279 </P>
1281 <PRE>
1282 %ScriptingPrefix = (
1285 );
1286 </PRE>
1288 <P>
1289 Code added at the end of each script block
1290 </P>
1292 <PRE>
1293 %ScriptingPostfix = (
1296 );
1297 </PRE>
1299 <P>
1300 Initialization code, inserted directly after opening (NEVER interpolated)
1301 </P>
1303 <PRE>
1304 %ScriptingInitialization = (
1309 );
1310 </PRE>
1312 <P>
1313 Cleanup code, inserted before closing (NEVER interpolated)
1314 </P>
1316 <PRE>
1317 %ScriptingCleanup = (
1323 );
1324 </PRE>
1326 <P>
1327 The SRC attribute is NOT magical for these interpreters. In short,
1328 all code inside a source file or {} block is written verbattim
1329 to the interpreter. No (pre-)processing or executional magic is done.
1330 </P>
1332 <P>
1333 A serious shortcomming of the described mechanism for handling other
1334 (scripting) languages, with respect to standard perl scripts
1335 (i.e., 'text/ssperl'), is that the code is only executed when
1336 the pipe to the interpreter is closed. So the pipe has to be
1337 closed at the end of each block. This means that the state of the
1338 interpreter (e.g., all variable values) is lost after the closing of
1340 all values and definitions.
1341 </P>
1346 <P>
1347 To ease some important auxilliary functions from within the
1348 html pages I have added them as MIME types. This uses
1349 the mechanism that is also used for the evaluation of
1350 other scripting languages, with interpolation of CGI
1351 parameters (and perl-variables). Actually, these are
1352 defined exactly like any other "scripting language".
1353 </P>
1355 <dl>
1356 <dt>text/ssdisplay:
1357 <dd>display some (HTML) text with interpolated
1358 variables (uses `cat`).
1359 <dt>text/sslogfile:
1360 <dd>write (append) the interpolated block to the file
1361 mentioned on the first, non-empty line
1362 (the filename can be preceded by 'File: ',
1363 note the space after the ':',
1365 <dt>text/ssmailto:
1366 <dd>send email directly from within the script block.
1367 The first line of the body must contain
1368 To:Name@Valid.Email.Address
1369 (note: NO space between 'To:' and the email adres)
1370 For other options see the mailto man pages.
1371 It works by directly sending the (interpolated)
1372 content of the text block to a pipe into the
1373 Linux program 'mailto'.
1374 </dl>
1376 <P>
1377 In these script blocks, all Perl variables will be
1378 replaced by their values. All CGI variables are cleaned before
1379 they are used. These CGI variables must be redefined with a
1380 CGI attribute to restore their original values.
1381 In general, this will be more secure than constructing
1382 e.g., your own email command lines. For instance, Mailto will
1383 not execute any odd (forged) email address, but just stops
1384 when the email address is invalid and awk will construct
1386 as a "valid" UNIX filename). Note that it will also gladly
1387 store this file anywhere (/../../../etc/passwd will work!).
1388 Use the CGIscriptor::CGIsafeFileName() function to clean the
1389 filename.
1390 </P>
1394 <P>
1395 If a shell script starts with the UNIX style "#! <shell command> \n"
1396 line, the rest of the shell script is piped into the indicated command,
1397 i.e.,
1398 open(COMMAND, "| command");print COMMAND $RestOfScript;
1399 </P>
1401 <P>
1402 In many ways this is equivalent to the MIME-type profiling for
1403 evaluating other scripting languages as discussed above. The
1404 difference breaks down to convenience. Shell script piping is a
1405 "raw" implementation. It allows you to control all aspects of
1406 execution. Using the MIME-type profiling is easier, but has a
1407 lot of defaults built in that might get in the way. Another
1408 difference is that shell script piping uses the SAFEqx() function,
1409 and MIME-type profiling does not.
1410 </P>
1412 <P>
1413 Execution of shell scripts is under the control of the Perl Script blocks
1414 in the document. The MIME-type triggered execution of <SCRIPT></SCRIPT>
1415 blocks can be simulated easily. You can switch to a different shell, e.g. tcl,
1416 completely by executing the following Perl commands inside your document:
1417 </P>
1419 <PRE>
1421 $main::ShellScriptContentType = "text/ssTcl"; # Yes, you can do this
1422 CGIscriptor::RedirectShellScript('/usr/bin/tcl'); # Pipe to Tcl
1423 $CGIscriptor::NoShellScriptInterpolation = 1;
1425 </PRE>
1427 <P>
1428 After this script is executed, CGIscriptor will parse scripts of
1430 WITHOUT interpolation (i.e., NO substitution of Perl variables).
1431 The crucial function is :
1432 </P>
1434 <PRE>
1435 CGIscriptor::RedirectShellScript('/usr/bin/tcl')
1436 </PRE>
1438 <P>
1439 After executing this function, all shell scripts AND all
1440 calls to SAFEqx()) are piped into '|/usr/bin/tcl'. If the argument
1441 of RedirectShellScript is empty, e.g., '', the original (default)
1442 value is reset.
1443 </P>
1445 <P>
1446 The standard output, STDOUT, of any pipe is send to the client.
1447 Currently, you should be carefull with quotes in such a piped script.
1448 The results of a pipe is NOT put on the @CGIscriptorResults stack.
1449 As a result, you do not have access to the output of any piped (#!)
1450 process! If you want such access, execute
1451 </P>
1453 <PRE>
1455 </PRE>
1457 <P>
1458 or
1459 </P>
1461 <PRE>
1463 $resultvar = SAFEqx('echo "script"|command');
1465 </PRE>
1467 <P>
1468 Safety is never complete. Although SAFEqx() prevents some of the
1469 most obvious forms of attacks and security slips, it cannot prevent
1470 them all. Especially, complex combinations of quotes and intricate
1471 variable references cannot be handled safely by SAFEqx. So be on
1472 guard.
1473 </P>
1477 <P>
1478 All PERL scripts are evaluated inside a PERL package. This package
1479 has a separate name space. This isolated name space protects the
1480 CGIscriptor.pl program against interference from user code. However,
1481 some variables, e.g., $_, are global and cannot be protected. You are
1482 advised NOT to use such global variable names. You CAN write
1483 directives that directly access the variables in the main program.
1484 You do so at your own risk (there is definitely enough rope available
1485 to hang yourself). The behavior of CGIscriptor becomes undefined if
1486 you change its private variables during run time. The PERL code
1487 directives are used as in:
1488 </P>
1490 <PRE>
1491 $Result = eval($directive); print $Result;'';
1492 </PRE>
1494 <P>
1497 the result is treated as a scalar. To prevent the VALUE of the code
1498 block from appearing on the client's screen, end the directive with
1500 eval(), blocks, and subroutines, but only as a scalar.
1501 </P>
1503 <P>
1506 (e.g., for "my $var;" declarations). This means that values assigned
1507 to a PERL variable can be used throughout the document unless they
1508 were declared with "my". The following will actually work as intended
1509 (note that the ``-quotes in this example are NOT evaluated, but used
1510 as simple quotes):
1511 </P>
1513 <PRE>
1515 anything ...
1517 anything ...
1519 </PRE>
1521 <P>
1524 construct will print the elements of $String separated by commas, leaving
1525 out the first element, i.e., $List[0].
1526 </P>
1528 <p>
1529 Another warning: './' and '~/' are ALWAYS replaced by the values of
1530 $YOUR_SCRIPTS and $YOUR_HTML_FILES, respectively . This can interfere
1531 with pattern matching, e.g., $a =~ s/aap\./noot\./g will result in the
1532 evaluations of $a =~ s/aap\\${YOUR_SCRIPTS}noot\./g. Use
1534 </p>
1536 <A NAME="SESSIONTICKETS"><H2 ALIGN="CENTER">SERVER SIDE SESSIONS AND ACCESS CONTROL (LOGIN)</H2></A>
1537 <p>
1538 An infrastructure for user acount authorization and file access control
1539 is available. Each request is matched against a list of URL path patterns.
1540 If the request matches, a Session Ticket is required to access the URL.
1541 This Session Ticket should be present as a CGI parameter or Cookie:
1542 </p>
1543 <p>
1546 <p>
1547 The example implementation stores Session Tickets as files in a local
1548 directory. To create Session Tickets, a Login request must be given
1550 password. The user name and (singly hashed) password are stored in a
1551 PASSWORD ticket with the same name as the user account (name cleaned up
1552 for security).
1553 </p>
1554 <p>
1555 The example session model implements 3 functions:
1556 <ol>
1558 The password is hashed with the user name and server side salt, and then
1559 hashed with a Random salt. Client and Server both perform these actions
1560 and the Server only grants access if restults are the same. The server
1561 side only stores the password hashed with the user name and
1562 server side salt. Neither the plain password, nor the hashed password is
1563 ever exchanged. Only values hashed with the one-time salt are exchanged.
1564 </li>
1566 For every access to a restricted URL, the Session Ticket is checked before
1567 access is granted. There are three session modes. The first uses a fixed
1568 Session Ticket that is stored as a cookie value in the browser (actually,
1569 as a sessionStorage value). The second uses only the IP address at login
1570 to authenticate requests. The third
1571 is a Challenge mode, where the client has to calculate the value of the
1572 one-time Session Ticket from a value derived from the password and
1573 a random string.
1574 </li>
1576 A new password is hashed with the user name and server side salt, and
1577 then encrypted (XORed)
1578 with the old password hashed with the user name and salt. That value is
1579 exchanged and XORed with the stored old hashed(salt+password+username).
1580 Again, the stored password value is never exchanged unencrypted.
1581 </li>
1582 </ol>
1583 </p>
1585 <p>
1586 The session authentication mechanism is based on the exchange of ticket
1587 identifiers. A ticket identifier is just a string of characters, a name
1588 or a random 40 character hexadecimal string. Ticket identifiers should be
1589 "safe" filenames (except user names). There are four types of tickets:
1590 <ul>
1594 <li>IPADDRESS: authetication tokens that allow access based on the IP address of the request</li>
1596 </ul>
1597 All tickets can have an expiration date in the form of a time duration
1599 An absolute time can be given in seconds since the epoch of the server host.
1600 </p>
1601 <p>
1602 A Login page should create a LOGIN ticket file locally and send a
1603 server specific SALT, a Random salt, and a LOGIN ticket
1604 identifier. The server side compares the username and hashed password,
1605 actually hashed(Random salt+hashed(SALT+password)) from the client with
1606 the values it calculates from the stored Random salt from the LOGIN
1607 ticket and the hashed(SALT+password) from the PASSWORD ticket. If
1608 successful, a new SESSION ticket is generated as a hash sum of the LOGIN
1609 ticket and the stored password. This SESSION ticket should also be
1610 generated by the client and stored as sessionStorage and cookie values
1611 as needed. The Username, IP address and Path are available as
1612 $LoginUsername, $LoginIPaddress, and $LoginPath, respectively.
1613 </p>
1614 <p>
1615 In the current example implementation, all random values are created as
1617 /dev/urandom.
1618 </p>
1621 <p>
1622 For strong security, please use end-to-end encryption. This can be
1623 achieved using a VPN (Virtual Private Network), SSH tunnel, or a HTTPS
1624 capable server with OpenSSL. The session ticket system of CGIscriptor.pl
1625 is intended to be used as a simple authentication mechanism WITHOUT
1626 END-TO-END ENCRYPTION. The authenticating mechanism tries to use some
1627 simple means to protect the authentication process from eavesdropping.
1628 For this it uses a secure hash function, SHA1. For all practial purposes,
1629 it is impossible to "decrypt" a SHA1 sum. But this login scheme is
1630 only as secure as your browser. Which, in general, is not secure.
1631 </p>
1632 <p>
1633 Humans tend to reuse passwords. A compromise of a site running
1634 CGIscriptor.pl could therefore lead to a compromise of user accounts at
1635 other sites. Therefore, plain text passwords are never stored, used, or
1636 even exchanged. Instead, a server site SALT value is "encrypted" with
1637 the plain password and user name, actually, all are concatenated and hashed
1638 with a one-way secure hash function (SHA1) into a single string.
1639 Whenever the word "password" is used, this hash sum is meant.
1640 </p>
1641 <p>
1642 For the authentication and a change of password, the (old) password
1643 is used to "encrypt" a random one-time token or the new password,
1644 respectively. For authentication, decryption is not needed, so a secure
1645 hash function (SHA1) is used to create a one-way hash sum "encryption".
1646 A new password must be decrypted. New passwords are encryped by XORing
1647 them with the old password.
1648 </p>
1652 <P>
1653 A CGIscriptor package is attached to the bottom of this file. With
1654 this package you can personalize your version of CGIscriptor by
1655 including often used perl routines. These subroutines can be
1656 accessed by prefixing their names with CGIscriptor::, e.g.,
1657 </P>
1659 <PRE>
1661 CGIscriptor::ListDocs("/Books/*") # List all documents in /Books
1663 </PRE>
1665 <P>
1666 It already contains some useful subroutines for Document Management.
1667 As it is a separate package, it has its own namespace, isolated from
1668 both the evaluator and the main program. To access variables from
1670 </P>
1672 <P>
1673 Currently, the following functions are implemented
1674 (precede them with CGIscriptor::, see below for more information)
1675 </P>
1677 <UL>
1679 Is used by text/osshell Shell scripts. Protects all CGI
1680 (client-supplied) values with single quotes before executing the
1681 commands (one of the few functions that also works WITHOUT CGIscriptor::
1682 in front)
1684 failure/success)<br>
1685 Is used by the META tag to define and initialize CGI and ENV
1686 name/value pairs. Tries to obtain an initializing value from (in
1687 order):<br>
1688 $ENV{$name}<br>
1689 The Query string<br>
1690 The default value given (if any)<br>
1691 (one of the few functions that also works WITHOUT CGIscriptor::
1692 in front)
1694 Check a string against the Allowed File Characters (and ../ /..).
1695 Returns an empty string for unsafe filenames.
1697 Check a string against correct email address pattern.
1698 Returns an empty string for unsafe addresses.
1700 Open a named PIPE for SAFEqx to receive ALL shell scripts
1704 Extract the value of a CGI variable from the global or a private
1705 URL-encoded query (multipart POST raw, NOT decoded)
1706 <li>CGIparseValueList (ValueName [, URL_encoded_QueryString])
1708 As CGIparseValue, but now assembles ALL values of ValueName into a list.
1710 Extract the header of a multipart CGI variable from the global or a private
1711 URL-encoded query ("" when not a multipart variable or absent)
1713 Decode the complete global URL-encoded query or a private
1714 URL-encoded query
1716 Returns the page from URL (with added base tag, both FTP and HTTP)
1717 Uses main::GET_URL(URL, 1) to get at the command to read the URL.
1718 <LI>BrowseDirs(RootDirectory [, Pattern, Startdir, CGIname]) # print browsable directories
1719 <LI>ListDocs(Pattern [,ListType]) # Prints a nested HTML directory listing of
1721 <LI>HTMLdocTree(Pattern [,ListType]) # Prints a nested HTML listing of all
1722 local links starting from a given document, e.g.,
1724 </UL>
1728 <P>
1729 If the pseudo-variable "$CGIscriptorResults" has been defined in a
1730 META tag, all subsequent SCRIPT and META results are pushed
1731 on the @CGIscriptorResults stack. This list is just another
1732 Perl variable and can be used and manipulated like any other list.
1733 $CGIscriptorResults[-1] is always the last result.
1734 This is only of limited use, e.g., to use the results of an OS shell
1735 script inside a Perl script. Will NOT contain the results of Pipes
1736 or code from MIME-profiling.
1737 </P>
1739 <A NAME="CGIPREDEFINED"><H2 ALIGN="CENTER">USEFULL CGI PREDEFINED VARIABLES (DO NOT ASSIGN TO THESE)</H2></A>
1741 <ul>
1742 <li>$CGI_HOME - The ServerRoot directory
1743 <li>$CGI_Decoded_QS - The complete decoded Query String
1744 <li>$CGI_Content_Length - The ACTUAL length of the Query String
1745 <li>$CGI_Date - Current date and time
1746 <li>$CGI_Year $CGI_Month $CGI_Day $CGI_WeekDay - Current Date
1747 <li>$CGI_Time - Current Time
1748 <li>$CGI_Hour $CGI_Minutes $CGI_Seconds - Current Time, split
1749 GMT Date/Time:
1750 <li>$CGI_GMTYear $CGI_GMTMonth $CGI_GMTDay $CGI_GMTWeekDay $CGI_GMTYearDay
1751 <li>$CGI_GMTHour $CGI_GMTMinutes $CGI_GMTSeconds $CGI_GMTisdst
1752 </ul>
1756 <P>
1757 Variables accessible (in APACHE) as $ENV{"<name>"}
1758 (see: "http://hoohoo.ncsa.uiuc.edu/cgi/env.html"):
1759 </P>
1761 <UL>
1762 <LI>QUERY_STRING - The query part of URL, that is, everything that follows the
1763 question mark.
1764 <LI>PATH_INFO - Extra path information given after the script name
1765 <LI>PATH_TRANSLATED - Extra pathinfo translated through the rule system.
1766 (This doesn't always make sense.)
1767 <LI>REMOTE_USER - If the server supports user authentication, and the script is
1768 protected, this is the username they have authenticated as.
1769 <LI>REMOTE_HOST - The hostname making the request. If the server does not have
1770 this information, it should set REMOTE_ADDR and leave this unset
1771 <LI>REMOTE_ADDR - The IP address of the remote host making the request.
1773 variable will be set to the remote user name retrieved from
1774 the server. Usage of this variable should be limited to logging
1775 only.
1776 <LI>AUTH_TYPE - If the server supports user authentication, and the script
1777 is protected, this is the protocol-specific authentication
1778 method used to validate the user.
1779 <LI>CONTENT_TYPE - For queries which have attached information, such as HTTP
1780 POST and PUT, this is the content type of the data.
1781 <LI>CONTENT_LENGTH - The length of the said content as given by the client.
1782 <LI>SERVER_SOFTWARE - The name and version of the information server software
1783 answering the request (and running the gateway).
1784 Format: name/version
1785 <LI>SERVER_NAME - The server's hostname, DNS alias, or IP address as it
1786 would appear in self-referencing URLs
1787 <LI>GATEWAY_INTERFACE - The revision of the CGI specification to which this
1788 server complies. Format: CGI/revision
1789 <LI>SERVER_PROTOCOL - The name and revision of the information protocol this
1790 request came in with. Format: protocol/revision
1791 <LI>SERVER_PORT - The port number to which the request was sent.
1792 <LI>REQUEST_METHOD - The method with which the request was made. For HTTP,
1794 <LI>SCRIPT_NAME - A virtual path to the script being executed, used for
1795 self-referencing URLs.
1796 <LI>HTTP_ACCEPT - The MIME types which the client will accept, as given by
1797 HTTP headers. Other protocols may need to get this
1798 information from elsewhere. Each item in this list should
1799 be separated by commas as per the HTTP spec.
1800 Format: type/subtype, type/subtype
1801 <LI>HTTP_USER_AGENT - The browser the client is using to send the request.
1802 General format: software/version library/version.
1803 </UL>
1807 <P>
1808 CGIscriptor.pl will run on any WWW server that runs Perl scripts,
1809 just add a line like the following to your srm.conf file
1810 (Apache example):
1811 </P>
1813 <pre>
1814 ScriptAlias /SHTML/ /real-path/CGIscriptor.pl/
1815 </pre>
1817 <p>
1818 URL's that refer to http://www.your.address/SHTML/... will now be handled
1819 by CGIscriptor.pl, which can use a private directory tree (default is the
1820 DOCUMENT_ROOT directory tree, but it can be anywhere, see manual).
1821 </P>
1823 <p>
1824 If your hosting ISP won't let you add ScriptAlias lines you can use
1826 (from Gerd Franke)
1827 </P>
1829 <pre>
1830 RewriteEngine On
1831 RewriteBase /
1832 RewriteCond %{REQUEST_FILENAME} .html$
1833 RewriteCond %{SCRIPT_FILENAME} !cgiscriptor.pl$
1834 RewriteCond %{REQUEST_FILENAME} -f
1835 RewriteRule ^(.*)$ /cgi-bin/cgiscriptor.pl/$1?%{QUERY_STRING}
1836 </Pre>
1838 <p>
1840 in the url and where the file "path/filename.html" exists is redirected
1841 to "/cgi.bin/cgiscriptor.pl/path/filename.html?query".
1842 The user configuration should get the same path-level as the
1843 .htaccess-file:
1844 </P>
1846 <pre>
1847 # Just enter your own directory path here
1848 $YOUR_HTML_FILES = "$ENV{'DOCUMENT_ROOT'}";
1849 # use DOCUMENT_ROOT only, if .htaccess lies in the root-directory.
1850 </Pre>
1852 <p>
1853 If this .htaccess goes in a specific directory, the path to this
1854 directory must be added to $ENV{'DOCUMENT_ROOT'}.
1855 </p>
1857 <p>
1858 The CGIscriptor file contains all documentation as comments. These comments
1859 can be removed to speed up loading (e.g., `egrep -v '^#' CGIscriptor.pl` >
1860 leanScriptor.pl). A bare bones version of CGIscriptor.pl, lacking
1861 documentation, most comments, access control, example functions etc.
1862 (but still with the copyright notice and some minimal documentation)
1863 can be obtained by calling CGIscriptor.pl on the command line with the
1864 '-slim' command line argument, e.g.,
1865 </p>
1867 <PRE>
1869 </PRE>
1871 <P>
1874 'do CGIscriptor.pl' after setting $ENV{PATH_INFO} and $ENV{QUERY_STRING},
1875 or CGIscriptor.pl can be loaded with 'require "/real-path/CGIscriptor.pl"'.
1876 In the latter case, requests are processed by 'Handle_Request();'
1877 (again after setting $ENV{PATH_INFO} and $ENV{QUERY_STRING}).
1878 </P>
1880 <p>
1881 The --help command line switch will print the manual.
1882 </p>
1884 <P>
1885 Using the command line execution option, CGIscriptor.pl can be used as a document
1886 (meta-)preprocessor. If the first argument is '-', STDIN will be read. For example:
1887 </P>
1889 <PRE>
1891 </PRE>
1893 <P>
1894 This command line will produce a STATIC file with the DYNAMIC content of
1895 MyDocument.html "interpolated". This option would be very dangerous when
1896 available over the internet. If someone could sneak a
1897 'http://www.your.domain/-' URL past your server, CGIscriptor could EXECUTE
1898 any POSTED contend. Therefore, for security reasons, STDIN will NOT
1899 be read if ANY of the HTTP server environment variables is set (e.g., SERVER_PORT,
1900 SERVER_PROTOCOL, SERVER_NAME, SERVER_SOFTWARE, HTTP_USER_AGENT,
1901 REMOTE_ADDR).<br>
1902 This block on processing STDIN on HTTP requests can be lifted by setting
1903 <pre>
1904 $BLOCK_STDIN_HTTP_REQUEST = 0;
1905 </pre>
1906 In the security configuration. But be carefull when doing this.
1907 It can be very dangerous.
1908 </P>
1910 <P>
1911 Running demo's and more information can be found at
1912 http://www.fon.hum.uva.nl/~rob/OSS/OSS.html
1913 </P>
1915 <P>
1916 A pocket-size HTTP daemon, CGIservlet.pl, is available from my web site
1917 or CPAN that can use CGIscriptor.pl as the base of a µWWW server and
1918 demonstrates its use.
1919 </P>
1923 <P>
1924 CGIscriptor.pl was mainly developed and tested on UNIX. However, as I
1925 coded part of the time on an Apple Macintosh under MacPerl, I made sure
1926 CGIscriptor did run under MacPerl (with command line options). But only as
1927 an independend script, not as part of a HTTP server. I have used it
1928 under Apache in Windows XP.
1929 </P>
1933 <P>
1934 This program is free software; you can redistribute it and/or
1935 modify it under the terms of the GNU General Public License
1936 as published by the Free Software Foundation; either version 2
1937 of the License, or (at your option) any later version.
1938 </P>
1940 <P>
1941 This program is distributed in the hope that it will be useful,
1942 but WITHOUT ANY WARRANTY; without even the implied warranty of
1943 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
1944 GNU General Public License for more details.
1945 </P>
1947 <P>
1948 You should have received a copy of the GNU General Public License
1949 along with this program; if not, write to the Free Software
1952 </P>
1954 <PRE>
1955 Author: Rob van Son
1956 email:
1957 R.J.J.H.vanSon@uva.nl
1958 University of Amsterdam
1961 Ver: 2.0
1962 Env: Perl 5.002
1963 </PRE>
1964 </BODY>
1966 </HTML>