class SecureSocket
package openfl.net
extends Socket › EventDispatcher
Available on all platforms
The SecureSocket class enables code to make socket connections using the Secure Sockets Layer (SSL) and Transport Layer Security (TLS) protocols.
You can test for support at run time using the SecureSocket.isSupported
property.
OpenFL target support: This feature is supported on all desktop operating systems, on iOS, and on Android. It is not supported on non-sys targets.
Adobe AIR profile support: This feature is supported on all desktop operating systems, but is not supported on all AIR for TV devices. On mobile devices, it is supported on Android and also supported on iOS starting from AIR 20. See AIR Profile Support for more information regarding API support across multiple profiles.
The SSL/TLS protocols provide a mechanism to handle both aspects of a secure socket connection:
- Encryption of data communication over the socket
- Authentication of the host's identity via its certificate
The supported encryption protocols are SSL 3.1 and higher, and TLS 1.0 and higher. (TLS is the successor protocol for SSL. TLS 1.0 equals SSL 3.1, TLS 1.1 equals SSL 3.2, and so on.) SSL versions 3.0 or lower are not supported.
Validation of the server certificate is performed using the trust store and
certificate validation support of the client platform. In addition you can
add your own certificates programmatically with the
addBinaryChainBuildingCertificate()
method. This API isn't supported on
all systems currently. Using this API on some systems will throw an
exception - "ArgumentError: Error #2004"
The SecureSocket class only connects to servers with valid, trusted certificates. You cannot choose to connect to a server in spite of a problem with its certificate. For example, there is no way to connect to a server with an expired certificate. The same is true for a certificate that doesn't chain to a trusted anchor certificate. The connection will not be made, 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 SecureSocket class, create a SecureSocket object
(new SecureSocket()
). Next, set up your listeners, and then run
SecureSocket.connect(host, port)
. When you successfully connect to the
server, the socket dispatches a connec
t event. A successful connection is
one in which the server's security protocols are supported and its
certificate is valid and trusted. 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 scenario could allow a server to use a revoked certificate.
Events:
close | Dispatched when the server closes the socket connection. |
---|---|
connect | Dispatched when a network connection has been established. |
ioError | Dispatched when an input or output error occurs that causes a send or receive operation to fail. |
securityError | Dispatched when a call to SecureSocket.connect() fails because of a security restriction. |
socketData | Dispatched when a socket has received data. |
Static variables
staticread onlyisSupported:Bool
Indicates whether secure sockets are supported on the current system.
Secure sockets are not supported on all platforms. Check this property before attempting to create a SecureSocket instance.
Constructor
new()
Creates a new SecureSocket object.
Check SecureSocket.isSupported
before attempting to create a
SecureSocket instance. If SSL 3.0 or TLS 1.0 sockets are not supported,
the runtime will throw an IllegalOperationError.
Throws:
IllegalOperationError | When SSL Version 3.0 (and higher) or TLS Version 1.0 (and higher) is not supported. |
---|---|
SecurityError | Local untrusted SWF files cannot communicate with the Internet. You can work around this problem by reclassifying this SWF file as local-with-networking or trusted. |
Variables
read onlyserverCertificate:X509Certificate
Holds the X.509 certificate obtained from the server after a secure
SSL/TLS connection is established. If a secure connection is not
established, this property is set to null
.
For more information on X.509 certificates, see RFC2459.
read onlyserverCertificateStatus:CertificateStatus
Returns 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 is 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 value of serverCertificateStatus
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".
Methods
addBinaryChainBuildingCertificate(certificate:ByteArray, trusted:Bool):Void
Adds an X.509 certificate to the local certificate chain that your system uses for validating the server certificate. The certificate is temporary, and lasts for the duration of the session.
Server certificate validation relies on your system's trust store for certificate chain building and validation. Use this method to programmatically add additional certification chains and trusted anchors.
On Mac OS, the System keychain is the default keychain used during the SSL/TLS handshake process. Any intermediate certificates in that keychain are included when building the certification chain.
The certificate you add with this API must be a DER-encoded X.509 certificate. If the trusted parameter is true, the certificate you add with this API is considered a trusted anchor.
For more information on X.509 certificates, see RFC2459.
Parameters:
certificate | A ByteArray object containing a DER-encoded X.509 digital certificate. |
---|---|
trusted | Set to true to designate this certificate as a trust anchor. |
Throws:
ArgumentError | When the certificate cannot be added. |
---|
connect(host:String, port:Int):Void
Connects the socket to the specified host and port using SSL or TLS.
When you call the SecureSocket.connect()
method, the socket attempts
SSL/TLS handshaking with the server. If the handshake succeeds, the
socket attempts to validate the server certificate. If the certificate
is valid and trusted, then the secure socket connection is established,
and 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 the IOError
event is
dispatched. (When a connect
event is dispatched, the certificate
status is always trusted
.)
If the socket was already connected, the existing connection is closed first.
Parameters:
host | The name or IP address of the host to connect to. |
---|---|
port | The port number to connect to. |
Throws:
IOError | When you don't specify a host and the connection fails. |
---|---|
SecurityError | When you specify a socket port less than zero or higher than 65535. |