<doc>
	<legacy_id></legacy_id>
	<name>secure socket</name>
	<type>command</type>

	<syntax>
		<example>secure socket <i>socket</i> [without verification]</example>
		<example>secure socket <i>socket</i> [with verification [for host verificationHostName]]</example>
	</syntax>

	<synonyms>
	</synonyms>

	<summary>Secures an open socket.</summary>

	<examples>
<example>secure socket "runrev.com:443"</example>
<example>open socket to "127.0.0.0:8080"
write "unencrypted message" to socket "127.0.0.0:8080"
secure socket "127.0.0.0:8080"
write "encrypted message" to socket "127.0.0.0:8080"</example>
<example>secure socket mySocket with verifcation for host "livecode.com"</example>
	</examples>

	<history>
		<introduced version="6.6">Added.</introduced>
		<deprecated version=""></deprecated>
		<removed version=""></removed>
		<changed version="6.7">Added verification for host variant</changed>
		<experimental version=""></experimental>
		<nonexperimental version=""></nonexperimental>
	</history>

	<objects>
	</objects>

	<platforms>
		<mac/>
		<windows/>
		<linux/>
	</platforms>

	<classes>
		<desktop/>
	</classes>

	<security>
		<network/>
	</security>


	<classification>
		<category>Files, Folders, &amp; Resources</category>
		<category>Standalone Applications</category>
	</classification>

	<references>
		<command tag="open socket">open socket Command</command>
		<property tag="sslCertificates">sslCertificates Property</property>
		<message tag="socketError">socketError Message</message>
	</references>

	<description>
	<overview>Use the <b>secure socket </b>command to secure an open socket.</overview>

		<parameters>
  <parameter>
    <name>socket</name>
    <description>A reference to an open socket.</description>
  </parameter>
  <parameter>
    <name>verificationHostName</name>
    <description>The IP address or domain name of the host you want to verify against.</description>
  </parameter>		</parameters>

	<value></value>
	<comments>If 'with verification' is specified, when connecting to a remote peer, the client verifies the peers certificate during the handshake process. The <property tag="sslCertificates">sslCertificates property</property> can be used to specify a list of certificates to verify against. In addition you can place system wide certificates in System/Library/OpenSSL/certs. If a verificationhostname is specified, the socket will be verified against that verificationhostname. An example of this is when you want to create a secure connection with a host while tunnelling through a proxy. Specifying the final host allows LiveCode to verify the socket against that host, rather than the proxy server.<p></p><p>If 'without verification' is specified then peers credentials are not authenticated, and any connection is accepted.</p><p></p><p>Once secured:</p><p>* All pending and future reads from the socket will be assumed to be encrypted.</p><p>* All pending writes will complete unencrypted. All future writes will be encrypted.</p><p></p><p>If the socket fails secure, a <message tag="socketError">socketError message</message> is sent to the object that opened the socket (not the object that attempted to secure it).</p><p></p><p></p><important> The secure secure socket command is part of the SSL &amp; Encryption library. To ensure that the command works in a standalone application, you must include this custom library when you create your standalone. In the Inclusions section on the General screen of the Standalone Application Settings window, make sure "SSL &amp; Encryption" is selected in the list of script libraries.</important><p>&#9;</p></comments>
	</description>
</doc>