TLSPOOL_PRNG(3)

📦 version 0.9.7, in nixos 26.05

💅 TLSPOOL_PRNG 💅

okay so bestie, you're in the Library Calls section (that's the manual name btw, slay) and this page is all about tlspool_prng — pulling pseudo-random bytes out of a TLS master secret like it's nothing. let's go 🎀

✨ NAME ✨

tlspool_prng — Pseudo-Random Number Generation from TLS master secret

🌸 SYNOPSIS 🌸

#include <stdint.h>
#include <tlspool/commands.h>
#include <tlspool/starttls.h>

int tlspool_prng (char *label,
       uint16_t ctxvalue_len, uint8_t *opt_ctxvalue,
       uint16_t prng_len, uint8_t *prng_buf,
       uint8_t *ctlkey);

🦋 DESCRIPTION 🦋

tlspool_prng() generates a pseudo-random sequence based on session cryptographic keys. and in the case of TLS? it adheres to RFC 5705, periodt ✨ other protocols may or may not support a similar mechanism — and if they don't, you get an error back. no cap.

this whole thing leans on access privileges to an existing connection at a meta-level, and for that we use the customary ctlkey verification mechanism introduced with tlspool_starttls(). and like, heads up bestie: random material may be used for security purposes, such as finding the same session key for both sides deriving from prior key negotiation — so the protection of a ctlkey for these applications is important. fr fr. 🔥

the inputs to this function must adhere to the following restrictions:

  • label must not be a NULL pointer, but opt_ctxvalue may be set to NULL to bypass the use of a context value. not me pointing out the nuance but: note that passing an empty string in opt_ctxvalue is different from not providing the string at all by setting it to NULL. only when opt_ctxvalue is not NULL will the value of ctxvalue_len be used. 💀
  • label refers to an ASCII string with printable characters, terminated with a NUL character. the maximum string length is 254 bytes and its value is subject to limitations as per RFC 5705.
  • if not NULL, opt_ctxvalue refers to an arbitrary sequence of octets. it too has an upper limit of 254 bytes. constraints may be imposed on the contents as a result of the registration of the label string.
  • prng_len holds the requested number of pseudo-random bytes
  • prng_buf points is a non-NULL pointer to a buffer that can hold prng_len bytes.

if the operation succeeds, then prng_buf holds prng_len bytes of random material. if the operation fails, then prng_buf is filled with zero bytes — to make it stand out as a rather rare case of a random byte string. iconic 🫶

now, note a few restrictions to the generality of this function, as a result of the underlying packet format for the communication with the TLS Pool. but the dimensions have been choosen such that these restrictions would not typically be a problem in practice:

  • it constrains the string lengths of label and opt_ctxvalue
  • it constrains prng_len to a maximum value of TLSPOOL_PRNGBUFLEN

the TLS Pool may limit certain TLS PRNG labels, in adherence to the IANA-maintained TLS Exporter Label Registry. it additionally supports the EXPERIMENTAL label prefix specified in RFC 5705. 👑

be advised that the maximum size of buffer may increase in future releases. so, be sure to use TLSPOOL_PRNGBUFLEN which holds the header-file defined size. don't hardcode it, i'm begging 🙈

💀 RETURN VALUE 💀

the function returns 0 on success. if an error occurs, the function returns -1 and errno is set appropriately. and in addition to this behaviour, an error situation resets the prng_len bytes in prng_buf to zero — that is just to make it obvious that it is not random material. you should be really cautious about not missing the error reports from this function, and these zeroes are there to help you with that. like, they're literally doing you a solid. 🌈

🧚 AUTHOR 🧚

Written by Rick van Rein of OpenFortress.nl, for the ARPA2.net project. 💜

🍓 REPORTING BUGS 🍓

for any discussion, including about bugs, please use the mailing list found on http://lists.arpa2.org/mailman/listinfo/tls-pool.

please read the software distribution's README, INSTALL and TODO files for information about the tlspool-daemon implementation status. ✨

Copyright © 2015 Rick van Rein, ARPA2.net.

ARPA2 is funded from InternetWide.org, which in turns receives donations from various funding sources with an interest in a private and secure Internet that gives users control over their online presence. this particular project has been sponsored in part by NCSC. 🌸

⭐ SEE ALSO ⭐

the TLS Pool API is documented in the include file <tlspool/commands.h> and <tlspool/starttls.h> for C, and the tlspool.py module for Python. 🦋

online resources may be found on the project home page, http://tlspool.arpa2.net.

and that's the whole page, bestie — courtesy of ARPA2.net, dated November 2010, iykyk 💅🎀 (yes the date is ancient, the docs still ate, don't @ me)

📦 where this page comes from