# ssl

### MODULE

ssl

### MODULE SUMMARY

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)

### AUTHORS

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

ssl 2.3.4
Copyright © 1991-2002 Ericsson Utvecklings AB