EMILUA(3em)

📦 version 0.12.1, in nixos 26.05, nixpkgs unstable

🎀 EMILUA 🎀

ok so this is the EMILUA(3em) page from the Emilua reference — she's the Lua execution engine bestie, and today we're doing the TLS context glow-up. grab a strawberry drink 🍓 and let's go.

✨ NAME ✨

Emilua — the Lua execution engine. that's the whole vibe. no cap. 💜

🔥 FUNCTIONS 🔥

🌸 new(method: string) → tls.context

the constructor, the main character, the moment. 👑

method has got to be one of these or it's not happening:

  • "sslv2"
  • "sslv2_client"
  • "sslv2_server"
  • "sslv3"
  • "sslv3_client"
  • "sslv3_server"
  • "tlsv1"
  • "tlsv1_client"
  • "tlsv1_server"
  • "sslv23"
  • "sslv23_client"
  • "sslv23_server"
  • "tlsv11"
  • "tlsv11_client"
  • "tlsv11_server"
  • "tlsv12"
  • "tlsv12_client"
  • "tlsv12_server"
  • "tlsv13"
  • "tlsv13_client"
  • "tlsv13_server"
  • "tls"
  • "tls_client"
  • "tls_server"

like i said. all of them. we don't skip. 💅

🔐 add_certificate_authority(self, data: byte_span)

drops in a certification authority so the verification can actually happen. it's giving trust issues but make it productive. 🫶

📁 add_verify_path(self, path: filesystem.path)

points at a whole directory of certificate authority files to use when verifying. bulk energy.

🧹 clear_options(self, flags: string[])

wipes options off the context. flags in, flags gone. iconic.

📜 load_verify_file(self, filename: filesystem.path)

loads a certification authority file for doing the verification. one file, one job. ⭐

🛣️ set_default_verify_paths(self)

sets the context up to use the default directories when hunting for certification authority certificates. set it and forget it, lowkey. ✨

⚙️ set_options(self, flags: string[])

the opposite of clear — puts options on the context. (there's a whole list of valid flags down in FUNCTION FLAGS, iykyk 👀)

🔑 set_password_callback(self, callback: function)

sets the password callback. the signature has to be exactly this, no improvising:

function callback(max_length: integer, purpose: string) -> string

and purpose is gonna be either "for_reading" or "for_writing".

⚠️ Note: this callback gets called from an unspecified fiber where IO/blocking operations are disabled. so like… don't go blocking in there, bestie, fr fr. 😭

✅ set_verify_callback(self, callback: string[, callback_options...])

sets the callback used to verify peer certificates. right now there is exactly one supported callback:

  • "host_name_verification" — and then callback_options is a single string holding the host name.

that's it. that's the list. 🌈

📏 set_verify_depth(self, depth: integer)

sets the peer verification depth. a number. a limit. boundaries are healthy. 🦋

🛡️ set_verify_mode(self, mode: string)

sets the peer verification mode. mode might be one of:

  • "none".
  • "peer".
  • "fail_if_no_peer_cert".
  • "client_once".

📄 use_certificate(self, data: byte_span, fmt: string)

uses a certificate straight out of a memory buffer. fmt might be one of:

  • "asn1" — ASN.1 file.
  • "pem" — PEM file.

🔗 use_certificate_chain(self, data: byte_span)

uses a certificate chain from a memory buffer. it's a chain. it's a vibe. ⛓️

📂 use_certificate_chain_file(self, filename: filesystem.path)

same chain energy, but from a file this time.

📄 use_certificate_file(self, filename: filesystem.path, fmt: string)

uses a certificate from a file. fmt might be one of:

  • "asn1" — ASN.1 file.
  • "pem" — PEM file.

🗝️ use_private_key(self, data: byte_span, fmt: string)

uses a private key from a memory buffer. (private!! 🙈) fmt might be one of:

  • "asn1" — ASN.1 file.
  • "pem" — PEM file.

🗝️ use_private_key_file(self, filename: filesystem.path, fmt: string)

uses a private key from a file. fmt might be one of:

  • "asn1" — ASN.1 file.
  • "pem" — PEM file.

🔑 use_rsa_private_key(self, data: byte_span, fmt: string)

uses an RSA private key from a memory buffer. fmt might be one of:

  • "asn1" — ASN.1 file.
  • "pem" — PEM file.

🔑 use_rsa_private_key_file(self, filename: filesystem.path, fmt: string)

uses an RSA private key from a file. fmt might be one of:

  • "asn1" — ASN.1 file.
  • "pem" — PEM file.

🌀 use_tmp_dh(self, data: byte_span)

uses the given memory buffer to get the temporary Diffie-Hellman parameters. iconic name, honestly.

🌀 use_tmp_dh_file(self, filename: filesystem.path)

uses the given file to get the temporary Diffie-Hellman parameters. same thing, file edition. 🎀

🚩 FUNCTION FLAGS 🚩

these are the flags you'd be passing to set_options / clear_options. every single one is the flag with the same name in Boost.Asio, and here's what each one has to say for itself:

🧸 default_workarounds

the flag of the same name in Boost.Asio — https://www.boost.org/doc/libs/1_78_0/doc/html/boost_asio/reference/ssl__context_base/default_workarounds.html — and it says:

"Implement various bug workarounds."

we love a flag that just handles it for us. 💖

🤐 no_compression

the flag of the same name in Boost.Asio — https://www.boost.org/doc/libs/1_78_0/doc/html/boost_asio/reference/ssl__context_base/no_compression.html — and it says:

"Disable compression. Compression is disabled by default."

so like… it's already off, but now it's officially off. 💅

🚫 no_sslv2

the flag of the same name in Boost.Asio — https://www.boost.org/doc/libs/1_78_0/doc/html/boost_asio/reference/ssl__context_base/no_sslv2.html — and it says:

"Disable SSL v2."

🚫 no_sslv3

the flag of the same name in Boost.Asio — https://www.boost.org/doc/libs/1_78_0/doc/html/boost_asio/reference/ssl__context_base/no_sslv3.html — and it says:

"Disable SSL v3."

🚫 no_tlsv1

the flag of the same name in Boost.Asio — https://www.boost.org/doc/libs/1_78_0/doc/html/boost_asio/reference/ssl__context_base/no_tlsv1.html — and it says:

"Disable TLS v1."

🚫 no_tlsv1_1

the flag of the same name in Boost.Asio — https://www.boost.org/doc/libs/1_78_0/doc/html/boost_asio/reference/ssl__context_base/no_tlsv1_1.html — and it says:

"Disable TLS v1.1."

🚫 no_tlsv1_2

the flag of the same name in Boost.Asio — https://www.boost.org/doc/libs/1_78_0/doc/html/boost_asio/reference/ssl__context_base/no_tlsv1_2.html — and it says:

"Disable TLS v1.2."

🚫 no_tlsv1_3

the flag of the same name in Boost.Asio — https://www.boost.org/doc/libs/1_78_0/doc/html/boost_asio/reference/ssl__context_base/no_tlsv1_3.html — and it says:

"Disable TLS v1.3."

🔄 single_dh_use

the flag of the same name in Boost.Asio — https://www.boost.org/doc/libs/1_78_0/doc/html/boost_asio/reference/ssl__context_base/single_dh_use.html — and it says:

"Always create a new key when using tmp_dh parameters."

fresh key every time. main character energy, no recycling. 👑

ok that's the whole page, we ate and left zero crumbs. 🍓✨

signing off on behalf of Emilua 0.12.1-nixpkgs1, dated 1980-01-01 — the EMILUA(3em) girlies stay timeless. mwah 💋🫶

📦 where this page comes from