Oğuzhan KARAGÜZEL

OĞUZHAN KARAGÜZEL

Yazılım geliştirici

Açık kaynak · NuGet paketİ · MIT lİsansİ

SpectraUtils

Türkiye'de yazılan .NET uygulamalarında her projede yeniden yazılan küçük işleri tek pakette toplayan bir kütüphane: TC kimlik, vergi numarası ve IBAN doğrulama, Türkçeye uygun isim düzeltme, PBKDF2 ile şifre saklama ve güvenli kod üretimi.

Bu sitenin çalıştığı Elevare de kullanıcı adlarını ve isim düzeltmelerini SpectraUtils ile yapıyor.

NuGet'te görGitHub'da incele
Program.cs
$ dotnet add package SpectraUtils

using SpectraUtils.Validation;

bool tckn = TurkishIdentityNumberValidator.IsValid("10000000146");  // true
bool vkn  = TurkishTaxNumberValidator.IsValid("1739750504");     // true
bool iban = IbanValidator.IsValid("TR33 0006 1005 1978 6457 8413 26", expectedCountryCode: "TR");

string ad = names.FullNameCorrection("oğuzhan", "karagüzel");  // "Oğuzhan KARAGÜZEL"

01 · Hikâye

Neden yazdım?

Türkiye'de çalışan hemen her uygulamada aynı küçük sorular çıkıyor: Kullanıcının yazdığı TC kimlik numarası gerçekten geçerli mi? Vergi numarasının son hanesi tutuyor mu? IBAN eksik ya da fazla haneyle mi girilmiş? İsimler de ayrı bir dert. "ismail" büyük harfe çevrildiğinde "İSMAİL" olmalı ama sunucunun dil ayarı İngilizceyse .NET size "ISMAIL" verir.

Bu kodları her yeni projede baştan yazmaktan ya da eski bir projeden kopyalamaktan sıkıldım. 2023'te hepsini tek bir pakette topladım ve NuGet'e koydum. O günden beri kullandıkça düzelttiğim, ihtiyaç çıktıkça büyüttüğüm bir kütüphane oldu. 3.0 sürümünde de baştan sona gözden geçirdim.

02 · Paketler

İki paket, ihtiyacınız kadarı

Çekirdek paket ASP.NET Core'a bağlı değildir; konsol uygulamasında da arka plan servisinde de çalışır. Dosya yükleme doğrulaması için ayrı bir paket var.

Çekirdek

SpectraUtils

Doğrulayıcılar ve doğrulama öznitelikleri, isim düzeltme, şifre hash'leme, token, tek kullanımlık kod ve şifre üretimi, LINQ ve metin uzantıları. Dışarıdan aldığı tek şey Microsoft'un DI ve Options soyutlamaları.

dotnet add package SpectraUtils
ASP.NET Core eki

SpectraUtils.AspNetCore

Dosya yüklemeleri için [AllowedExtensions] özniteliği. IFormFile ve IFormFileCollection üzerinde uzantıyı ve boyutu denetler. Yalnızca form ile dosya alıyorsanız gerekir.

dotnet add package SpectraUtils.AspNetCore

03 · İçindekiler

Neler var?

Hepsi tek bir derdi çözen küçük parçalar. İstediğinizi kullanır, gerisine dokunmazsınız.

01

TC kimlik numarası

İki kontrol hanesiyle birlikte doğrular. [TCIDValidation] boş değeri de geçersiz sayar, yani alanı kendiliğinden zorunlu yapar.

02

Vergi numarası

10 haneli vergi kimlik numarasının kontrol hanesini resmî algoritmayla hesaplar. Aradaki boşlukları görmezden gelir.

03

IBAN

ISO 13616 ve MOD-97 kontrolünün üstüne ülkeye göre uzunluk denetimi yapar: TR ile başlayan bir IBAN 26 karakter olmak zorundadır.

04

Yaş sınırı

[MinimumAge(18)] doğum tarihinden yaşı hesaplar. DateOnly, DateTime ve DateTimeOffset ile çalışır; bugünün tarihini TimeProvider'dan aldığı için testte istediğiniz güne sabitleyebilirsiniz.

05

Türkçe isimler

" aYşe nur " gelir, "Ayşe Nur" kaydedilir. Soyadı büyük harfe çevrilir, i ile İ ve ı ile I birbirine karışmaz. İsimden kullanıcı adı da üretir.

06

Şifre saklama

PBKDF2-HMAC-SHA256 ve 600.000 tur, yani OWASP'ın bugün önerdiği değerler. Her hash kendi ayarlarını içinde taşır; ayarları değiştirseniz de eski hash'ler doğrulanmaya devam eder.

07

Güvenli üreticiler

Şifre sıfırlama token'ı, SMS ile gidecek kod, rastgele şifre. Hepsi RandomNumberGenerator ile ve mod sapması olmadan üretilir.

08

Dosya yükleme

İzin verilen uzantılar ve boyut sınırı. Birden çok dosya gönderildiğinde her biri ayrı ayrı denetlenir; hata mesajında sınır KB ya da MB olarak okunur.

09

Uzantılar

Koşullu filtre için WhereIf, emojiyi bozmadan metni ters çeviren ReverseSafe, Tap ve ForEach gibi her gün lazım olan küçük yardımcılar.

04 · Kullanım

Birkaç örnek

Kurulum tek satır. Gerisi alışık olduğunuz .NET kalıpları: bağımlılık enjeksiyonu ve DataAnnotations.

Servisleri ekleyin

builder.Services.AddSpectraUtils();

// Ayarları değiştirmek isterseniz:
builder.Services.AddSpectraUtils(options =>
{
    options.Pbkdf2.Iterations = 700_000;
});

Servislerin hepsi durumsuzdur ve singleton olarak eklenir. TryAdd kullanıldığı için sizin kayıtlarınız önce gelir. DI kullanmıyorsanız her sınıfı doğrudan new ile oluşturabilirsiniz.

Modeli doğrulayın

public class KayitIstegi
{
    [TCIDValidation]
    public string? KimlikNo { get; set; }

    [TurkishTaxNumberValidation]
    public string? VergiNo { get; set; }

    [IbanValidation("TR")]
    public string? Iban { get; set; }

    [MinimumAge(18, ErrorMessage = "En az {1} yaşında olmalısınız.")]
    public DateOnly? DogumTarihi { get; set; }
}

Hata mesajında {0} alanın adına, {1} de yaş sınırına dönüşür. Mesajları kaynak dosyasından çevirmek için ErrorMessageResourceType de kullanılabilir.

Şifreleri saklayın

string hash = hasher.Hash("Parola123!");
// PBKDF2$SHA256$600000$<salt>$<key>

if (hasher.Verify(girilen, kullanici.SifreHash))
{
    if (hasher.NeedsRehash(kullanici.SifreHash))
        kullanici.SifreHash = hasher.Hash(girilen);
}

NeedsRehash, eski ayarlarla üretilmiş bir hash'i kullanıcı giriş yaptığı anda yeniler. Kimseye şifre değiştirtmeniz gerekmez.

İsimleri düzeltin

names.NameCorrection("  aYşe   nur ");             // "Ayşe Nur"
names.NameCorrection("ismail");                    // "İsmail"
names.SurnameCorrection("yılmaz");                 // "YILMAZ"
names.FullNameCorrection("oğuzhan", "karagüzel");  // "Oğuzhan KARAGÜZEL"
names.StandardizeCharacters("Çağdaş Işık");        // "Cagdas Isik"
names.CreateUserName("Ayşe Nur");                  // "aysenur0427" gibi

Varsayılan olarak Türkçe kurallar geçerlidir. Başka bir kültür isterseniz ayarlardan NameCulture'ı değiştirmeniz yeterli.

Token, kod ve şifre üretin

string token = tokenGenerator.GenerateToken();          // 32 rastgele bayt, URL'de güvenle kullanılır
string kod   = otpGenerator.GenerateNumericCode();      // "048213"
string sifre = passwordHelper.CreateStandardPassword(); // 12 karakter, her türden en az biri

Tek kullanımlık kodları kısa ömürlü sırlar gibi kullanın: birkaç dakikada geçersiz olsun, deneme sayısı sınırlı olsun.

05 · Sürüm 3.0

Neler düzeldi?

3.0, kütüphaneyi baştan sona gözden geçirdiğim sürüm. Bulduğum hataların bazıları can sıkıcıydı; hiçbirini saklamadım, hepsi sürüm notlarında yazıyor.

  1. Geçerli vergi numaralarının yaklaşık %60'ı reddediliyordu

    Resmî algoritmada, sıfırdan farklı olup 9'a tam bölünen bir ara sonuç 9 sayılır. 2.x bunu 0 sayıyordu. Eski sürümün örnek olarak verdiği numara bile aslında geçersizdi.

  2. Çok uzun bir girdi uygulamayı çökertebiliyordu

    IBAN ve vergi numarası doğrulayıcıları, girdinin uzunluğu kadar stack belleği ayırıyordu. API'ye gönderilen birkaç megabaytlık bir metin, süreci stack overflow ile sonlandırıyordu. Artık uzunluk bellek ayrılmadan önce sınırlanıyor.

  3. Uzun tek kullanımlık kodlar zayıftı

    10 ile 18 hane arasındaki kodlar int.MaxValue aralığından çekiliyordu ve hiçbiri 3 ile 9 arasında bir rakamla başlamıyordu. Artık her hane ayrı ayrı ve eşit olasılıkla seçiliyor.

  4. Türkçe harfler kayboluyordu

    Küçük Docker imajlarında sık kullanılan globalization-invariant modda "Ayşe" adından "aye" kullanıcı adı çıkıyordu. Artık her ortamda aynı sonuç çıkıyor.

  5. Sunucunun dosya sistemi yoklanabiliyordu

    Dosya doğrulama özniteliği, kullanıcının gönderdiği metinle File.Exists çağırıyordu. Bu sayede dışarıdan sunucuda hangi dosyaların olduğu denenebiliyordu. Bu çağrı tamamen kaldırıldı.

  6. İki isim tek isim oluyordu

    "ahmet can" düzeltildiğinde "Ahmetcan" çıkıyordu. Artık kelimeler korunuyor ve sonuç "Ahmet Can" oluyor. Soyadları için de aynısı geçerli.

3.0 ayrıca .NET 8 ve .NET 10'u hedefliyor ve isim alanlarını sadeleştiriyor. 2.x kullanıyorsanız geçiş adımları sürüm notlarında. Kayıtlı şifre hash'leri için bir şey yapmanız gerekmiyor; 2.x ile üretilenler doğrulanmaya devam ediyor.

06 · İlkeler

Nasıl davranır?

Bir yardımcı kütüphanenin en kötü yanı sürprizdir. SpectraUtils'te bunları baştan kural olarak koydum.

Doğrulayıcılar hata fırlatmaz

null, boş, bozuk ya da aşırı uzun bir değer için yalnızca false döner. Doğrulama yüzünden try/catch yazmanız gerekmez.

Karşılaştırma sabit zamanlı

Şifre doğrulaması, yanlış bir şifrenin ne kadarının doğru olduğunu geçen süreden belli etmez. Bozuk bir hash istisna değil false üretir.

Ayarlar eski veriyi bozmaz

Tur sayısını, tuz boyutunu ya da algoritmayı değiştirdiğinizde eski hash'ler çalışmaya devam eder. Kurcalanmış ve tur sayısı abartılmış hash'ler ise reddedilir.

07 · Kurulum

Üç adımda başlayın

  1. Paketi ekleyin

    dotnet add package SpectraUtils

  2. Servisleri kaydedin

    using SpectraUtils.Extensions;

builder.Services.AddSpectraUtils();

  3. İstediğiniz yerde kullanın

    public class KayitServisi(IPasswordHasher hasher, INameEdit names)
{
    // ...
}

    Arayüzler SpectraUtils.Abstractions, öznitelikler SpectraUtils.Attributes.ValidationAttributes isim alanındadır.

Kaynak kodu GitHub'da

Bir hata bulursanız ya da eksik bir doğrulayıcı aklınıza gelirse depoda issue açabilirsiniz. Güvenlik açıklarını ise GitHub'ın gizli bildirim kanalından iletin.

Depoya gitNuGet sayfası