| blob | 3ceb21f3e1646fb2c69ff12f64705e586f5c7b52 |
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 CGI or Cookie value 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 variable value.
511 The following is an example of a SESSION ticket:
512 <pre>
513 Type: SESSION
514 IPaddress: 127.0.0.1
515 AllowedPaths: ^/Private/Name/
516 DeniedPaths: ^/Private/CreateUser\.
517 Expires: +3600
518 Username: test
519 ...
520 </pre>
521 Other content can follow. <br />
522 <br />
523 It is adviced that Session Tickets should expire and be deleted
524 after some (idle) time. The IP address should be the IP number at login, and
525 the ticket will be rejected if it is presented from another IP address.
526 AllowedPaths and DeniedPaths are perl regexps. Be careful how they match. Make sure to delimit
529 time the ticket will remain valid after creation (file ctime). Time can be given
531 Only the <em>Type:</em> field needs be present.<br />
532 <br />
533 Next to Session Tickets, there are four other type of ticket files:<br />
534 - LOGIN tickets store information about a current login request<br />
535 - PASSWORD tickets store account information to authorize login requests<br />
536 - IPADDRESS tickets for IP address-only checks<br />
537 - CHALLENGE tickets for challenge tasks for every request<br />
538 </p>
539 <P>
540 <dt>8 Query length limiting
541 <dd>The length of the Query string can be limited. If CONTENT_LENGTH is larger
542 than this limit, the request is rejected. The combined length of the
543 Query string and the POST input is checked before any processing is done.
544 This will prevent clients from overloading the scripts.
545 The actual, combined, Query Size is accessible as a variable through
546 $CGI_Content_Length.
547 </P>
549 <P>
550 <dt>9 Illegal filenames, paths, and protected directories
551 <dd>One of the primary security concerns in handling CGI-scripts is the
553 malicious commands. Examples are inserting ';', null bytes, or <newline> characters
554 in URL's and filenames, followed by executable commands. A special
555 variable $FileAllowedChars stores a string of all allowed characters.
556 Any request that translates to a filename with a character OUTSIDE
557 this set will be rejected.<br>
558 In general, all (readable files) in the ServerRoot tree are accessible.
559 This might not be what you want. For instance, your ServerRoot directory
560 might be the working directory of a CVS project and contain sensitive
561 information (e.g., the password to get to the repository). You can block
562 access to these subdirectories by adding the corresponding patterns to
563 the $BlockPathAccess variable. For instance, $BlockPathAccess = '/CVS/'
564 will block any request that contains '/CVS/' or:<br>
565 <pre>
566 die if $BlockPathAccess && $ENV{'PATH_INFO'} =~ m@$BlockPathAccess@;
567 </pre>
568 </P>
570 <P>
571 <dt>10 The execution of code blocks can be controlled in a transparent way
572 by adding IF or UNLESS conditions in the tags themselves.
573 <dd>That is, a simple check of the validity of filenames or email
574 addresses can be done before any code is executed.
575 </p>
577 </dl>
579 <hr>
583 <UL>
604 </UL>
608 <P>
609 CGIscriptor removes embedded scripts, indicated by an HTML 4 type
610 <SCRIPT TYPE='text/ssperl'> </SCRIPT> or <SCRIPT TYPE='text/osshell'>
611 </SCRIPT> constructs. The contents of the directive are executed by
612 the PERL eval() and `` functions (in a separate name space). The
613 result of the eval() function replaces the <SCRIPT> </SCRIPT> construct
614 in the output file. You can use the values that are delivered in
617 defined in a <META> or <SCRIPT> tag.
619 subsequent <SCRIPT> and <META> results (including the defining
620 tag) will also be pushed onto a stack: @CGIscriptorResults. This list
621 behaves like any other, ordinary list and can be manipulated.
622 </P>
624 <P>
625 Both GET and POST requests are accepted. These two methods are treated
626 equal. Variables, i.e., those values that are determined when a file is
627 processed, are indicated in the CGI attribute by $<name> or
628 $<name>=<default> in which <name> is the name of the
629 variable and <default> is the value used when there is NO current CGI
630 value for <name> (you can use white-spaces in
631 $<name>=<default> but really DO make sure that the default
632 value is followed by white space or is quoted). Names can contain any
633 alphanumeric characters and _ (i.e., names match /[\w]+/).<br>
634 If the <i>Content-type:</i> is 'multipart/*', the input is treated as a
635 MIME multipart message and automatically delimited. CGI variables get the
637 </P>
639 <P>
640 Variables can be CGI variables, i.e., those from the QUERY_STRING,
641 environment variables, e.g., REMOTE_USER, REMOTE_HOST, or REMOTE_ADDR,
642 or predefined values, e.g., CGI_Decoded_QS (The complete, decoded,
643 query string), CGI_Content_Length (the length of the decoded query
644 string), CGI_Year, CGI_Month, CGI_Time, and CGI_Hour (the current
645 date and time).
646 </P>
648 <P>
649 All these are available when defined in a CGI attribute. All environment
650 variables are accessible as $ENV{'name'}. So, to access the REMOTE_HOST
651 and the REMOTE_USER, use, e.g.:
652 </P>
654 <PRE>
655 <SCRIPT TYPE='text/ssperl'>
657 </SCRIPT>
658 </PRE>
660 <P>
662 Another way to do this is:
663 </P>
665 <PRE>
668 </PRE>
670 or
672 <PRE>
675 </PRE>
677 <P>
678 This is possible because ALL environment variables are available as
679 CGI variables. The environment variables take precedence over CGI
681 </P>
683 <PRE>
685 </PRE>
687 <P>
688 Will print the current HOME directory (environment) irrespective whether
689 there is a CGI variable from the query
691 THIS IS A SECURITY FEATURE. It prevents clients from changing
692 the values of defined environment variables (e.g., by supplying
693 a bogus $REMOTE_ADDR). Although $ENV{} is not changed by the META tags,
694 it would make the use of declared variables insecure. You can still
695 access CGI variables after a name clash with
696 CGIscriptor::CGIparseValue(<name>).
697 </P>
699 <P>
700 Some CGI variables are present several times in the query string
701 (e.g., from multiple selections). These should be defined as
702 @VARIABLENAME=default in the CGI attribute. The list @VARIABLENAME
703 will contain ALL VARIABLENAME values from the query, or a single
704 default value. If there is an ENVIRONMENT variable of the
705 same name, it will be used instead of the default AND the query
706 values. The corresponding function is
707 CGIscriptor::CGIparseValueList(<name>)
708 </P>
710 <P>
711 CGI variables collected in a @VARIABLENAME list are unordered.
712 When more structured variables are needed, a hash table can be used.
713 A variable defined as %VARIABLE=default will collect all
714 CGI-parameter values whose name start with 'VARIABLE' in a hash table
715 with the remainder of the name as a key. For instance, %PERSON will
716 collect PERSONname='John Doe', PERSONbirthdate='01 Jan 00', and
717 PERSONspouse='Alice' into a hash table %PERSON such that
718 $PERSON{'spouse'} equals 'Alice'. Any default value or environment
720 variable of the same name, it will be used instead of the default
721 AND the query values. The corresponding function is
722 CGIscriptor::CGIparseValueHash(<name>)
723 </P>
725 <P>
726 This method of first declaring your environment and CGI variables
727 before being able to use them in the scripts might seem somewhat
728 clumsy, but it protects you from inadvertedly printing out the values of
729 system environment variables when their names coincide with those used
731 values for your private variables.
732 THIS IS A SECURITY FEATURE!
733 </P>
737 <P>
739 message before anything is printed. This has been extended to include
740 plain text (.txt) files, for which the Content-type (MIME type)
741 'text/plain' is printed. In all other respects, text files are treated as
742 HTML files (this can be switched off by removing '.txt' from the
743 $FilePattern variable). When the content type should be something else,
744 e.g., with multipart files, use the $RawFilePattern (.xmr, see also next
745 item). CGIscriptor will not print a Content-type message for this file type
746 (which must supply its OWN Content-type message). Raw files must still
747 conform to the <SCRIPT></SCRIPT> and <META> tag
748 specifications.
749 </P>
753 <P>
754 CGIscriptor is intended to process HTML and text files only. You can
756 with the .xmr extension. However, CGIscriptor will not process binary files
757 of any type, e.g., pictures or sounds. Given the sheer number of formats, I
758 do not have any intention to do so. However, an escape route has been
759 provided. You can construct a genuine raw (.xmr) text file that contains
760 the perl code to service any file type you want. If the global
761 $BinaryMapFile variable contains the path to this file (e.g.,
762 /BinaryMapFile.xmr), this file will be called whenever an unsupported
763 (non-HTML) file type is requested. The path to the requested binary file
764 is stored in $ENV('CGI_BINARY_FILE') and can be used like any other
765 CGI-variable. Servicing binary files then becomes supplying the correct
767 file and writing it to STDOUT (e.g., using sysread() and syswrite()).
768 </P>
772 <P>
773 All attributes of a META tag are ignored, except the
775 inside the quotes following the CONTENT= indication (white-space is
776 ignored, "'` (){}[]-quotes are allowed, plus their \ versions) MUST
777 start with any of the CGIscriptor mime-types (e.g.: text/ssperl or
778 text/osshell) and a comma or semicolon.
779 The quoted string following CGI= contains a white-space separated list
780 of declarations of the CGI (and Environment) values and default values
781 used when no CGI values are supplied by the query string.
782 </P>
784 <P>
785 If the default value is a longer string containing special characters,
786 possibly spanning several lines, the string must be enclosed in quotes.
787 You may use any pair of quotes or brackets from the list '', "", ``, (),
788 [], or {} to distinguish default values (or preceded by \, e.g., \(...\)
789 is different from (...)). The outermost pair will always be used and any
790 other quotes inside the string are considered to be part of the string
791 value, e.g.,
792 </P>
794 <PRE>
795 $Value = {['this'
796 "and" (this)]}
797 </PRE>
799 <P>
800 will result in $Value getting the default value
801 </P>
803 <PRE>
804 ['this'
805 "and" (this)]
806 </PRE>
808 <P>
809 (NOTE that the newline is part of the default value!).
810 </P>
812 <P>
813 Internally, for defining and initializing CGI (ENV) values, the META
814 and SCRIPT tags use the function "defineCGIvariable($name, $default)"
815 (scalars) and "defineCGIvariableList($name, $default)" (lists).
816 These functions can be used inside scripts as
817 "CGIscriptor::defineCGIvariable($name, $default)" and
818 "CGIscriptor::defineCGIvariableList($name, $default)".
819 </P>
821 <P>
822 The CGI attribute will be processed exactly identical when used inside
824 HTML 4.0 specifications of the W3C.
825 </P>
829 <P>
830 There is a problem when constructing html files containing
831 server-side perl scripts with standard HTML tools. These
832 tools will refuse to process any text between
834 tags. This is quite annoying when you want to use large
835 HTML templates where you will fill in values.
836 </P>
838 <P>
839 For this purpose, CGIscriptor will read the neutral
842 tag (in Cascading Style Sheet manner) Note that "varname" has
843 NO '$' before it, it is a bare name. Any text between
846 to '$varname' as is (e.g., as a literal). No
847 processing or interpolation will be performed.
848 There is also NO nesting possible. Do NOT nest
850 Moreover, DIV tags do NOT ensure a block structure in
851 the final rendering (i.e., no empty lines).
852 </P>
854 <P>
856 is handled the XML way. No content is processed,
857 but varname is defined, and any SRC directives are
858 processed.
859 </P>
861 <P>
862 You can use $varname like any other variable name.
863 However, $varname is NOT a CGI variable and will be
864 completely internal to your script. There is NO
865 interaction between $varname and the outside world.
866 </P>
868 <P>
869 To interpolate a DIV derived text, you can use:
870 <pre>
871 $varname =~ s/([\]])/\\\1/g; # Mark ']'-quotes
872 $varname = eval("qq[$varname]"); # Interpolate all values
873 </pre>
874 </P>
876 <p>
877 The DIV tag will process IF, UNLESS, CGI and SRC attributes.
878 The SRC files will be pre-pended to the body
879 text of the tag.
880 </p>
883 CONDITIONAL PROCESSING: THE 'IF' AND 'UNLESS' ATTRIBUTES
884 </H2></A>
886 <p>
887 It is often necessary to include code-blocks that should be executed
888 conditionally, e.g., only for certain browsers or operating system.
889 Furthermore, quite often sanity and security checks are necessary
890 before user (form) data can be processed, e.g., with respect to
891 email addresses and filenames.
892 </p>
894 <p>
895 Checks added to the code are often difficult to find, interpret or
896 maintain and in general mess up the code flow. This kind of confussion
897 is dangerous. Also, for many of the supported "foreign" scripting
898 languages, adding these checks is cumbersome or even impossible.
899 </p>
901 <p>
902 As a uniform method for asserting the correctness of "context", two
903 attributes are added to all supported tags: IF and UNLESS.
904 They both evaluate their value and block execution when the
907 the backslash in the '\>' is removed and only used to differentiate
909 backslash in '\<' is also removed. Inside these conditionals,
910 ~/ and ./ are expanded to their respective directory root paths.
911 </p>
913 <p>
914 For example, the following tag will be ignored when the filename is
915 invalid:
916 </p>
918 <pre>
919 <SCRIPT TYPE='text/ssperl' CGI='$FILENAME'
920 IF='CGIscriptor::CGIsafeFileName($FILENAME);'>
921 ...
923 </pre>
925 <p>
926 The IF and UNLESS values must be quoted. The same quotes are supported
927 as with the other attributes. The SRC attribute is ignored when IF and
928 UNLESS block execution.
929 </p>
932 THE MAGIC SOURCE ATTRIBUTE (SRC=)</H2></A>
934 <P>
935 The SRC attribute inside tags accepts a list of filenames and URL's
937 </P>
939 <P>
940 ALL the variable values defined in the CGI attribute are available in
941 @ARGV as if the file was executed from the command line, in
942 the exact order in which they were declared in the preceding CGI
943 attribute.
944 </P>
946 <P>
947 First, a SRC={}-block will be evaluated as if the code inside the
949 "print do { code };'';" or `code` (i.e., SAFEqx('code)).
950 Only a single block is evaluated. Note that this is processed less
952 depends on the content-type: Perl for text/ssperl and OS shell for
953 text/osshell. For other mime types (scripting languages), anything in
954 the source block is put in front of the code block "inside" the tag.
955 </P>
957 <P>
958 Second, executable files (i.e., -x filename != 0) are evaluated as:
960 That is, you can actually call executables savely from the SRC tag.
961 </P>
963 <P>
964 Third, text files that match the file pattern, used by CGIscriptor to
965 check whether files should be processed ($FilePattern), are
966 processed in-line (i.e., recursively) by CGIscriptor as if the code
967 was inserted in the original source file. Recursions, i.e., calling
968 a file inside itself, are blocked. If you need them, you have to code
969 them explicitely using "main::ProcessFile($file_path)".
970 </P>
972 <P>
973 Fourth, Perl text files (i.e., -T filename != 0) are evaluated as:
974 "do FileName;'';".
975 </P>
977 <P>
978 Last, URL's (i.e., starting with 'HTTP://', 'FTP://', 'GOPHER://', 'TELNET://',
980 and document header is done by main::GET_URL($URL [, 0]). You can enter your own
983 </P>
985 <P>
986 There are two pseudo-file names: PREFIX and POSTFIX. These implement
987 a switch from prefixing the SRC code/files (PREFIX, default) before the content of
988 the tag to appending the code after the content of the tag (POSTFIX). The switches
989 are done in the order in which the PREFIX and POSTFIX labels are encountered.
990 You can mix PREFIX and POSTFIX labels in any order with the SRC files.
991 Note that the ORDER of file execution is determined for prefixed and
992 postfixed files seperately.
993 <P>
995 <P>
996 File paths can be preceded by the URL protocol prefix "file://". This
997 is simply STRIPPED from the name.
998 </P>
1000 <P>
1001 Example:
1002 </P>
1004 <P>
1005 The request
1006 "http://cgi-bin/Action_Forms.pl/Statistics/Sign_Test.html?positive=8&negative=22
1009 </P>
1011 <P>
1012 on encountering the lines:
1013 </P>
1015 <PRE>
1018 </SCRIPT></b><p>"
1019 </PRE>
1021 This line will be processed as:
1023 <PRE>
1024 "<b>`${SS_SCRIPT}/Statistics/SignTest.pl '8' '22'`</b><p>"
1025 </PRE>
1027 <P>
1028 In which "${SS_SCRIPT}/Statistics/SignTest.pl" is an executable script,
1029 This line will end up printed as:
1030 </P>
1032 <PRE>
1033 "<b>p <= 0.0161</b><p>"
1034 </PRE>
1036 <P>
1037 Note that the META tag itself will never be printed, and is invisible to
1038 the outside world.
1039 </P>
1041 <P>
1042 The SRC files in a DIV/INS tag will be added (pre-pended) to the body
1044 </P>
1048 <P>
1051 public directories can be accessed without direct reference to the
1052 actual paths. Filepaths starting with "./" are replaced by
1053 "$YOUR_SCRIPTS/" and this should only be used for scripts.
1054 The "$YOUR_SCRIPTS" directory is added to @INC so, e.g., the
1055 'require' command will load from the "$YOUR_SCRIPTS" directory.
1056 </P>
1058 <P>
1060 out for constructs like $a =~ s/aap\./noot./g, use
1061 $a =~ s@aap\.@noot.@g instead.
1062 </P>
1064 <P>
1065 CGIscriptor.pl will assign the values of $SS_PUB and $SS_SCRIPT
1066 (i.e., $YOUR_HTML_FILES and $YOUR_SCRIPTS) to the environment variables
1067 $SS_PUB and $SS_SCRIPT. These can be accessed by the scripts that are
1068 executed. The "$SS_SCRIPT" ($YOUR_SCRIPTS) directory is added to
1069 @INC so, e.g., the 'require' command will load from the "$SS_SCRIPT"
1070 directory.<br>
1071 Values not preceded by $, ~/, or ./ are used as literals
1072 </P>
1074 <A NAME="OSSHELL"><H2 ALIGN="CENTER">OS SHELL SCRIPT EVALUATION (CONTENT-TYPE=TEXT/OSSHELL)</H2></A>
1076 <P>
1077 OS scripts are executed by a "safe" version of the `` operator (i.e.,
1078 SAFEqx(), see also below) and any output is printed. CGIscriptor will
1079 interpolate the script and replace all user-supplied CGI-variables by
1080 their ''-quoted values (actually, all variables defined in CGI attributes are
1081 quoted). Other Perl variables are interpolated in a simple fasion, i.e.,
1082 $scalar by their value, @list by join(' ', @list), and %hash by their
1083 name=value pairs. Complex references, e.g., @$variable, are all
1084 evaluated in a scalar context. Quotes should be used with care.
1085 NOTE: the results of the shell script evaluation will appear in the
1086 @CGIscriptorResults stack just as any other result.
1087 </P>
1089 <P>
1090 All occurrences of $@% that should NOT be interpolated must be
1091 preceeded by a "\". Interpolation can be switched off completely by
1092 setting $CGIscriptor::NoShellScriptInterpolation = 1
1093 (set to 0 or undef to switch interpolation on again)
1094 i.e.,
1095 </P>
1097 <PRE>
1099 $CGIscriptor::NoShellScriptInterpolation = 1;
1101 </PRE>
1106 <p>
1107 Allows general and global conversions of files using Regular Expressions.
1108 Very handy (but costly) to rewrite legacy pages to a new format.
1109 Select files to use it on with <br>
1110 my $TranslationPaths = 'filepattern';<br>
1111 This is costly. For efficiency, define:<br>
1112 $TranslationPaths = ''; when not using translations.<br>
1113 Accepts general regular expressions: [$pattern, $replacement]
1114 </p>
1116 <p>
1117 Define:</p>
1118 <pre>
1119 my $TranslationPaths = 'filepattern'; # Pattern matching PATH_INFO
1121 push(@TranslationTable, ['pattern', 'replacement']);
1122 # e.g. (for Ruby Rails):
1126 # Runs:
1127 my $currentRegExp;
1128 foreach $currentRegExp (@TranslationTable)
1129 {
1130 my ($pattern, $replacement) = @$currentRegExp;
1131 $$text =~ s!$pattern!$replacement!msg;
1132 };
1133 </pre>
1137 </A>
1139 <P>
1140 Adding a MIME-type and an interpreter command to
1141 %ScriptingLanguages automatically will catch any other
1142 scripting language in the standard
1144 E.g., adding: $ScriptingLanguages{'text/sspython'} = 'python';
1145 will actually execute the folowing code in an HTML page
1146 (ignore 'REMOTE_HOST' for the moment):
1147 </P>
1149 <PRE>
1151 # A Python script
1155 </PRE>
1157 <P>
1158 The script code is NOT interpolated by perl, EXCEPT for those
1159 interpreters that cannot handle variables themselves.
1160 Currently, several interpreters are pre-installed:
1161 </P>
1163 <PRE>
1170 # "| egrep -v '> |^rep. |^nil\\\$'",
1180 "rebol --quiet|egrep -v '^[> ]* == '|sed 's/^\s*\[> \]* //g'",
1182 (psql)
1183 </PRE>
1185 <P>
1186 Note that the "value" of $ScriptingLanguages{mime} must be a command
1187 that reads Standard Input and writes to standard output. Any extra
1188 output of interactive interpreters (banners, echo's, prompts)
1189 should be removed by piping the output through 'tail', 'grep',
1190 'sed', or even 'awk' or 'perl'.
1191 </P>
1193 <P>
1194 For access to CGI variables there is a special hashtable:
1195 %ScriptingCGIvariables.
1196 CGI variables can be accessed in three ways.
1197 <dl>
1199 nothing is done and the script itself should parse the relevant
1200 environment variables.
1202 value is empty, e.g., $ScriptingCGIvariables{"text/sspraat"} = '';,
1203 the script text is interpolated by perl. That is, all $var, @array,
1204 %hash, and \-slashes are replaced by their respective values.
1206 in front of the script according to the format stored in
1207 %ScriptingCGIvariables. That is, the following (pseudo-)code is
1208 executed for each CGI- or Environment variable defined in the CGI-tag:
1209 printf(INTERPRETER, $ScriptingCGIvariables{$mime}, $CGI_NAME, $CGI_VALUE);
1210 </dl>
1211 </P>
1213 <P>
1216 (note that these definitions are not save, the real ones contain '-quotes).
1217 </P>
1219 <P>
1220 THIS WILL NOT WORK FOR @VARIABLES, the (empty) $VARIABLES will be used
1221 instead.
1222 </P>
1224 <P>
1225 The $CGI_VALUE parameters are "shrubed" of all control characters
1226 and quotes (by &shrubCGIparameter($CGI_VALUE)). Control characters
1230 if a client would supply the string value (in standard perl)
1231 </P>
1233 <P>
1235 it would be processed as
1237 (e.g., sh or bash would process the latter more according to your
1238 intentions).<br>
1239 If your intepreter requires different protection measures, you will
1240 have to supply these in %main::SHRUBcharacterTR (string => translation),
1241 e.g.,
1243 <PRE>
1245 </PRE>
1246 </P>
1248 <P>
1249 Currently, the following definitions are used:
1250 </P>
1252 <PRE>
1253 %ScriptingCGIvariables = (
1271 );
1272 </PRE>
1274 <P>
1275 Four tables allow fine-tuning of interpreter with code that should be
1276 added before and after each code block:
1277 </P>
1279 <P>
1280 Code added before each script block
1281 </P>
1283 <PRE>
1284 %ScriptingPrefix = (
1287 );
1288 </PRE>
1290 <P>
1291 Code added at the end of each script block
1292 </P>
1294 <PRE>
1295 %ScriptingPostfix = (
1298 );
1299 </PRE>
1301 <P>
1302 Initialization code, inserted directly after opening (NEVER interpolated)
1303 </P>
1305 <PRE>
1306 %ScriptingInitialization = (
1311 );
1312 </PRE>
1314 <P>
1315 Cleanup code, inserted before closing (NEVER interpolated)
1316 </P>
1318 <PRE>
1319 %ScriptingCleanup = (
1325 );
1326 </PRE>
1328 <P>
1329 The SRC attribute is NOT magical for these interpreters. In short,
1330 all code inside a source file or {} block is written verbattim
1331 to the interpreter. No (pre-)processing or executional magic is done.
1332 </P>
1334 <P>
1335 A serious shortcomming of the described mechanism for handling other
1336 (scripting) languages, with respect to standard perl scripts
1337 (i.e., 'text/ssperl'), is that the code is only executed when
1338 the pipe to the interpreter is closed. So the pipe has to be
1339 closed at the end of each block. This means that the state of the
1340 interpreter (e.g., all variable values) is lost after the closing of
1342 all values and definitions.
1343 </P>
1348 <P>
1349 To ease some important auxilliary functions from within the
1350 html pages I have added them as MIME types. This uses
1351 the mechanism that is also used for the evaluation of
1352 other scripting languages, with interpolation of CGI
1353 parameters (and perl-variables). Actually, these are
1354 defined exactly like any other "scripting language".
1355 </P>
1357 <dl>
1358 <dt>text/ssdisplay:
1359 <dd>display some (HTML) text with interpolated
1360 variables (uses `cat`).
1361 <dt>text/sslogfile:
1362 <dd>write (append) the interpolated block to the file
1363 mentioned on the first, non-empty line
1364 (the filename can be preceded by 'File: ',
1365 note the space after the ':',
1367 <dt>text/ssmailto:
1368 <dd>send email directly from within the script block.
1369 The first line of the body must contain
1370 To:Name@Valid.Email.Address
1371 (note: NO space between 'To:' and the email adres)
1372 For other options see the mailto man pages.
1373 It works by directly sending the (interpolated)
1374 content of the text block to a pipe into the
1375 Linux program 'mailto'.
1376 </dl>
1378 <P>
1379 In these script blocks, all Perl variables will be
1380 replaced by their values. All CGI variables are cleaned before
1381 they are used. These CGI variables must be redefined with a
1382 CGI attribute to restore their original values.
1383 In general, this will be more secure than constructing
1384 e.g., your own email command lines. For instance, Mailto will
1385 not execute any odd (forged) email address, but just stops
1386 when the email address is invalid and awk will construct
1388 as a "valid" UNIX filename). Note that it will also gladly
1389 store this file anywhere (/../../../etc/passwd will work!).
1390 Use the CGIscriptor::CGIsafeFileName() function to clean the
1391 filename.
1392 </P>
1396 <P>
1397 If a shell script starts with the UNIX style "#! <shell command> \n"
1398 line, the rest of the shell script is piped into the indicated command,
1399 i.e.,
1400 open(COMMAND, "| command");print COMMAND $RestOfScript;
1401 </P>
1403 <P>
1404 In many ways this is equivalent to the MIME-type profiling for
1405 evaluating other scripting languages as discussed above. The
1406 difference breaks down to convenience. Shell script piping is a
1407 "raw" implementation. It allows you to control all aspects of
1408 execution. Using the MIME-type profiling is easier, but has a
1409 lot of defaults built in that might get in the way. Another
1410 difference is that shell script piping uses the SAFEqx() function,
1411 and MIME-type profiling does not.
1412 </P>
1414 <P>
1415 Execution of shell scripts is under the control of the Perl Script blocks
1416 in the document. The MIME-type triggered execution of <SCRIPT></SCRIPT>
1417 blocks can be simulated easily. You can switch to a different shell, e.g. tcl,
1418 completely by executing the following Perl commands inside your document:
1419 </P>
1421 <PRE>
1423 $main::ShellScriptContentType = "text/ssTcl"; # Yes, you can do this
1424 CGIscriptor::RedirectShellScript('/usr/bin/tcl'); # Pipe to Tcl
1425 $CGIscriptor::NoShellScriptInterpolation = 1;
1427 </PRE>
1429 <P>
1430 After this script is executed, CGIscriptor will parse scripts of
1432 WITHOUT interpolation (i.e., NO substitution of Perl variables).
1433 The crucial function is :
1434 </P>
1436 <PRE>
1437 CGIscriptor::RedirectShellScript('/usr/bin/tcl')
1438 </PRE>
1440 <P>
1441 After executing this function, all shell scripts AND all
1442 calls to SAFEqx()) are piped into '|/usr/bin/tcl'. If the argument
1443 of RedirectShellScript is empty, e.g., '', the original (default)
1444 value is reset.
1445 </P>
1447 <P>
1448 The standard output, STDOUT, of any pipe is send to the client.
1449 Currently, you should be carefull with quotes in such a piped script.
1450 The results of a pipe is NOT put on the @CGIscriptorResults stack.
1451 As a result, you do not have access to the output of any piped (#!)
1452 process! If you want such access, execute
1453 </P>
1455 <PRE>
1457 </PRE>
1459 <P>
1460 or
1461 </P>
1463 <PRE>
1465 $resultvar = SAFEqx('echo "script"|command');
1467 </PRE>
1469 <P>
1470 Safety is never complete. Although SAFEqx() prevents some of the
1471 most obvious forms of attacks and security slips, it cannot prevent
1472 them all. Especially, complex combinations of quotes and intricate
1473 variable references cannot be handled safely by SAFEqx. So be on
1474 guard.
1475 </P>
1479 <P>
1480 All PERL scripts are evaluated inside a PERL package. This package
1481 has a separate name space. This isolated name space protects the
1482 CGIscriptor.pl program against interference from user code. However,
1483 some variables, e.g., $_, are global and cannot be protected. You are
1484 advised NOT to use such global variable names. You CAN write
1485 directives that directly access the variables in the main program.
1486 You do so at your own risk (there is definitely enough rope available
1487 to hang yourself). The behavior of CGIscriptor becomes undefined if
1488 you change its private variables during run time. The PERL code
1489 directives are used as in:
1490 </P>
1492 <PRE>
1493 $Result = eval($directive); print $Result;'';
1494 </PRE>
1496 <P>
1499 the result is treated as a scalar. To prevent the VALUE of the code
1500 block from appearing on the client's screen, end the directive with
1502 eval(), blocks, and subroutines, but only as a scalar.
1503 </P>
1505 <P>
1508 (e.g., for "my $var;" declarations). This means that values assigned
1509 to a PERL variable can be used throughout the document unless they
1510 were declared with "my". The following will actually work as intended
1511 (note that the ``-quotes in this example are NOT evaluated, but used
1512 as simple quotes):
1513 </P>
1515 <PRE>
1517 anything ...
1519 anything ...
1521 </PRE>
1523 <P>
1526 construct will print the elements of $String separated by commas, leaving
1527 out the first element, i.e., $List[0].
1528 </P>
1530 <p>
1531 Another warning: './' and '~/' are ALWAYS replaced by the values of
1532 $YOUR_SCRIPTS and $YOUR_HTML_FILES, respectively . This can interfere
1533 with pattern matching, e.g., $a =~ s/aap\./noot\./g will result in the
1534 evaluations of $a =~ s/aap\\${YOUR_SCRIPTS}noot\./g. Use
1536 </p>
1538 <A NAME="SESSIONTICKETS"><H2 ALIGN="CENTER">SERVER SIDE SESSIONS AND ACCESS CONTROL (LOGIN)</H2></A>
1539 <p>
1540 An infrastructure for user acount authorization and file access control
1541 is available. Each request is matched against a list of URL path patterns.
1542 If the request matches, a Session Ticket is required to access the URL.
1543 This Session Ticket should be present as a CGI parameter or Cookie, eg:
1544 </p>
1545 <p>
1548 <p>
1549 The example implementation stores Session Tickets as files in a local
1550 directory. To create Session Tickets, a Login request must be given
1552 password. The user name and (singly hashed) password are stored in a
1553 PASSWORD ticket with the same name as the user account (name cleaned up
1554 for security).
1555 </p>
1556 <p>
1557 The example session model implements 4 functions:
1558 <ol>
1560 The password is hashed with the user name and server side salt, and then
1561 hashed with a random salt. Client and Server both perform these actions
1562 and the Server only grants access if restults are the same. The server
1563 side only stores the password hashed with the user name and
1564 server side salt. Neither the plain password, nor the hashed password is
1565 ever exchanged. Only values hashed with the one-time salt are exchanged.
1566 </li>
1568 For every access to a restricted URL, the Session Ticket is checked before
1569 access is granted. There are three session modes. The first uses a fixed
1570 Session Ticket that is stored as a cookie value in the browser (actually,
1571 as a sessionStorage value). The second uses only the IP address at login
1572 to authenticate requests. The third
1573 is a Challenge mode, where the client has to calculate the value of the
1574 next one-time Session Ticket from a value derived from the password and
1575 a random string.
1576 </li>
1578 A new password is hashed with the user name and server side salt, and
1579 then encrypted (XORed)
1580 with the old password hashed with the user name and salt and rehashed with
1581 the login ticket number. Ath the server side this operation is reversed.
1582 Again, the stored password value is never exchanged unencrypted.
1583 </li>
1585 The text of a new account (Type: PASSWORD) file is constructed from
1588 The same process is used to encrypt
1589 the new password as is used for the Password Change function.
1590 Again, the stored password value is never exchanged unencrypted.
1591 Some default setting are encoded. For display in the browser, the new password
1592 is reencrypted (XORed) with a special key, the old password hash
1593 hashed with a session specific random hex value sent initially with the
1594 session login ticket ($RANDOMSALT).
1597 <pre>
1598 Type: PASSWORD
1599 Username: newuser
1600 Password: 84b26fd2aaacae1c2e42fe07da1793e8232ffe548eceb519b46646fe9ff32612
1601 Salt: 970e68017413fb0ea84d7fe3c463077636dd6d53486910d4a53c693dd4109b1a
1602 AllowedPaths: ^/Private/[\w\-]+\.html?
1603 AllowedPaths: ^/Private/newuser/
1604 Session: SESSION
1606 Time: 1339677280
1607 </pre>
1608 The password is created with the Unix commands:
1609 <pre>
1610 printf '%s' '970e68017413fb0ea84d7fe3c463077636dd6d53486910d4a53c693dd4109b1aNewPasswordnewuser'|shasum -a 256
1611 </pre>
1612 </li>
1613 </ol>
1614 </p>
1616 <p>
1617 The session authentication mechanism is based on the exchange of ticket
1618 identifiers. A ticket identifier is just a string of characters, a name
1619 or a random 64 character hexadecimal string. Ticket identifiers should be
1620 "safe" filenames (except user names). There are four types of tickets:
1621 <ul>
1624 <li>IPADDRESS: Authetication tokens that allow access based on the IP address of the request</li>
1627 </ul>
1628 All tickets can have an expiration date in the form of a time duration
1630 An absolute time can be given in seconds since the epoch of the server host.
1631 Note that expiration times of CHALLENGE authetication tokens are calculated
1632 from the last access time. Accounts can include a maximal lifetime
1633 for session tickets (MaxLifetime).
1634 </p>
1635 <p>
1636 A Login page should create a LOGIN ticket file locally and send a
1637 server specific salt, a Random salt, and a LOGIN ticket
1638 identifier. The server side compares the username and hashed password,
1639 actually hashed(Random salt+hashed(serversalt+password)) from the client with
1640 the values it calculates from the stored Random salt from the LOGIN
1641 ticket and the hashed(serversalt+password) from the PASSWORD ticket. If
1642 successful, a new SESSION ticket is generated as a hash sum of the LOGIN
1643 ticket and the stored password. This SESSION ticket should also be
1644 generated by the client and stored as sessionStorage and cookie values
1645 as needed. The Username, IP address and Path are available as
1646 $LoginUsername, $LoginIPaddress, and $LoginPath, respectively.
1647 </p>
1648 <p>
1649 The CHALLENGE protocol stores the same value as the SESSION tickets.
1650 However, this value is not exchanged, but kept secret in the JavaScript
1652 server will contain a one-time Challenge value ($CHALLENGETICKET) which
1653 has to be hashed with the stored value to return the current ticket
1654 id string.
1655 </p>
1656 <p>
1657 In the current example implementation, all random values are created as
1659 /dev/urandom.
1660 </p>
1663 <p>
1664 For strong security, please use end-to-end encryption. This can be
1665 achieved using a VPN (Virtual Private Network), SSH tunnel, or a HTTPS
1666 capable server with OpenSSL. The session ticket system of CGIscriptor.pl
1667 is intended to be used as a simple authentication mechanism WITHOUT
1668 END-TO-END ENCRYPTION. The authenticating mechanism tries to use some
1669 simple means to protect the authentication process from eavesdropping.
1670 For this it uses a secure hash function, SHA256. For all practial purposes,
1671 it is impossible to "decrypt" a SHA256 sum. But this login scheme is
1672 only as secure as your browser. Which, in general, is not very secure.
1673 </p>
1674 <p>
1675 Humans tend to reuse passwords. A compromise of a site running
1676 CGIscriptor.pl could therefore lead to a compromise of user accounts at
1677 other sites. Therefore, plain text passwords are never stored, used, or
1678 exchanged. Instead, a server site salt value is "encrypted" with
1679 the plain password and user name. Actually, all are concatenated and hashed
1680 with a one-way secure hash function (SHA256) into a single string.
1681 Whenever the word "password" is used, this hash sum is meant. Note that
1682 the salts are generated from /dev/urandom. You should check whether the
1683 implementation of /dev/urandom on your platform is secure before
1684 relying on it. This might be a problem when running CGIscriptor under
1685 Cygwin on MS Windows.<br />
1686 <em>Note: no attempt is made to slow down the password hash, so bad
1687 passwords can be cracked by brute force</em>
1688 </p>
1689 <p>
1690 As the (hashed) passwords are all that is needed to identify at the site,
1691 these should not be stored in this form. A site specific passphrase
1692 can be entered as an environment variable ($ENV{'CGIMasterKey'}). This
1693 phrase is hashed with the server site salt and the result is hashed with
1694 the user name and then XORed with the password when it is stored. Also, to
1695 detect changes to the account (PASSWORD) and session tickets, a
1696 (HMAC) hash of some of the contents of the ticket with the server salt and
1697 CGIMasterKey is stored in each ticket.
1698 </p>
1699 <p>
1700 Creating a valid (hashed) password, encrypt it with the CGIMasterKey and
1701 construct a signature of the ticket are non-trivial. This has to be redone
1702 with every change of the ticket file or CGIMasterKey change. CGIscriptor
1703 can do this from the command line with the command:
1704 <pre>
1705 perl CGIscriptor.pl --managelogin salt=Private/.Passwords/SALT \
1706 masterkey='Sherlock investigates oleander curry in Bath' \
1707 password='There is no password like more password' \
1708 admin
1709 </pre>
1710 CGIscriptor will exit after this command with the first option being
1712 <ul>
1714 stored in the ticket file. Will replace the stored value if a new
1715 password is given. If you change the server salt, you have to
1717 to recover plaintext passwords, except asking the account holders.
1718 You are strongly adviced to make a backup before you apply such a change</li>
1720 the ticket</li>
1722 and write the ticket. Defaults to the masterkey. If you change
1723 the masterkey, you will have to reset all the accounts. You are strongly
1724 adviced to make a backup before you apply such a change</li>
1726 </ul>
1727 When the value of an option is a existing file path, the first line of
1728 that file is used. Options are followed by one or more paths plus names
1729 of existing ticket files. Each password option is only used for a single
1730 ticket file. It is most definitely a bad idea to use a password that is
1731 identical to an existing filepath, as the file will be read instead. Be
1732 aware that the name of the file should be a cleaned up version of the
1733 Username.This will not be checked.
1734 </p>
1735 <p>
1736 For the authentication and a change of password, the (old) password
1737 is used to "encrypt" a random one-time token or the new password,
1738 respectively. For authentication, decryption is not needed, so a secure
1739 hash function (SHA256) is used to create a one-way hash sum "encryption".
1740 A new password must be decrypted. New passwords are encryped by XORing
1741 them with the old password.
1742 </p>
1746 <p >
1747 Your password might be vulnerable to
1750 costly in terms of code complexity, bugs, and execution time.
1751 However, there is a very simple and secure counter measure. See the
1754 be both much easier to remember, and still stronger than
1756 on the Internet.<br />
1757 For the procedures used at this site, a basic computer setup can check
1758 in the order of a billion passwords per second. You need a password (or
1759 phrase) strength in the order of 56 bits to be a little secure (one year
1760 on a single computer). One of the largest network in the world, Bitcoin
1763 It would take a passwords strength of ~68 bits to keep the equivalent of
1764 the Bitcoin computer network occupied for around a year before it found
1765 a match.<br />
1766 Please be so kind and add the name of your favorite flower, dish,
1767 fictional character, or small town to your password. Say,
1771 do not try this curry at home). That would be more effective than adding
1772 a thousand rounds of encryption.
1773 Typing long passwords without seeing what you are typing is problematic.
1774 So a button should be included to make password visible.
1775 </p>
1777 <p>
1778 Client side JavaScript code definitions. Variable names starting with '$'
1779 are CGIscriptor CGI variables. Some of the hashes could be strengthened
1780 by switching to HMAC signatures. However, the security issues of
1781 maintaining parallel functions for HMAC in both Perl and Javascript seem
1782 to be more serious than the attack vectors against the hashes. But HMAC
1783 is indeed used for the ticket signatures.
1784 </p>
1785 <pre>
1786 // On Login
1787 HashPlaintextPassword() {
1788 var plaintextpassword = document.getElementById('PASSWORD');
1789 var serversalt = document.getElementById('SERVERSALT');
1790 var username = document.getElementById('CGIUSERNAME');
1791 return hex_sha256(serversalt.value+plaintextpassword.value+username.value.toLowerCase());
1792 }
1793 var randomsalt = $RANDOMSALT; // From CGIscriptor
1794 var loginticket = $LOGINTICKET; // From CGIscriptor
1795 // Hash plaintext password
1796 var password = HashPlaintextPassword();
1797 // Authorize login
1798 var hashedpassword = hex_sha256(randomsalt+password);
1799 // Sessionticket
1800 var sessionticket = hex_sha256(loginticket+password);
1801 sessionStorage.setItem("CGIscriptorPRIVATE", sessionticket);
1802 // Secretkey for encrypting new passwords, acts like a one-time pad
1804 // and for each create new user request
1805 var secretkey = hex_sha256(randomsalt+loginticket+password);
1806 sessionStorage.setItem("CGIscriptorSECRET", secretkey);
1808 // For a SESSION type request
1809 sessionticket = sessionStorage.getItem("CGIscriptorPRIVATE");
1812 // For a CHALLENGE type request
1813 var sessionset = "$CHALLENGETICKET"; // From CGIscriptor
1814 var sessionkey = sessionStorage.getItem("CGIscriptorPRIVATE");
1815 sessionticket = hex_sha256(sessionset+sessionkey);
1818 // For transmitting a new password
1819 HashPlaintextNewPassword() {
1820 var plaintextpassword = document.getElementById('NEWPASSWORD');
1821 var serversalt = document.getElementById('SERVERSALT');
1822 var username = document.getElementById('NEWUSERNAME');
1823 return hex_sha256(serversalt.value+plaintextpassword.value+username.value.toLowerCase());
1824 }
1826 var newpassword = document.getElementById('NEWPASSWORD');
1827 var newpasswordrep = document.getElementById('NEWPASSWORDREP');
1828 // Hash plaintext password
1829 newpassword.value = HashPlaintextNewPassword();
1830 var secretkey = sessionStorage.getItem("CGIscriptorSECRET");
1832 var encrypted = XOR_hex_strings(secretkey, newpassword.value);
1833 newpassword.value = encrypted;
1834 newpasswordrep.value = encrypted;
1836 // XOR of hexadecimal strings of equal length
1837 function XOR_hex_strings(hex1, hex2) {
1838 var resultHex = "";
1839 var maxlength = Math.max(hex1.length, hex2.length);
1842 var h1 = hex1.charAt(i);
1843 if(! h1) h1='0';
1844 var h2 = hex2.charAt(i);
1845 if(! h2) h2 ='0';
1846 var d1 = parseInt(h1,16);
1847 var d2 = parseInt(h2,16);
1848 var resultD = d1^d2;
1849 resultHex = resultHex+resultD.toString(16);
1850 };
1851 return resultHex;
1852 };
1855 </pre>
1859 <P>
1860 A CGIscriptor package is attached to the bottom of this file. With
1861 this package you can personalize your version of CGIscriptor by
1862 including often used perl routines. These subroutines can be
1863 accessed by prefixing their names with CGIscriptor::, e.g.,
1864 </P>
1866 <PRE>
1868 CGIscriptor::ListDocs("/Books/*") # List all documents in /Books
1870 </PRE>
1872 <P>
1873 It already contains some useful subroutines for Document Management.
1874 As it is a separate package, it has its own namespace, isolated from
1875 both the evaluator and the main program. To access variables from
1877 </P>
1879 <P>
1880 Currently, the following functions are implemented
1881 (precede them with CGIscriptor::, see below for more information)
1882 </P>
1884 <UL>
1886 Is used by text/osshell Shell scripts. Protects all CGI
1887 (client-supplied) values with single quotes before executing the
1888 commands (one of the few functions that also works WITHOUT CGIscriptor::
1889 in front)
1891 failure/success)<br>
1892 Is used by the META tag to define and initialize CGI and ENV
1893 name/value pairs. Tries to obtain an initializing value from (in
1894 order):<br>
1895 $ENV{$name}<br>
1896 The Query string<br>
1897 The default value given (if any)<br>
1898 (one of the few functions that also works WITHOUT CGIscriptor::
1899 in front)
1901 Check a string against the Allowed File Characters (and ../ /..).
1902 Returns an empty string for unsafe filenames.
1904 Check a string against correct email address pattern.
1905 Returns an empty string for unsafe addresses.
1907 Open a named PIPE for SAFEqx to receive ALL shell scripts
1911 Extract the value of a CGI variable from the global or a private
1912 URL-encoded query (multipart POST raw, NOT decoded)
1913 <li>CGIparseValueList (ValueName [, URL_encoded_QueryString])
1915 As CGIparseValue, but now assembles ALL values of ValueName into a list.
1917 Extract the header of a multipart CGI variable from the global or a private
1918 URL-encoded query ("" when not a multipart variable or absent)
1920 Decode the complete global URL-encoded query or a private
1921 URL-encoded query
1923 Returns the page from URL (with added base tag, both FTP and HTTP)
1924 Uses main::GET_URL(URL, 1) to get at the command to read the URL.
1925 <LI>BrowseDirs(RootDirectory [, Pattern, Startdir, CGIname]) # print browsable directories
1926 <LI>ListDocs(Pattern [,ListType]) # Prints a nested HTML directory listing of
1928 <LI>HTMLdocTree(Pattern [,ListType]) # Prints a nested HTML listing of all
1929 local links starting from a given document, e.g.,
1931 </UL>
1935 <P>
1936 If the pseudo-variable "$CGIscriptorResults" has been defined in a
1937 META tag, all subsequent SCRIPT and META results are pushed
1938 on the @CGIscriptorResults stack. This list is just another
1939 Perl variable and can be used and manipulated like any other list.
1940 $CGIscriptorResults[-1] is always the last result.
1941 This is only of limited use, e.g., to use the results of an OS shell
1942 script inside a Perl script. Will NOT contain the results of Pipes
1943 or code from MIME-profiling.
1944 </P>
1946 <A NAME="CGIPREDEFINED"><H2 ALIGN="CENTER">USEFULL CGI PREDEFINED VARIABLES (DO NOT ASSIGN TO THESE)</H2></A>
1948 <ul>
1949 <li>$CGI_HOME - The ServerRoot directory
1950 <li>$CGI_Decoded_QS - The complete decoded Query String
1951 <li>$CGI_Content_Length - The ACTUAL length of the Query String
1952 <li>$CGI_Date - Current date and time
1953 <li>$CGI_Year $CGI_Month $CGI_Day $CGI_WeekDay - Current Date
1954 <li>$CGI_Time - Current Time
1955 <li>$CGI_Hour $CGI_Minutes $CGI_Seconds - Current Time, split
1956 GMT Date/Time:
1957 <li>$CGI_GMTYear $CGI_GMTMonth $CGI_GMTDay $CGI_GMTWeekDay $CGI_GMTYearDay
1958 <li>$CGI_GMTHour $CGI_GMTMinutes $CGI_GMTSeconds $CGI_GMTisdst
1959 </ul>
1963 <P>
1964 Variables accessible (in APACHE) as $ENV{"<name>"}
1965 (see: "http://hoohoo.ncsa.uiuc.edu/cgi/env.html"):
1966 </P>
1968 <UL>
1969 <LI>QUERY_STRING - The query part of URL, that is, everything that follows the
1970 question mark.
1971 <LI>PATH_INFO - Extra path information given after the script name
1972 <LI>PATH_TRANSLATED - Extra pathinfo translated through the rule system.
1973 (This doesn't always make sense.)
1974 <LI>REMOTE_USER - If the server supports user authentication, and the script is
1975 protected, this is the username they have authenticated as.
1976 <LI>REMOTE_HOST - The hostname making the request. If the server does not have
1977 this information, it should set REMOTE_ADDR and leave this unset
1978 <LI>REMOTE_ADDR - The IP address of the remote host making the request.
1980 variable will be set to the remote user name retrieved from
1981 the server. Usage of this variable should be limited to logging
1982 only.
1983 <LI>AUTH_TYPE - If the server supports user authentication, and the script
1984 is protected, this is the protocol-specific authentication
1985 method used to validate the user.
1986 <LI>CONTENT_TYPE - For queries which have attached information, such as HTTP
1987 POST and PUT, this is the content type of the data.
1988 <LI>CONTENT_LENGTH - The length of the said content as given by the client.
1989 <LI>SERVER_SOFTWARE - The name and version of the information server software
1990 answering the request (and running the gateway).
1991 Format: name/version
1992 <LI>SERVER_NAME - The server's hostname, DNS alias, or IP address as it
1993 would appear in self-referencing URLs
1994 <LI>GATEWAY_INTERFACE - The revision of the CGI specification to which this
1995 server complies. Format: CGI/revision
1996 <LI>SERVER_PROTOCOL - The name and revision of the information protocol this
1997 request came in with. Format: protocol/revision
1998 <LI>SERVER_PORT - The port number to which the request was sent.
1999 <LI>REQUEST_METHOD - The method with which the request was made. For HTTP,
2001 <LI>SCRIPT_NAME - A virtual path to the script being executed, used for
2002 self-referencing URLs.
2003 <LI>HTTP_ACCEPT - The MIME types which the client will accept, as given by
2004 HTTP headers. Other protocols may need to get this
2005 information from elsewhere. Each item in this list should
2006 be separated by commas as per the HTTP spec.
2007 Format: type/subtype, type/subtype
2008 <LI>HTTP_USER_AGENT - The browser the client is using to send the request.
2009 General format: software/version library/version.
2010 </UL>
2014 <P>
2015 CGIscriptor.pl will run on any WWW server that runs Perl scripts,
2016 just add a line like the following to your srm.conf file
2017 (Apache example):
2018 </P>
2020 <pre>
2021 ScriptAlias /SHTML/ /real-path/CGIscriptor.pl/
2022 </pre>
2024 <p>
2025 URL's that refer to http://www.your.address/SHTML/... will now be handled
2026 by CGIscriptor.pl, which can use a private directory tree (default is the
2027 DOCUMENT_ROOT directory tree, but it can be anywhere, see manual).
2028 </P>
2030 <p>
2031 If your hosting ISP won't let you add ScriptAlias lines you can use
2033 (from Gerd Franke)
2034 </P>
2036 <pre>
2037 RewriteEngine On
2038 RewriteBase /
2039 RewriteCond %{REQUEST_FILENAME} .html$
2040 RewriteCond %{SCRIPT_FILENAME} !cgiscriptor.pl$
2041 RewriteCond %{REQUEST_FILENAME} -f
2042 RewriteRule ^(.*)$ /cgi-bin/cgiscriptor.pl/$1?%{QUERY_STRING}
2043 </Pre>
2045 <p>
2047 in the url and where the file "path/filename.html" exists is redirected
2048 to "/cgi.bin/cgiscriptor.pl/path/filename.html?query".
2049 The user configuration should get the same path-level as the
2050 .htaccess-file:
2051 </P>
2053 <pre>
2054 # Just enter your own directory path here
2055 $YOUR_HTML_FILES = "$ENV{'DOCUMENT_ROOT'}";
2056 # use DOCUMENT_ROOT only, if .htaccess lies in the root-directory.
2057 </Pre>
2059 <p>
2060 If this .htaccess goes in a specific directory, the path to this
2061 directory must be added to $ENV{'DOCUMENT_ROOT'}.
2062 </p>
2064 <p>
2065 The CGIscriptor file contains all documentation as comments. These comments
2066 can be removed to speed up loading (e.g., `egrep -v '^#' CGIscriptor.pl` >
2067 leanScriptor.pl). A bare bones version of CGIscriptor.pl, lacking
2068 documentation, most comments, access control, example functions etc.
2069 (but still with the copyright notice and some minimal documentation)
2070 can be obtained by calling CGIscriptor.pl on the command line with the
2071 '-slim' command line argument, e.g.,
2072 </p>
2074 <PRE>
2076 </PRE>
2078 <P>
2081 'do CGIscriptor.pl' after setting $ENV{PATH_INFO} and $ENV{QUERY_STRING},
2082 or CGIscriptor.pl can be loaded with 'require "/real-path/CGIscriptor.pl"'.
2083 In the latter case, requests are processed by 'Handle_Request();'
2084 (again after setting $ENV{PATH_INFO} and $ENV{QUERY_STRING}).
2085 </P>
2087 <p>
2088 The --help command line switch will print the manual.
2089 </p>
2091 <P>
2092 Using the command line execution option, CGIscriptor.pl can be used as a document
2093 (meta-)preprocessor. If the first argument is '-', STDIN will be read. For example:
2094 </P>
2096 <PRE>
2098 </PRE>
2100 <P>
2101 This command line will produce a STATIC file with the DYNAMIC content of
2102 MyDocument.html "interpolated". This option would be very dangerous when
2103 available over the internet. If someone could sneak a
2104 'http://www.your.domain/-' URL past your server, CGIscriptor could EXECUTE
2105 any POSTED contend. Therefore, for security reasons, STDIN will NOT
2106 be read if ANY of the HTTP server environment variables is set (e.g., SERVER_PORT,
2107 SERVER_PROTOCOL, SERVER_NAME, SERVER_SOFTWARE, HTTP_USER_AGENT,
2108 REMOTE_ADDR).<br>
2109 This block on processing STDIN on HTTP requests can be lifted by setting
2110 <pre>
2111 $BLOCK_STDIN_HTTP_REQUEST = 0;
2112 </pre>
2113 In the security configuration. But be carefull when doing this.
2114 It can be very dangerous.
2115 </P>
2117 <P>
2118 Running demo's and more information can be found at
2119 http://www.fon.hum.uva.nl/~rob/OSS/OSS.html
2120 </P>
2122 <P>
2123 A pocket-size HTTP daemon, CGIservlet.pl, is available from my web site
2124 or CPAN that can use CGIscriptor.pl as the base of a µWWW server and
2125 demonstrates its use.
2126 </P>
2130 <P>
2131 CGIscriptor.pl was mainly developed and tested on UNIX. However, as I
2132 coded part of the time on an Apple Macintosh under MacPerl, I made sure
2133 CGIscriptor did run under MacPerl (with command line options). But only as
2134 an independend script, not as part of a HTTP server. I have used it
2135 under Apache in Windows XP.
2136 </P>
2140 <P>
2141 This program is free software; you can redistribute it and/or
2142 modify it under the terms of the GNU General Public License
2143 as published by the Free Software Foundation; either version 2
2144 of the License, or (at your option) any later version.
2145 </P>
2147 <P>
2148 This program is distributed in the hope that it will be useful,
2149 but WITHOUT ANY WARRANTY; without even the implied warranty of
2150 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
2151 GNU General Public License for more details.
2152 </P>
2154 <P>
2155 You should have received a copy of the GNU General Public License
2156 along with this program; if not, write to the Free Software
2159 </P>
2161 <PRE>
2162 Author: Rob van Son
2163 email:
2164 R.J.J.H.vanSon@uva.nl
2165 University of Amsterdam
2168 Ver: 2.0
2169 Env: Perl 5.002
2170 </PRE>
2171 </BODY>
2173 </HTML>