'\"
'\" 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