2 '\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
4 '\" See the file "license.terms" for information on usage and redistribution
5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
7 .TH "Safe Tcl" n 8.0 Tcl "Tcl Built-In Commands"
8 .\" The -*- nroff -*- definitions below are for supplemental macros used
9 .\" in Tcl/Tk manual entries.
11 .\" .AP type name in/out ?indent?
12 .\" Start paragraph describing an argument to a library procedure.
13 .\" type is type of argument (int, etc.), in/out is either "in", "out",
14 .\" or "in/out" to describe whether procedure reads or modifies arg,
15 .\" and indent is equivalent to second arg of .IP (shouldn't ever be
16 .\" needed; use .AS below instead)
19 .\" Give maximum sizes of arguments for setting tab stops. Type and
20 .\" name are examples of largest possible arguments that will be passed
21 .\" to .AP later. If args are omitted, default tab stops are used.
24 .\" Start box enclosure. From here until next .BE, everything will be
25 .\" enclosed in one large box.
28 .\" End of box enclosure.
31 .\" Begin code excerpt.
36 .\" .VS ?version? ?br?
37 .\" Begin vertical sidebar, for use in marking newly-changed parts
38 .\" of man pages. The first argument is ignored and used for recording
39 .\" the version when the .VS was added, so that the sidebars can be
40 .\" found and removed when they reach a certain age. If another argument
41 .\" is present, then a line break is forced before starting the sidebar.
44 .\" End of vertical sidebar.
47 .\" Begin an indented unfilled display.
50 .\" End of indented unfilled display.
53 .\" Start of list of standard options for a Tk widget. The manpage
54 .\" argument defines where to look up the standard options; if
55 .\" omitted, defaults to "options". The options follow on successive
56 .\" lines, in three columns separated by tabs.
59 .\" End of list of standard options for a Tk widget.
61 .\" .OP cmdName dbName dbClass
62 .\" Start of description of a specific option. cmdName gives the
63 .\" option's name as specified in the class command, dbName gives
64 .\" the option's name in the option database, and dbClass gives
65 .\" the option's class in the option database.
68 .\" Print arg1 underlined, then print arg2 normally.
71 .\" Print arg1 in quotes, then arg2 normally (for trailing punctuation).
74 .\" Print an open parenthesis, arg1 in quotes, then arg2 normally
75 .\" (for trailing punctuation) and then a closing parenthesis.
77 .\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
81 .\" # Start an argument description
85 . ie !"\\$2"" .TP \\n()Cu
90 \&\\$1 \\fI\\$2\\fP (\\$3)
103 .\" # define tabbing values for .AP
106 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
109 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
110 .nr )C \\n()Bu+\\w'(in/out)'u+2n
112 .AS Tcl_Interp Tcl_CreateInterp in/out
113 .\" # BS - start boxed text
114 .\" # ^y = starting y location
122 .if n \l'\\n(.lu\(ul'
125 .\" # BE - end boxed text (draw box now)
130 .ie n \l'\\n(^lu\(ul'
132 .\" Draw four-sided box normally, but don't draw top of
133 .\" box if the box started on an earlier page.
135 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
138 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
145 .\" # VS - start vertical sidebar
146 .\" # ^Y = starting y location
147 .\" # ^v = 1 (for troff; for nroff this doesn't matter)
151 .ie n 'mc \s12\(br\s0
154 .\" # VE - end of vertical sidebar
162 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
169 .\" # Special macro to handle page bottom: finish off current
170 .\" # box/sidebar if in box/sidebar mode, then invoked standard
171 .\" # page bottom macro.
178 .\" Draw three-sided box if this is the box's first page,
179 .\" draw two sides but no top otherwise.
180 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
181 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
184 .nr ^x \\n(^tu+1v-\\n(^Yu
185 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
198 .\" # DS - begin display
204 .\" # DE - end display
210 .\" # SO - start of list of standard options
212 'ie '\\$1'' .ds So \\fBoptions\\fR
213 'el .ds So \\fB\\$1\\fR
214 .SH "STANDARD OPTIONS"
220 .\" # SE - end of list of standard options
225 See the \\*(So manual entry for details on the standard options.
227 .\" # OP - start of full description for a single option
232 Command-Line Name: \\fB\\$1\\fR
233 Database Name: \\fB\\$2\\fR
234 Database Class: \\fB\\$3\\fR
238 .\" # CS - begin code excerpt
244 .\" # CE - end code excerpt
249 .\" # UL - underline word
253 .\" # QW - apply quotation marks to word
255 .ie '\\*(lq'"' ``\\$1''\\$2
256 .\"" fix emacs highlighting
257 .el \\*(lq\\$1\\*(rq\\$2
259 .\" # PQ - apply parens and quotation marks to word
261 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
262 .\"" fix emacs highlighting
263 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
265 .\" # QR - quoted range
267 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
268 .\"" fix emacs highlighting
269 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
271 .\" # MT - "empty" string
276 '\" Note: do not modify the .SH NAME line immediately below!
278 safe \- Creating and manipulating safe interpreters
280 \fB::safe::interpCreate\fR ?\fIslave\fR? ?\fIoptions...\fR?
282 \fB::safe::interpInit\fR \fIslave\fR ?\fIoptions...\fR?
284 \fB::safe::interpConfigure\fR \fIslave\fR ?\fIoptions...\fR?
286 \fB::safe::interpDelete\fR \fIslave\fR
288 \fB::safe::interpAddToAccessPath\fR \fIslave\fR \fIdirectory\fR
290 \fB::safe::interpFindInAccessPath\fR \fIslave\fR \fIdirectory\fR
292 \fB::safe::setLogCmd\fR ?\fIcmd arg...\fR?
295 ?\fB\-accessPath\fR \fIpathList\fR?
296 ?\fB\-statics\fR \fIboolean\fR? ?\fB\-noStatics\fR?
297 ?\fB\-nested\fR \fIboolean\fR? ?\fB\-nestedLoadOk\fR?
298 ?\fB\-deleteHook\fR \fIscript\fR?
301 Safe Tcl is a mechanism for executing untrusted Tcl scripts
302 safely and for providing mediated access by such scripts to
303 potentially dangerous functionality.
305 Safe Tcl ensures that untrusted Tcl scripts cannot harm the
307 It prevents integrity and privacy attacks. Untrusted Tcl
308 scripts are prevented from corrupting the state of the hosting
309 application or computer. Untrusted scripts are also prevented from
310 disclosing information stored on the hosting computer or in the
311 hosting application to any party.
313 Safe Tcl allows a master interpreter to create safe, restricted
314 interpreters that contain a set of predefined aliases for the \fBsource\fR,
315 \fBload\fR, \fBfile\fR, \fBencoding\fR, and \fBexit\fR commands and
316 are able to use the auto-loading and package mechanisms.
318 No knowledge of the file system structure is leaked to the
319 safe interpreter, because it has access only to a virtualized path
320 containing tokens. When the safe interpreter requests to source a file, it
321 uses the token in the virtual path as part of the file name to source; the
322 master interpreter transparently
323 translates the token into a real directory name and executes the
324 requested operation (see the section \fBSECURITY\fR below for details).
325 Different levels of security can be selected by using the optional flags
326 of the commands described below.
328 All commands provided in the master interpreter by Safe Tcl reside in
329 the \fBsafe\fR namespace.
331 The following commands are provided in the master interpreter:
333 \fB::safe::interpCreate\fR ?\fIslave\fR? ?\fIoptions...\fR?
334 Creates a safe interpreter, installs the aliases described in the section
335 \fBALIASES\fR and initializes the auto-loading and package mechanism as
336 specified by the supplied \fIoptions\fR.
337 See the \fBOPTIONS\fR section below for a description of the
339 If the \fIslave\fR argument is omitted, a name will be generated.
340 \fB::safe::interpCreate\fR always returns the interpreter name.
342 \fB::safe::interpInit\fR \fIslave\fR ?\fIoptions...\fR?
343 This command is similar to \fBinterpCreate\fR except it that does not
344 create the safe interpreter. \fIslave\fR must have been created by some
345 other means, like \fBinterp create\fR \fB\-safe\fR.
347 \fB::safe::interpConfigure\fR \fIslave\fR ?\fIoptions...\fR?
348 If no \fIoptions\fR are given, returns the settings for all options for the
349 named safe interpreter as a list of options and their current values
350 for that \fIslave\fR.
351 If a single additional argument is provided,
352 it will return a list of 2 elements \fIname\fR and \fIvalue\fR where
353 \fIname\fR is the full name of that option and \fIvalue\fR the current value
354 for that option and the \fIslave\fR.
355 If more than two additional arguments are provided, it will reconfigure the
356 safe interpreter and change each and only the provided options.
357 See the section on \fBOPTIONS\fR below for options description.
362 # Create new interp with the same configuration as "$i0":
363 set i1 [safe::interpCreate {*}[safe::interpConfigure $i0]]
365 # Get the current deleteHook
366 set dh [safe::interpConfigure $i0 \-del]
368 # Change (only) the statics loading ok attribute of an
369 # interp and its deleteHook (leaving the rest unchanged):
370 safe::interpConfigure $i0 \-delete {foo bar} \-statics 0
374 \fB::safe::interpDelete\fR \fIslave\fR
375 Deletes the safe interpreter and cleans up the corresponding
376 master interpreter data structures.
377 If a \fIdeleteHook\fR script was specified for this interpreter it is
378 evaluated before the interpreter is deleted, with the name of the
379 interpreter as an additional argument.
381 \fB::safe::interpFindInAccessPath\fR \fIslave\fR \fIdirectory\fR
382 This command finds and returns the token for the real directory
383 \fIdirectory\fR in the safe interpreter's current virtual access path.
384 It generates an error if the directory is not found.
389 $slave eval [list set tk_library \e
390 [::safe::interpFindInAccessPath $name $tk_library]]
394 \fB::safe::interpAddToAccessPath\fR \fIslave\fR \fIdirectory\fR
395 This command adds \fIdirectory\fR to the virtual path maintained for the
396 safe interpreter in the master, and returns the token that can be used in
397 the safe interpreter to obtain access to files in that directory.
398 If the directory is already in the virtual path, it only returns the token
399 without adding the directory to the virtual path again.
404 $slave eval [list set tk_library \e
405 [::safe::interpAddToAccessPath $name $tk_library]]
409 \fB::safe::setLogCmd\fR ?\fIcmd arg...\fR?
410 This command installs a script that will be called when interesting
411 life cycle events occur for a safe interpreter.
412 When called with no arguments, it returns the currently installed script.
413 When called with one argument, an empty string, the currently installed
414 script is removed and logging is turned off.
415 The script will be invoked with one additional argument, a string
416 describing the event of interest.
417 The main purpose is to help in debugging safe interpreters.
418 Using this facility you can get complete error messages while the safe
419 interpreter gets only generic error messages.
420 This prevents a safe interpreter from seeing messages about failures
421 and other events that might contain sensitive information such as real
428 ::safe::setLogCmd puts stderr
431 Below is the output of a sample session in which a safe interpreter
432 attempted to source a file not found in its virtual access path.
433 Note that the safe interpreter only received an error message saying that
434 the file was not found:
437 NOTICE for slave interp10 : Created
438 NOTICE for slave interp10 : Setting accessPath=(/foo/bar) staticsok=1 nestedok=0 deletehook=()
439 NOTICE for slave interp10 : auto_path in interp10 has been set to {$p(:0:)}
440 ERROR for slave interp10 : /foo/bar/init.tcl: no such file or directory
444 The following options are common to
445 \fB::safe::interpCreate\fR, \fB::safe::interpInit\fR,
446 and \fB::safe::interpConfigure\fR.
447 Any option name can be abbreviated to its minimal
449 Option names are not case sensitive.
451 \fB\-accessPath\fR \fIdirectoryList\fR
452 This option sets the list of directories from which the safe interpreter
453 can \fBsource\fR and \fBload\fR files.
454 If this option is not specified, or if it is given as the
455 empty list, the safe interpreter will use the same directories as its
456 master for auto-loading.
457 See the section \fBSECURITY\fR below for more detail about virtual paths,
458 tokens and access control.
460 \fB\-statics\fR \fIboolean\fR
461 This option specifies if the safe interpreter will be allowed
462 to load statically linked packages (like \fBload {} Tk\fR).
463 The default value is \fBtrue\fR :
464 safe interpreters are allowed to load statically linked packages.
467 This option is a convenience shortcut for \fB\-statics false\fR and
468 thus specifies that the safe interpreter will not be allowed
469 to load statically linked packages.
471 \fB\-nested\fR \fIboolean\fR
472 This option specifies if the safe interpreter will be allowed
473 to load packages into its own sub-interpreters.
474 The default value is \fBfalse\fR :
475 safe interpreters are not allowed to load packages into
476 their own sub-interpreters.
479 This option is a convenience shortcut for \fB\-nested true\fR and
480 thus specifies the safe interpreter will be allowed
481 to load packages into its own sub-interpreters.
483 \fB\-deleteHook\fR \fIscript\fR
484 When this option is given a non-empty \fIscript\fR, it will be
485 evaluated in the master with the name of
486 the safe interpreter as an additional argument
487 just before actually deleting the safe interpreter.
488 Giving an empty value removes any currently installed deletion hook
489 script for that safe interpreter.
490 The default value (\fB{}\fR) is not to have any deletion call back.
492 The following aliases are provided in a safe interpreter:
494 \fBsource\fR \fIfileName\fR
495 The requested file, a Tcl source file, is sourced into the safe interpreter
497 The \fBsource\fR alias can only source files from directories in
498 the virtual path for the safe interpreter. The \fBsource\fR alias requires
499 the safe interpreter to
500 use one of the token names in its virtual path to denote the directory in
501 which the file to be sourced can be found.
502 See the section on \fBSECURITY\fR for more discussion of restrictions on
505 \fBload\fR \fIfileName\fR
506 The requested file, a shared object file, is dynamically loaded into the
507 safe interpreter if it is found.
508 The filename must contain a token name mentioned in the virtual path for
509 the safe interpreter for it to be found successfully.
510 Additionally, the shared object file must contain a safe entry point; see
511 the manual page for the \fBload\fR command for more details.
513 \fBfile\fR ?\fIsubCmd args...\fR?
514 The \fBfile\fR alias provides access to a safe subset of the subcommands of
515 the \fBfile\fR command; it allows only \fBdirname\fR, \fBjoin\fR,
516 \fBextension\fR, \fBroot\fR, \fBtail\fR, \fBpathname\fR and \fBsplit\fR
517 subcommands. For more details on what these subcommands do see the manual
518 page for the \fBfile\fR command.
520 \fBencoding\fR ?\fIsubCmd args...\fR?
521 The \fBencoding\fR alias provides access to a safe subset of the
522 subcommands of the \fBencoding\fR command; it disallows setting of
523 the system encoding, but allows all other subcommands including
524 \fBsystem\fR to check the current encoding.
527 The calling interpreter is deleted and its computation is stopped, but the
528 Tcl process in which this interpreter exists is not terminated.
530 Safe Tcl does not attempt to completely prevent annoyance and
531 denial of service attacks. These forms of attack prevent the
532 application or user from temporarily using the computer to perform
533 useful work, for example by consuming all available CPU time or
534 all available screen real estate.
535 These attacks, while aggravating, are deemed to be of lesser importance
536 in general than integrity and privacy attacks that Safe Tcl
539 The commands available in a safe interpreter, in addition to
540 the safe set as defined in \fBinterp\fR manual page, are mediated aliases
541 for \fBsource\fR, \fBload\fR, \fBexit\fR, and safe subsets of
542 \fBfile\fR and \fBencoding\fR. The safe interpreter can also auto-load
543 code and it can request that packages be loaded.
545 Because some of these commands access the local file system, there is a
546 potential for information leakage about its directory structure.
547 To prevent this, commands that take file names as arguments in a safe
548 interpreter use tokens instead of the real directory names.
549 These tokens are translated to the real directory name while a request to,
550 e.g., source a file is mediated by the master interpreter.
551 This virtual path system is maintained in the master interpreter for each safe
552 interpreter created by \fB::safe::interpCreate\fR or initialized by
553 \fB::safe::interpInit\fR and
554 the path maps tokens accessible in the safe interpreter into real path
555 names on the local file system thus preventing safe interpreters
556 from gaining knowledge about the
557 structure of the file system of the host on which the interpreter is
559 The only valid file names arguments
560 for the \fBsource\fR and \fBload\fR aliases provided to the slave
561 are path in the form of
562 \fB[file join \fItoken filename\fB]\fR (i.e. when using the
563 native file path formats: \fItoken\fB/\fIfilename\fR
564 on Unix and \fItoken\fB\e\fIfilename\fR on Windows),
565 where \fItoken\fR is representing one of the directories
566 of the \fIaccessPath\fR list and \fIfilename\fR is
567 one file in that directory (no sub directories access are allowed).
569 When a token is used in a safe interpreter in a request to source or
570 load a file, the token is checked and
571 translated to a real path name and the file to be
572 sourced or loaded is located on the file system.
573 The safe interpreter never gains knowledge of the actual path name under
574 which the file is stored on the file system.
576 To further prevent potential information leakage from sensitive files that
577 are accidentally included in the set of files that can be sourced by a safe
578 interpreter, the \fBsource\fR alias restricts access to files
579 meeting the following constraints: the file name must
580 fourteen characters or shorter, must not contain more than one dot
582 must end up with the extension
587 Each element of the initial access path
588 list will be assigned a token that will be set in
589 the slave \fBauto_path\fR and the first element of that list will be set as
590 the \fBtcl_library\fR for that slave.
592 If the access path argument is not given or is the empty list,
593 the default behavior is to let the slave access the same packages
594 as the master has access to (Or to be more precise:
595 only packages written in Tcl (which by definition cannot be dangerous
596 as they run in the slave interpreter) and C extensions that
597 provides a _SafeInit entry point). For that purpose, the master's
598 \fBauto_path\fR will be used to construct the slave access path.
599 In order that the slave successfully loads the Tcl library files
600 (which includes the auto-loading mechanism itself) the \fBtcl_library\fR will be
601 added or moved to the first position if necessary, in the
602 slave access path, so the slave
603 \fBtcl_library\fR will be the same as the master's (its real
604 path will still be invisible to the slave though).
605 In order that auto-loading works the same for the slave and
606 the master in this by default case, the first-level
607 sub directories of each directory in the master \fBauto_path\fR will
608 also be added (if not already included) to the slave access path.
609 You can always specify a more
610 restrictive path for which sub directories will never be searched by
611 explicitly specifying your directory list with the \fB\-accessPath\fR flag
612 instead of relying on this default mechanism.
614 When the \fIaccessPath\fR is changed after the first creation or
615 initialization (i.e. through \fBinterpConfigure -accessPath \fR\fIlist\fR),
616 an \fBauto_reset\fR is automatically evaluated in the safe interpreter
617 to synchronize its \fBauto_index\fR with the new token list.
619 interp(n), library(n), load(n), package(n), source(n), unknown(n)
621 alias, auto\-loading, auto_mkindex, load, master interpreter, safe
622 interpreter, slave interpreter, source
OSDN Git Service
