'\"
'\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: safe.n,v 1.2 2003/11/24 05:09:59 bbbush Exp $
'\" 
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
'\"	or "in/out" to describe whether procedure reads or modifies arg,
'\"	and indent is equivalent to second arg of .IP (shouldn't ever be
'\"	needed;  use .AS below instead)
'\"
'\" .AS ?type? ?name?
'\"	Give maximum sizes of arguments for setting tab stops.  Type and
'\"	name are examples of largest possible arguments that will be passed
'\"	to .AP later.  If args are omitted, default tab stops are used.
'\"
'\" .BS
'\"	Start box enclosure.  From here until next .BE, everything will be
'\"	enclosed in one large box.
'\"
'\" .BE
'\"	End of box enclosure.
'\"
'\" .CS
'\"	Begin code excerpt.
'\"
'\" .CE
'\"	End code excerpt.
'\"
'\" .VS ?version? ?br?
'\"	Begin vertical sidebar, for use in marking newly-changed parts
'\"	of man pages.  The first argument is ignored and used for recording
'\"	the version when the .VS was added, so that the sidebars can be
'\"	found and removed when they reach a certain age.  If another argument
'\"	is present, then a line break is forced before starting the sidebar.
'\"
'\" .VE
'\"	End of vertical sidebar.
'\"
'\" .DS
'\"	Begin an indented unfilled display.
'\"
'\" .DE
'\"	End of indented unfilled display.
'\"
'\" .SO
'\"	Start of list of standard options for a Tk widget.  The
'\"	options follow on successive lines, in four columns separated
'\"	by tabs.
'\"
'\" .SE
'\"	End of list of standard options for a Tk widget.
'\"
'\" .OP cmdName dbName dbClass
'\"	Start of description of a specific option.  cmdName gives the
'\"	option's name as specified in the class command, dbName gives
'\"	the option's name in the option database, and dbClass gives
'\"	the option's class in the option database.
'\"
'\" .UL arg1 arg2
'\"	Print arg1 underlined, then print arg2 normally.
'\"
'\" RCS: @(#) $Id: safe.n,v 1.2 2003/11/24 05:09:59 bbbush Exp $
'\"
'\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.TH "safe" 3tcl 8.0 Tcl "Tcl Built-In Commands"
.SH NAME
Safe \- 用來建立和操縱安全解釋器的機制。
.SH "總覽 SYNOPSIS"
\fB::safe::interpCreate\fR ?\fIslave\fR? ?\fIoptions...\fR?
.sp
\fB::safe::interpInit\fR \fIslave\fR ?\fIoptions...\fR?
.sp
\fB::safe::interpConfigure\fR \fIslave\fR ?\fIoptions...\fR?
.sp
\fB::safe::interpDelete\fR \fIslave\fR
.sp
\fB::safe::interpAddToAccessPath\fR \fIslave\fR \fIdirectory\fR
.sp
\fB::safe::interpFindInAccessPath\fR \fIslave\fR \fIdirectory\fR
.sp
\fB::safe::setLogCmd\fR ?\fIcmd arg...\fR?
.SH OPTIONS
.PP
?\fB\-accessPath\fR \fIpathList\fR?
?\fB\-statics\fR \fIboolean\fR? ?\fB\-noStatics\fR?
?\fB\-nested\fR \fIboolean\fR? ?\fB\-nestedLoadOk\fR?
?\fB\-deleteHook\fR \fIscript\fR?

.SH "描述 DESCRIPTION"
Safe Tcl 是一種機制，用於安全的執行不可信任的 Tcl 
腳本，併爲有潛在危險功能的腳本提供訪問中介。
.PP
Safe Base 確保不可信任的 Tcl 腳本不能損壞宿主應用。Safe 
Base 防止完整性和隱私攻擊。防止不可信任的 Tcl 
腳本敗壞宿主應用或計算機的狀況。防止不可信任的腳本把存儲在宿主主機或宿主應用中的信息泄露給任何人羣。
.PP
Safe Base 
允許一個主解釋器建立安全、受限制的解釋器，它包括爲  \fBsource\fR,
\fBload\fR, \fBfile\fR, \fBencoding\fR, 和 \fBexit\fR 命令預定義的一系列別名，並可以使用自動裝載和包機制。
.PP
不向安全解釋器透露文件系統的任何東西，它只能訪問包含記號(token)的虛擬的路徑。當安全解釋器請求 
source(載入)一個文件的時候，它使用在虛擬路徑中的記號作爲要 source 的文件名的一部分；主解釋器透明的把這個記號轉換成一個實際的路徑名並執行所要求的操作 (詳情參見下面的 \fBSECURITY\fR 安全 章節).
可以使用下面描述的命令標誌來選擇不同的安全級別。
.PP
Safe Base 在主解釋器中提供的所有命令駐留在 \fBsafe\fR 
名字空間中:

.SH "命令 COMMANDS"
在主解釋器中提供了下列命令:
.TP
\fB::safe::interpCreate\fR ?\fIslave\fR? ?\fIoptions...\fR?
建立一個安全解釋器，安裝在\fBALIASES\fR  別名 章節中描述的別名並初始化在 \fBOPTIONS\fR 選項 中提供的自動裝載和包機制。對可選擇的參數的描述請參見下面 \fBOPTIONS\fR 選項 章節。如果省略了\fIslave\fR 參數，則生成一個名字。\fB::safe::interpCreate\fR 總是返回解釋器的名字。
.TP
\fB::safe::interpInit\fR \fIslave\fR ?\fIoptions...\fR?
除了不建立安全解釋器之外，這個命令類似於 \fBinterpCreate\fR   命令。必須已經通過其他方式如 \fBinterp create -safe\fR建立了這個 \fIslave\fR。
.TP
如果未給出 \fIoptions\fR，則把給指名的這個解釋器所有選項的設置返回爲給這個 \fIslave \fR的選項和它們當前的值的一個列表。如果提供了一個單一的補充參數，它將返回有兩個元素 \fIname\fR 和 \fIvalue\fR 的一個列表，這裏的 \fIname\fR 是選項的全名而 \fIvalue\fR 是給 \fIslave \fR的這個選項當前值。如果提供多於兩個補充選項，它將重新配置這個安全解釋器並只改變每個提供的選項。關於選項的描述請參見下面的 OPTIONS 章節。使用的例子:
.RS
# Create a new interp with the same configuration as "$i0" :
set i1 [eval safe::interpCreate [safe::interpConfigure $i0]]
# Get the current deleteHook
set dh [safe::interpConfigure $i0  \-del]
# Change (only) the statics loading ok attribute of an interp
# and its deleteHook (leaving the rest unchanged) :
safe::interpConfigure $i0  \-delete {foo bar} \-statics 0 ;
.RE
.TP
\fB::safe::interpDelete\fR \fIslave\fR
刪除這個安全解釋器並清除相應的主解釋器數據結構。如果爲這個解釋器指定了一個 \fIdeleteHook\fR 腳本，則在刪除這個解釋器之前執行這個腳本，把這個解釋器的名字作爲一個補充參數。
.TP
\fB::safe::interpFindInAccessPath\fR \fIslave\fR \fIdirectory\fR
這個命令尋找並返回在安全解釋器的當前虛擬訪問路徑中給實際路徑 
\fIdirectory\fR 
的記號。如果未找到這個路徑則生成一個錯誤。使用的例子:
.RS
$slave eval [list set tk_library [::safe::interpFindInAccessPath $name $tk_library]]
.RE
.TP
\fB::safe::interpAddToAccessPath\fR \fIslave\fR \fIdirectory\fR
這個命令把 \fIdirectory\fR 添加到在主解釋器中爲安全解釋器維護的虛擬路徑中，並返回可在安全解釋器中被用來獲得到在這個目錄中的文件的訪問的記號。如果這個路徑已經存在於虛擬路徑中，則它只返回記號而不再次把這個路徑添加到虛擬路徑中。使用的例子:
.RS
$slave eval [list set tk_library [::safe::interpAddToAccessPath $name $tk_library]]
.RE
.TP
\fB::safe::setLogCmd\fR ?\fIcmd arg...\fR?
這個命令安裝在一個腳本，在這個安全解釋器的特定的生命週期事件發生的時候將被調用。在調用這個命令而不加參數時，它返回當前安裝的腳本。在調用並加一個參數空串時，則刪除當前安裝的腳本並關閉日誌記錄。調用這個腳本時將加上一個補充參數，它描述所感興趣的事件。主要的目的是幫助調試安全解釋器。在安全解釋器只能得到一個一般錯誤消息的時候你可以使用這個設施獲得完整的錯誤消息。這防止安全解釋器見到關於失敗的消息和其他可能包含敏感信息如真實路徑名的其他事件的消息。
.RS
使用的例子:

::safe::setLogCmd puts stderr

下面是一個樣本對話的輸出，這裏一個安全解釋器嘗試着 source 一個在它的虛擬
訪問路徑中找不到的文件。注意這個安全解釋器只接收到一個錯誤消息，說這個文
件未找到:

.nf
NOTICE for slave interp10 : Created
NOTICE for slave interp10 : Setting accessPath=(/foo/bar) staticsok=1 nestedok=0 deletehook=()
NOTICE for slave interp10 : auto_path in interp10 has been set to {$p(:0:)}
ERROR for slave interp10 : /foo/bar/init.tcl: no such file or directory
.fi
.RE

.SH "選項 OPTIONS"
下列選項通用於 \fB::safe::interpCreate\fR、\fB::safe::interpInit\fR、和 \fB::safe::interpConfigure\fR。任何選項都可縮寫爲它的最小的無歧義的名字。選項的名字是大小寫不敏感的。
.TP 
\fB\-accessPath\fR \fIdirectoryList\fR
這個選項設置目錄的列表，安全解釋器可以從中 \fBsource\fR 和 \fBload\fR 文件。如果未指定這個選項，或者它被給定爲一個空列表，安全解釋器將使用的目錄同與它的主解釋器用於自動裝載的目錄。關於虛擬路徑、記號和訪問控制的詳情請參見下面的 \fBSECURITY\fR 安全 章節。
.TP
\fB\-statics\fR \fIboolean\fR
這個選項指定是否允許這個安全解釋器裝載靜態連接包(如 \fBload {} Tk\fR)。缺省值是 \fBtrue\fR : 允許安全解釋器裝載靜態連接包。
.TP
\fB\-noStatics\fR
這個選項是 \fB-statics false\fR     的一個方便的簡寫，它指定不允許這個安全解釋器裝載靜態連接包。
.TP
\fB\-nested\fR \fIboolean\fR
這個選項指定是否允許這個安全解釋器把包裝載到它自己的子解釋器中。缺省值是     \fBfalse\fR :     不允許安全解釋器把包裝載到它自己的子解釋器中。
.TP
\fB\-nestedLoadOk\fR
這個選項是 \fB-nested true\fR     的一個方便的簡寫，它指定允許安全解釋器把包裝載到它自己的子解釋器中。
.TP 
\fB\-deleteHook\fR \fIscript\fR
當給這個選項以一個非空的 \fIscript\fR     的時候，它將在實際刪除這個從解釋器之前在主解釋器中被求值，並加上這個安全解釋器的名字作爲一個補充的參數。給予一個空值則去除任何當前爲這個安全解釋器安裝的刪除回調(hook)腳本。缺省值(\fB{}\fR)是沒有任何刪除回調腳本。
.SH "別名 ALIASES"
在安全解釋器中提供了下列別名:
.TP
\fBsource\fR \fIfileName\fR
如果找到了要求的這個 Tcl 源文件，則把它 source(裝載)到安全解釋器中。
\fBsource\fR 別名只可以從給這個安全解釋器的虛擬路徑中的目錄 source 文件。
關於在有效文件名上的限制的更多信息請參見 \fBSECURITY\fR 安全 章節。
.TP
\fBload\fR \fIfileName\fR
如果找到了要求的這個共享的目標文件，則把它動態的裝載到安全解釋器中。爲了能成功的找到它，文件名必須包含在給這個安全解釋器的虛擬路徑中提及的一個記號的名字。還有，這個共享的目標文件必須包含一個安全入口點；詳情請參見 \fBload\fR 命令的手冊條目。
.TP
\fBfile\fR ?\fIsubCmd args...\fR?
\fBfile\fR 別名提供到 \fBfile\fR命令的子命令的一個安全子集的訪問；它只允許 \fBdirname\fR、\fBjoin\fR、  \fBextension\fR、\fBroot\fR、\fBtail\fR、\fBpathname\fR 和 \fBsplit\fR  子命令。關於這些子命令的詳情請參見 \fBfile\fR  命令的手冊條目。
.TP
\fBencoding\fR ?\fIsubCmd args...\fR?
\fBenconding\fR 別名提供到 \fBencoding\fR 命令的子命令的一個安全子集的訪問；它不允許設置系統編碼，不允許其他子命令包括 \fBsystem\fR 檢查當前編碼。
.TP
\fBexit\fR
刪除調用它的腳本並停止它的計算，但這個解釋器存在於其中的那個 Tcl 進程不被終止。

.SH "安全 SECURITY"
Safe Base 不嘗試完全的防止煩惱(annoyance)和拒絕服務攻擊。這些形式的攻擊妨礙應用或用戶臨時的使用計算機來完成有用的工作，例如消耗所有可利用的 CPU 時間或所有可利用的屏幕 real estate。這些攻擊儘管很惡劣，但一般不如 Safe Base 主要防護的完整性和隱私攻擊那麼重要。
.PP
除了在 \fBinterp\fR 手冊頁中定義的安全命令集之外，在安全解釋器中可獲得的命令還包括給 \fBsource\fR、\fBload\fR、\fBexit\fR 的作爲中介的(mediate)別名以及 \fBfile\fR 和 \fBencoding\fR 命令的安全子集。安全解釋器還可以自動裝載代碼並可以請求裝載包。
.PP
因爲這些命令中的一些命令訪問本地文件系統，存在着對它的目錄結構的潛在的信息泄露。爲了防止這個問題，接受文件名作爲參數的命令在安全解釋器中使用記號來替代真實的目錄名。在主解釋器中介一個要求例如 
source 一個文件的時候，把這些記號轉換成實際路徑名。在主解釋器中維護這個虛擬路徑系統，針對每個用 
\fB::safe::interpCreate\fR 建立的或用 \fB::safe::interpInit\fR 
初始化的安全解釋器，這個路徑把在安全解釋器中可訪問的記號映射成在本地文件系統上的真實路徑名，這樣就防止了安全解釋器去獲取關於這個解釋器在其上執行的主機的文件系統結構的知識。可以提供給從解釋器中的 
\fBsource\fR 和 \fBload\fR 別名的有效的文件名參數只能是下面這種形式的路徑：
\fB[file join \fR\fItoken filename\fR\fB]\fR (比如，在使用本地文件路徑格式的時候: 
在 Unix 上是 \fItoken\fR\fB/\fR\fIfilename\fR，在 Windows 上是 \fItoken\fR\fB\\\fIfilename\fR，在 
Mac 上是 \fItoken\fR\fB:\fR\fIfilename\fR  )，這裏的 \fItoken\fR 表示 
\fIaccessPath \fR列表中的一個目錄而 \fIfilename\fR 是在這個目錄中一個文件(不允許訪問子目錄)。
.PP
在一個安全解釋器中，當在要 source 或裝載一個文件的一個請求中使用一個記號的時候，檢查這個記號並把它轉換成真實路徑名，並在文件系統上定位要被 source 或裝載的文件。安全解釋器不能獲取關於文件系統上在其下存儲這個文件的實際路徑名的知識。
.PP
爲了進一步防止潛在的對偶然的包括在可以被安全解釋器 source 的文件集中的敏
感文件的信息泄露，限制 \fBsource\fR 別名爲訪問滿足下列約束的文件: 文件名
必須是十四個字符或更短，必須不包含多於一個的點(\(lq\fB.\fR\(rq)，不許終止於擴
展 \fB.tcl\fR 或是被調用的 \fBtclIndex\fR。
.PP
初始的訪問路徑列表中的每個元素將分配一個記號，它們將被設置在從解釋器的 
\fBauto_path\fR 中並且這個列表的第一個元素將被設置爲這個從解釋器的 \fBtcl_library\fR。
.PP
如果未給出訪問路徑參數或者是一個空列表，缺省的行爲是讓從解釋器訪問的包與主解釋器已經訪問了的包相同(更精確的描述: 
只允許用 Tcl 寫成的包(因爲它們將在從解釋器中運行所以不可能是危險的)和提供 
Safe_Init 入口點的 C 擴展)。爲此，用主解釋器的 \fBauto_path\fR 
來構造從解釋器的訪問路徑。爲了從解釋器能成功的裝載 Tcl 
庫文件(它自身包括自動裝載機制)，如果需要的話，把 \fBtcl_library\fR 
增加或移動到在從解釋器的訪問路徑中的第一個的位置上，這樣從解釋器的 \fBtcl_library\fR 將與主解釋器的相同(它的真實路徑對從解釋器仍是不可見的)。爲了使自動裝載對於從解釋器和主解釋器在缺省的情況下以相同的方式工作，在主解釋器 \fBauto_path\fR 中的每個目錄的第一層子目錄將被添加(如果未曾包含的話)到從解釋器的訪問路徑中。你總是可以通過顯式的使用 \fB-accessPath\fR 標誌指定你的目錄列表，而不是依賴於這個缺省機制，來指定一個更受限制的路徑，它的子目錄永遠不能被查找。
.PP
在首次建立或初始化(例如通過 \fBinterpConfigure -accessPath \fR\fIlist\fR)之後變更 
\fIaccessPath\fR 的時候，將在安全解釋器中自動的求值 \fBauto_reset\fR 
來使它的 \fBauto_index\fR 與新的記號列表同步。

.SH "參見 SEE ALSO"
interp(n), library(n), load(n), package(n), source(n), unknown(n)
 
.SH "關鍵字 KEYWORDS"
alias, auto\-loading, auto_mkindex, load, master interpreter, safe
interpreter, slave interpreter, source

.SH "[中文版維護人]"
.B 寒蟬退士
.SH "[中文版最新更新]"
.B 2001/11/07
.SH "《中國 Linux 論壇 man 手冊頁翻譯計劃》:"
.BI http://cmpp.linuxforum.net
.SH "跋"
.br
本頁面中文版由中文 man 手冊頁計劃提供。
.br
中文 man 手冊頁計劃：\fBhttps://github.com/man-pages-zh/manpages-zh\fR