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, asn1, 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.

Data Types

opts()

opts() = [{backlog, non_neg_integer()} | {cacertfile, string()} | {cacerts, [Der::binary()]} | {cert, Der::binary()} | {certfile, string()} | {ciphers, [ssl:erl_cipher_suite()] | string()} | {fail_if_no_peer_cert, boolean()} | {hibernate_after, integer() | undefined} | {ip, inet:ip_address()} | {key, Der::binary()} | {keyfile, string()} | {next_protocols_advertised, [binary()]} | {nodelay, boolean()} | {password, string()} | {port, inet:port_number()} | {raw, non_neg_integer(), non_neg_integer(), non_neg_integer() | binary()} | {reuse_session, function()} | {reuse_sessions, boolean()} | {secure_renegotiate, boolean()} | {verify, ssl:verify_type()} | {verify_fun, {function(), InitialUserState::term()}}]

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/2Equivalent to sendfile(Socket, Filename, 0, 0, []).
sendfile/4Equivalent to sendfile(Socket, File, Offset, Bytes, []).
sendfile/5Send part of 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::opts()) -> {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).
cert
Optional. The DER encoded users certificate. If this option is supplied it will override the certfile option.
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).
hibernate_after
When an integer-value is specified, the ssl_connection will go into hibernation after the specified number of milliseconds of inactivity, thus reducing its memory footprint. When undefined is specified (this is the default), the process will never go into hibernation.
ip
Interface to listen on. Listen on all interfaces by default.
key
Optional. The DER encoded users private key. If this option is supplied it will override the keyfile option.
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)
reuse_session
Optional. Enables the ssl server to have a local policy for deciding if a session should be reused or not, only meaningful if reuse_sessions is set to true.
reuse_sessions
Optional. Specifies if the server should agree to reuse sessions when the clients request to do so.
secure_renegotiate
Optional. Specifies if to reject renegotiation attempt that does not live up to RFC 5746. By default secure_renegotiate is set to false i.e. secure renegotiation will be used if possible but it will fallback to unsecure renegotiation if the peer does not support RFC 5746.
verify
Optional. If set to verify_peer, performs an x509-path validation and request the client for a certificate.
verify_fun
Optional. The verify fun will be called during the X509-path validation when an error or an extension unknown to the ssl application is encountered. Additionally it will be called when a certificate is considered valid by the path validation to allow access to each certificate in the path to the user application.
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(), Filename::file:name_all()) -> {ok, non_neg_integer()} | {error, atom()}

Equivalent to sendfile(Socket, Filename, 0, 0, []).

sendfile/4

sendfile(Socket::ssl:sslsocket(), File::file:name_all() | file:fd(), Offset::non_neg_integer(), Bytes::non_neg_integer()) -> {ok, non_neg_integer()} | {error, atom()}

Equivalent to sendfile(Socket, File, Offset, Bytes, []).

sendfile/5

sendfile(Socket::ssl:sslsocket(), File::file:name_all() | file:fd(), Offset::non_neg_integer(), Bytes::non_neg_integer(), Opts::ranch_transport:sendfile_opts()) -> {ok, non_neg_integer()} | {error, atom()}

Send part of 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. Note that unlike file:sendfile/5 this function accepts either a file or a file name.

See also: file:sendfile/5, ranch_transport:sendfile/6.

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, Nov 19 2013, 11:10:19.