SecureSocket

套件	flash.net
類別	public class SecureSocket
繼承	SecureSocket Socket EventDispatcher Object

語言版本:

ActionScript 3.0

執行階段版本:

Flash Player 11, AIR 2

SecureSocket 類別讓程式碼可以使用通訊端連線，以運用安全通訊端階層 (SSL) 及傳輸層安全性 (TLS) 通訊協定。

AIR 描述檔支援：所有桌上型電腦作業系統都支援此項功能，但所有 AIR for TV 裝置都不支援。從 AIR 20 開始，即在 Android 以及 iOS 等行動裝置上受到支援。您可以使用 SecureSocket.isSupported 屬性測試執行階段的支援狀況。如需有關跨多個描述檔之 API 支援的詳細資訊，請參閱 AIR 描述檔支援。

SSL/TLS 通訊協定提供一種機制，可處理安全通訊端連線的兩個面向：

透過通訊端加密資料通訊
透過主機的憑證驗證識別名稱

支援的加密通訊協定為 SSL 3.1 及以上版本和 TLS 1.0 及以上版本 (TLS 是 SSL 的後繼者。TLS 1.0 等於 SSL 3.1，TLS 1.1 等於 SSL 3.2，以此類推)。不支援 SSL 3.0 以前的版本。

伺服器憑證的驗證是利用用戶端平台的信任儲存區及憑證驗證支援。此外，您還可以使用 addBinaryChainBuildingCertificate() 方法，以程式設計方式加入自己的憑證。iOS 目前不支援這個 API。在 iOS 使用這個 API 可能會擲回例外：「ArgumentError: 錯誤 #2004」

SecureSocket 類別只會連線到具有有效且受信任憑證的伺服器。您不能選取連線到憑證有問題的伺服器。例如，沒有辦法使用過期的憑證連線到伺服器。同樣地，憑證若未鏈結到信任的錨點憑證，也不能連線。即使憑證是有效的，還是無法連線。

SecureSocket 類別對於執行受信任伺服器的加密通訊非常實用。在其他方面，SecureSocket 物件的行為就和一般 Socket 物件一樣。

若要使用 SecureSocket 類別，請建立 SecureSocket 物件 (new SecureSocket())。接著，設定您的偵聽程式，然後執行 SecureSocket.connect(host, port)。當您成功連線到伺服器時，通訊端會傳送 connect 事件。成功連線即證明，伺服器的安全性通訊協定受支援，並且憑證是有效且受信任的。如果無法驗證憑證，Socket 會傳送 IOError 事件。

重要：所有作業系統皆不支援 Online Certificate Status Protocol (OCSP)。使用者也可以停用個別電腦上的 OCSP 檢查。如果不支援或已停用 OCSP，且憑證未包含使用 Certificate Revocation List (CRL) 進行檢查時所需的資訊，就不會檢查憑證撤銷。如果憑證有效，則會予以接受。這個案例可以允許伺服器使用撤銷的憑證。

相關 API 元素

公用屬性

	屬性		定義自
		bytesAvailable : uint [唯讀] 可在輸入緩衝區中讀取之資料的位元組數。	Socket
		bytesPending : uint [唯讀] 指出寫入緩衝區中剩餘的位元組數目。	Socket
		connected : Boolean [唯讀] 指出此 Socket 物件目前是否已連線。	Socket
		constructor : Object 類別物件的參照或是特定物件實體的建構函數。	Object
		endian : String 表示資料的位元組順序。	Socket
		isSupported : Boolean [靜態] [唯讀] 指出在目前系統上是否支援安全通訊端。	SecureSocket
		localAddress : String [唯讀] 在本機電腦上，這個通訊端繫結的 IP 位址。	Socket
		localPort : int [唯讀] 在本機電腦上，這個通訊端繫結的通訊埠。	Socket
		objectEncoding : uint 會控制寫入或讀取物件時使用的 AMF 版本。	Socket
		remoteAddress : String [唯讀] 這個通訊端連線的遠端電腦 IP 位址。	Socket
		remotePort : int [唯讀] 這個通訊端連線的遠端電腦連接埠。	Socket
		serverCertificate : X509Certificate [唯讀] 在建立安全 SSL/TLS 連線之後，保留從伺服器取得的 X.509 憑證。	SecureSocket
		serverCertificateStatus : String [唯讀] 傳回伺服器憑證的狀態。	SecureSocket
		timeout : uint 指出等待連線的毫秒數。	Socket

公用方法

隱藏繼承公用方法

顯示繼承公用方法

	方法		定義自
		SecureSocket() 建立新的 SecureSocket 物件。	SecureSocket
		addBinaryChainBuildingCertificate(certificate:ByteArray, trusted:Boolean):void 在系統用來驗證伺服器憑證的本機憑證鏈結中加入 X.509 憑證。	SecureSocket
		addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void 會在 EventDispatcher 物件註冊事件偵聽程式，以便讓偵聽程式收到事件的通知。	EventDispatcher
		close():void 會關閉通訊端。	Socket
		connect(host:String, port:int):void [覆寫] 使用 SSL 或 TLS 將通訊端連線到指定的主機或連接埠。	SecureSocket
		dispatchEvent(event:Event):Boolean 會將事件傳送到事件流程。	EventDispatcher
		flush():void 會清除通訊端輸出緩衝區中累積的任何資料。	Socket
		hasEventListener(type:String):Boolean 會檢查 EventDispatcher 物件是否有對特定的事件類型註冊偵聽程式。	EventDispatcher
		hasOwnProperty(name:String):Boolean 指出物件是否有已定義的指定屬性。	Object
		isPrototypeOf(theClass:Object):Boolean 指出 Object 類別的實體是否位於指定為參數的物件原型鏈中。	Object
		propertyIsEnumerable(name:String):Boolean 指出指定的屬性是否存在，以及是否可列舉。	Object
		readBoolean():Boolean 會從通訊端讀取 Boolean 值。	Socket
		readByte():int 會從通訊端讀取具有正負號的位元組。	Socket
		readBytes(bytes:ByteArray, offset:uint = 0, length:uint = 0):void 從通訊端讀取由 length 參數指定的資料位元組數目。	Socket
		readDouble():Number 會從通訊端讀取 IEEE 754 雙精度浮點數。	Socket
		readFloat():Number 會從通訊端讀取 IEEE 754 單精度浮點數。	Socket
		readInt():int 會從通訊端讀取具有正負號的 32 位元整數。	Socket
		readMultiByte(length:uint, charSet:String):String 會使用指定的字元集，從位元組串流讀取多位元組字串。	Socket
		readObject():* 會從通訊端讀取物件，並以 AMF 序列化格式編碼。	Socket
		readShort():int 會從通訊端讀取具有正負號的 16 位元整數。	Socket
		readUnsignedByte():uint 會從通訊端讀取無正負號的位元組。	Socket
		readUnsignedInt():uint 會從通訊端讀取無正負號的 32 位元整數。	Socket
		readUnsignedShort():uint 會從通訊端讀取無正負號的 16 位元整數。	Socket
		readUTF():String 會從通訊端讀取 UTF-8 字串。	Socket
		readUTFBytes(length:uint):String 從通訊端讀取由 length 參數指定的 UTF-8 資料位元組數目，然後傳回字串。	Socket
		removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void 會從 EventDispatcher 物件移除偵聽程式。	EventDispatcher
		setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void 為迴圈作業設定動態屬性的可用性。	Object
		toLocaleString():String 傳回代表此物件的字串，根據地區特定慣例進行格式化。	Object
		toString():String 會傳回指定之物件的字串形式。	Object
		valueOf():Object 會傳回指定之物件的基本值。	Object
		willTrigger(type:String):Boolean 檢查此 EventDispatcher 物件是否已註冊事件偵聽程式，或者此物件的任何祖系已為特定事件類型註冊事件偵聽程式。	EventDispatcher
		writeBoolean(value:Boolean):void 會將 Boolean 值寫入通訊端。	Socket
		writeByte(value:int):void 會將位元組寫入通訊端。	Socket
		writeBytes(bytes:ByteArray, offset:uint = 0, length:uint = 0):void 會從指定的位元組陣列寫入位元組的序列。	Socket
		writeDouble(value:Number):void 會將 IEEE 754 雙精度浮點數寫入通訊端。	Socket
		writeFloat(value:Number):void 會將 IEEE 754 單精度浮點數寫入通訊端。	Socket
		writeInt(value:int):void 會將具有正負號的 32 位元整數寫入通訊端。	Socket
		writeMultiByte(value:String, charSet:String):void 會使用指定的字元集，從位元組串流寫入多位元組字串。	Socket
		writeObject(object:*):void 會使用 AMF 序列化格式，將物件寫入通訊端。	Socket
		writeShort(value:int):void 會將 16 位元整數寫入通訊端。	Socket
		writeUnsignedInt(value:uint):void 會將無正負號的 32 位元整數寫入通訊端。	Socket
		writeUTF(value:String):void 將下列資料寫入通訊端：無正負號的 16 位元整數 (表示指定之 UTF-8 字串的長度，以位元組為單位)，後面接著字串本身。	Socket
		writeUTFBytes(value:String):void 會將 UTF-8 字串寫入通訊端。	Socket

事件

按一下以瞭解事件的詳細資訊

隱藏繼承事件

顯示繼承事件

	摘要	定義自
activate	[廣播事件] 當 Flash Player 或 AIR 應用程式取得作業系統焦點並成為作用中時傳送。	EventDispatcher
close	會在伺服器關閉通訊端連線時傳送。	SecureSocket
connect	會在網路連線已建立時傳送。	SecureSocket
deactivate	[廣播事件] 當 Flash Player 或 AIR 應用程式失去作業系統焦點並成為非作用中時傳送。	EventDispatcher
ioError	發生輸入或輸出錯誤，因而導致傳送或接收作業失敗時傳送。	SecureSocket
outputProgress	在通訊端將資料從它的寫入緩衝區移到網路傳輸層時傳送	Socket
securityError	當對 SecureSocket.connect() 的呼叫因為安全性限制而失敗時傳送。	SecureSocket
socketData	在通訊端收到資料時傳送。	SecureSocket

屬性詳細資訊

isSupported

屬性

isSupported:Boolean [唯讀]

語言版本:

ActionScript 3.0

執行階段版本:

Flash Player 11, AIR 2

指出在目前系統上是否支援安全通訊端。

並非所有平台都支援安全通訊端。嘗試建立 SecureSocket 實體之前，請檢查這個屬性。

實作
public static function get isSupported():Boolean

serverCertificate

屬性

serverCertificate:X509Certificate [唯讀]

語言版本:

ActionScript 3.0

執行階段版本:

Flash Player 11, AIR 3

在建立安全 SSL/TLS 連線之後，保留從伺服器取得的 X.509 憑證。如果未建立安全連線，這個屬性就會設定為 null。iOS 目前並未支援，因此，若是 iOS，則會設定為 null。

如需有關 X.509 憑證的詳細資訊，請參閱 RFC2459。

實作
public function get serverCertificate():X509Certificate

serverCertificateStatus

屬性

serverCertificateStatus:String [唯讀]

語言版本:

ActionScript 3.0

執行階段版本:

Flash Player 11, AIR 2

傳回伺服器憑證的狀態。

此狀態是 CertificateStatus.UNKNOWN，直到通訊端嘗試連線至伺服器。驗證後，狀態是 CertificateStatus 類別列舉的字串之一。只有在憑證為有效且受信任時，連線才會成功。因此，在 connect 事件後，serverCertificateStatus 的值永遠都是 trusted。

注意：一旦驗證或拒絕憑證，在下次呼叫 connect() 方法之前，不會更新狀態值。呼叫 close() 不會將狀態值重設為「不明」。

實作
public function get serverCertificateStatus():String

相關 API 元素

CertificateStatus 類別

建構函式詳細資料

()

建構函式

public function SecureSocket()

語言版本:

ActionScript 3.0

執行階段版本:

Flash Player 11, AIR 2

建立新的 SecureSocket 物件。

在嘗試建立 SecureSocket 實體之前，請檢查 SecureSocket.isSupported。如果不支援 SSL 3.0 或 TLS 1.0 通訊端，執行階段將擲回 IllegalOperationError。

擲回值

	`IllegalOperationError` — 不支援 SSL 3.0 版本 (及以上版本) 或 TLS 1.0 版本 (及以上版本) 時，就會擲回錯誤。

	`SecurityError` — 本機不受信任的 SWF 檔無法與網際網路進行通訊。您可以透過將此 SWF 檔重新分類為「具有網路連線的本機」或受信任，解決此問題。

方法詳細資訊

addBinaryChainBuildingCertificate

()

方法

public function addBinaryChainBuildingCertificate(certificate:ByteArray, trusted:Boolean):void

語言版本:

ActionScript 3.0

執行階段版本:

Flash Player 11, AIR 3

在系統用來驗證伺服器憑證的本機憑證鏈結中加入 X.509 憑證。憑證是暫時性的，只在工作階段持續期間內提供使用。

伺服器憑證驗證會依賴您的系統信任儲存區，以進行憑證鏈結繫結和驗證。使用這個方法，能以程式設計方式加入其他憑證鏈結和信任的錨點。

在 Mac OS 上，系統鑰匙圈是 SSL/TLS 交握過程中使用的預設鑰匙圈。在建立憑證鏈結時，會包含該鑰匙圈中的任何中繼憑證。

使用此 API 加入的憑證必須是 DER 編碼的 X.509 憑證。如果 trusted 參數為 true，使用此 API 加入的憑證也會被視為是信任的錨點。

如需有關 X.509 憑證的詳細資訊，請參閱 RFC2459。

參數

	`certificate:ByteArray` — 包含 DER 編碼 X.509 數位憑證的 ByteArray 物件。

	`trusted:Boolean` — 設定為 true，可將這個憑證指定為信任錨點。

擲回值

ArgumentError — 無法加入憑證時，就會擲回錯誤。

connect

()

方法

override public function connect(host:String, port:int):void

語言版本:

ActionScript 3.0

執行階段版本:

Flash Player 11, AIR 2

使用 SSL 或 TLS 將通訊端連線到指定的主機或連接埠。

當您呼叫 SecureSocket.connect() 方法時，通訊端會嘗試與伺服器進行 SSL/TLS 交握。如果交握成功，通訊端就會嘗試驗證伺服器憑證。如果憑證是有效且受信任的，則會建立安全通訊端連線，而且通訊端會傳送 connect 事件。如果交握失敗或無法驗證憑證，通訊端會傳送 IOError 事件。您可以在傳送 IOError 事件之後，透過讀取 serverCertificateStatus 屬性查看憑證驗證結果 (當您傳送 connect 事件時，憑證狀態永遠都是 trusted)。

如果通訊端已經連線，就會先關閉現有的連線。

參數

	`host:String` — 要連線的目標主機名稱或 IP 位址。

	`port:int` — 要連線的目標連接埠號。

事件

	`connect:Event` — 會在網路連線已建立時傳送。

	`ioError:IOErrorEvent` — 在已指定主機，而且發生輸入/輸出錯誤並導致連線失敗時傳送。這個包含 SSL/TLS 交握錯誤及無法成功驗證主機的伺服器憑證。

	`securityError:SecurityErrorEvent` — 當 `Socket.connect()` 呼叫嘗試連線的伺服器未提供通訊端原則檔，或連線的伺服器其原則檔未授與呼叫端主機對指定的連接埠進行存取時傳送。如需原則檔的詳細資訊，請參閱「ActionScript 3.0 開發人員指南」中的「網站控制 (原則檔)」及「Flash Player 開發人員中心」主題：「安全性」。

擲回值

	`IOError` — 未指定主機且連線失敗時，就會擲回錯誤。

	`SecurityError` — 指定的通訊端連接埠低於零或高於 65535 時，就會擲回錯誤。

事件詳細資訊

close

事件

事件物件類型: flash.events.Event
屬性 Event.type = flash.events.Event.CLOSE

語言版本:

ActionScript 3.0

執行階段版本:

Flash Player 11, AIR 2

會在伺服器關閉通訊端連線時傳送。

只有當伺服器關閉連線時，才會傳送 close 事件。當您呼叫 Socket.close() 方法時，則不會傳送此事件。

Event.CLOSE 常數會定義 close 事件物件的 type 屬性值。

這個事件具有下列屬性：

屬性	值
`bubbles`	`false`
`cancelable`	`false`；沒有要取消的預設行為指令。
`currentTarget`	正主動使用事件偵聽程式處理 Event 物件的物件。
`target`	其連線已關閉的物件。

connect

事件

事件物件類型: flash.events.Event
屬性 Event.type = flash.events.Event.CONNECT

語言版本:

ActionScript 3.0

執行階段版本:

Flash Player 11, AIR 2

會在網路連線已建立時傳送。

Event.CONNECT 常數會定義 connect 事件物件的 type 屬性值。

這個事件具有下列屬性：

屬性	值
`bubbles`	`false`
`cancelable`	`false`；沒有要取消的預設行為指令。
`currentTarget`	正主動使用事件偵聽程式處理 Event 物件的物件。
`target`	已建立網路連線的 Socket 或 XMLSocket 物件。

ioError

事件

事件物件類型: flash.events.IOErrorEvent
屬性 IOErrorEvent.type = flash.events.IOErrorEvent.IO_ERROR

語言版本:

ActionScript 3.0

執行階段版本:

Flash Player 11, AIR 2

發生輸入或輸出錯誤，因而導致傳送或接收作業失敗時傳送。

無法驗證伺服器憑證時，傳送的錯誤事件是一種 IOError。在此情況下，您可以檢查 serverCertificateStatus 屬性以判斷造成該問題的原因。

定義 ioError 事件物件的 type 屬性值。

這個事件具有下列屬性：

屬性	值
`bubbles`	`false`
`cancelable`	`false`；沒有要取消的預設行為指令。
`currentTarget`	正主動使用事件偵聽程式處理 Event 物件的物件。
`errorID`	與特定錯誤相關聯的參考號碼 (僅限 AIR)。
`target`	遭遇輸入/輸出錯誤的網路物件。
`text`	要顯示為錯誤訊息的文字。

securityError

事件

事件物件類型: flash.events.SecurityErrorEvent
屬性 SecurityErrorEvent.type = flash.events.SecurityErrorEvent.SECURITY_ERROR

語言版本:

ActionScript 3.0

執行階段版本:

Flash Player 11, AIR 2

當對 SecureSocket.connect() 的呼叫因為安全性限制而失敗時傳送。

當在應用程式安全執行程序以外的 Flash Player 或 AIR 中執行的程式碼嘗試連線到不同網域中的伺服器，或是連線到小於 1024 的連接埠且伺服器未提供允許連線的原則檔案時，會傳送安全性錯誤事件。請注意，在 AIR 應用程式安全執行程序內執行的程式碼可以連線到位於任何網域的伺服器，也可以在沒有原則檔案的情況下連線到小於 1024 的連接埠。

SecurityErrorEvent.SECURITY_ERROR 常數會定義 securityError 事件物件的 type 屬性值。

這個事件具有下列屬性：

屬性	值
`bubbles`	`false`
`cancelable`	`false`；沒有要取消的預設行為指令。
`currentTarget`	正主動使用事件偵聽程式處理 Event 物件的物件。
`target`	回報安全性錯誤的網路物件。
`text`	要顯示為錯誤訊息的文字。

相關 API 元素

SecureSocket.connect()

socketData

事件

事件物件類型: flash.events.ProgressEvent
屬性 ProgressEvent.type = flash.events.ProgressEvent.SOCKET_DATA

語言版本:

ActionScript 3.0

執行階段版本:

Flash Player 11, AIR 2

在通訊端收到資料時傳送。類型為 socketData 的事件不會使用 ProgressEvent.bytesTotal 屬性。

定義 socketData 事件物件的 type 屬性值。

這個事件具有下列屬性：

屬性	值
`bubbles`	`false`
`cancelable`	`false`；沒有要取消的預設行為指令。
`currentTarget`	主動處理 Event 的物件。
`bytesLoaded`	在偵聽程式處理事件時，載入的項目或位元組數目。
`bytesTotal`	0；`socketData` 事件物件無法使用此屬性。
`target`	回報進度的通訊端。

範例如何使用本範例

SecureSocketExample.as

下列範例說明如何建立和連接 SecureSocket 物件。

package
{
    import flash.display.Sprite;
    import flash.errors.IOError;
    import flash.events.Event;
    import flash.events.IOErrorEvent;
    import flash.net.SecureSocket;
    
    public class SecureSocketExample extends Sprite
    {
        private var secureSocket:SecureSocket = new SecureSocket();
        
        public function SecureSocketExample()
        {
            secureSocket.addEventListener( Event.CONNECT, onConnect )
            secureSocket.addEventListener( IOErrorEvent.IO_ERROR, onError );
            
            try
            {
                secureSocket.connect( "208.77.188.166", 443 );
            }
            catch ( error:Error )
            {
                trace ( error.toString() );
            }
        }
        
        private function onConnect( event:Event ):void
        {
            trace("Connected.");
        }
        
        private function onError( error:IOErrorEvent ):void
        {
            trace( error.text + ", " + secureSocket.serverCertificateStatus );
        }
    }
}

法律聲明 | 線上隱私權政策

SecureSocket - AS3

類別 x

isSupported

serverCertificate

serverCertificateStatus

SecureSocket

addBinaryChainBuildingCertificate

connect

close

connect

ioError

securityError

socketData