Merge branch 'main' into codex/update-readme-with-pbkdf2-security-notes

Author: LimiNode

.github/workflows/CI-macOS.yml

@@ -0,0 +1,48 @@
+name: CI-macOS
+
+on:
+  push:
+    branches:
+      - main
+      - release/**
+      - stable
+  pull_request:
+    branches:
+      - main
+      - release/**
+      - codex/**
+
+jobs:
+  Tests-macOS:
+    runs-on: macos-latest
+    strategy:
+      matrix:
+        std: [11, 17]
+    steps:
+      - uses: actions/checkout@v3
+      - name: Install dependencies
+        run: |
+          brew update
+          brew uninstall --ignore-dependencies cmake || true
+          brew install cmake
+      - name: Configure
+        run: cmake -S . -B build -DBUILD_TESTS=ON -DCMAKE_CXX_STANDARD=${{ matrix.std }}
+      - name: Build
+        run: cmake --build build
+      - name: Run tests
+        run: cd build && ctest --output-on-failure
+  vcpkg:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Install vcpkg
+        run: |
+          git clone https://github.com/microsoft/vcpkg.git
+          ./vcpkg/bootstrap-vcpkg.sh
+          ./vcpkg/vcpkg install gtest
+      - name: Configure
+        run: cmake -S . -B build -DBUILD_TESTS=ON -DCMAKE_TOOLCHAIN_FILE=./vcpkg/scripts/buildsystems/vcpkg.cmake
+      - name: Build
+        run: cmake --build build
+      - name: Run tests
+        run: cd build && ctest --output-on-failure

.github/workflows/benchmarks.yml

@@ -0,0 +1,16 @@
+name: Benchmarks
+
+on:
+  push:
+    tags:
+      - '*'
+
+jobs:
+  benchmark:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Install dependencies
+        run: sudo apt-get update && sudo apt-get install -y cmake hyperfine
+      - name: Run benchmarks
+        run: scripts/run_benchmarks.sh

README-RU.md

@@ -2,6 +2,8 @@
 
 [![Linux](https://github.com/NewYaroslav/hmac-cpp/actions/workflows/CI-Linux.yml/badge.svg?branch=main)](https://github.com/NewYaroslav/hmac-cpp/actions/workflows/CI-Linux.yml)
 [![Windows](https://github.com/NewYaroslav/hmac-cpp/actions/workflows/CI-Win.yml/badge.svg?branch=main)](https://github.com/NewYaroslav/hmac-cpp/actions/workflows/CI-Win.yml)
+[![macOS](https://github.com/NewYaroslav/hmac-cpp/actions/workflows/CI-macOS.yml/badge.svg?branch=main)](https://github.com/NewYaroslav/hmac-cpp/actions/workflows/CI-macOS.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
 Лёгкая `C++11` библиотека для вычисления `HMAC` (hash-based message authentication code), поддерживающая поддерживающая `SHA256`, `SHA512`, `SHA1`, а также одноразовые пароли `HOTP` и `TOTP`.
 
@@ -278,4 +280,4 @@ int main() {
 Проект распространяется под лицензией **MIT**.  
 Это означает, что вы можете свободно использовать, копировать, модифицировать и распространять код, при условии сохранения оригинального уведомления о лицензии.
 
-См. файл [`LICENSE`](./LICENSE) для подробностей.
+См. файл [`LICENSE`](./LICENSE) для подробностей.

README.md

@@ -2,6 +2,8 @@
 
 [![Linux](https://github.com/NewYaroslav/hmac-cpp/actions/workflows/CI-Linux.yml/badge.svg?branch=main)](https://github.com/NewYaroslav/hmac-cpp/actions/workflows/CI-Linux.yml)
 [![Windows](https://github.com/NewYaroslav/hmac-cpp/actions/workflows/CI-Win.yml/badge.svg?branch=main)](https://github.com/NewYaroslav/hmac-cpp/actions/workflows/CI-Win.yml)
+[![macOS](https://github.com/NewYaroslav/hmac-cpp/actions/workflows/CI-macOS.yml/badge.svg?branch=main)](https://github.com/NewYaroslav/hmac-cpp/actions/workflows/CI-macOS.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
 A lightweight `C++11` library for computing `HMAC` (hash-based message authentication codes), supporting `SHA1`, `SHA256`, `SHA512`, as well as one-time passwords compliant with `HOTP` (RFC 4226) and `TOTP` (RFC 6238).
 
@@ -78,6 +80,10 @@ Alternatively, use the helper script:
 scripts/run_tests.sh
 ```
 
+## Test Vectors
+
+The test suite covers official vectors from [RFC 4231](https://www.rfc-editor.org/rfc/rfc4231) and [RFC 6070](https://www.rfc-editor.org/rfc/rfc6070) and runs in CI.
+
 ## 📦 MQL5 Compatibility
 
 The repository includes `sha256.mqh`, `sha512.mqh`, `hmac.mqh`, and `hmac_utils.mqh` files, fully compatible with `MetaTrader 5`.
@@ -207,6 +213,22 @@ The pepper is a secret key stored separately from the hashed password.
 - Salts and iteration counts must be unique per password.
 - Example serialization: `{magic|ver|prf|salt|iters|dkLen|…}`.
 
+#### PBKDF2-HMAC-SHA256 + AES-GCM
+
+```cpp
+#include <hmac_cpp/hmac_utils.hpp>
+#include <aes_cpp/aes_utils.hpp>
+
+std::string password = "correct horse battery staple";
+std::vector<uint8_t> salt(16, 0x00); // 16 random bytes
+auto key = hmac::pbkdf2(password, salt, 100000, 32, hmac::Pbkdf2Hash::Sha256);
+
+std::string plaintext = "secret";
+std::vector<uint8_t> aad = {'h','e','a','d','e','r'};
+auto pkt = aes_cpp::utils::encrypt_gcm(plaintext, key, aad);
+auto restored = aes_cpp::utils::decrypt_gcm_to_string(pkt, key, aad);
+```
+
 ### HKDF (RFC 5869)
 
 ```cpp
@@ -312,6 +334,12 @@ int main() {
 **Note:** avoid checking input lengths before calling `constant_time_equal`.
 Early length comparisons can leak information through timing side channels.
 
+## Security Notes
+
+- PBKDF2 is CPU-bound and vulnerable to massive GPU/ASIC brute force. Choose high iteration counts or stronger KDFs.
+- Every password requires a unique, random salt of sufficient length.
+- Salts, iteration counts, and algorithms are not secrets—store them alongside the hash for verification.
+
 ## 📚 Resources
 
 * Original [SHA256 implementation](http://www.zedwood.com/article/cpp-sha256-function)

scripts/run_benchmarks.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+cmake -S . -B build-bench -DCMAKE_BUILD_TYPE=Release
+cmake --build build-bench --config Release
+hyperfine "./build-bench/example"