Feature Request — Yandex 2FA (yaotp scheme)

[lapytko]

Summary

Add support for Yandex's proprietary OTP scheme (yaotp), which is not compatible with standard TOTP (RFC 6238). The differences are fundamental: the output is 8 lowercase letters (not digits), the HMAC key is derived by hashing PIN ‖ secret via SHA-256, and the final code is base-26 encoded. A standard TOTP library cannot produce correct Yandex OTPs without a dedicated implementation.

---

URI Format

Yandex Authenticator exports the following URI scheme when scanning a QR code from Yandex ID:

otpauth://yaotp/<login>?secret=<BASE32>&pin=<PIN>&length=8&pin_length=<N>
    &chars=alpha&uid=<UID>&name=<DISPLAY_NAME>
    &is_2fa=true&is_pin_saved_by_user=true&is_team=false
    &machine_readable_login=<login>&image=<URL>&creation_type=unknown

Real-world example (redacted)

otpauth://yaotp/username?chars=alpha&length=8&pin=244277&pin_length=6
    &secret=CZJSEQFM2EQCT2CAKPSUSDHZNY&uid=131541563

URI field reference

Field	Value (example)	Meaning
scheme	yaotp	Not totp — requires separate parser branch
secret	CZJSEQFM2EQCT2CAKPSUSDHZNY	Base32-encoded 16-byte TOTP seed
pin	244277	Numeric PIN, present in plaintext in the URI
pin_length	6	Must match len(pin) — validate on import
length	8	OTP output length in characters
chars	alpha	Output charset: lowercase letters a–z only, not digits
uid	131541563	Yandex user ID (informational, not used in OTP math)
is_pin_saved_by_user	true	PIN was set by user (always true for yaotp)

Critical: algorithm and period are not present in the URI. Both are fixed and implied:

• Algorithm: SHA-256 (always)
• Period: 30 seconds (always)

---

Algorithm Specification

Reference implementation: KeeYaOtp (C#, GPL-3.0).

Full pipeline

Step	Operation	Detail
1	Decode secret	key_material = base32_decode(secret) — all bytes of the decoded secret
2	Build HMAC key input	key_input = PIN_utf8 ‖ key_material (bytes concatenation)
3	Derive key hash	key_hash = SHA-256(key_input)
4	Strip leading zero	If key_hash[0] == 0x00: key_hash = key_hash[1:] (31 bytes)
5	Compute time counter	period = floor(unix_timestamp_utc / 30) as uint64
6	HMAC	mac = HMAC-SHA256(key=key_hash, msg=period_big_endian_8_bytes)
7	Dynamic truncation	offset = mac[-1] & 0x0F; slice = int64_be(mac[offset:offset+8]) & 0x7FFFFFFFFFFFFFFF
8	Base-26 encode	otp = base26(slice % 26^8), zero-padded to 8 lowercase letters

Comparison with standard RFC 6238 TOTP

Property	RFC 6238 (standard)	Yandex yaotp
URI scheme	totp	yaotp
HMAC key	raw base32-decoded secret	SHA-256(PIN_utf8 ‖ decoded_secret)
Hash algorithm	SHA-1 (default)	SHA-256 (fixed)
Time step	30 s	30 s
Output length	6 digits	8 characters
Output charset	0–9	a–z (base-26)
PIN handling	none	key derivation input

Reference Python implementation

import base64, hmac, hashlib, struct, time

def decode_b32(s: str) -> bytes:
    s = s.upper()
    s += "=" * ((8 - len(s) % 8) % 8)
    return base64.b32decode(s)

def yandex_otp(secret_b32: str, pin: str, timestamp: float = None, step: int = 30) -> str:
    """
    Generate a Yandex yaotp one-time password.

    Args:
        secret_b32: Base32-encoded secret from the yaotp URI `secret` field.
        pin:        Numeric PIN string from the yaotp URI `pin` field.
        timestamp:  Unix timestamp (UTC). Defaults to time.time().
        step:       Time step in seconds. Always 30 for Yandex.

    Returns:
        8-character lowercase OTP string (a–z).
    """
    if timestamp is None:
        timestamp = time.time()

    # Step 1–2: derive HMAC key
    key_material = decode_b32(secret_b32)
    key_input    = pin.encode("utf-8") + key_material
    key_hash     = hashlib.sha256(key_input).digest()

    # Step 4: strip leading 0x00 byte if present
    if key_hash[0] == 0x00:
        key_hash = key_hash[1:]

    # Step 5: time counter
    period = int(timestamp) // step
    msg    = struct.pack(">Q", period)

    # Step 6: HMAC-SHA256
    mac = hmac.new(key_hash, msg, hashlib.sha256).digest()

    # Step 7: dynamic truncation (RFC 4226 style, but 8 bytes → int64)
    offset    = mac[-1] & 0x0F
    slice_val = struct.unpack(">Q", mac[offset:offset + 8])[0] & 0x7FFFFFFFFFFFFFFF

    # Step 8: base-26 encode to 8 lowercase letters
    val    = slice_val % (26 ** 8)
    result = ["a"] * 8
    for i in range(7, -1, -1):
        result[i] = chr(ord("a") + val % 26)
        val //= 26

    return "".join(result)

---

Test Vectors

Generated with secret=CZJSEQFM2EQCT2CAKPSUSDHZNY, pin=244277, step=30.
Use a fixed timestamp (do not call time.time()) to reproduce these values.

Timestamp (T)	Period (T÷30)	Expected OTP
0	0	srfywrjz
30	1	uklhjvdc
1700000000	56666666	bjtoownp
1700000030	56666667	aempofsc
1750000000	58333333	cgaycunq
1750000030	58333334	kkukwufu

Reproduce with:

assert yandex_otp("CZJSEQFM2EQCT2CAKPSUSDHZNY", "244277", timestamp=0)          == "srfywrjz"
assert yandex_otp("CZJSEQFM2EQCT2CAKPSUSDHZNY", "244277", timestamp=1700000000) == "bjtoownp"
assert yandex_otp("CZJSEQFM2EQCT2CAKPSUSDHZNY", "244277", timestamp=1750000000) == "cgaycunq"

---

URI Parser Requirements

The parser must handle the yaotp scheme as a separate code path from totp/hotp:

1. Detect otpauth://yaotp/ and route to the Yandex OTP handler.
2. Read secret, pin, length, pin_length, chars fields.
3. Validate chars == "alpha" and length == 8 (reject or warn otherwise).
4. Validate len(pin) == int(pin_length).
5. Store secret and pin as separate fields — never pre-concatenate or bake the PIN into the secret at storage time.
6. Do not require algorithm or period fields — they are absent from the URI and implied.

---

Secret Storage Schema

{
  "type":       "yaotp",       // distinguishes from "totp"
  "secret":     "<BASE32>",    // raw base32 seed, stored as-is
  "pin":        "<digits>",    // numeric string, stored separately
  "pin_length": 6,             // integer, for validation
  "length":     8,             // OTP output character count (always 8)
  "chars":      "alpha",       // always "alpha" for Yandex
  "period":     30,            // implied, stored explicitly for clarity
  "uid":        "<string>"     // optional, informational only
}

PIN and secret must be stored separately so that a PIN change does not require re-enrollment.

---

Acceptance Criteria

• otpauth://yaotp/ URI is parsed without error; otpauth://totp/ behavior is unchanged
• Key derivation uses SHA-256(PIN_utf8 ‖ base32_decode(secret)) with leading-zero-byte stripping
• HMAC input is floor(unix_utc / 30) as 8-byte big-endian uint64
• Output is 8 lowercase letters (a–z), base-26 encoded
• All 6 test vectors above pass with fixed timestamps
• pin and secret are stored in separate fields; concatenation occurs only at OTP generation time
• len(pin) != pin_length triggers a validation error on import
• Unit tests cover: correct OTP, PIN="0000" edge case, leading-zero-byte stripping (mock SHA-256 to return 00...), malformed base32

---

References

• KeeYaOtp — reference C# implementation (GPL-3.0) — the only known open-source implementation with full algorithm source
• RFC 6238 — TOTP
• RFC 4226 — HOTP
• Bitwarden Community: Yandex TOTP discussion
• Yandex ID 2FA documentation (ru)

[stefan0xC]

This would have to be implemented client side. See FAQs#I have a feature request for the web-vault (or any other client).