This module contains interface functions to the Secure Socket Layer.
New implementations shall use this module, and not the old
ssl_socket module, which is obsolete.
The following datatypes are used in the functions below:
options() = [option()]
option() = socketoption() | ssloption()
socketoption() = binary | {packet, size()} |
{nodelay, boolean()} | {active, boolean()} |
{backlog, integer()} | {ip, ipaddress()}
ssloption() = {verify, code()} | {depth, depth()} |
{certfile, path()} |
{keyfile, path()} | {password, string()} | {cacertfile, path()} |
{ciphers, string()} | {cachetimeout, integer()}
size() = 0 | 1 | 2 | 4
reason() = atom() | {atom(), string()}
bytes() = [byte()]
string() = [byte()]
byte() = 0 | 1 | 2 | ... | 255
code() = 0 | 1 | 2
depth() = byte()
address() = hostname() | ipstring() | ipaddress()
ipaddress() = ipstring() | iptuple()
hostname() = string()
ipstring() = string()
iptuple() = {byte(), byte(), byte(), byte()}
sslsocket()
The socket options {backlog, integer()} and {ip,
ipaddress} are for listen/2 only.
The following socket options are set by default: {packet,
0}, {nodelay, false}, {active, true},
{backlog, 5}, and {ip, {0,0,0,0}}.
The ssl options are for setting specific SSL parameters as follows:
{verify, code()} Specifies type of verification:
0 = do not verify peer; 1 = verify peer, verify client once, 2 =
verify peer, verify client once, fail if no peer certificate.
The default value is 0.
{depth, depth()} Specifies verification depth,
i.e. how far in a chain of certificates the verification
process shall proceed before the verification is considered
successful. The default value is 1.
{certfile, path()} Path to a file containing a
chain of PEM encoded certificates.
{keyfile, path()} Path to file containing user's
private PEM encoded key.
{password, string()} String containing the user's
password. Only used if the private keyfile is password protected.
{cacertfile, path()} Path to file containing PEM encoded
CA certificates.
{ciphers, string()} String of ciphers as a colon
separated list of ciphers.
{cachetimeout, integer()} Session cache timeout in
seconds.
The type sslsocket() is opaque to the user.
The owner of a socket is the one that created it by a call to
accept/1, connect/3/4/, or listen/2.
When a socket is in active mode (the default), data from the socket is delivered to the owner of the socket in the form of messages:
{ssl, Socket, Data}
{ssl_closed, Socket}
{ssl_error, Socket, Reason}
A Timeout argument specifies a timeout in milliseconds. The
default value for a Timeout argument is infinity.
Functions listed below may return the value {error,
closed}, which only indicates that the SSL socket is
considered closed for the operation in question. It is for
instance possible to have {error, closed} returned from
an call to send/2, and a subsequent call to recv/3
returning {ok, Data}.
Hence a return value of {error, closed} must not be
interpreted as if the socket was completely closed. On the
contrary, in order to free all resources occupied by an SSL
socket, close/1 must be called, or else the process owning
the socket has to terminate.
For each SSL socket there is an Erlang process representing the
socket. When a socket is opened, that process links to the
calling client process. Implementations that want to detect
abnormal exits from the socket process by receiving {'EXIT',
Pid, Reason} messages, should use the function pid/1
to retreive the process identifier from the socket, in order to
be able to match exit messages properly.
accept(ListenSocket) -> {ok, Socket} | {error, Reason}
accept(ListenSocket, Timeout) -> {ok, Socket} |
{error, Reason}
ListenSocket = Socket = sslsocket()Timeout = integer()Accepts an incoming connection request on a listen socket.
ListenSocket must be a socket returned from listen/2.
The accepted socket inherits the options set for ListenSocket
in listen/2.
The default value for Timeout is infinity. If
Timeout is specified, and no connection is accepted within
the given time, {error, timeout} is returned.
close(Socket) -> ok | {error, Reason}
Socket = sslsocket()Closes a socket returned by accept/1/2, connect/3/4,
or listen/2
connect(Address, Port, Options) -> {ok, Socket} | {error, Reason}
connect(Address, Port, Options, Timeout) -> {ok, Socket} | {error, Reason}
Address = address()Port = integer()Options = [connect_option()]connect_option() = binary | {packet, size()} |
{nodelay, boolean()} | {active, boolean()} |
{verify, code()} | {depth, depth()} |
{certfile, path()} | {keyfile, path()} | {password, string()} |
{cacertfile, path()} | {ciphers, string()} |
{cachetimeout, integer()}Timeout = integer()Socket = sslsocket()Connects to Port at Address. If the optional
Timeout argument is specified, and a connection could not
be established within the given time, {error, timeout} is
returned. The default value for Timeout is infinity.
controlling_process(Socket, NewOwner) -> ok | {error, Reason}
Socket = sslsocket()NewOwner = pid()Assigns a new controlling process to Socket. A controlling
process is the owner of a socket, and receives all messages from
the socket.
format_error(ErrorCode) -> string()
ErrorCode = term()Returns a diagnostic string describing an error.
listen(Port, Options) -> {ok, ListenSocket} | {error, Reason}
Port = integer()Options = [listen_option()]listen_option() = binary | {packet, size()} |
{active, boolean()} | {backlog, integer()} | {ip, ipaddress()} |
{verify, code()} | {depth, depth()} |
{certfile, path()} | {keyfile, path()} |
{password, string()} | {cacertfile, path()} | {ciphers, string()} |
{cachetimeout, integer()}ListenSocket = sslsocket()Sets up a socket to listen on port Port at the local host.
If Port is zero, listen/2 picks an available port
number (use port/1 to retreive it).
The listen queue size defaults to 5. If a different value is
wanted, the option {backlog, Size} should be added to the
list of options.
An empty Options list is considered an error, and
{error, enooptions} is returned.
The returned ListenSocket can only be used in calls to
accept/1/2.
peername(Socket) -> {ok, {Address, Port}} | {error, Reason}
Socket = sslsocket()Address = ipaddress()Port = integer()Returns the address and port number of the peer.
Socket = sslsocket()Returns the pid of the socket process. The returned pid should only be used for receiving exit messages.
Socket = sslsocket()Port = integer()Returns the local port number of socket Socket.
recv(Socket, Length) -> {ok, Data} | {error, Reason}
recv(Socket, Length, Timeout) -> {ok, Data} | {error, Reason}
Socket = sslsocket()Length = integer() >= 0Timeout = integer()Data = bytes() | binary()
Receives data on socket Socket when the socket is in
passive mode, i.e. when the option {active, false}
has been specified.
A notable return value is {error, closed} which
indicates that the socket is closed.
A positive value of the Length argument is only
valid when the socket is in raw mode (option {packet,
0} is set, and the option binary is not
set); otherwise it should be set to 0, whence all available
bytes are returned.
If the optional Timeout parameter is specified, and
no data was available within the given time, {error,
timeout} is returned. The default value for
Timeout is infinity.
send(Socket, Data) -> ok | {error, Reason}
Socket = sslsocket()Data = iolist() | binary()Writes Data to Socket.
A notable return value is {error, closed} indicating that
the socket is closed.
setopts(Socket, Options) -> ok | {error, Reason}
Socket = sslsocket()Options = options()Sets options according to Options for the socket
Socket.
Only the following option can be set: {nodelay, boolean()}.
sockname(Socket) -> {ok, {Address, Port}} | {error, Reason}
Socket = sslsocket()Address = ipaddress()Port = integer()Returns the local address and port number of the socket
Socket.
The possible error reasons and the corresponding diagnostic strings
returned by format_error/1 are either the same as those defined
in the inet(3) reference manual, or as follows:
closedebadsocketebadstateebrokertypeecacertfileecertfileechaintoolongecipherekeyfileekeymismatchenoissuercertenoservercertenotlistenerenoproxysocketenooptionseoptionsepeercertepeercertexpiredepeercertinvalideselfsignedcertesslacceptesslconnectesslerrsslewantconnectex509lookup{badcall, Call}{badcast, Cast}{badinfo, Info}gen_tcp(3), inet(3)