neon/ssl

Types

ConnectOptions

opaque </>

Options for establishing an SSL/TLS connection.

pub opaque type ConnectOptions

HandshakeOptions

opaque </>

Options for performing a server-side TLS handshake.

Create with handshake_options, then optionally configure with cacerts and handshake_timeout before passing to handshake.

pub opaque type HandshakeOptions

PrivateKey

opaque </>

A private key for SSL/TLS server authentication.

pub opaque type PrivateKey

Ssl

</>

An SSL/TLS socket.

pub type Ssl

SslError

</>

Errors that can occur during SSL/TLS operations.

pub type SslError {
  Closed
  Timeout
  Posix(net.Posix)
  TlsAlert(TlsAlert, String)
  SslError(String)
  SslNotStarted
  InvalidPid
}

Constructors

```
Closed
```
The connection was closed.
```
Timeout
```
The operation timed out.
```
Posix(net.Posix)
```
A POSIX error.
```
TlsAlert(TlsAlert, String)
```
A TLS alert.
```
SslError(String)
```
A generic SSL error with a description.
```
SslNotStarted
```
The SSL application has not been started. Call start first.
```
InvalidPid
```
The target pid is not alive.

SslMessage

</>

Messages received from an SSL socket in active mode.

Use select to register handlers for these messages on a Selector.

pub type SslMessage {
  Packet(Ssl, BitArray)
  SocketClosed(Ssl)
  SocketError(Ssl, SslError)
}

Constructors

```
Packet(Ssl, BitArray)
```
Data received from the socket.
```
SocketClosed(Ssl)
```
The socket was closed by the remote peer.
```
SocketError(Ssl, SslError)
```
An error occurred on the socket.

TlsAlert

</>

TLS alert descriptions as defined in the Erlang ssl module documentation.

pub type TlsAlert {
  CloseNotify
  UnexpectedMessage
  BadRecordMac
  RecordOverflow
  HandshakeFailure
  BadCertificate
  UnsupportedCertificate
  CertificateRevoked
  CertificateExpired
  CertificateUnknown
  IllegalParameter
  UnknownCa
  AccessDenied
  DecodeError
  DecryptError
  ExportRestriction
  ProtocolVersion
  InsufficientSecurity
  InternalError
  InappropriateFallback
  UserCanceled
  NoRenegotiation
  UnsupportedExtension
  CertificateUnobtainable
  UnrecognizedName
  BadCertificateStatusResponse
  BadCertificateHashValue
  UnknownPskIdentity
  NoApplicationProtocol
}

Constructors

```
CloseNotify
```
```
UnexpectedMessage
```
```
BadRecordMac
```
```
RecordOverflow
```
```
HandshakeFailure
```
```
BadCertificate
```
```
UnsupportedCertificate
```
```
CertificateRevoked
```
```
CertificateExpired
```
```
CertificateUnknown
```
```
IllegalParameter
```
```
UnknownCa
```
```
AccessDenied
```
```
DecodeError
```
```
DecryptError
```
```
ExportRestriction
```
```
ProtocolVersion
```
```
InsufficientSecurity
```
```
InternalError
```
```
InappropriateFallback
```
```
UserCanceled
```
```
NoRenegotiation
```
```
UnsupportedExtension
```
```
CertificateUnobtainable
```
```
UnrecognizedName
```
```
BadCertificateStatusResponse
```
```
BadCertificateHashValue
```
```
UnknownPskIdentity
```
```
NoApplicationProtocol
```

Values

accept

</>

pub fn accept(
  socket: Ssl,
  timeout: net.Timeout,
) -> Result(Ssl, SslError)

Accepts an incoming connection on an SSL listen socket.

Returns a transport socket that has not yet completed the TLS handshake. Call handshake to complete the TLS negotiation.

active

</>

pub fn active(socket: Ssl) -> Result(Ssl, SslError)

Sets the socket to active mode.

In active mode, incoming data is delivered as messages to the socket owner’s mailbox. Use select to handle these messages.

connect

</>

pub fn connect(opts: ConnectOptions) -> Result(Ssl, SslError)

Establishes an SSL/TLS connection using the given options.

This either opens a new connection or upgrades an existing TCP socket, depending on whether new or from_tcp was used to create the options.

start must be called before this function.

connect_cacerts

</>

pub fn connect_cacerts(
  opts: ConnectOptions,
  certs: List(BitArray),
) -> ConnectOptions

Sets the CA certificates to use for peer verification.

When set, these certificates are used instead of the system CA store. Only has an effect when verify_peer is enabled.

controlling_process

</>

pub fn controlling_process(
  socket: Ssl,
  pid: process.Pid,
) -> Result(Nil, SslError)

Change the controlling process of a socket.

The controlling process is the process that the socket sends messages to. Note that if the provided Pid is invalid, this function will no-op and return Ok(Nil).

ec_private_key

</>

pub fn ec_private_key(key: BitArray) -> PrivateKey

Creates an EC private key from a DER-encoded binary.

from_tcp

</>

pub fn from_tcp(
  socket: tcp.Tcp,
  address: net.Address,
) -> ConnectOptions

Creates connection options to upgrade an existing TCP socket to SSL/TLS.

The provided address can be a hostname or an IP Address. If the address is a hostname, that hostname is used for Server Name Indication. If the address is an IP Address, SNI is disabled. Defaults to verify_peer and an infinite timeout.

handshake

</>

pub fn handshake(
  socket: Ssl,
  opts: HandshakeOptions,
) -> Result(Ssl, SslError)

Performs the server-side TLS handshake on a transport socket returned by accept.

start must be called before this function.

handshake_cacerts

</>

pub fn handshake_cacerts(
  opts: HandshakeOptions,
  certs: List(BitArray),
) -> HandshakeOptions

Sets the CA certificates for client certificate verification.

handshake_from_tcp

</>

pub fn handshake_from_tcp(
  socket: tcp.Tcp,
  opts: HandshakeOptions,
) -> Result(Ssl, SslError)

Performs a server-side TLS handshake on a raw TCP socket.

This is the server-side counterpart to from_tcp and is used for START-TLS upgrades where an existing TCP connection is promoted to TLS.

start must be called before this function.

handshake_options

</>

pub fn handshake_options(
  cert: BitArray,
  key: PrivateKey,
) -> HandshakeOptions

Creates handshake options with the given certificate and private key.

The certificate should be a DER-encoded binary. Defaults to no CA certificates and an infinite timeout.

handshake_timeout

</>

pub fn handshake_timeout(
  opts: HandshakeOptions,
  timeout: net.Timeout,
) -> HandshakeOptions

Sets the handshake timeout.

listen

</>

pub fn listen(
  port: net.Port,
  ip_address: net.IpAddress,
) -> Result(Ssl, SslError)

Creates an SSL listen socket bound to the given port and IP address.

new

</>

pub fn new(
  address: net.Address,
  port: net.Port,
) -> ConnectOptions

Creates connection options for a fresh SSL/TLS connection to the given address and port.

Defaults to verify_peer and an infinite timeout.

passive

</>

pub fn passive(socket: Ssl) -> Result(Ssl, SslError)

Sets the socket to passive mode.

In passive mode, data must be read explicitly using receive.

port

</>

pub fn port(socket: Ssl) -> Result(net.Port, SslError)

Returns the port number assigned to an SSL socket by the operating system.

receive

</>

pub fn receive(
  socket: Ssl,
  length: Int,
  timeout: net.Timeout,
) -> Result(BitArray, SslError)

Receives data from an SSL/TLS socket.

The length parameter specifies the number of bytes to receive. Use 0 to receive whatever data is available. Must be non-negative.

rsa_private_key

</>

pub fn rsa_private_key(key: BitArray) -> PrivateKey

Creates an RSA private key from a DER-encoded binary.

select

</>

pub fn select(
  selector: process.Selector(t),
  mapper: fn(SslMessage) -> t,
) -> process.Selector(t)

Adds SSL message handlers to a selector for use with active mode sockets.

In active mode, incoming data, close notifications, and errors are delivered as messages to the socket owner’s mailbox. Use this function to register handlers for these messages on a Selector.

send

</>

pub fn send(
  socket: Ssl,
  payload: BitArray,
) -> Result(Nil, SslError)

Sends data over an SSL/TLS socket.

shutdown

</>

pub fn shutdown(socket: Ssl) -> Result(Nil, SslError)

Shuts down the SSL/TLS connection for both reading and writing.

start

</>

pub fn start() -> Result(Nil, SslError)

Starts the SSL application and its dependencies.

Must be called before any SSL/TLS operations. This function is idempotent and can safely be called multiple times.

stop

</>

pub fn stop() -> Nil

Stops the SSL application.

After calling this, SSL/TLS operations will fail with SslNotStarted until start is called again.

timeout

</>

pub fn timeout(
  opts: ConnectOptions,
  timeout: net.Timeout,
) -> ConnectOptions

Sets the connection timeout.

verify_none

</>

pub fn verify_none(opts: ConnectOptions) -> ConnectOptions

Disables certificate verification.

This is insecure and should only be used for testing or when connecting to hosts with self-signed certificates.

verify_peer

</>

pub fn verify_peer(opts: ConnectOptions) -> ConnectOptions

Enables certificate verification against the system CA store.

This is the default.