Skip to content

docs: clarify HOTP/TOTP parameters and examples #65

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 5, 2025
Merged

docs: clarify HOTP/TOTP parameters and examples #65

Show file tree
Hide file tree
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
14 changes: 14 additions & 0 deletions README-RU.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand All @@ -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)
Expand All @@ -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). Эти токены:
Expand Down
15 changes: 15 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand All @@ -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)
Expand All @@ -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:
Expand Down
Loading