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 设备都支持此功能。在移动设备上，Android 以及 AIR 20 以上版本的 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: Error #2004”

SecureSocket 类仅连接到具有有效的受信任证书的服务器。您无法选择连接到证书存在问题的服务器。例如，无法连接到证书过期的服务器。对于没有链接到受信锚点证书的证书也同样如此。即使证书为有效证书也不会建立连接。

SecureSocket 类在执行与受信任服务器的加密通信时很有用。在其他方面，SecureSocket 对象与常规 Socket 对象相同。

若要使用 SecureSocket 类，请创建一个 SecureSocket 对象 (new SecureSocket())。接着，设置侦听器，然后运行 SecureSocket.connect(host, port)。成功连接到服务器后，该套接字会调度 connect 事件。成功连接是指服务器的安全协议受支持并且其证书有效、可信。如果证书没有通过验证，则 Socket 将调度 IOError 事件。

重要信息：并非所有操作系统都支持联机证书状态协议 (OCSP)。用户也可以在各计算机上禁用 OCSP 检查。如果不支持或已禁用 OCSP，并且证书中不包含使用证书吊销列表 (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 从套接字读取一个布尔值。	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 将一个布尔值写入套接字。	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() 不会将状态值重置为“unknown”。

实现
public function get serverCertificateStatus():String

()

构造函数

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 文件无法与 Internet 通信。您可以通过将此 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 握手。如果握手成功，套接字将尝试验证服务器证书。如果该证书有效且可信，则建立安全套接字连接，并且 Socket 将调度 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`	要显示为错误消息的文本。

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`	当前正在处理此事件的对象。
`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

语言元素

附录

包 flash.net

isSupported

serverCertificate

serverCertificateStatus

SecureSocket

addBinaryChainBuildingCertificate

connect

close

connect

ioError

securityError

socketData