Skip to content

docs: sync Russian README with English #78

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
LimiNode merged 1 commit into from
Sep 6, 2025
Merged

docs: sync Russian README with English #78

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 64 additions & 11 deletions README-RU.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,20 @@ CI охватывает Linux/Windows/macOS. Тестировалась с GCC,

---

## 📈 Версионирование / политика SemVer

* Следуем [Semantic Versioning](https://semver.org).
* MAJOR: изменения, ломающие заголовки или экспортируемые символы.
* MINOR: обратно совместимые добавления.
* PATCH: исправления ошибок и внутренние изменения.

Макросы версии находятся в `<hmac_cpp/version.hpp>`:
`HMAC_CPP_VERSION_MAJOR`, `HMAC_CPP_VERSION_MINOR`,
`HMAC_CPP_VERSION_PATCH` и `HMAC_CPP_VERSION`.
История — в [CHANGELOG.md](CHANGELOG.md).

---

## 🔧 Сборка и установка

Примеры, тесты и бенчмарки по умолчанию отключены. Включаются опциями:
Expand All @@ -39,6 +53,10 @@ CI охватывает Linux/Windows/macOS. Тестировалась с GCC,
* `HMACCPP_BUILD_TESTS`
* `HMACCPP_BUILD_BENCH`

Библиотека по умолчанию собирается **статически**. Чтобы получить динамическую,
используйте `-DHMACCPP_BUILD_SHARED=ON`. Макрос `HMAC_CPP_API` пуст для статической
сборки и управляет экспортом/импортом символов в динамической.

### Сборка

```bash
Expand All @@ -50,23 +68,21 @@ cmake --build build

```bash
cmake --install build --prefix _install
# MSVC
cmake --install build --config Release --prefix _install
```

Структура установки:

```
_install/
├─ include/hmac_cpp/
│ ├─ hmac.hpp
│ ├─ hmac_utils.hpp
│ ├─ sha1.hpp
│ ├─ sha256.hpp
│ ├─ sha512.hpp
│ └─ secure_buffer.hpp # если включён в сборку
├─ include/hmac_cpp/...
└─ lib/
└─ libhmac_cpp.a
```

Файл `hmac_cpp.pc` устанавливается для `pkg-config`.

### Использование с CMake

```cmake
Expand All @@ -79,6 +95,10 @@ target_link_libraries(my_app PRIVATE hmac_cpp::hmac_cpp)
```bash
# подберите пути под свой префикс
g++ example.cpp -std=c++11 -I_install/include -L_install/lib -lhmac_cpp
# MSVC
cl /EHsc example.cpp /I _install\\include /link /LIBPATH:_install\\lib hmac_cpp.lib
# pkg-config
c++ example.cpp $(pkg-config --cflags --libs hmac_cpp)
```

Предусмотрены скрипты сборки для MinGW: `build_*.bat`.
Expand Down Expand Up @@ -117,6 +137,26 @@ secure_buffer key(std::move(secret_string)); // обнуляет перемещ
auto mac = hmac::get_hmac(key, payload, hmac::TypeHash::SHA256);
```

### HMAC (сырой буфер)

```cpp
std::vector<uint8_t> get_hmac(
const void* key_ptr, size_t key_len,
const void* msg_ptr, size_t msg_len,
TypeHash type);
```

### HMAC (векторы)

```cpp
template<typename T>
std::vector<uint8_t> get_hmac(
const std::vector<T>& key,
const std::vector<T>& msg,
TypeHash type);
// T должен быть char или uint8_t
```

### PBKDF2 (RFC 8018)

Вывод ключа из пароля.
Expand All @@ -133,6 +173,8 @@ auto key = hmac::pbkdf2_hmac_sha256(password, salt, iters, 32); // 32 = AES-256
* **Итерации**: подберите ~100–250 мс на целевой платформе (настольный ≈ 600k, ноутбук ≈ 300k, мобильный ≈ 150k).
* **Длина ключа**: 32 байта; **PRF**: HMAC-SHA256.

> PBKDF2 в основном нагружает CPU; для пользовательских паролей по возможности предпочтительны KDF с высокой требовательностью к памяти, например Argon2 или scrypt.

**Пример сериализации** (бинарный):

```
Expand Down Expand Up @@ -208,6 +250,16 @@ bool v2 = hmac::is_token_valid(t2, secret_key, fingerprint, 60);

---

### Помощники кодирования

`hmac_cpp::encoding` предоставляет простые преобразования:

* **Base64** — стандартный `+/` и URL-безопасный `-_` алфавиты; `pad=true/false` включает или отключает `=`. `strict=true` отклоняет пробелы, смешанный паддинг и `+`/`/` при URL-алфавите; `strict=false` игнорирует ASCII-пробелы, допускает эти символы и добавляет недостающий паддинг.
* **Base32** — `pad=true/false` управляет `=`; `strict=true/false` работает аналогично.
* **Base36** — кодирует сырые байты в ASCII-цифры/буквы; при декодировании требуется полный ввод.

---

## 📦 Совместимость с MQL5

Репозиторий предоставляет `sha256.mqh`, `sha512.mqh`, `hmac.mqh`, `hmac_utils.mqh` (MetaTrader 5).
Expand Down Expand Up @@ -281,18 +333,19 @@ g++ example.cpp -std=c++11 -I_install/include -L_install/lib -lhmac_cpp
MSVC:

```bat
cl /EHsc example.cpp /I _install\\include /link /LIBPATH:_install\\lib hmach_cpp.lib
cl /EHsc example.cpp /I _install\\include /link /LIBPATH:_install\\lib hmac_cpp.lib
```

---

## ⚠️ Исключения и контракты

* Функции могут бросать `std::invalid_argument` (неверные параметры) и `std::runtime_error` (внутренние ошибки).
* `constant_time_equal` предполагает публичность длин; сравнивайте размеры заранее.
* `pbkdf2`, `hkdf_*`, HOTP/TOTP и временные токены проверяют параметры и бросают `std::invalid_argument`; функции временных токенов также могут бросать `std::runtime_error`, если системные часы недоступны.
* `base64_decode` и `base32_decode` помечены `noexcept` и возвращают `false` при некорректном вводе.
* `constant_time_equal` — `noexcept`; перед сравнением проверьте совпадение размеров.
* Ограничения PBKDF2: `dkLen ≤ (2^32−1)·hLen`; итераций ≥ 1; рекомендуемая длина соли ≥ 16 байт.
* Ограничения HKDF: `L ≤ 255·HashLen`.
* Потокобезопасность: функции статичны и потокобезопасны при раздельных буферах.
* Потокобезопасность: функции не имеют состояния и потокобезопасны при раздельных буферах.

---

Expand Down
Loading