SSLOn (Socket function): Difference between revisions
m (→Syntax terms) |
mNo edit summary |
||
| Line 1: | Line 1: | ||
{{Template:Socket:SSLOn subtitle}} | {{Template:Socket:SSLOn subtitle}} | ||
This [[Notation conventions for methods#Callable functions|callable]] method turns on SSL processing, that is, starts an SSL handshake as a client | |||
on a connection. | |||
<var>SSLOn</var> has an effect similar to <var>[[$Sock_Ssl_On]]</var>. | |||
==Syntax== | ==Syntax== | ||
{{Template:Socket:SSLOn syntax}} | {{Template:Socket:SSLOn syntax}} | ||
===Syntax terms=== | ===Syntax terms=== | ||
<table class="syntaxTable"> | <table class="syntaxTable"> | ||
<tr><th>%number</th><td> | <tr><th>%number</th> | ||
<td>This is a numeric variable to contain the returned indicator of success of the function. | |||
The possible return values are listed in [[#Return codes|"Return codes"]] below. </td></tr> | |||
<tr><th>socket</th> | <tr><th>socket</th> | ||
<td>A variable or an expression that is a reference to a <var>Socket</var> object.</td></tr> | <td>A variable or an expression that is a reference to a <var>Socket</var> object.</td></tr> | ||
</table> | |||
===Return codes=== | |||
The method's return value (<var class="term">%number</var>) is one of these: | |||
<table> | |||
<tr><th> 0</th> | |||
<td>Successfully switched to SSL.</td></tr> | |||
<tr><th>-110</th> | |||
<td>Attempted on non-SSL port. <var>SSLOn</var> can only be attempted on a port with <var>[[SSL]]</var> and <var>[[SSLOPT]]</var> on the <var>[[JANUS DEFINE]]</var> command.</td></tr> | |||
<tr><th>-111</th> | |||
<td>SSL handshake error. Likely result of trying to use the <var>SSLOn</var> method against a non-SSL port.</td></tr> | |||
<tr><th>-112</th> | |||
<td>Have pending incoming data. The <var>SSLOn</var> method is invalid until all incoming (presumably) non-SSL data has been received.</td></tr> | |||
<tr><th>-149</th> | |||
<td>Other error during connection.</td></tr> | |||
</table> | </table> | ||
==Usage notes== | ==Usage notes== | ||
<ul> | |||
<li><var>SSLOn</var> makes it possible to: | |||
<ol> | |||
<li>Make an initial connection from a <var class="product">Janus Sockets</var> client application to a proxy server | |||
<li>Issue the HTTP CONNECT | |||
method/command to connect to a server through the proxy | |||
<li>Communicate via SSL with the back end server, simply having the proxy server | |||
act as a "tunnel" for the SSL data | |||
</ol> | |||
As shown in [[#Examples|"Examples"]] below, the <var>SSLOn</var> method should be | |||
used after a positive response has been received for a CONNECT method | |||
request on a <var class="product">Janus Sockets</var> client socket. | |||
</ul> | |||
==Examples== | ==Examples== | ||
The following code shows the use of the <var>SSLOn</var> method; | |||
<p class="code">%sock is Object <var>Socket</var> | |||
%sock = New('WEBDROPS', 'proxy') | |||
%r = %sock:Set('LINEND', '0D0A') | |||
%r = %sock:Set('PRSTOK', '0D0A') | |||
%r = %sock:Send('CONNECT ') | |||
%r = %sock:Send('sirius-software.com:443') | |||
%r = %sock:SendWithLineEnd(' HTTP/1.0') | |||
%r = %sock:SendWithLineEnd('') | |||
%r = %sock:ReceiveAndParse(%s) | |||
If $WORD(%s, , 2) Ne '200' Then | |||
Call CONNECT_ERROR | |||
End If | |||
Repeat Forever | |||
%r = %sock:ReceiveAndParse(%s) | |||
If $LSTR_LEN(%s) Eq 0 Then | |||
Loop End | |||
End If | |||
End Repeat | |||
%r = %sock:SSLOn | |||
If %r Then | |||
Call SSL_ERROR | |||
End If | |||
%r = %sock:Send('GET ') | |||
%r = %sock:Send(%URL) | |||
%r = %sock:SendWithLineEnd(' HTTP/1.0') | |||
%r = %sock:SendWithLineEnd('') | |||
... | |||
</p> | |||
For more information about HTTP tunneling and the CONNECT method, see | |||
http://www.ietf.org/rfc/rfc2817.txt. | |||
Many other references are also available on the web. | |||
==See also== | ==See also== | ||
{{Template:Socket:SSLOn footer}} | {{Template:Socket:SSLOn footer}} | ||
Revision as of 18:37, 11 June 2012
Turn on SSL processing (Socket class)
This callable method turns on SSL processing, that is, starts an SSL handshake as a client on a connection. SSLOn has an effect similar to $Sock_Ssl_On.
Syntax
[%number =] socket:SSLOn
Syntax terms
| %number | This is a numeric variable to contain the returned indicator of success of the function. The possible return values are listed in "Return codes" below. |
|---|---|
| socket | A variable or an expression that is a reference to a Socket object. |
Return codes
The method's return value (%number) is one of these:
| 0 | Successfully switched to SSL. |
|---|---|
| -110 | Attempted on non-SSL port. SSLOn can only be attempted on a port with SSL and SSLOPT on the JANUS DEFINE command. |
| -111 | SSL handshake error. Likely result of trying to use the SSLOn method against a non-SSL port. |
| -112 | Have pending incoming data. The SSLOn method is invalid until all incoming (presumably) non-SSL data has been received. |
| -149 | Other error during connection. |
Usage notes
- SSLOn makes it possible to:
- Make an initial connection from a Janus Sockets client application to a proxy server
- Issue the HTTP CONNECT method/command to connect to a server through the proxy
- Communicate via SSL with the back end server, simply having the proxy server act as a "tunnel" for the SSL data
As shown in "Examples" below, the SSLOn method should be used after a positive response has been received for a CONNECT method request on a Janus Sockets client socket.
Examples
The following code shows the use of the SSLOn method;
%sock is Object Socket %sock = New('WEBDROPS', 'proxy') %r = %sock:Set('LINEND', '0D0A') %r = %sock:Set('PRSTOK', '0D0A') %r = %sock:Send('CONNECT ') %r = %sock:Send('sirius-software.com:443') %r = %sock:SendWithLineEnd(' HTTP/1.0') %r = %sock:SendWithLineEnd() %r = %sock:ReceiveAndParse(%s) If $WORD(%s, , 2) Ne '200' Then Call CONNECT_ERROR End If Repeat Forever %r = %sock:ReceiveAndParse(%s) If $LSTR_LEN(%s) Eq 0 Then Loop End End If End Repeat %r = %sock:SSLOn If %r Then Call SSL_ERROR End If %r = %sock:Send('GET ') %r = %sock:Send(%URL) %r = %sock:SendWithLineEnd(' HTTP/1.0') %r = %sock:SendWithLineEnd() ...
For more information about HTTP tunneling and the CONNECT method, see http://www.ietf.org/rfc/rfc2817.txt. Many other references are also available on the web.