ssl(3)

MODULE
ssl - Interface Functions for Secure Socket Layer

DESCRIPTION

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.

Common data types

The following datatypes are used in the functions below:

    *   options() = [option()]

    *   option() = socketoption() | ssloption()

    *   socketoption() = {mode, list} | {mode, binary} | binary | {packet, packettype()} | {header, integer()} | {nodelay, boolean()} | {active, activetype()} | {backlog, integer()} | {ip, ipaddress()}

    *   ssloption() = {verify, code()} | {depth, depth()} | {certfile, path()} | {keyfile, path()} | {password, string()} | {cacertfile, path()} | {ciphers, string()} | {cachetimeout, integer()}

    *   packettype() (see inet(3))

    *   activetype() (see inet(3))

    *   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: {mode, list}, {packet, 0}, {header, 0}, {nodelay, false}, {active, true}, {backlog, 5}, and {ip, {0, 0, 0, 0}}.

Note that the options {mode, binary} and binary are equivalent. Similarly {mode, list and the absence of option binary are equivalent.

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.

EXPORTS

accept(ListenSocket) -> {ok, Socket} | {error, Reason}
accept(ListenSocket, Timeout) -> {ok, Socket} | {error, Reason}

    Types
        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}

    Types
        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}

    Types
        Address = address()
        Port = integer()
        Options = [connect_option()]
        connect_option() = {mode, list} | {mode, binary} | binary | {packet, packettype()} | {header, integer()} | {nodelay, boolean()} | {active, activetype()} | {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}

    Types
        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()

    Types
        ErrorCode = term()

    Returns a diagnostic string describing an error.

getopts(Socket, OptionsTags) -> {ok, Options} | {error, Reason}

    Types
        Socket = sslsocket()
        OptionTags = [optiontag()]()

    Returns the options the tags of which are OptionTags for for the socket Socket.

listen(Port, Options) -> {ok, ListenSocket} | {error, Reason}

    Types
        Port = integer()
        Options = [listen_option()]
        listen_option() = {mode, list} | {mode, binary} | binary | {packet, packettype()} | {header, integer()} | {active, activetype()} | {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}

    Types
        Socket = sslsocket()
        Address = ipaddress()
        Port = integer()

    Returns the address and port number of the peer.

pid(Socket) -> pid()

    Types
        Socket = sslsocket()

    Returns the pid of the socket process. The returned pid should only be used for receiving exit messages.

port(Socket) -> {ok, Port}

    Types
        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}

    Types
        Socket = sslsocket()
        Length = integer() >= 0
        Timeout = 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}

    Types
        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}

    Types
        Socket = sslsocket()
        Options = [socketoption]()

    Sets options according to Options for the socket Socket.

sockname(Socket) -> {ok, {Address, Port}} | {error, Reason}

    Types
        Socket = sslsocket()
        Address = ipaddress()
        Port = integer()

    Returns the local address and port number of the socket Socket.

ERRORS

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:

    closed:
        Connection closed for the operation in question.

    ebadsocket:
        Connection not found (internal error).

    ebadstate:
        Connection not in connect state (internal error).

    ebrokertype:
        Wrong broker type (internal error).

    ecacertfile:
        Own CA certificate file is invalid.

    ecertfile:
        Own certificate file is invalid.

    echaintoolong:
        The chain of certificates provided by peer is too long.

    ecipher:
        Own list of specified ciphers is invalid.

    ekeyfile:
        Own private key file is invalid.

    ekeymismatch:
        Own private key does not match own certificate.

    enoissuercert:
        Cannot find certificate of issuer of certificate provided by peer.

    enoservercert:
        Attempt to do accept without having set own certificate.

    enotlistener:
        Attempt to accept on a non-listening socket.

    enoproxysocket:
        No proxy socket found (internal error).

    enooptions:
        The list of options is empty.

    eoptions:
        Invalid list of options.

    epeercert:
        Certificate provided by peer is in error.

    epeercertexpired:
        Certificate provided by peer has expired.

    epeercertinvalid:
        Certificate provided by peer is invalid.

    eselfsignedcert:
        Certificate provided by peer is self signed.

    esslaccept:
        Server SSL handshake procedure between client and server failed.

    esslconnect:
        Client SSL handshake procedure between client and server failed.

    esslerrssl:
        SSL protocol failure. Typically because of a fatal alert from peer.

    ewantconnect:
        Protocol wants to connect, which is not supported in this version of the SSL application.

    ex509lookup:
        Protocol wants X.509 lookup, which is not supported in this version of the SSL application.

    {badcall, Call}:
        Call not recognized for current mode (active or passive) and state of socket.

    {badcast, Cast}:
        Call not recognized for current mode (active or passive) and state of socket.

    {badinfo, Info}:
        Call not recognized for current mode (active or passive) and state of socket.

SEE ALSO

gen_tcp(3), inet(3)

AUTHOR
Peter Högfeldt - support@erlang.ericsson.se