Socket.SSL (socket2 v2.1.2)

Copy Markdown

This module allows usage of SSL sockets and promotion of TCP sockets to SSL sockets.

Options

When creating a socket you can pass a series of options to use for it.

  • :cert can either be an encoded certificate or [path: "path/to/certificate"]
  • :key can either be an encoded certificate, [path: "path/to/key"], [rsa: "rsa encoded"] or [dsa: "dsa encoded"] or [ec: "ec encoded"]
  • :authorities can iehter be an encoded authorities or [path: "path/to/authorities"]
  • :dh can either be an encoded dh or [path: "path/to/dh"]
  • :verify can either be false to disable peer certificate verification, or a keyword list containing a :function and an optional :data
  • :cacerts can be a custom list of certificates to accept during certificate verification
  • :password the password to use to decrypt certificates
  • :renegotiation if it's set to :secure renegotiation will be secured
  • :ciphers is a list of ciphers to allow
  • :advertised_protocols is a list of strings representing the advertised protocols for NPN
  • :preferred_protocols is a list of strings representing the preferred next protocols for NPN

You can also pass TCP options.

Smart garbage collection

Normally sockets in Erlang are closed when the controlling process exits, with smart garbage collection the controlling process will be the Socket.Manager and it will be closed when there are no more references to it.

Summary

Types

error()
t()

Functions

accept(self)

Accept a connection from a listening SSL socket or start an SSL connection on the given client socket.

accept(socket, options)

Accept a connection from a listening SSL socket with the given options or start an SSL connection on the given client socket with the given options.

accept!(socket)

Accept a connection from a listening SSL socket or start an SSL connection on the given client socket, raising if an error occurs.

accept!(socket, options)

Accept a connection from a listening SSL socket with the given options or start an SSL connection on the given client socket with the given options, raising if an error occurs.

arguments(options)

Convert SSL options to :ssl.setopts compatible arguments.

certificate(socket)

Get the certificate of the peer.

certificate!(socket)

Get the certificate of the peer, raising if an error occurs.

ciphers(version \\ :"tlsv1.3")

Get the list of supported ciphers.

connect(socket)

Connect to the given address and port tuple or SSL connect the given socket.

connect(wrap, options)

Connect to the given address and port tuple with the given options or SSL connect the given socket with the given options or connect to the given address and port.

connect(address, port, options)

Connect to the given address and port with the given options.

connect!(socket_or_descriptor)

Connect to the given address and port tuple or SSL connect the given socket, raising if an error occurs.

connect!(descriptor, options)

Connect to the given address and port tuple with the given options or SSL connect the given socket with the given options or connect to the given address and port, raising if an error occurs.

connect!(address, port, options)

Connect to the given address and port with the given options, raising if an error occurs.

error(code)

Return a proper error string for the given code or nil if it can't be converted.

handshake(socket, options \\ [])

Execute the handshake; useful if you want to delay the handshake to make it in another process.

handshake!(socket)

Execute the handshake, raising if an error occurs; useful if you want to delay the handshake to make it in another process.

handshake!(socket, options)
info(socket)

Get information about the SSL connection.

info!(socket)

Get information about the SSL connection, raising if an error occurs.

listen()

Create an SSL socket listening on an OS chosen port, use local to know the port it was bound on.

listen(port)

Create an SSL socket listening on an OS chosen port using the given options or listening on the given port.

listen(port, options)

Create an SSL socket listening on the given port and using the given options.

listen!()

Create an SSL socket listening on an OS chosen port, use local to know the port it was bound on, raising in case of error.

listen!(port_or_options)

Create an SSL socket listening on an OS chosen port using the given options or listening on the given port, raising in case of error.

listen!(port, options)

Create an SSL socket listening on the given port and using the given options, raising in case of error.

negotiated_protocol(socket)

Get the negotiated protocol.

options(socket, options)

Set options of the socket.

options!(socket, options)

Set options of the socket, raising if an error occurs.

process(socket, pid)

Set the process which will receive the messages.

process!(socket, pid)

Set the process which will receive the messages, raising if an error occurs.

renegotiate(socket)

Renegotiate the secure connection.

renegotiate!(socket)

Renegotiate the secure connection, raising if an error occurs.

versions()

Get the list of supported SSL/TLS versions.

Types

error()

@type error() :: nil | String.t()

t()

@opaque t()

Functions

accept(self)

@spec accept(Socket.t() | t()) :: {:ok, t()} | {:error, term()}

Accept a connection from a listening SSL socket or start an SSL connection on the given client socket.

accept(socket, options)

@spec accept(Socket.t(), Keyword.t()) :: {:ok, t()} | {:error, term()}

Accept a connection from a listening SSL socket with the given options or start an SSL connection on the given client socket with the given options.

accept!(socket)

@spec accept!(Socket.t() | t()) :: t() | no_return()

Accept a connection from a listening SSL socket or start an SSL connection on the given client socket, raising if an error occurs.

accept!(socket, options)

@spec accept!(Socket.t(), t() | Keyword.t()) :: t() | no_return()

Accept a connection from a listening SSL socket with the given options or start an SSL connection on the given client socket with the given options, raising if an error occurs.

arguments(options)

@spec arguments(Keyword.t()) :: list()

Convert SSL options to :ssl.setopts compatible arguments.

certificate(socket)

@spec certificate(t()) :: {:ok, String.t()} | {:error, term()}

Get the certificate of the peer.

certificate!(socket)

@spec certificate!(t()) :: String.t() | no_return()

Get the certificate of the peer, raising if an error occurs.

ciphers(version \\ :"tlsv1.3")

Get the list of supported ciphers.

connect(socket)

@spec connect(Socket.t() | {Socket.t(), :inet.port_number()}) ::
  {:ok, t()} | {:error, term()}

Connect to the given address and port tuple or SSL connect the given socket.

connect(wrap, options)

@spec connect(
  {Socket.Address.t(), :inet.port_number()} | Socket.t() | Socket.Address.t(),
  Keyword.t() | :inet.port_number()
) :: {:ok, t()} | {:error, term()}

Connect to the given address and port tuple with the given options or SSL connect the given socket with the given options or connect to the given address and port.

connect(address, port, options)

@spec connect(Socket.Address.t(), :inet.port_number(), Keyword.t()) ::
  {:ok, t()} | {:error, term()}

Connect to the given address and port with the given options.

connect!(socket_or_descriptor)

@spec connect!(Socket.t() | {Socket.t(), :inet.port_number()}) :: t() | no_return()

Connect to the given address and port tuple or SSL connect the given socket, raising if an error occurs.

connect!(descriptor, options)

@spec connect!(
  {Socket.Address.t(), :inet.port_number()} | Socket.t() | Socket.Address.t(),
  Keyword.t() | :inet.port_number()
) :: t() | no_return()

Connect to the given address and port tuple with the given options or SSL connect the given socket with the given options or connect to the given address and port, raising if an error occurs.

connect!(address, port, options)

@spec connect!(Socket.Address.t(), :inet.port_number(), Keyword.t()) ::
  t() | no_return()

Connect to the given address and port with the given options, raising if an error occurs.

error(code)

@spec error(term()) :: String.t()

Return a proper error string for the given code or nil if it can't be converted.

handshake(socket, options \\ [])

@spec handshake(t(), Keyword.t()) :: :ok | {:error, term()}

Execute the handshake; useful if you want to delay the handshake to make it in another process.

handshake!(socket)

@spec handshake!(t()) :: :ok | no_return()

Execute the handshake, raising if an error occurs; useful if you want to delay the handshake to make it in another process.

handshake!(socket, options)

@spec handshake!(t(), Keyword.t()) :: :ok | no_return()

info(socket)

@spec info(t()) :: {:ok, list()} | {:error, term()}

Get information about the SSL connection.

info!(socket)

@spec info!(t()) :: list() | no_return()

Get information about the SSL connection, raising if an error occurs.

listen()

@spec listen() :: {:ok, t()} | {:error, term()}

Create an SSL socket listening on an OS chosen port, use local to know the port it was bound on.

listen(port)

@spec listen(:inet.port_number() | Keyword.t()) :: {:ok, t()} | {:error, term()}

Create an SSL socket listening on an OS chosen port using the given options or listening on the given port.

listen(port, options)

@spec listen(:inet.port_number(), Keyword.t()) :: {:ok, t()} | {:error, term()}

Create an SSL socket listening on the given port and using the given options.

listen!()

@spec listen!() :: t() | no_return()

Create an SSL socket listening on an OS chosen port, use local to know the port it was bound on, raising in case of error.

listen!(port_or_options)

@spec listen!(:inet.port_number() | Keyword.t()) :: t() | no_return()

Create an SSL socket listening on an OS chosen port using the given options or listening on the given port, raising in case of error.

listen!(port, options)

@spec listen!(:inet.port_number(), Keyword.t()) :: t() | no_return()

Create an SSL socket listening on the given port and using the given options, raising in case of error.

negotiated_protocol(socket)

@spec negotiated_protocol(t()) :: String.t() | nil

Get the negotiated protocol.

options(socket, options)

@spec options(t() | :ssl.sslsocket(), Keyword.t()) :: :ok | {:error, Socket.Error.t()}

Set options of the socket.

options!(socket, options)

@spec options!(t() | t() | port(), Keyword.t()) :: :ok | no_return()

Set options of the socket, raising if an error occurs.

process(socket, pid)

@spec process(t() | port(), pid()) :: :ok | {:error, :closed | :not_owner | Error.t()}

Set the process which will receive the messages.

process!(socket, pid)

@spec process!(t() | port(), pid()) :: :ok | no_return()

Set the process which will receive the messages, raising if an error occurs.

renegotiate(socket)

@spec renegotiate(t()) :: :ok | {:error, term()}

Renegotiate the secure connection.

renegotiate!(socket)

@spec renegotiate!(t()) :: :ok | no_return()

Renegotiate the secure connection, raising if an error occurs.

versions()

@spec versions() :: [tuple()]

Get the list of supported SSL/TLS versions.