Skip to content

DTLSContext

[Source]

A DTLS context is used to create DTLS sessions.

DTLS is the datagram variant of TLS. It provides the same authentication and encryption guarantees over unreliable transports like UDP. A DTLS context uses DTLS_method() internally and accepts only DTLS version numbers.

This type is separate from SSLContext because DTLS and TLS are not interchangeable: a TLS context cannot create a DTLS session and vice versa. Keeping them separate makes the wrong combination a compile error.

class val DTLSContext

Constructors

create

[Source]

Create a DTLS context.

new ref create()
: DTLSContext ref^

Returns

Public Functions

client

[Source]

Create a client-side DTLS session. If a hostname is supplied and client verification is on, the server side certificate must be valid for that hostname. Raises an error if the context has been disposed.

The session holds the context, so the context lives for as long as the session can handshake.

fun val client(
  hostname: String val = "")
: DTLS iso^ ?

Parameters

Returns

server

[Source]

Create a server-side DTLS session. Raises an error if the context has been disposed.

The session holds the context, so the context and the ALPN resolver it installed with OpenSSL live for as long as the session can handshake.

fun val server()
: DTLS iso^ ?

Returns

set_cert

[Source]

The cert file is a PEM certificate chain. The key file is a private key. Servers must set this. For clients, it is optional. Raises an error if the context has been disposed.

fun ref set_cert(
  cert: FilePath val,
  key: FilePath val)
: None val ?

Parameters

Returns

set_authority

[Source]

Use a PEM file and/or a directory of PEM files to specify certificate authorities. Clients must set this. For servers, it is optional. Use None to indicate no file or no path. Raises an error if these verify locations aren't valid, or if the context has been disposed.

If both file and path are None, on Windows this method loads the system root certificates. On Posix it raises an error.

fun ref set_authority(
  file: (FilePath val | None val),
  path: (FilePath val | None val) = reference)
: None val ?

Parameters

Returns

set_ciphers

[Source]

Set the accepted ciphers. This replaces the existing list. Raises an error if the cipher list is invalid, or if the context has been disposed.

fun ref set_ciphers(
  ciphers: String val)
: None val ?

Parameters

Returns

set_client_verify

[Source]

Set to true to require verification. Defaults to true.

A client session created with state false never reports SSLAuthFail.

fun ref set_client_verify(
  state: Bool val)
: None val

Parameters

Returns

set_server_verify

[Source]

Set to true to require verification. Defaults to false.

A server session created with state false never reports SSLAuthFail. It sends no certificate request, so it has no peer identity to reject.

fun ref set_server_verify(
  state: Bool val)
: None val

Parameters

Returns

set_verify_depth

[Source]

Set the verify depth. Defaults to 6. Does nothing if the context has been disposed.

A depth of 2^31 or more arrives at the SSL library as a negative depth. What each backend does with one is undocumented, so do not use a depth that large.

fun ref set_verify_depth(
  depth: U32 val)
: None val

Parameters

  • depth: U32 val

Returns

set_min_proto_version

[Source]

Set minimum protocol version. Set to SSLAutoVersion, 0, to automatically manage lowest version.

Raises an error if the context has been disposed or if the SSL library rejects the version.

Supported versions: DTLS1Version, DTLS1u2Version

fun ref set_min_proto_version(
  version: ULong val)
: None val ?

Parameters

Returns

get_min_proto_version

[Source]

Get minimum protocol version. Returns SSLAutoVersion, 0, when automatically managing lowest version. A disposed context returns SSLAutoVersion.

Supported versions: DTLS1Version, DTLS1u2Version

fun box get_min_proto_version()
: ILong val

Returns

set_max_proto_version

[Source]

Set maximum protocol version. Set to SSLAutoVersion, 0, to automatically manage highest version.

Raises an error if the context has been disposed or if the SSL library rejects the version.

Supported versions: DTLS1Version, DTLS1u2Version

fun ref set_max_proto_version(
  version: ULong val)
: None val ?

Parameters

Returns

get_max_proto_version

[Source]

Get maximum protocol version. Returns SSLAutoVersion, 0, when automatically managing highest version. A disposed context returns SSLAutoVersion.

Supported versions: DTLS1Version, DTLS1u2Version

fun box get_max_proto_version()
: ILong val

Returns

alpn_set_resolver

[Source]

Use resolver to choose the protocol to be selected for incoming connections.

OpenSSL holds a raw pointer to resolver that the Pony garbage collector cannot see. The context keeps resolver alive, and every session made from the context keeps the context alive, so resolver lives for as long as any session that can reach it. The resolver has to be set before any session is created, which the capabilities enforce: this method needs a mutable context, and client and server need one that has been made immutable.

Returns true on success. Returns false if the context has been disposed.

fun ref alpn_set_resolver(
  resolver: ALPNProtocolResolver val)
: Bool val

Parameters

Returns

alpn_set_client_protocols

[Source]

Advertise the protocol names in protocols when connecting to a server. Each name must be between 1 and 255 bytes.

Returns true on success. Returns false if the context has been disposed, if protocols is empty or holds a name of an unusable size, or if OpenSSL would not take the list.

fun ref alpn_set_client_protocols(
  protocols: Array[String val] box)
: Bool val

Parameters

Returns

dispose

[Source]

Free the DTLS context. A disposed context cannot create a session, and no configuration of it can take effect.

fun ref dispose()
: None val

Returns