kafein

Types

Certificate

Record to describe a certificate.

pub type Certificate {
  Certificate(
    certfile: String,
    keyfile: String,
    password: option.Option(fn() -> String),
  )
}

Constructors

Certificate(
  certfile: String,
  keyfile: String,
  password: option.Option(fn() -> String),
)

Curve

</>

Curve that can be used for key exchange.

pub type Curve {
  X25519
  X448
  Secp521r1
  BrainpoolP512r1
  BrainpoolP384r1
  Secp384r1
  BrainpoolP256r1
  Secp256r1
  Sect571r1
  Sect571k1
  Sect409k1
  Sect409r1
  Sect283k1
  Sect283r1
  Secp256k1
  Sect239k1
  Sect233k1
  Sect233r1
  Secp224k1
  Secp224r1
  Sect193r1
  Sect193r2
  Secp192k1
  Secp192r1
  Sect163k1
  Sect163r1
  Sect163r2
  Secp160k1
  Secp160r1
  Secp160r2
}

Constructors

```
X25519
```
```
X448
```
```
Secp521r1
```
```
BrainpoolP512r1
```
```
BrainpoolP384r1
```
```
Secp384r1
```
```
BrainpoolP256r1
```
```
Secp256r1
```
```
Sect571r1
```
```
Sect571k1
```
```
Sect409k1
```
```
Sect409r1
```
```
Sect283k1
```
```
Sect283r1
```
```
Secp256k1
```
```
Sect239k1
```
```
Sect233k1
```
```
Sect233r1
```
```
Secp224k1
```
```
Secp224r1
```
```
Sect193r1
```
```
Sect193r2
```
```
Secp192k1
```
```
Secp192r1
```
```
Sect163k1
```
```
Sect163r1
```
```
Sect163r2
```
```
Secp160k1
```
```
Secp160r1
```
```
Secp160r2
```

Error

</>

Error that can occur on some operation.

For more details, check out the Erlang docs:

pub type Error {
  Closed
  Timeout
  Other(dynamic.Dynamic)
  PosixError(mug.Error)
  CipherSuiteNotRecognized(name: String)
  TlsAlert(kind: TlsAlertKind, description: String)
}

Constructors

```
Closed
```
Connection was closed
```
Timeout
```
Conncetion timed out
```
Other(dynamic.Dynamic)
```
An opaque error meant for debugging
```
PosixError(mug.Error)
```
Error that comes from the connection
```
CipherSuiteNotRecognized(name: String)
```
A specified cipher suite was not recognized

TlsAlert(kind: TlsAlertKind, description: String)

Error that comes from the TLS interaction

ExportKeyMaterialsError

</>

Error that can occur when exporting keying material(s).

pub type ExportKeyMaterialsError {
  ExporterMasterSecretAlreadyConsumed
  BadInput
}

Constructors

```
ExporterMasterSecretAlreadyConsumed
```
```
BadInput
```

ProtocolVersion

</>

Enum of supported protocol version.

pub type ProtocolVersion {
  Tlsv1
  Tlsv1m1
  Tlsv1m2
  Tlsv1m3
}

Constructors

```
Tlsv1
```
```
Tlsv1m1
```
```
Tlsv1m2
```
```
Tlsv1m3
```

SslMessage

</>

Enum of message that comes from an SSL socket.

pub type SslMessage {
  Packet(SslSocket, BitArray)
  SocketClosed(SslSocket)
  SslError(SslSocket, Error)
}

Constructors

```
Packet(SslSocket, BitArray)
```
```
SocketClosed(SslSocket)
```
```
SslError(SslSocket, Error)
```

SslSocket

</>

An SSL Socket, upgraded form of TCP socket used for sending and receiving TCP messages.

pub type SslSocket

TlsAlertKind

</>

Error that might occur throughout the lifetime of the socket, see https://www.erlang.org/doc/apps/ssl/ssl.html#t:tls_alert/0.

pub type TlsAlertKind {
  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
```

VerificationType

</>

Enum of verification type.

pub type VerificationType {
  VerifyNone
  VerifyPeer
}

Constructors

```
VerifyNone
```
```
VerifyPeer
```

WrapOptions

</>

Record to describe options when wrapping a TCP socket.

pub type WrapOptions {
  WrapOptions(
    protocol_versions: List(ProtocolVersion),
    alpn: List(String),
    cacert_file: option.Option(String),
    cipher_suites: List(String),
    depth: Int,
    verify: VerificationType,
    certificates: List(Certificate),
    curves: List(Curve),
    handshake_pause: Bool,
    server_name_indication: option.Option(String),
  )
}

Constructors

WrapOptions(
  protocol_versions: List(ProtocolVersion),
  alpn: List(String),
  cacert_file: option.Option(String),
  cipher_suites: List(String),
  depth: Int,
  verify: VerificationType,
  certificates: List(Certificate),
  curves: List(Curve),
  handshake_pause: Bool,
  server_name_indication: option.Option(String),
)

Values

alpn

</>

pub fn alpn(
  options: WrapOptions,
  protocols alpn: List(String),
) -> WrapOptions

Set supported ALPN protocols.

cacert_file

</>

pub fn cacert_file(
  options: WrapOptions,
  file cacert_file: String,
) -> WrapOptions

Set cacert file used for TLS.

certificate

</>

pub fn certificate(
  options: WrapOptions,
  certificate cert: Certificate,
) -> WrapOptions

Add certificate used for TLS.

certificates

</>

pub fn certificates(
  options: WrapOptions,
  certificates certs: List(Certificate),
) -> WrapOptions

Add list of certificates used for TLS.

cipher_suites

</>

pub fn cipher_suites(
  options: WrapOptions,
  ciphers cipher_suites: List(String),
) -> WrapOptions

Set ciphers suites used for TLS.

curves

</>

pub fn curves(
  options: WrapOptions,
  curves curves: List(Curve),
) -> WrapOptions

Set curves used for TLS.

default_options

</>

pub const default_options: WrapOptions

Default options for wrapping.

depth

</>

pub fn depth(
  options: WrapOptions,
  depth depth: Int,
) -> WrapOptions

Set depth of allowed certificate chain.

export_key_material

</>

pub fn export_key_material(
  socket: SslSocket,
  label label: BitArray,
  context context: option.Option(BitArray),
  wanted_length length: Int,
) -> Result(BitArray, ExportKeyMaterialsError)

Export a single key material.

Returns an error if exporting was failed.

export_key_materials

</>

pub fn export_key_materials(
  socket: SslSocket,
  labels labels: List(BitArray),
  contexts contexts: List(option.Option(BitArray)),
  wanted_lengths lengths: List(Int),
) -> Result(List(BitArray), ExportKeyMaterialsError)

Export some of key materials.

Returns an error if exporting was failed.

handshake_cancel

</>

pub fn handshake_cancel(socket: SslSocket) -> Result(Nil, Error)

Cancel the handshake operation.

Returns an error if cancellation was failed.

handshake_continue

</>

pub fn handshake_continue(
  options options: WrapOptions,
  socket socket: SslSocket,
  timeout_miliseconds timeout: Int,
) -> Result(SslSocket, Error)

Continue the handshake with specified wrap options.

Returns an error if handshake was failed.

handshake_pause

</>

pub fn handshake_pause(options: WrapOptions) -> WrapOptions

Make handshake pause after HELLO.

protocol_versions

</>

pub fn protocol_versions(
  options: WrapOptions,
  versions protocol_versions: List(ProtocolVersion),
) -> WrapOptions

Set protocol versions for upgrade.

receive

</>

pub fn receive(
  socket: SslSocket,
  timeout_miliseconds timeout: Int,
) -> Result(BitArray, mug.Error)

receive_exact

</>

pub fn receive_exact(
  socket: SslSocket,
  byte_size size: Int,
  timeout_miliseconds timeout: Int,
) -> Result(BitArray, mug.Error)

receive_next_packet_as_message

</>

pub fn receive_next_packet_as_message(socket: SslSocket) -> Nil

select_ssl_messages

</>

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

send

</>

pub fn send(
  socket: SslSocket,
  data: BitArray,
) -> Result(Nil, mug.Error)

send_builder

</>

pub fn send_builder(
  socket: SslSocket,
  data: bytes_tree.BytesTree,
) -> Result(Nil, mug.Error)

server_name_indication

</>

pub fn server_name_indication(
  options: WrapOptions,
  hostname name: String,
) -> WrapOptions

Set SNI.

shutdown

</>

pub fn shutdown(socket: SslSocket) -> Result(Nil, mug.Error)

verify

</>

pub fn verify(
  options: WrapOptions,
  verify_type verify: VerificationType,
) -> WrapOptions

Set verification type for certificate.

wrap

</>

pub fn wrap(
  optiohns options: WrapOptions,
  socket socket: mug.Socket,
) -> Result(SslSocket, Error)

Upgrades a TCP connection to SSL connection.

Returns an error if upgrading was failed.