From fbdb9ea35ec4ed5a56b223609ea0d4ba0e6fcb52 Mon Sep 17 00:00:00 2001 From: Aster Seker Date: Sat, 6 Sep 2025 04:44:29 +0300 Subject: [PATCH] docs: document versioning and build policies --- CMakeLists.txt | 9 +++++ README.md | 61 ++++++++++++++++++++++++--------- cmake/hmac_cpp.pc.in | 10 ++++++ include/hmac_cpp/hmac_utils.hpp | 1 + include/hmac_cpp/version.hpp | 9 +++++ 5 files changed, 73 insertions(+), 17 deletions(-) create mode 100644 cmake/hmac_cpp.pc.in create mode 100644 include/hmac_cpp/version.hpp diff --git a/CMakeLists.txt b/CMakeLists.txt index 4728950..cc11d35 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -4,6 +4,11 @@ project(hmac_cpp VERSION 0.3.0 LANGUAGES CXX) option(HMACCPP_BUILD_EXAMPLES "Build the example program" OFF) option(HMACCPP_BUILD_TESTS "Build the test suite" OFF) option(HMACCPP_BUILD_BENCH "Build benchmarks" OFF) +option(HMACCPP_BUILD_SHARED "Build hmac_cpp as a shared library" OFF) + +if(HMACCPP_BUILD_SHARED) + set(BUILD_SHARED_LIBS ON) +endif() set(HMAC_SOURCES src/sha1.cpp @@ -23,6 +28,7 @@ set(HMAC_HEADERS include/hmac_cpp/sha512.hpp include/hmac_cpp/secure_buffer.hpp include/hmac_cpp/encoding.hpp + include/hmac_cpp/version.hpp ) add_library(hmac_cpp ${HMAC_SOURCES}) @@ -91,6 +97,9 @@ install(FILES DESTINATION lib/cmake/hmac_cpp ) +configure_file(cmake/hmac_cpp.pc.in "${CMAKE_CURRENT_BINARY_DIR}/hmac_cpp.pc" @ONLY) +install(FILES "${CMAKE_CURRENT_BINARY_DIR}/hmac_cpp.pc" DESTINATION lib/pkgconfig) + if(HMACCPP_BUILD_TESTS) enable_testing() include(FetchContent) diff --git a/README.md b/README.md index f51800f..0816941 100644 --- a/README.md +++ b/README.md @@ -32,6 +32,20 @@ CI covers Linux/Windows/macOS. Tested with GCC, Clang, and MSVC; requires C++11. --- +## πŸ“ˆ Versioning / SemVer policy + +* Follows [Semantic Versioning](https://semver.org). +* MAJOR: breaking changes to headers or exported symbols. +* MINOR: backward-compatible additions. +* PATCH: bug fixes and internal changes. + +Version macros live in ``: +`HMAC_CPP_VERSION_MAJOR`, `HMAC_CPP_VERSION_MINOR`, +`HMAC_CPP_VERSION_PATCH`, and `HMAC_CPP_VERSION`. +See [CHANGELOG.md](CHANGELOG.md) for history. + +--- + ## πŸ”§ Build & Installation Examples, tests, and benchmarks are OFF by default. Enable via: @@ -40,6 +54,10 @@ Examples, tests, and benchmarks are OFF by default. Enable via: * `HMACCPP_BUILD_TESTS` * `HMACCPP_BUILD_BENCH` +The library builds **static** by default. Use `-DHMACCPP_BUILD_SHARED=ON` +to produce a shared library. The `HMAC_CPP_API` macro is empty for static +builds and controls symbol export/import for shared builds. + ### Build ```bash @@ -51,23 +69,21 @@ cmake --build build ```bash cmake --install build --prefix _install +# MSVC +cmake --install build --config Release --prefix _install ``` Install layout: ``` _install/ -β”œβ”€ include/hmac_cpp/ -β”‚ β”œβ”€ hmac.hpp -β”‚ β”œβ”€ hmac_utils.hpp -β”‚ β”œβ”€ sha1.hpp -β”‚ β”œβ”€ sha256.hpp -β”‚ β”œβ”€ sha512.hpp -β”‚ └─ secure_buffer.hpp # if included in your build -└─ lib/ - └─ libhmac_cpp.a +β”œβ”€β”€ include/hmac_cpp/... +└── lib/ + └── libhmac_cpp.a ``` +A `hmac_cpp.pc` file is installed for `pkg-config`. + ### Consume with CMake ```cmake @@ -80,6 +96,10 @@ target_link_libraries(my_app PRIVATE hmac_cpp::hmac_cpp) ```bash # adjust paths to your prefix 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) ``` Predefined MinGW build scripts are available: `build_*.bat`. @@ -154,6 +174,8 @@ auto key = hmac::pbkdf2_hmac_sha256(password, salt, iters, 32); // 32 = AES-256 * **Iterations**: tune for \~100–250 ms on target hardware (e.g., desktop β‰ˆ 600k, laptop β‰ˆ 300k, mobile β‰ˆ 150k; adjust). * **Derived key length**: 32 bytes; **PRF**: HMAC-SHA256. +> PBKDF2 is CPU-bound; for user passwords prefer memory-hard KDFs such as Argon2 or scrypt if available. + **Serialization example** (binary): ``` @@ -262,12 +284,14 @@ ctest --test-dir build --output-on-failure Covered vectors: -* HMAC β€” **RFC 4231** -* PBKDF2 β€” **RFC 6070** -* HOTP β€” **RFC 4226** (Appendix D) -* TOTP β€” **RFC 6238** (Appendix B) +| Suite | RFC | +| ------ | --- | +| HMAC | RFC 4231 | +| PBKDF2 | RFC 6070 | +| HOTP | RFC 4226 (App D) | +| TOTP | RFC 6238 (App B) | -CI runs these on Linux/Windows/macOS. +CI: [GitHub Actions](https://github.com/NewYaroslav/hmac-cpp/actions). --- @@ -302,15 +326,18 @@ 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 ``` --- ## ⚠️ Exceptions & Contracts -* Functions may throw `std::invalid_argument` (bad params) and `std::runtime_error` (internal errors). -* `constant_time_equal` assumes lengths are public; compare sizes first. +* `pbkdf2`, `hkdf_*`, HOTP/TOTP, and time-token helpers validate parameters and throw + `std::invalid_argument`; time-token helpers also throw `std::runtime_error` if the + system clock fails. +* `base64_decode` and `base32_decode` are `noexcept` and return `false` on invalid input. +* `constant_time_equal` is `noexcept`; compare sizes first. * PBKDF2 limits: `dkLen ≀ (2^32βˆ’1)Β·hLen`; iterations β‰₯ 1; salt length β‰₯ 16 recommended. * HKDF limits: `L ≀ 255Β·HashLen`. * Thread-safety: functions are stateless and thread-safe given separate buffers. diff --git a/cmake/hmac_cpp.pc.in b/cmake/hmac_cpp.pc.in new file mode 100644 index 0000000..d7dc602 --- /dev/null +++ b/cmake/hmac_cpp.pc.in @@ -0,0 +1,10 @@ +prefix=@CMAKE_INSTALL_PREFIX@ +exec_prefix=${prefix} +libdir=${exec_prefix}/lib +includedir=${prefix}/include + +Name: hmac_cpp +Description: HMAC/PBKDF2/HKDF library +Version: @PROJECT_VERSION@ +Libs: -L${libdir} -lhmac_cpp +Cflags: -I${includedir} diff --git a/include/hmac_cpp/hmac_utils.hpp b/include/hmac_cpp/hmac_utils.hpp index c393df9..fc71c59 100644 --- a/include/hmac_cpp/hmac_utils.hpp +++ b/include/hmac_cpp/hmac_utils.hpp @@ -76,6 +76,7 @@ namespace hmac_cpp { /// PBKDF2 Security Notes: /// - Use a random salt of at least 16 bytes and never reuse it. + /// - PBKDF2 is CPU-bound; prefer Argon2 or scrypt for user passwords when available. /// - Choose iterations so the derivation takes about 200–500 ms on 2025 hardware. /// - Store {salt, iterations} with the ciphertext or hash; these values are public. /// - Salts and iteration counts must be unique per password. diff --git a/include/hmac_cpp/version.hpp b/include/hmac_cpp/version.hpp new file mode 100644 index 0000000..2afb937 --- /dev/null +++ b/include/hmac_cpp/version.hpp @@ -0,0 +1,9 @@ +#ifndef HMAC_CPP_VERSION_HPP +#define HMAC_CPP_VERSION_HPP + +#define HMAC_CPP_VERSION_MAJOR 0 +#define HMAC_CPP_VERSION_MINOR 3 +#define HMAC_CPP_VERSION_PATCH 0 +#define HMAC_CPP_VERSION "0.3.0" + +#endif // HMAC_CPP_VERSION_HPP