/*
*******************************************************************************
\file safe.h
\brief Safe (regular) calculations
\project bee2 [cryptographic library]
\created 2013.10.07
\version 2025.07.24
\copyright The Bee2 authors
\license Licensed under the Apache License, Version 2.0 (see LICENSE.txt).
*******************************************************************************
*/

/*!
*******************************************************************************
\file safe.h
\brief Регулярные вычисления
*******************************************************************************
*/

#ifndef __BEE2_SAFE_H
#define __BEE2_SAFE_H

#ifdef __cplusplus
extern "C" {
#endif


/*!
*******************************************************************************
\file safe.h

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

Регулярные вычисления -- это "равномерные" вычисления, всегда одни и те же 
при обработке различных данных определенных размерностей. 

Комментарии о регулярности даются в окружении \\safe. В этом окружении 
указываются источники нерегулярности и причины, по которым регулярность 
подерржать невозмножно / нецелесообразно:
-	условные переходы (условия определяются входными данными);
-	цикл с переменным числом шагов (условие выхода из цикла определяется 
	входными данными);
-	нерегулярные композиционные блоки (например, вызываемые функции);
-	обрабатываемые данные не могут быть секретными;
-	логика работы функции противоречит регулярности (например, функция
	рассчитывает характеристики данных).
.

Функция f() может быть представлена в двух редакциях: регулярной и ускоренной 
нерегулярной. Имя ускоренной редакции: FAST(f).

Регулярная и ускоренная редакции функции имеют одинаковый интерфейс и не
отличаются глубиной стека (см. \ref stack.h).

Для анализа падения производительности обычных (одноредакционных) функций
предусмотрена директива SAFE_FAST. При включении директивы задействуются
ускоренные редакции фрагментов кода, при невключении -- регулярные.
Директива будет поддерживаться вплоть до завершения регуляризации bee2.

\warning Директива SAFE_FAST используется исключительно для исследований.
Она не должна включаться при обычной сборке программ. 

\remark Длины строк, размерности массивов не считаются критическими данными.

\remark Флуктуации при загрузке данных из массивов пока не считаются факторами
нерегулярности.

\remark Отладочные версии заведомо нерегулярны.
*******************************************************************************
*/

/*!	\brief Имя ускоренной редакции функции f */
#define FAST(f) f##_fast

#ifdef __cplusplus
} /* extern "C" */
#endif

#endif /* __BEE2_SAFE_H */
