bee2-rs 0.2.3

Bindings for cryptographic library Bee2
Documentation 
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
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160

/*
*******************************************************************************
\file blob.h
\brief Blobs
\project bee2 [cryptographic library]
\created 2012.04.01
\version 2022.06.17
\copyright The Bee2 authors
\license Licensed under the Apache License, Version 2.0 (see LICENSE.txt).
*******************************************************************************
*/

/*!
*******************************************************************************
\file blob.h
\brief Блобы
*******************************************************************************
*/

#ifndef __BEE2_BLOB_H
#define __BEE2_BLOB_H

#include "bee2/defs.h"

#ifdef __cplusplus
extern "C" {
#endif

/*!
*******************************************************************************
\file blob.h

Блоб -- объект в памяти определенного размера. В функциях работы с блобами
используются их дескрипторы -- "умные" указатели. С дескрипторами можно
работать как с обычными указателями, т.е. использовать их в функциях типа
memcpy, memset. Дополнительно по указателю можно определить размер блоба.

Реализация работы с блобами может быть платформенно-зависимой.

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

\pre В функциях работы с блобами дескрипторы входных блобов корректны.
*******************************************************************************
*/

/*! Дескриптор блоба. */
typedef void* blob_t;

/*!	\brief Создание блоба

	Создается блоб размера size.
	\return Дескриптор созданного блоба. Нулевой дескриптор возвращается
	при нулевом size и при нехватке памяти.
	\post Выходной блоб корректен.
	\remark При создании блоба все его октеты обнуляются.
*/
blob_t blobCreate(
	size_t size		/*!< [in] размер */
);

/*!	\brief Корректный блоб?

	Проверяется корректность блоба blob.
	\return Признак корректности.
	\remark Блоб с нулевым дескриптором считается корректным.
*/
bool_t blobIsValid(
	const blob_t blob		/*!< [in] блоб */
);

/*!	\brief Изменение размера блоба

	Размер блоба blob изменяется на size с сохранением содержимого.
	\return Дескриптор созданного блоба. Нулевой дескриптор
	возвращается при нулевом size и при нехватке памяти.
	\remark Если блоб еще не создан, то он создается.
	\remark При ошибках выделения памяти blob остается действительным.
	\remark Если размер блоба не меняется, то и дескриптор не меняется.
	\remark Вызов с нулевым size эквивалентен вызову blobClose().
	\remark При увеличении размера в блоб дописываются нулевые октеты.
	\remark При уменьшении размера ненужные октеты отбрасываются,
	но первые size октетов сохраняются.
*/
blob_t blobResize(
	blob_t blob,	/*!< [in] блоб */
	size_t size		/*!< [in] новый размер */
);

/*!	\brief Очистка блоба

	Выполняется очистка блоба blob.
*/
void blobWipe(
	blob_t blob		/*!< [in] блоб */
);

/*!	\brief Очистка и освобождение блоба

	Выполняется очистка и освобождение блоба blob.
*/
void blobClose(
	blob_t blob		/*!< [in] блоб */
);

/*!	\brief Размер блоба

	Определяется размер блоба blob.
	\return Размер блоба.
*/
size_t blobSize(
	const blob_t blob		/*!< [in] блоб */
);

/*!	\brief Копирование блоба

	Блоб src копируется в блоб dest.
	\return Дескриптор блоба-приемника. Дескриптор совпадает c dest
	при совпадении размеров dest и src. Нулевой дескриптор
	возвращается при нулевом src и при нехватке памяти.
	\remark При нулевом dest блоб-приемник создается, при ненулевом --
	настраивается размер блоба.
*/
blob_t blobCopy(
	blob_t dest,			/*!< [out] назначение */
	const blob_t src		/*!< [in] источник */
);

/*!	\brief Совпадение блобов

	Проверяется совпадение блобов blob1 и blob2: a == b, если 
	size(a) == size(b) и value(a) < value(b).
	\return Признак совпадения.
*/
bool_t blobEq(
	const blob_t blob1,		/*!< [in] первый блоб */
	const blob_t blob2		/*!< [in] второй блоб */
);

/*!	\brief Сравнение блобов

	Блоб blob1 сравнивается с блобом blob2: a < b, если size(a) < size(b) 
	или size(a) == size(b) и value(a) < value(b).
	Условие value(a) < value(b) означает, что имеется i < size(a) т.ч.
	value(a)[0..i - 1] == value(b)[0..i - 1] и value(a)[i] < value(b)[i].
	\return 0, если блобы совпадают,
	< 0, если blob1 меньше blob2,
	> 0, если blob1 больше blob2.
*/
int blobCmp(
	const blob_t blob1,		/*!< [in] первый блоб */
	const blob_t blob2		/*!< [in] второй блоб */
);

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

#endif /* __BEE2_BLOB_H */