Module ranch_ssl

SSL transport API.

Behaviours: ranch_transport.

See also: ssl.

Description

SSL transport API.

Wrapper around ssl implementing the Ranch transport API.

This transport requires the crypto, public_key and ssl 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.

Function Index

accept/2Accept connections with the given listening socket.
close/1Close the given socket.
controlling_process/2Give control of the socket to a new process.
listen/1Listen for connections on the given port number.
messages/0Atoms used to identify messages in {active, once | true} mode.
name/0Name of this transport, ssl.
peername/1Return the remote address and port of the connection.
recv/3Receive data from a socket in passive mode.
send/2Send data on a socket.
sendfile/2Send a file on a socket.
setopts/2Set options on the given socket.
sockname/1Return the local address and port of the connection.

Function Details

accept/2

accept(LSocket::ssl:sslsocket(), Timeout::timeout()) -> {ok, ssl:sslsocket()} | {error, closed | timeout | atom() | tuple()}

Accept connections with the given listening socket.

Note that this function does both the transport accept and the SSL handshake. The returned socket is thus fully connected.

See also: ssl:ssl_accept/2, ssl:transport_accept/2.

close/1

close(Socket::ssl:sslsocket()) -> ok

Close the given socket.

See also: ssl:close/1.

controlling_process/2

controlling_process(Socket::ssl:sslsocket(), Pid::pid()) -> ok | {error, closed | not_owner | atom()}

Give control of the socket to a new process.

Must be called from the process currently controlling the socket, otherwise an {error, not_owner} tuple will be returned.

See also: ssl:controlling_process/2.

listen/1

listen(Opts::[{backlog, non_neg_integer()} | {cacertfile, string()} | {certfile, string()} | {ciphers, [ssl:erl_cipher_suite()] | string()} | {fail_if_no_peer_cert, boolean()} | {ip, inet:ip_address()} | {keyfile, string()} | {next_protocols_advertised, [binary()]} | {nodelay, boolean()} | {password, string()} | {port, inet:port_number()} | {verify, ssl:verify_type()}]) -> {ok, ssl:sslsocket()} | {error, atom()}

Listen for connections on the given port number.

Calling this function returns a listening socket that can then The available options are:

backlog
Maximum length of the pending connections queue. Defaults to 1024.
cacertfile
Optional. Path to file containing PEM encoded CA certificates (trusted certificates used for verifying a peer certificate).
certfile
Mandatory. Path to a file containing the user's certificate.
ciphers
Optional. The cipher suites that should be supported. The function ssl:cipher_suites/0 can be used to find all available ciphers.
fail_if_no_peer_cert
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).
ip
Interface to listen on. Listen on all interfaces by default.
keyfile
Optional. Path to the file containing the user's private PEM encoded key.
next_protocols_advertised
Optional. Erlang R16B+ required. List of protocols advertised by TLS Next Protocol Negotiation extension.
nodelay
Optional. Enable TCP_NODELAY. Enabled by default.
password
Optional. String containing the user's password. All private keyfiles must be password protected currently.
port
TCP port number to open. Defaults to 0 (see below)
verify
Optional. If set to verify_peer, performs an x509-path validation and request the client for a certificate.
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.

See also: ssl:listen/2.

messages/0

messages() -> any()

Atoms used to identify messages in {active, once | true} mode.

name/0

name() -> any()

Name of this transport, ssl.

peername/1

peername(Socket::ssl:sslsocket()) -> {ok, {inet:ip_address(), inet:port_number()}} | {error, atom()}

Return the remote address and port of the connection.

See also: ssl:peername/1.

recv/3

recv(Socket::ssl:sslsocket(), Length::non_neg_integer(), Timeout::timeout()) -> {ok, any()} | {error, closed | atom()}

Receive data from a socket in passive mode.

See also: ssl:recv/3.

send/2

send(Socket::ssl:sslsocket(), Packet::iodata()) -> ok | {error, atom()}

Send data on a socket.

See also: ssl:send/2.

sendfile/2

sendfile(Socket::ssl:sslsocket(), Filepath::file:name()) -> {ok, non_neg_integer()} | {error, atom()}

Send a file on a socket.

Unlike with TCP, no syscall can be used here, so sending files through SSL will be much slower in comparison.

See also: file:sendfile/2.

setopts/2

setopts(Socket::ssl:sslsocket(), Opts::list()) -> ok | {error, atom()}

Set options on the given socket.

See also: ssl:setopts/2.

sockname/1

sockname(Socket::ssl:sslsocket()) -> {ok, {inet:ip_address(), inet:port_number()}} | {error, atom()}

Return the local address and port of the connection.

See also: ssl:sockname/1.


Generated by EDoc, Aug 3 2013, 11:17:12.