brng.h(3)

📦

version 2.2.0 · 2 versions

2.2.0 · fedora 44 (latest)
2.1.6 · fedora 43

🌈 brng.h(3) — Library Functions Manual 🌈

okay so bestie, this is brng.h(3), library functions manual, section 3. it's giving crypto, it's giving standards-compliance, and we are so ready. 💅

🎀 NAME 🎀

brng.h — the СТБ 34.101.47 (brng) algorithms. that's the whole name, no notes. 💖

✨ SYNOPSIS ✨

#include 'bee2/defs.h'

🦋 Функции (the functions) 🦋

size_t brngCTR_keep() — how many bytes the CTR functions need for their state. the length of the state, periodt. 💫
void brngCTRStart(void *state, const octet key[32], const octet iv[32]) — boot up CTR mode. ✨
void brngCTRStepR(void *buf, size_t count, void *state) — generate a chunk in CTR mode. 🍓
void brngCTRStepG(octet iv[32], void *state) — grab the sync vector (iv) for CTR mode. 👀
err_t brngCTRRand(void *buf, size_t count, const octet key[32], octet iv[32]) — generate, CTR style. 🔥
size_t brngHMAC_keep() — how many bytes the HMAC functions need for their state. 💫
void brngHMACStart(void *state, const octet key[], size_t key_len, const octet iv[], size_t iv_len) — boot up HMAC mode. ✨
void brngHMACStepR(void *buf, size_t count, void *state) — generate in HMAC mode. 🍓
err_t brngHMACRand(void *buf, size_t count, const octet key[], size_t key_len, const octet iv[], size_t iv_len) — generate in HMAC mode, the high-level way. 🔥

💖 Подробное описание (DESCRIPTION) 💖

so what's actually in here: these are the pseudorandom number generation algorithms defined in СТБ 34.101.47 (brng). when this page talks about algorithms, tables, or any other object, it means the sections of СТБ 34.101.47-2012 where those objects are defined. iykyk. 📚

in every single case, the auxiliary hashing algorithm is belt-hash (see СТБ 345.101.31). yes bestie, every case. 💅

СТБ 34.101.47 also defines an auxiliary key-dependent hashing algorithm, HMAC. the implementation of that algorithm built on top of belt-hash lives over in belt.h. go say hi. 🦋

the main algorithms are grouped into groups, and those groups define these cryptographic mechanisms:

CTR — generation in counter mode;
HMAC — generation in HMAC mode.

CTR mode uses a 32-octet key. HMAC mode uses a key of arbitrary length — but the recommendation is a 32-octet key, fr fr. 🎀

each mechanism is implemented by a pair of functions. those functions share a common state, and the pointer to it gets passed into the function as an extra parameter. there's also a _keep function that tells you how much memory the state needs. the calling program allocates that memory, and the calling program is also the one on the hook for wiping it clean. you make the mess, you clean the mess. 🧹

the state can be copied like any old fragment of memory. no drama, it's just bytes. 💜

every pair must have an initialization function (Start) plus one or more functions that generate data or hand back service data (StepX). 🌸

here's the logic behind the StepX suffixes:

R — rand (generate it);
G — get (grab the sync vector).

a function of type StepR matches the gen_i interface (see defs.h). 👑

the functions in a pair are designed to be as simple and efficient as possible. and like, in particular? they do not check their input data. not even a little. 🙈

each pair is covered by a high-level function that handles all the data in one go. and those high-level functions? they do check input data. the adults are supervising. ✨

🫶 Ожидается (what's expected)

the shared state of a function pair is not modified outside of those functions. stay in your lane, state. 💅

🫶 Ожидается [ERR_BAD_INPUT] (what's expected, error edition)

all input pointers are valid. all of them. every single one. ⭐

🫶 Предусловие (precondition)

unless stated otherwise, the input buffers of the functions in a pair do not overlap. don't do it. 💀

okay bestie, that's the shape of it — buffers, states, pairs, and zero input validation in the low-level stuff. more of this page is coming. 🌈

🎀 Функции 🎀

Оки-окей bestie, вот тут начинается самое вкусное — сами функции ✨ Их две большие семейки: одна генерит в режиме CTR, вторая — в режиме HMAC. Идём по порядку, я всё разложу, ничего не потеряется, обещаю 🫶

`size_t brngCTR_keep ()`

Слушай, это буквально «сколько места мне надо под стейт» — функция возвращает длину состояния (в октетах) для функций генерации в режиме CTR. Вызови её заранее, зарезервируй местечко, и живи спокойно 💅

Возвращает

Длина состояния.

`err_t brngCTRRand (void * buf, size_t count, const octet key[32], octet iv[32])`

В буфер [count]buf записываются псевдослучайные данные, которые сгенерировались в режиме CTR на ключе key при использовании синхропосылки iv 🔥

И вот бонус, который все вечно забывают: в iv дополнительно возвращается обновлённая синхропосылка, и её можно спокойно юзать при повторном вызове функции с тем же ключом. It's giving «сам себя обновляю» 😌

Возвращает

ERR_OK, если данные успешно сгенерированы, и код ошибки в противном случае.

Предупреждения

При многократном вызове функции с одним и тем же ключом должны использоваться различные синхропосылки. При повторе синхропосылок могут быть повторно сгенерированы те же данные.

Да, серьёзно. Один ключ + повторяющиеся синхропосылки = ты сама себе испортила рандом 😭 Не делай так.

Прим.

Первоначальное содержимое buf используется для формирования дополнительного слова X алгоритма генерации (см. п. 6.2.2). Слово X разбивается на последовательные блоки из 32 октетов, при необходимости дополняясь нулевыми октетами 🦋

Аргументы

buf — дополн. / псевдослучайные данные
count — число октетов buf
key — ключ
iv — первонач. / обновл. синхропосылка

`void brngCTRStart (void * state, const octet key[32], const octet iv[32])`

По ключу key и синхропосылке iv в state формируются структуры данных, необходимые для генерации псевдослучайных чисел в режиме CTR ✨ Типа «разложи всё по местам, потом будем генерить».

Предусловие

По адресу state зарезервировано brngCTR_keep() октетов. Не зарезервировала? Ну тогда не жалуйся 🙈

Предупреждения

При многократном вызове функции с одним и тем же ключом должны использоваться различные синхропосылки. При повторе синхропосылок могут быть повторно сгенерированы те же данные.

Да-да, опять это. Это правило преследует нас по всей семейке CTR, прими как факт 💀

Прим.

Разрешается передавать нулевой указатель iv. В этом случае будет использоваться нулевая синхропосылка 👑

Аргументы

state — состояние
key — ключ
iv — синхропосылка

`void brngCTRStepG (octet iv[32], void * state)`

Возвращается синхропосылка iv, установленная при вызове brngCTRStart() и изменённая затем при последовательных вызовах brngCTRStepR() 🎀

Ожидается

(brngCTRStepR()* < brngCTRStepG())*

Прим.

Если сгенерировано полное число блоков, то полученная синхропосылка будет отличаться от ранее использованных. Поэтому эту синхропосылку можно задавать при повторном вызове функций связки с тем же ключом 💖

Аргументы

iv — синхропосылка
state — состояние

`void brngCTRStepR (void * buf, size_t count, void * state)`

В буфер [count]buf записываются октеты, полученные в результате псевдослучайной генерации в режиме CTR. При генерации используются структуры данных, развёрнутые в state 🔥

Ожидается

brngCTRStart() < brngCTRStepR()*

Прим.

Данные в режиме CTR генерируются блоками по 32 октета. Реализована буферизация блоков, и функцию можно вызвать с произвольным значением count. Если не все данные сгенерированного ранее блока израсходованы, то они будут возвращены в первую очередь ✨

Если работает буферизация и возвращаются данные сгенерированного ранее блока, то соответствующие октеты buf не используются для формирования слова X, эти октеты пропускаются. Поэтому, в частности, строки

brngCTRStepR(buf + 16, 16, state), brngCTRStepR(buf + 16, 16, state);
brngCTRStepR(buf, 32, state);

вызываемые сразу после brngCTRStart(), не эквивалентны друг другу 😳

Да, вот такие дела. Не взаимозаменяй их, ок?

Аргументы

buf — дополн. / псевдослучайные данные
count — число октетов buf
state — состояние

`size_t brngHMAC_keep ()`

Возвращается длина состояния (в октетах) функций генерации в режиме HMAC 🎀 Тот же вайб, что и у CTR-версии, только для HMAC-семейки.

Возвращает

Длина состояния.

`err_t brngHMACRand (void * buf, size_t count, const octet key[], size_t key_len, const octet iv[], size_t iv_len)`

В буфер [count]buf записываются псевдослучайные данные, сгенерированные в режиме HMAC на ключе [key_len]key при использовании синхропосылки [iv_len]iv 💅

Ожидается `[ERR_BAD_INPUT]`

Буферы buf и iv не пересекаются. Типа — не накладывай их друг на друга, это буквально просьба 😭

Возвращает

ERR_OK, если данные успешно сгенерированы, и код ошибки в противном случае.

Предупреждения

При многократном вызове функции с одним и тем же ключом должны использоваться различные синхропосылки. При повторе синхропосылок будут повторно сгенерированы те же данные.

Заметь: тут будут повторно сгенерированы, без всяких «могут». Так что не повторяй синхропосылки, серьёзно 💀

Прим.

Ограничений на iv_len нет (ср. с функцией brngHMACStart()) 🔥

Рекомендуется использовать ключ из 32 октетов 👑

Аргументы

buf — выходные данные
count — число октетов buf
key — ключ
key_len — длина ключа в октетах
iv — синхропосылка
iv_len — длина синхропосылки в октетах

`void brngHMACStart (void * state, const octet key[], size_t key_len, const octet iv[], size_t iv_len)`

По ключу [key_len]key и синхропосылке [iv_len]iv в state формируются структуры данных, необходимые для генерации псевдослучайных чисел в режиме HMAC ✨

Предусловие

По адресу state зарезервировано brngHMAC_keep() октетов.

Ожидается

Если длина синхропосылки в октетах (iv_len) больше 64, то буфер iv остаётся корректным и постоянным вплоть до завершения работы с механизмом ⚠️ То есть не трогай его, пока не закончишь, ок?

Предупреждения

При многократном вызове функции с одним и тем же ключом должны использоваться различные синхропосылки. При повторе синхропосылок будут повторно сгенерированы те же данные.

Прим.

Рекомендуется использовать ключ из 32 октетов 👑

При iv_len <= 64 содержимое [iv_len]iv сохраняется в state 🎀

Аргументы

state — состояние
key — ключ
key_len — длина ключа в октетах
iv — синхропосылка
iv_len — длина синхропосылки в октетах

`void brngHMACStepR (void * buf, size_t count, void * state)`

В буфер [count]buf записываются октеты, полученные в результате псевдослучайной генерации в режиме HMAC. При генерации используются структуры данных, развёрнутые в state 🔥

Ожидается

brngHMACStart() < brngHMACStepR()*

Прим.

Данные в режиме HMAC генерируются блоками по 32 октета. Реализована буферизация блоков, и функцию можно вызвать с произвольным значением count. Если не все данные сгенерированного ранее блока израсходованы, то они будут возвращены в первую очередь ✨

Аргументы

buf — псевдослучайные данные
count — размер buf в октетах
state — состояние

🌸 Автор 🌸

Автоматически создано Doxygen для Библиотека Bee2 из исходного текста 🦋

Всё, bestie, это была страничка brng.h(3) из Библиотека Bee2, и дата у неё — Вс 25 Янв 2026 00:00:00. Слэй, ты дочитала до конца, я тобой горжусь 💖✨🎀

📦 where this page comes from

fedora 44: bee2-devel 2.2.0-1.fc44 · GPL-3.0-only and GPL-3.0-or-later
fedora 44: bee2-devel 2.2.0-1.fc44 · GPL-3.0-only and GPL-3.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms