1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
/*
*******************************************************************************
\file stack.h
\brief Controlled stack
\project bee2 [cryptographic library]
\created 2012.05.10
\version 2025.04.25
\copyright The Bee2 authors
\license Licensed under the Apache License, Version 2.0 (see LICENSE.txt).
*******************************************************************************
*/
/*!
*******************************************************************************
\file stack.h
\brief Контролируемый стек
*******************************************************************************
*/
#ifndef __BEE2_STACK_H
#define __BEE2_STACK_H
#ifdef __cplusplus
extern "C" {
#endif
/*!
*******************************************************************************
\file stack.h
Локальные переменные функций могут размещаться в контролируемом стеке --
области памяти, указатель на которую передается как дополнительный
параметр функции.
Контролируемый стек создается в высокоуровневой функции, передается по
цепочке в низкоуровневые функции, очищается и разрушается при завершении
высокоуровневой функции.
Низкоуровневые функции могут не заботиться об утечке данных через
контролируемый стек и размещать в этом стеке критические объекты.
Низкоуровневые функции могут размещать критические объекты не только
в контролируемом стеке, но еще в переменных, объявленных с ключевым
словом register. При завершении низкоуровневой функции такие переменные
должны быть обнулены.
Значения критических переменных могут определяться через возвращаемые
функциями значения (как правило, значения возвращаются через регистр).
Критические переменные не должны передаваться через обычный стек как
параметры функций.
Пример работы с контролируемым стеком и критической переменной:
\code
void f2(octet a[], size_t n, octet b[], size_t m, void* stack)
{
register word sensitive;
octet* tmp1 = (octet*)stack;
octet* tmp2 = tmp1 + 2 * n;
stack = tmp2 + m;
...
sensitive = f1(tmp1, 2 * n, stack);
...
sensitive = 0;
}
\endcode
Определение функции f, которая использует контролируемый стек, должно
сопровождаться определением функции f_deep, которая определяет
максимальную глубину стека f. Функция f_deep берет на вход произвольное
число аргументов типа size_t (размерностей) или других типов и возвращает
глубину стека в октетах.
Значение f_deep не должно уменьшаться при увеличении любого ее аргумента.
В описании функции f, использующей вспомогательный стек, должен быть
описаны параметры f_deep (схема расчета глубины стека).
Схему рекомендуется описывать следующим образом:
\code
f_deep( // функция
dim1, // первая размерность
dim2, // вторая размерность
...
dimX // последняя размерность
);
\endcode
Например, f1_deep(n), f2_deep2(n, m), f3_deep().
Локальные переменные, размещаемые в контролируемом стеке, могут использоваться
не в одной, а в нескольких функциях. Эти функции образуют, так называемую,
\e связку. Общие локальные переменные функций связки образуют \e состояние.
Указатель на состояние передается как дополнительный параметр функций связки.
Определение связки g должно сопровождаться функцией g_keep, которая возвращает
\e захват стека -- длину состояния в октетах. Функции типа _keep имеют такой
же интерфейс, как и функции типа _deep.
Состояние функции связки и ее стек могут размещаться в одном буфере памяти.
Тем не менее, указатель на состояние (state) рекомендуется отделять от
указателя на стек (stack). Тогда высокоуровневые функции могут более точно
рассчитывать суммарный объем контролируемого стека (состояния различных
связок надо поддерживать неизменными, а стек -- не обязательно).
Для стандартизированного оформления описаний в doxygen предусмотрены
окружения \\deep, \\deep{stack}, \\keep, \\keep{state}.
*******************************************************************************
*/
#ifdef __cplusplus
} /* extern "C" */
#endif
#endif /* __BEE2_STACK_H */