flash.net.SecureSocket - Adobe® Flex® 4 Language Reference (Flex 4)

Package	flash.net
Class	public class SecureSocket
Inheritance	SecureSocket Socket EventDispatcher Object

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 2

The SecureSocket class enables code to make socket connections utilizing the Secure Sockets Layer (SSL) and Transport Layer Security (TLS) protocols.

The SSL/TLS protocols provide a mechanism by which the identity of a host can be authenticated via its certificate, and provides for encrypted communication over the socket. SSLv3 and TLSv1 are supported. Validation of the server certificate is performed using the trust store and certificate validation support of the client platform.

The SecureSocket class will only connect to servers with valid, trusted certificates. You cannot choose to connect to a server in spite of a problem with it's certificate. For example, there is no way to connect to a server with an expired certificate or a certificate that doesn't chain to a trusted root certificate even though the certificate would be valid otherwise.

The SecureSocket class is useful for performing encrypted communication to a trusted server. In other respects a SecureSocket object behaves like a regular Socket object.

To use the methods of the SecureSocket class, first use the constructor, new SecureSocket(), to create a SecureSocket object. When you connect to a server, the server certificate is validated. If the certificate is valid and trusted, the connection is established and the Socket dispatches a connect event. If the certificate cannot be validated, the Socket dispatches an IOError event.

Important: The Online Certificate Status Protocol (OCSP) is not supported by all operating systems. Users can also disable OCSP checking on individual computers. If OCSP is not supported or is disabled and a certificate does not contain the information necessary to check revocation using a Certificate Revocation List (CRL), then certificate revocation is not checked. The certificate is accepted if otherwise valid. This could allow a server to use a revoked certificate.

View the examples

See also

Socket class

Public Properties

Hide Inherited Public Properties

Show Inherited Public Properties

	Property		Defined By
		bytesAvailable : uint [read-only] The number of bytes of data available for reading in the input buffer.	Socket
		connected : Boolean [read-only] Indicates whether this Socket object is currently connected.	Socket
		constructor : Object A reference to the class object or constructor function for a given object instance.	Object
		endian : String Indicates the byte order for the data.	Socket
		isSupported : Boolean [static] [read-only] Indicates whether the secure sockets are supported on the current system.	SecureSocket
		localAddress : String [read-only] The IP address this socket is bound to on the local machine.	Socket
		localPort : int [read-only] The port this socket is bound to on the local machine.	Socket
		objectEncoding : uint Controls the version of AMF used when writing or reading an object.	Socket
		prototype : Object [static] A reference to the prototype object of a class or function object.	Object
		remoteAddress : String [read-only] The IP address of the remote machine to which this socket is connected.	Socket
		remotePort : int [read-only] The port on the remote machine to which this socket is connected.	Socket
		serverCertificateStatus : String [read-only] The status of the server's certificate.	SecureSocket
		timeout : uint Indicates the number of milliseconds to wait for a connection.	Socket

Public Methods

Hide Inherited Public Methods

Show Inherited Public Methods

	Method		Defined By
		SecureSocket() Creates a new SecureSocket object.	SecureSocket
		addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void Registers an event listener object with an EventDispatcher object so that the listener receives notification of an event.	EventDispatcher
		close():void Closes the socket.	Socket
		connect(host:String, port:int):void [override] Connects the socket to the specified host and port using SSL or TLS.	SecureSocket
		dispatchEvent(event:Event):Boolean Dispatches an event into the event flow.	EventDispatcher
		flush():void Flushes any accumulated data in the socket's output buffer.	Socket
		hasEventListener(type:String):Boolean Checks whether the EventDispatcher object has any listeners registered for a specific type of event.	EventDispatcher
		hasOwnProperty(name:String):Boolean Indicates whether an object has a specified property defined.	Object
		isPrototypeOf(theClass:Object):Boolean Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter.	Object
		propertyIsEnumerable(name:String):Boolean Indicates whether the specified property exists and is enumerable.	Object
		readBoolean():Boolean Reads a Boolean value from the socket.	Socket
		readByte():int Reads a signed byte from the socket.	Socket
		readBytes(bytes:ByteArray, offset:uint = 0, length:uint = 0):void Reads the number of data bytes specified by the length parameter from the socket.	Socket
		readDouble():Number Reads an IEEE 754 double-precision floating-point number from the socket.	Socket
		readFloat():Number Reads an IEEE 754 single-precision floating-point number from the socket.	Socket
		readInt():int Reads a signed 32-bit integer from the socket.	Socket
		readMultiByte(length:uint, charSet:String):String Reads a multibyte string from the byte stream, using the specified character set.	Socket
		readObject():* Reads an object from the socket, encoded in AMF serialized format.	Socket
		readShort():int Reads a signed 16-bit integer from the socket.	Socket
		readUnsignedByte():uint Reads an unsigned byte from the socket.	Socket
		readUnsignedInt():uint Reads an unsigned 32-bit integer from the socket.	Socket
		readUnsignedShort():uint Reads an unsigned 16-bit integer from the socket.	Socket
		readUTF():String Reads a UTF-8 string from the socket.	Socket
		readUTFBytes(length:uint):String Reads the number of UTF-8 data bytes specified by the length parameter from the socket, and returns a string.	Socket
		removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void Removes a listener from the EventDispatcher object.	EventDispatcher
		setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Sets the availability of a dynamic property for loop operations.	Object
		toLocaleString():String Returns the string representation of this object, formatted according to locale-specific conventions.	Object
		toString():String Returns the string representation of the specified object.	Object
		valueOf():Object Returns the primitive value of the specified object.	Object
		willTrigger(type:String):Boolean Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type.	EventDispatcher
		writeBoolean(value:Boolean):void Writes a Boolean value to the socket.	Socket
		writeByte(value:int):void Writes a byte to the socket.	Socket
		writeBytes(bytes:ByteArray, offset:uint = 0, length:uint = 0):void Writes a sequence of bytes from the specified byte array.	Socket
		writeDouble(value:Number):void Writes an IEEE 754 double-precision floating-point number to the socket.	Socket
		writeFloat(value:Number):void Writes an IEEE 754 single-precision floating-point number to the socket.	Socket
		writeInt(value:int):void Writes a 32-bit signed integer to the socket.	Socket
		writeMultiByte(value:String, charSet:String):void Writes a multibyte string from the byte stream, using the specified character set.	Socket
		writeObject(object:*):void Write an object to the socket in AMF serialized format.	Socket
		writeShort(value:int):void Writes a 16-bit integer to the socket.	Socket
		writeUnsignedInt(value:uint):void Writes a 32-bit unsigned integer to the socket.	Socket
		writeUTF(value:String):void Writes the following data to the socket: a 16-bit unsigned integer, which indicates the length of the specified UTF-8 string in bytes, followed by the string itself.	Socket
		writeUTFBytes(value:String):void Writes a UTF-8 string to the socket.	Socket

Events

Click for more information on events

Hide Inherited Events

Show Inherited Events

	Summary	Defined By
activate	[broadcast event] Dispatched when the Flash Player or AIR application gains operating system focus and becomes active.	EventDispatcher
close	Dispatched when the server closes the socket connection.	SecureSocket
connect	Dispatched when a network connection has been established.	SecureSocket
deactivate	[broadcast event] Dispatched when the Flash Player or AIR application operating loses system focus and is becoming inactive.	EventDispatcher
ioError	Dispatched when an input or output error occurs that causes a send or receive operation to fail.	SecureSocket
securityError	Dispatched if a call to Socket.connect() attempts to connect to a server prohibited by the caller's security sandbox or to a port lower than 1024 and no socket policy file exists to permit such a connection.	Socket
socketData	Dispatched when a socket has received data.	SecureSocket

Property Detail

isSupported

property

isSupported:Boolean [read-only]

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 2

Indicates whether the secure sockets are supported on the current system.

Secure sockets are not supported on all platforms. Check this property before attempting to create a new SecureSocket instance.

Implementation
public static function get isSupported():Boolean

serverCertificateStatus

property

serverCertificateStatus:String [read-only]

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 2

The status of the server's certificate.

The status is CertificateStatus.UNKNOWN until the socket attempts to connect to a server. After validation, the status will be one of the strings enumerated by the CertificateStatus class. The connection only succeeds when the certificate is valid and trusted. Thus, after a connect event, the status is always trusted.

Note: Once the certificate has been validated or rejected, the status value is not updated until the next call to the connect() method. Calling close() does not reset the status value to "unknown".

Implementation
public function get serverCertificateStatus():String

SecureSocket

()

Constructor

public function SecureSocket()

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 2

Creates a new SecureSocket object.

Check SecureSocket.isSupported before attempting to create a SecureSocket instance. If SSLv3 or TLSv1 sockets are not supported, the runtime will throw an IllegalOperationError.

Throws

IllegalOperationError — This error occurs when SSLv3 or TLSv1 support is not available.

Method Detail

connect

()

method

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

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 2

Connects the socket to the specified host and port using SSL or TLS.

When you call the connect() method, the server certificate is validated. If the SSL/TLS handshake succeeds and the certificate is valid and trusted, the connection is established, the socket dispatches a connect event. If the handshake fails or the certificate cannot be validated, the socket dispatches an IOError event. You can check the certificate validation result by reading the serverCertificateStatus property after one of these events has been dispatched. (When a connect event is dispatched, the certificate status is always trusted.)

If the socket is already connected, the existing connection is closed first.

Parameters

	`host:String` — The name or IP address of the host to connect to.

	`port:int` — The port number to connect to.

Events

	`connect:Event` — Dispatched when a network connection has been established.

	`ioError:IOErrorEvent` — Dispatched if a host is specified and an input/output error occurs that causes the connection to fail. This includes SSL/TLS handshake errors and failure to successfully validate the host's server certificate.

Throws

	`IOError` — No host was specified and the connection failed.

	`SecurityError` — This error occurs if you specify a socket port less than zero or higher than 65535.

Event Detail

close

Event

Event Object Type: flash.events.Event
property Event.type = flash.events.Event.CLOSE

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 2

Dispatched when the server closes the socket connection.

The close event is dispatched only when the server closes the connection; it is not dispatched when you call the SecureSocket.close() method.

The Event.CLOSE constant defines the value of the type property of a close event object.

This event has the following properties:

Property	Value
`bubbles`	`false`
`cancelable`	`false`; there is no default behavior to cancel.
`currentTarget`	The object that is actively processing the Event object with an event listener.
`target`	The object whose connection has been closed.

connect

Event

Event Object Type: flash.events.Event
property Event.type = flash.events.Event.CONNECT

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 2

Dispatched when a network connection has been established.

The Event.CONNECT constant defines the value of the type property of a connect event object.

This event has the following properties:

Property	Value
`bubbles`	`false`
`cancelable`	`false`; there is no default behavior to cancel.
`currentTarget`	The object that is actively processing the Event object with an event listener.
`target`	The Socket or XMLSocket object that has established a network connection.

ioError

Event

Event Object Type: flash.events.IOErrorEvent
property IOErrorEvent.type = flash.events.IOErrorEvent.IO_ERROR

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 2

Dispatched when an input or output error occurs that causes a send or receive operation to fail.

When a server certificate cannot be validated, the error event dispatched is an IOError. In this case, you can check the serverCertificateStatus property to determine the cause of the problem.

Defines the value of the type property of an ioError event object.

This event has the following properties:

Property	Value
`bubbles`	`false`
`cancelable`	`false`; there is no default behavior to cancel.
`currentTarget`	The object that is actively processing the Event object with an event listener.
`errorID`	A reference number associated with the specific error (AIR only).
`target`	The network object experiencing the input/output error.
`text`	Text to be displayed as an error message.

socketData

Event

Event Object Type: flash.events.ProgressEvent
property ProgressEvent.type = flash.events.ProgressEvent.SOCKET_DATA

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 2

Dispatched when a socket has received data. Events of type socketData do not use the ProgressEvent.bytesTotal property.

Defines the value of the type property of a socketData event object.

This event has the following properties:

Property	Value
`bubbles`	`false`
`cancelable`	`false`; there is no default behavior to cancel.
`currentTarget`	The object that is actively processing the Event.
`bytesLoaded`	The number of items or bytes loaded at the time the listener processes the event.
`bytesTotal`	0; this property is not used by `socketData` event objects.
`target`	The socket reporting progress.

Examples How to use this example

SecureSocketExample.as

The following example illustrates how to create and connect a SecureSocket object.

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 );
        }
    }
}