Yerel İmza Aracı (Local Signer) Entegrasyonu

Bu rehber, son kullanıcının bilgisayarında kurulu e‑imza aracı ile tarayıcı arasındaki iletişimi ve PrimeAPI ile bütün akışı açıklar. Amaç: güvenli, hızlı ve kullanıcı dostu bir imzalama deneyimi sağlamak.

Mimari gereği X-API-KEY yalnız sizin sunucu katmanında tutulur. Tarayıcı PrimeAPI'ye doğrudan erişmez.

Mimarinin genel resmi

  • İstemci (tarayıcı): Yerel imza aracı ile konuşur ve sadece sizin sunucunuza istek atar.
  • Yerel İmza Aracı: Son kullanıcının bilgisayarında çalışır (8099 portu). Uç noktalar: /ping, /reset, /signStepTwo.
  • Sizin Sunucunuz: PrimeAPI ile konuşur; CreateState... ve FinishSign... çağrılarını yapar; operationId zincirini yönetir.
  • PrimeAPI: Belge ve imza işlemlerini gerçekleştirir, her adımda yeni operationId üretir.
TarayıcıYerel İmza Aracı (8099)Sizin SunucunuzPrimeAPI/ping, /reset, /signStepTwoCreateState..., FinishSign...İstemci → Sizin SunucuSunucu → PrimeAPI

Bağlantı tespiti: ping zinciri

Tarayıcı yerel araca sırasıyla bağlanmayı dener:

  1. https://localsigner.onaylarim.com:8099/ping (500ms timeout)
  2. http://localsigner.onaylarim.com:8099/ping
  3. http://localhost:8099/ping
// Ping akışı (özet)
const httpsOk = await LocalSignerPing(true, false)
if (!httpsOk) {
  const httpOk = await LocalSignerPing(false, false)
  if (!httpOk) {
    const httpLocalhostOk = await LocalSignerPing(false, true)
  }
}

Kod örneği:

async function LocalSignerPing(useHttps: boolean, useLocalhost: boolean): Promise<boolean> {
  const base = useLocalhost ? 'localhost:8099' : 'localsigner.onaylarim.com:8099'
  const url = `${useHttps ? 'https' : 'http'}://${base}/ping`
  try {
    const axiosResponse = await axios.get(url, { timeout: 500 })
    return !!axiosResponse?.data && !axiosResponse?.data?.error
  } catch {
    return false
  }
}

RESET: sertifikaları ve sürümü alma

Bağlantı kurulduktan sonra GET /reset çağrısı ile:

  • Takılı sertifikalar listelenir.
  • Ajan platformu (windows/macos/linux/freebsd) ve DLL sürümü okunur.
  • Onaylarım API’den çekilen “son sürüm” ile kıyaslanır; eskiyse kullanıcı yönlendirilir.

Kod örneği:

function LocalSignerReset() {
  axios.get(workingUrl.value + '/reset').then((result) => {
    signerAppResetResult.value = result.data
    // platforma göre desiredVersion seç ve dllVersion ile kıyasla
    // sertifika listesini kullanıcıya göster
  })
}

İmzalama akışı (PAdES örneği)

  1. İstemci dosyayı sunucuya yükler → operationId (op1)
  2. Sunucu, PrimeAPI’ye CreateStateOnOnaylarimApiForPadesV2 çağrısı yapar → keyID, keySecret, state ve yeni operationId (op2)
  3. Tarayıcı yerel araca POST /signStepTwo gönderir (kart şifresi/PIN ile imzalar) → signedData
  4. İstemci signedData’yı sunucuya gönderir; sunucu PrimeAPI’de FinishSignForPadesV2 yapar → yeni operationId (op3)

Kod akışı (özet):

// 2) Sunucu → PrimeAPI: CreateState... → keyId, keySecret, state, operationId
// 3) Tarayıcı → Yerel Ajan: POST ${workingUrl}/signStepTwo (PIN/sertifika ile imzalar)
// 4) Tarayıcı → Sunucu: signedData; Sunucu → PrimeAPI: FinishSign... → yeni operationId

signStepTwo istek gövdesi örneği:

{
  "keyId": "KEY_ID",
  "keySecret": "KEY_SECRET",
  "state": "STATE",
  "pkcsLibrary": "pkcs11-lib-path-or-name",
  "slot": 0,
  "pin": "****",
  "certificateIndex": 0
}

CAdES ve XAdES için izlenen model aynıdır; yalnızca sunucu tarafında kullanılan CreateState... ve FinishSign... uç noktaları değişir.

Hata yönetimi

Yerel ajan dönüşleri:

  • INCORRECT_PIN: Kullanıcıya şifre yanlış mesajı gösterin; tekrar denemesine izin verin.
  • PIN_BLOCKED: Kart şifresi bloke; kurtarma/yardım yönlendirmesi yapın.
  • Diğer hatalar: Ham hata mesajını kullanıcı-dostu metne çevirip loglayın.

Kod örneği:

if (signStepTwoResult?.error) {
  const err = String(signStepTwoResult.error)
  if (err.includes('INCORRECT_PIN')) {
    // kullanıcıya şifrenin hatalı olduğunu bildir, yeniden denet
  } else if (err.includes('PIN_BLOCKED')) {
    // kart şifresi bloke mesajı ve yardım yönlendirmesi
  }
}

Güvenlik ve UX notları

  • X-API-KEY asla tarayıcıya verilmez; PrimeAPI çağrıları sadece sunucudan yapılır.
  • 500ms ping timeout ile hızlı tespit; başarısızsa otomatik fallback kademeleri.
  • Ajanı başlatmak için özel şema: onaylarimsignerapp:"start".
  • Sertifika birden fazlaysa seçim ekranı; tekse otomatik seçim.

Örnek uçtan uca (özet)

# İstemci → Sizin Sunucunuz
POST /Onaylarim/UploadFileV2           # op1
# Sunucu → PrimeAPI: CreateState...     # op2
# İstemci → Yerel ajan: /signStepTwo    # signedData
# İstemci → Sizin Sunucunuz: FinishSign # op3

İlgili kaynaklar

Was this page helpful?