<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Module ranch_ssl</title>
<link rel="stylesheet" type="text/css" href="stylesheet.css" title="EDoc">
</head>
<body bgcolor="white">
<div class="navbar"><a name="#navbar_top"></a><table width="100%" border="0" cellspacing="0" cellpadding="2" summary="navigation bar"><tr><td><a href="overview-summary.html" target="overviewFrame">Overview</a></td><td><a href="http://www.erlang.org/"><img src="erlang.png" align="right" border="0" alt="erlang logo"></a></td></tr></table></div>
<hr>
<h1>Module ranch_ssl</h1>
<ul class="index"><li><a href="#description">Description</a></li><li><a href="#index">Function Index</a></li><li><a href="#functions">Function Details</a></li></ul>SSL transport API.
<p><b>Behaviours:</b> <a href="ranch_transport.html"><tt>ranch_transport</tt></a>.</p>
<p><b>See also:</b> <a href="ssl.html">ssl</a>.</p>
<h2><a name="description">Description</a></h2><p>SSL transport API.</p>
<p>Wrapper around <em>ssl</em> implementing the Ranch transport API.</p>
This transport requires the <em>crypto</em>, <em>public_key</em>
and <em>ssl</em> applications to be started. If they aren't started,
it will try to start them itself before opening a port to listen.
Applications aren't stopped when the listening socket is closed, though.
<h2><a name="index">Function Index</a></h2>
<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#accept-2">accept/2</a></td><td>Accept connections with the given listening socket.</td></tr>
<tr><td valign="top"><a href="#close-1">close/1</a></td><td>Close the given socket.</td></tr>
<tr><td valign="top"><a href="#controlling_process-2">controlling_process/2</a></td><td>Give control of the socket to a new process.</td></tr>
<tr><td valign="top"><a href="#listen-1">listen/1</a></td><td>Listen for connections on the given port number.</td></tr>
<tr><td valign="top"><a href="#messages-0">messages/0</a></td><td>Atoms used to identify messages in {active, once | true} mode.</td></tr>
<tr><td valign="top"><a href="#name-0">name/0</a></td><td>Name of this transport, <em>ssl</em>.</td></tr>
<tr><td valign="top"><a href="#peername-1">peername/1</a></td><td>Return the remote address and port of the connection.</td></tr>
<tr><td valign="top"><a href="#recv-3">recv/3</a></td><td>Receive data from a socket in passive mode.</td></tr>
<tr><td valign="top"><a href="#send-2">send/2</a></td><td>Send data on a socket.</td></tr>
<tr><td valign="top"><a href="#sendfile-2">sendfile/2</a></td><td>Send a file on a socket.</td></tr>
<tr><td valign="top"><a href="#setopts-2">setopts/2</a></td><td>Set options on the given socket.</td></tr>
<tr><td valign="top"><a href="#sockname-1">sockname/1</a></td><td>Return the local address and port of the connection.</td></tr>
</table>
<h2><a name="functions">Function Details</a></h2>
<h3 class="function"><a name="accept-2">accept/2</a></h3>
<div class="spec">
<p><tt>accept(LSocket::<a href="ssl.html#type-sslsocket">ssl:sslsocket()</a>, Timeout::timeout()) -> {ok, <a href="ssl.html#type-sslsocket">ssl:sslsocket()</a>} | {error, closed | timeout | atom() | tuple()}</tt><br></p>
</div><p><p>Accept connections with the given listening socket.</p>
Note that this function does both the transport accept and
the SSL handshake. The returned socket is thus fully connected.
</p>
<p><b>See also:</b> <a href="ssl.html#ssl_accept-2">ssl:ssl_accept/2</a>, <a href="ssl.html#transport_accept-2">ssl:transport_accept/2</a>.</p>
<h3 class="function"><a name="close-1">close/1</a></h3>
<div class="spec">
<p><tt>close(Socket::<a href="ssl.html#type-sslsocket">ssl:sslsocket()</a>) -> ok</tt><br></p>
</div><p>Close the given socket.</p>
<p><b>See also:</b> <a href="ssl.html#close-1">ssl:close/1</a>.</p>
<h3 class="function"><a name="controlling_process-2">controlling_process/2</a></h3>
<div class="spec">
<p><tt>controlling_process(Socket::<a href="ssl.html#type-sslsocket">ssl:sslsocket()</a>, Pid::pid()) -> ok | {error, closed | not_owner | atom()}</tt><br></p>
</div><p><p>Give control of the socket to a new process.</p>
Must be called from the process currently controlling the socket,
otherwise an {error, not_owner} tuple will be returned.
</p>
<p><b>See also:</b> <a href="ssl.html#controlling_process-2">ssl:controlling_process/2</a>.</p>
<h3 class="function"><a name="listen-1">listen/1</a></h3>
<div class="spec">
<p><tt>listen(Opts::[{backlog, non_neg_integer()} | {cacertfile, string()} | {certfile, string()} | {ciphers, [<a href="ssl.html#type-erl_cipher_suite">ssl:erl_cipher_suite()</a>] | string()} | {fail_if_no_peer_cert, boolean()} | {ip, <a href="inet.html#type-ip_address">inet:ip_address()</a>} | {keyfile, string()} | {next_protocols_advertised, [binary()]} | {nodelay, boolean()} | {password, string()} | {port, <a href="inet.html#type-port_number">inet:port_number()</a>} | {verify, <a href="ssl.html#type-verify_type">ssl:verify_type()</a>}]) -> {ok, <a href="ssl.html#type-sslsocket">ssl:sslsocket()</a>} | {error, atom()}</tt><br></p>
</div><p><p>Listen for connections on the given port number.</p>
<p>Calling this function returns a listening socket that can then
The available options are:</p>
<dl>
<dt>backlog</dt><dd>Maximum length of the pending connections queue.
Defaults to 1024.</dd>
<dt>cacertfile</dt><dd>Optional. Path to file containing PEM encoded
CA certificates (trusted certificates used for verifying a peer
certificate).</dd>
<dt>certfile</dt><dd>Mandatory. Path to a file containing the user's
certificate.</dd>
<dt>ciphers</dt><dd>Optional. The cipher suites that should be supported.
The function ssl:cipher_suites/0 can be used to find all available
ciphers.</dd>
<dt>fail_if_no_peer_cert</dt><dd>Optional. Used together with {verify, verify_peer}.
If set to true, the server will fail if the client does not have a certificate
to send, i.e. sends a empty certificate, if set to false (that is by default)
it will only fail if the client sends an invalid certificate (an empty
certificate is considered valid).</dd>
<dt>ip</dt><dd>Interface to listen on. Listen on all interfaces
by default.</dd>
<dt>keyfile</dt><dd>Optional. Path to the file containing the user's
private PEM encoded key.</dd>
<dt>next_protocols_advertised</dt><dd>Optional. Erlang R16B+ required.
List of protocols advertised by TLS Next Protocol Negotiation
extension.</dd>
<dt>nodelay</dt><dd>Optional. Enable TCP_NODELAY. Enabled by default.</dd>
<dt>password</dt><dd>Optional. String containing the user's password.
All private keyfiles must be password protected currently.</dd>
<dt>port</dt><dd>TCP port number to open. Defaults to 0 (see below)</dd>
<dt>verify</dt><dd>Optional. If set to verify_peer, performs an x509-path
validation and request the client for a certificate.</dd>
</dl>
You can listen to a random port by setting the port option to 0.
It is then possible to retrieve this port number by calling
sockname/1 on the listening socket. If you are using Ranch's
listener API, then this port number can obtained through
ranch:get_port/1 instead.
</p>
<p><b>See also:</b> <a href="ssl.html#listen-2">ssl:listen/2</a>.</p>
<h3 class="function"><a name="messages-0">messages/0</a></h3>
<div class="spec">
<p><tt>messages() -> any()</tt></p>
</div><p>Atoms used to identify messages in {active, once | true} mode.</p>
<h3 class="function"><a name="name-0">name/0</a></h3>
<div class="spec">
<p><tt>name() -> any()</tt></p>
</div><p>Name of this transport, <em>ssl</em>.</p>
<h3 class="function"><a name="peername-1">peername/1</a></h3>
<div class="spec">
<p><tt>peername(Socket::<a href="ssl.html#type-sslsocket">ssl:sslsocket()</a>) -> {ok, {<a href="inet.html#type-ip_address">inet:ip_address()</a>, <a href="inet.html#type-port_number">inet:port_number()</a>}} | {error, atom()}</tt><br></p>
</div><p>Return the remote address and port of the connection.</p>
<p><b>See also:</b> <a href="ssl.html#peername-1">ssl:peername/1</a>.</p>
<h3 class="function"><a name="recv-3">recv/3</a></h3>
<div class="spec">
<p><tt>recv(Socket::<a href="ssl.html#type-sslsocket">ssl:sslsocket()</a>, Length::non_neg_integer(), Timeout::timeout()) -> {ok, any()} | {error, closed | atom()}</tt><br></p>
</div><p>Receive data from a socket in passive mode.</p>
<p><b>See also:</b> <a href="ssl.html#recv-3">ssl:recv/3</a>.</p>
<h3 class="function"><a name="send-2">send/2</a></h3>
<div class="spec">
<p><tt>send(Socket::<a href="ssl.html#type-sslsocket">ssl:sslsocket()</a>, Packet::iodata()) -> ok | {error, atom()}</tt><br></p>
</div><p>Send data on a socket.</p>
<p><b>See also:</b> <a href="ssl.html#send-2">ssl:send/2</a>.</p>
<h3 class="function"><a name="sendfile-2">sendfile/2</a></h3>
<div class="spec">
<p><tt>sendfile(Socket::<a href="ssl.html#type-sslsocket">ssl:sslsocket()</a>, Filepath::<a href="file.html#type-name">file:name()</a>) -> {ok, non_neg_integer()} | {error, atom()}</tt><br></p>
</div><p><p>Send a file on a socket.</p>
Unlike with TCP, no syscall can be used here, so sending files
through SSL will be much slower in comparison.
</p>
<p><b>See also:</b> <a href="file.html#sendfile-2">file:sendfile/2</a>.</p>
<h3 class="function"><a name="setopts-2">setopts/2</a></h3>
<div class="spec">
<p><tt>setopts(Socket::<a href="ssl.html#type-sslsocket">ssl:sslsocket()</a>, Opts::list()) -> ok | {error, atom()}</tt><br></p>
</div><p>Set options on the given socket.</p>
<p><b>See also:</b> <a href="ssl.html#setopts-2">ssl:setopts/2</a>.</p>
<h3 class="function"><a name="sockname-1">sockname/1</a></h3>
<div class="spec">
<p><tt>sockname(Socket::<a href="ssl.html#type-sslsocket">ssl:sslsocket()</a>) -> {ok, {<a href="inet.html#type-ip_address">inet:ip_address()</a>, <a href="inet.html#type-port_number">inet:port_number()</a>}} | {error, atom()}</tt><br></p>
</div><p>Return the local address and port of the connection.</p>
<p><b>See also:</b> <a href="ssl.html#sockname-1">ssl:sockname/1</a>.</p>
<hr>
<div class="navbar"><a name="#navbar_bottom"></a><table width="100%" border="0" cellspacing="0" cellpadding="2" summary="navigation bar"><tr><td><a href="overview-summary.html" target="overviewFrame">Overview</a></td><td><a href="http://www.erlang.org/"><img src="erlang.png" align="right" border="0" alt="erlang logo"></a></td></tr></table></div>
<p><i>Generated by EDoc, Mar 9 2013, 09:38:59.</i></p>
</body>
</html>
