IBAN ve TC Kimlik No Doğrulama: Kontrol Haneleri Nasıl Hesaplanır, Neyi Kanıtlamaz?

Geçerli biçim, var olan hesap demek değil

Diyelim ki ödeme formunuz IBAN alanını yeşile boyadı, kayıt veritabanına girdi ve ertesi gün transfer "alıcı hesap bulunamadı" diye geri döndü. Kodunuzda hata yok. Doğrulama size yalnızca bir şey söylüyordu ve o şey "bu hesap var" değildi.

Aynı yanılgı TC Kimlik No için de geçerli. Kontrol hanesi tutan on bir hane, bir insanın varlığını kanıtlamaz. Üstüne bir de ters yönden risk var: geçerli bir TCKN üretmek o kadar kolay ki örnek verirken bile birinin gerçek numarasını yazıya dökebilirsiniz. Bu yazıda o yüzden tek bir tam ve geçerli TCKN göreceksiniz: hiç.

Önce iki algoritmanın içine girip JavaScript ve Python ile çalıştıracağız, sonra doğrulamanın bittiği yeri ve KVKK tarafını konuşacağız.

IBAN'ın anatomisi

ISO 13616-1:2020'ye göre bir IBAN, iki harfli ISO 3166 ülke kodu, iki kontrol hanesi ve ülkenin kendi belirlediği BBAN'dan (Basic Bank Account Number) oluşur. Toplam uzunluk en fazla 34 karakterdir ama her ülke kendi sabit uzunluğunu kullanır. SWIFT'in tuttuğu IBAN Registry'ye göre bu uzunluk Norveç'te 15, Saint Lucia'da 32 karakter.

Türkiye tarafını belirleyen metin TCMB'nin 2008/6 sayılı Uluslararası Banka Hesap Numarası Hakkında Tebliğ'i. IBAN 26 karakterdir ve alanlar soldan sağa şöyle dizilir:

Tebliğ iki ayrıntıyı daha açıkça yazıyor. IBAN içinde İ, Ç, Ğ, Ö, Ş, Ü harfleri ve küçük harf kullanılmaz. Registry'deki resmî örnek TR330006100519786457841326. Kurum kodu 00061, rezerv hane 0, kalanı hesap numarası. Rezerv hanenin sıfır olması size bedava bir kontrol veriyor. IBAN'ın 10. karakteri 0 değilse, kontrol hanelerine hiç bakmadan reddedebilirsiniz.

MOD 97-10 adım adım

Kontrol hanelerinin hesabı ISO/IEC 7064:2003'teki MOD 97-10 yöntemine dayanıyor. Doğrulama dört adım:

1. 1Boşlukları atın, harfleri büyütün.
2. 2İlk dört karakteri (ülke kodu ve kontrol haneleri) en sona taşıyın.
3. 3Her harfi iki haneli bir sayıyla değiştirin: A=10, B=11, ... Z=35. TR böylece 2927 olur.
4. 4Ortaya çıkan sayının 97'ye bölümünden kalan 1 ise IBAN biçim olarak geçerlidir.

Registry örneğinde üçüncü adımın sonunda 28 haneli bir sayı çıkıyor. JavaScript'in Number tipi ise yalnızca 2⁵³'e kadar olan tam sayıları kayıpsız tutabiliyor, yani 16 hane civarında hassasiyet bitiyor. Sayıyı doğrudan çevirip mod almak sessizce yanlış sonuç verir:

1const digits = '0006100519786457841326292733';2 3console.log(Number(digits));4// 6.100519786457841e+245console.log(Number(digits) % 97);6// 96  (yanlış)7console.log(BigInt(digits) % 97n);8// 1n  (doğru)

Kalan 96 çıkıyor ve hiçbir hata fırlatılmıyor. ES2020 ile gelen BigInt sorunu çözüyor ama eski tarayıcıları da destekliyorsanız yaygın ve her ortamda çalışan yol daha sağlam: sayıyı soldan parça parça işleyip her adımda kalanı bir sonraki parçanın önüne eklemek. Kalan en fazla iki hane olduğundan yedi hanelik parçalarla ara değer dokuz haneyi hiç geçmiyor.

1function normalizeIban(input) {2  return input.normalize('NFKC').replace(/[\s-]/g, '').toUpperCase();3}4 5// Ülke kodu ve kontrol hanelerini sona at, harfleri sayıya çevir (A=10 ... Z=35)6function toDigits(iban) {7  const rearranged = iban.slice(4) + iban.slice(0, 4);8  return rearranged.replace(/[A-Z]/g, (ch) => String(ch.charCodeAt(0) - 55));9}10 11// Uzun sayıyı 7'şer hanelik parçalarla mod 97'ye indir12function mod97(digits) {13  let rest = 0;14  for (let i = 0; i < digits.length; i += 7) {15    rest = Number(rest + digits.slice(i, i + 7)) % 97;16  }17  return rest;18}19 20function isValidTrIban(input) {21  const iban = normalizeIban(input);22  if (!/^TR[0-9]{2}[0-9]{5}0[0-9A-Z]{16}$/.test(iban)) return false;23  return mod97(toDigits(iban)) === 1;24}25 26console.log(toDigits('TR330006100519786457841326'));27// 000610051978645784132629273328console.log(mod97(toDigits('TR330006100519786457841326')));29// 130console.log(isValidTrIban('tr33 0006 1005 1978 6457 8413 26'));31// true32console.log(isValidTrIban('TR330006100519786457841362')); // son iki hane yer değiştirdi33// false

Son satırdaki örnekte yalnızca iki hanenin yeri değişti ve mod 97 bunu yakaladı. Bu bir tesadüf değil. Aşağıda TCKN ile karşılaştırırken tekrar döneceğim.

Kontrol hanelerini kendiniz üretmek

Hesap numarasından IBAN üretmeniz gerekiyorsa aynı işlemi tersinden yaparsınız. Kontrol hanelerinin yerine 00 koyup kalanı bulun, 98'den çıkarın ve sonucu iki haneye tamamlayın. Python'un tam sayıları sınırsız büyüdüğü için parçalamaya gerek kalmıyor:

1import re2import unicodedata3 4def normalize(raw: str) -> str:5    raw = unicodedata.normalize('NFKC', raw)6    return re.sub(r'[\s-]', '', raw).upper()7 8def to_digits(s: str) -> str:9    # int('T', 36) == 29, int('7', 36) == 710    return ''.join(str(int(ch, 36)) for ch in s)11 12def check_digits(country: str, bban: str) -> str:13    n = int(to_digits(bban + country + '00'))14    return f'{98 - n % 97:02d}'15 16def is_valid(raw: str) -> bool:17    iban = normalize(raw)18    if not re.fullmatch(r'[A-Z]{2}[0-9]{2}[0-9A-Z]{11,30}', iban):19        return False20    return int(to_digits(iban[4:] + iban[:4])) % 97 == 121 22def print_format(iban: str) -> str:23    return ' '.join(iban[i:i + 4] for i in range(0, len(iban), 4))24 25bban = '00061' + '0' + '0519786457841326'26cd = check_digits('TR', bban)27print(cd)28# 3329print(print_format('TR' + cd + bban))30# TR33 0006 1005 1978 6457 8413 2631print(is_valid('TR33 0006 1005 1978 6457 8413 26'))32# True33print(is_valid('TR３３ 0006 1005 1978 6457 8413 26'))  # tam genişlikli rakamlar34# True

İki küçük ayrıntı var. int(ch, 36) hem rakamları hem harfleri tek hamlede çeviriyor, A için 10, Z için 35 veriyor. Regex'te \d yerine [0-9] yazmamın sebebi de şu: Python'da \d varsayılan olarak bütün Unicode rakamlarını kabul eder, "３" gibi tam genişlikli bir karakter de buna dahil. Kullanıcının yapıştırdığı metni önce NFKC ile normalleştirip sonra yalnızca ASCII kabul etmek, veritabanına garip karakter sızmasını önlüyor.

TCKN: dokuz hane veri, iki hane kontrol

TC Kimlik No 11 hanedir ve ilk hanesi 0 olamaz. Son iki hane, ilk dokuz haneden hesaplanan kontrol haneleridir. 10. haneyi bulmak için 1, 3, 5, 7 ve 9. hanelerin toplamını 7 ile çarpar, 2, 4, 6 ve 8. hanelerin toplamını bundan çıkarır ve sonucun mod 10'unu alırsınız. 11. hane daha basit, ilk on hanenin toplamının mod 10'u.

Bir not düşmem gerekiyor. Bu kural yıllardır yazılımcıdan yazılımcıya aktarılıyor ve sayısız sistemde çalışıyor, ama NVİ'nin yayımladığı resmî bir spesifikasyonda bulabildiğim bir metin yok. O yüzden bu bölümün kaynakçasında bir referans görmeyeceksiniz. Algoritmayı aşağıda kodla sınadım, iddiaları da yalnızca çalıştırdığım koddan türetiyorum.

Adım adım bakalım. Örnek olarak bilerek geçersiz bir önek seçiyorum: 012345678. İlk hanesi 0 olduğu için hiçbir kimlik numarası bununla başlayamaz, ama aritmetiği göstermek için yeterli.

Ortaya çıkan 01234567840 iki kontrol hanesinden de geçiyor ama ilk hane kuralına takılıyor. Bir doğrulayıcıyı test ederken tam da bu yüzden işe yarıyor.

Formülden şaşırtıcı bir sonuç çıkıyor. Tek pozisyonların toplamına T, çiftlerinkine Ç dersek 10. hane 7T − Ç'ye denk, ilk on hanenin toplamı ise T + Ç + 7T − Ç = 8T'ye denk düşüyor. Yani 11. hane hep 8T'nin son rakamı ve bu yüzden hep çift. Son hanesi tek olan bir numarayı başka hiçbir hesaba girmeden reddedebilirsiniz. İlk dokuz hane serbest olduğundan olası numara sayısı da tam 900 milyon.

JavaScript'in negatif mod tuzağı

Formülü JavaScript'e olduğu gibi yazdığınızda (7T − Ç) % 10 her zaman 0 ile 9 arasında kalmaz. JavaScript'te % bölümden kalanı bölünenin işaretiyle döndürüyor, matematikteki mod gibi davranmıyor. İlk hane en az 1 olduğu için T en az 1, Ç ise en fazla 36. 7 × 1 − 36 = −29 ve -29 % 10 sonucu −9 oluyor.

1function isValidTckn(input) {2  const s = String(input).trim();3  if (!/^[1-9][0-9]{10}$/.test(s)) return false;4 5  const d = Array.from(s, Number);6  const odd = d[0] + d[2] + d[4] + d[6] + d[8];7  const even = d[1] + d[3] + d[5] + d[7];8 9  // JavaScript'te % negatif sonuç verebilir, 10 ekleyip tekrar mod al10  const tenth = (((odd * 7 - even) % 10) + 10) % 10;11  const eleventh = (odd + even + d[9]) % 10;12 13  return d[9] === tenth && d[10] === eleventh;14}15 16console.log((10 * 7 - 36) % 10, (1 * 7 - 36) % 10);17// 4 -918console.log(isValidTckn('01234567840')); // kontrol haneleri tutuyor, ilk hane 019// false20console.log(isValidTckn('12345678901'));21// false

Bu hata neden testlerde görünmüyor? 900 milyon önekin tamamını taradığımda negatif ara sonuç veren yalnızca 99.090 önek çıktı, yaklaşık 9.000'de bir. Rastgele birkaç yüz numarayla yazılmış bir test bunu neredeyse hiç yakalamaz. Sonra bir gün gerçek bir kullanıcı numarasını girer ve formunuz "geçersiz" der. Python'da % bölenin işaretini aldığı için aynı satır doğru çalışıyor.

Python'da isdigit tuzağı

1def tckn_check_digits(first9: str) -> str:2    d = [int(c) for c in first9]3    odd = d[0] + d[2] + d[4] + d[6] + d[8]4    even = d[1] + d[3] + d[5] + d[7]5    tenth = (odd * 7 - even) % 10        # Python'da sonuç hep 0-96    eleventh = (odd + even + tenth) % 107    return f'{tenth}{eleventh}'8 9def is_valid_tckn(raw: str) -> bool:10    s = raw.strip()11    if len(s) != 11 or not (s.isascii() and s.isdigit()) or s[0] == '0':12        return False13    return s[9:] == tckn_check_digits(s[:9])14 15print(tckn_check_digits('012345678'))16# 4017print(is_valid_tckn('01234567840'))18# False19print('1234567890²'.isdigit())20# True21print(is_valid_tckn('1234567890²'))22# False

str.isdigit() üst simge "²" gibi karakterler için de True döndürüyor, ardından int() bunları çeviremeyip ValueError fırlatıyor. Doğrulayıcınız bir exception yüzünden 500 dönmesin diye isascii() kontrolünü öne koyun ya da regex'te [0-9] kullanın.

Kontrol hanesinin kör noktası

İki algoritma da tek bir hanenin yanlış yazılmasını her durumda yakalıyor. Fark, yan yana iki hanenin yer değiştirmesinde ortaya çıkıyor. TCKN'de tek ve çift pozisyondaki iki hane yer değiştirince 10. hanenin ara değeri 8 × (fark) kadar oynuyor. Fark 5 ise bu 40 ediyor ve mod 10'da sıfıra düşüyor. 11. hane de 8T'ye bağlı olduğundan aynı şekilde susuyor. 20.000 rastgele numara üzerinde çalıştırdığım betikte farklı rakamlı yan yana yer değiştirmelerin %9,91'i fark edilmedi ve kaçanların hepsinde rakamlar arasındaki fark 5'ti.

Farkın kaynağı bölen. 97 iki haneye sığan en büyük asal sayı ve 10 ile ortak böleni yok. Tek bir rakamın değişmesi sayıyı δ × 10ᵏ kadar, yan yana iki rakamın yer değiştirmesi 9 × δ × 10ᵏ kadar oynatıyor ve δ en fazla 9 olduğu için bu farkların hiçbiri 97'ye tam bölünmüyor. Mod 10'daki "fark 5" tuzağının burada karşılığı yok.

Doğrulamanın kanıtlamadığı şeyler

Kontrol hanesi bir yazım denetimidir. Size "bu dizi kurala uygun" der, başka hiçbir şey söylemez. Biçim doğrulamasından geçmiş bir IBAN kapatılmış bir hesaba, başka birine ait bir hesaba ya da hiç açılmamış bir hesap numarasına işaret ediyor olabilir. Bunu bilen tek taraf, hesabı tutan kurumdur. Transferin gerçekten kime gideceğini ödeme sistemi ve bankanın sunduğu servisler doğrular.

TCKN için de durum aynı. Numaranın bir kişiye ait olup olmadığını ve beyan edilen adla eşleşip eşleşmediğini NVİ söyler. NVİ'nin tckimlik.nvi.gov.tr üzerindeki KPSPublic SOAP servisi en az 2010'dan beri TCKimlikNoDogrula adında bir işlem sunuyor. İşlem TCKN, ad, soyad ve doğum yılını alıp true ya da false dönüyor. Daha kapsamlı sorgular ise NVİ'ye başvurup erişim izni alan kurumların kullanabildiği Kimlik Paylaşımı Sistemi (KPS) üzerinden yapılıyor.

KVKK: TCKN log'a düşmesin

6698 sayılı Kişisel Verilerin Korunması Kanunu, verinin işlendiği amaçla bağlantılı, sınırlı ve ölçülü olmasını (madde 4) ve veri sorumlusunun hukuka aykırı erişimi önleyecek teknik ve idari tedbirleri almasını (madde 12) istiyor. Uygulamada TCKN'nin en sık sızdığı yerler formun kendisi değil, onun etrafındaki altyapı oluyor:

• GET isteğine konmuş bir ?tckn= parametresi, web sunucusunun erişim log'una olduğu gibi yazılır.
• Doğrulama hatasında fırlatılan exception, mesajında değeri de taşıyorsa hata takip aracına gider.
• Request body'yi olduğu gibi loglayan bir middleware, formdaki TCKN'yi de düz metin olarak saklar.
• Analitik event'lerine "debug için" eklenen alanlar üçüncü taraf bir sunucuya taşınır.

Maskeleme işe yarıyor ama kontrol haneleri burada beklenmedik bir sızıntı yaratıyor. Son dört haneyi gösterdiğinizde, bilinmeyen yedi hane için kaba hesapla 9 milyon olasılık kalması gerekir. 10. ve 11. hane ilk dokuz haneye bağlı olduğundan bu sayı 180.000'e iniyor, ben bunu bütün olasılıkları tarayarak saydım. Yalnızca son iki haneyi gösterdiğinizde bile 900 milyonluk uzay 18 milyona düşüyor. Ekranda göstermeniz gerekiyorsa son iki hane yeterli, log'a ise hiçbir parçasını yazmayın.

Bir de "özetini alırız" fikri var. TCKN'nin düz SHA-256 özeti anonimleştirme değildir, çünkü girdi uzayı küçük. 900 milyon adayı tek çekirdekte Python ile özetlemek dakikalar sürüyor. Kayıt eşleştirmek ya da tekrar eden başvuruyu yakalamak için arama anahtarı gerekiyorsa, anahtarı veritabanının dışında duran bir HMAC kullanın. Asıl değeri geri okumanız gerekiyorsa da şifreleme kullanın.

1import hashlib2import hmac3import os4 5def mask_tckn(tckn: str) -> str:6    return '*' * 9 + tckn[-2:]7 8def mask_iban(iban: str) -> str:9    return iban[:4] + ' **** **** **** **** **' + iban[-4:-2] + ' ' + iban[-2:]10 11# Anahtar koddan değil, gizli ortam değişkeninden ya da secret manager'dan gelir12KEY = os.environ.get('TCKN_HMAC_KEY', 'dev-only-key').encode()13 14def tckn_lookup_key(tckn: str) -> str:15    return hmac.new(KEY, tckn.encode(), hashlib.sha256).hexdigest()16 17print(mask_tckn('12345678901'))18# *********0119print(mask_iban('TR330006100519786457841326'))20# TR33 **** **** **** **** **13 2621print(len(tckn_lookup_key('12345678901')))22# 64

Veritabanı tarafında TCKN'yi BIGINT değil CHAR(11) olarak tutmanızı öneririm. Bir kimlik numarası üzerinde toplama yapılmaz, maskeleme ve biçimlendirme metin işlemidir. IBAN zaten harf içerdiği için metin olmak zorunda. Hangi sütuna hangi tipi seçeceğinizi SQL ve RDBMS rehberinde daha ayrıntılı anlattım.

Formda kullanıcıyı yormadan

İnsanlar IBAN'ı bankanın mobil uygulamasından kopyalar, e-postadan yapıştırır, bazen de kâğıttan okuyup dörtlü gruplar hâlinde yazar. Doğrulayıcının işi bu çeşitliliği reddetmek değil, sindirmek. Benim tercih ettiğim akış şöyle:

1. 1Girdiyi önce normalleştirin: NFKC, boşluk ve tire temizliği, büyük harf. Kullanıcıdan "boşluksuz yazın" diye istemeyin.
2. 2Saklarken ve API'ye gönderirken boşluksuz elektronik biçimi kullanın. Tebliğ de elektronik ortamda IBAN'ın bitişik yazılmasını istiyor.
3. 3Gösterirken dört karakterlik gruplara bölün. Yazılı belgelerde dörtlü gösterim tebliğin açık kuralı, ekranda da okumayı ve karşılaştırmayı kolaylaştırıyor.
4. 4Hata mesajını ayırın. "26 karakter olmalı" ile "bir hane yanlış yazılmış olabilir" farklı sorunlar ve kullanıcıya farklı şey yaptırır.
5. 5Doğrulamayı her tuş vuruşunda değil, alan bittiğinde ya da uzunluk tamamlandığında yapın. Yarım bir IBAN'a kırmızı göstermek kullanıcıyı haksız yere suçlar.

Biçim kontrolü için regex yeterli ama aritmetik yapamaz. Desen "TR ve ardından 24 karakter" der, mod 97'yi ise kod hesaplar. Elinizdeki bir IBAN'ı hızlıca kontrol etmek isterseniz IBAN Doğrulama aracı aynı adımları tarayıcıda uyguluyor.

Sonuç

Kontrol hanesini yazım hatasını kullanıcı daha formdayken yakalayan ucuz bir filtre olarak kullanın ve ondan fazlasını beklemeyin. Kuralım şu: biçim kontrolü istemcide ve sunucuda, gerçek doğrulama kaynağında, TCKN ise hiçbir log satırında. Bu üçünden biri eksikse ya kullanıcıyı boşuna yoruyorsunuz ya parayı yanlış yere gönderiyorsunuz ya da sızmayı bekleyen bir veriyi saklıyorsunuz.