From 11f58ba3d33a110f6b4ac336c2775ceee3951aeb Mon Sep 17 00:00:00 2001
From: Aster Seker <git.electroyar@gmail.com>
Date: Sat, 6 Sep 2025 01:59:45 +0300
Subject: [PATCH] docs(readme): clarify HOTP/TOTP parameters

---
 README-RU.md | 14 ++++++++++++++
 README.md    | 15 +++++++++++++++
 2 files changed, 29 insertions(+)

diff --git a/README-RU.md b/README-RU.md
index 5460de0..a20e930 100644
--- a/README-RU.md
+++ b/README-RU.md
@@ -195,6 +195,11 @@ auto key  = hmac::pbkdf2_hmac_sha256(password, salt, iters, 32);
 ### 🕓 HOTP и TOTP токены
 
 Библиотека поддерживает генерацию одноразовых паролей по RFC 4226 и RFC 6238.
+Секрет передаётся в виде сырых байт. Если он задан в Base32 (часто в OTP URI),
+сначала декодируйте его.
+
+- **HOTP** — 6 цифр, SHA-1.
+- **TOTP** — период 30 с, 6 цифр, SHA-1. `is_totp_token_valid` допускает окно ±1 интервал.
 
 #### HOTP (HMAC-based One-Time Password)
 
@@ -205,6 +210,7 @@ std::string key = "12345678901234567890"; // raw key
 uint64_t counter = 0;
 int otp = get_hotp_code(key, counter); // по умолчанию: 6 цифр, SHA1
 std::cout << "HOTP: " << otp << std::endl;
+bool ok = (otp == 755224); // тестовый вектор RFC 4226
 ```
 
 #### TOTP (Time-based One-Time Password)
@@ -224,6 +230,14 @@ uint64_t time_at = 1700000000;
 int otp = get_totp_code_at(key, time_at);
 ```
 
+Для проверки кода:
+
+```cpp
+bool valid = hmac::is_totp_token_valid(94287082, key, 59, 30, 8, hmac::TypeHash::SHA1); // тестовый вектор RFC 6238
+```
+
+Известные тестовые векторы: [RFC 4226, приложение D](https://www.rfc-editor.org/rfc/rfc4226#appendix-D) и [RFC 6238, приложение B](https://www.rfc-editor.org/rfc/rfc6238#appendix-B).
+
 ### 🕓 Временные токены на основе HMAC (Custom HMAC Time Tokens)
 
 Библиотека также включает **облегчённую реализацию временных HMAC-токенов**, не связанную напрямую с RFC 4226/6238 (HOTP/TOTP). Эти токены:
diff --git a/README.md b/README.md
index 83b4fac..cad2483 100644
--- a/README.md
+++ b/README.md
@@ -236,6 +236,12 @@ auto okm = hmac::hkdf_expand_sha256(prk, {}, 32); // derive 32 bytes
 ### 🕓 HOTP and TOTP Tokens
 
 The library supports generating one-time passwords based on RFC 4226 and RFC 6238.
+Secrets are supplied as raw bytes. If you receive a Base32 string (common in OTP
+URIs), decode it before calling the functions.
+
+- **HOTP** — 6 digits, SHA-1.
+- **TOTP** — 30 s period, 6 digits, SHA-1. `is_totp_token_valid` accepts tokens
+  from the previous and next interval (±1).
 
 #### HOTP (HMAC-based One-Time Password)
 
@@ -246,6 +252,7 @@ std::string key = "12345678901234567890"; // raw key
 uint64_t counter = 0;
 int otp = get_hotp_code(key, counter); // defaults: 6 digits, SHA1
 std::cout << "HOTP: " << otp << std::endl;
+bool ok = (otp == 755224); // RFC 4226 test vector
 ```
 
 #### TOTP (Time-based One-Time Password)
@@ -265,6 +272,14 @@ uint64_t time_at = 1700000000;
 int otp = get_totp_code_at(key, time_at);
 ```
 
+To verify a received code:
+
+```cpp
+bool valid = hmac::is_totp_token_valid(94287082, key, 59, 30, 8, hmac::TypeHash::SHA1); // RFC 6238 test vector
+```
+
+Known test vectors: [RFC 4226 Appendix D](https://www.rfc-editor.org/rfc/rfc4226#appendix-D) and [RFC 6238 Appendix B](https://www.rfc-editor.org/rfc/rfc6238#appendix-B).
+
 ### 🕓 Time-Based HMAC Tokens (Custom HMAC Time Tokens)
 
 The library also includes a **lightweight implementation of time-based HMAC tokens**, which are not directly based on RFC 4226/6238 (HOTP/TOTP). These tokens: