Uzaktan Kod İmzalama API Referansı

Bu belge, uzaktan imzalama yeteneğini doğrudan entegre etmesi gereken Developer'lara yönelik olup aşağıdaki iki arayüzü açıklamaktadır:

• POST /v1/codesign/sign: İmzalanacak hash özetini gönderir ve RSA PKCS#1 imza sonucunu alır.
• POST /v1/codesign/report-sign: İstemcinin nihai işlem sonucunu raporlar (imza sayacını etkilemez).

---

Erişim Adresi

Ortam	Adres
Üretim ortamı (varsayılan)	https://ssl.face.racent.com
NICSRS ortamı	https://ssl.face.nicsrs.com

Diğer ortam adresleri için teslimat veya operasyon ekibinin sağladığı adres geçerlidir.

---

Genel Kurallar

İstek Formatı

• Protokol: HTTPS
• Method: POST
• Body: JSON
• Headers:

Content-Type: application/json
Accept: application/json
Authorization: Basic <base64(accessKey:accessSecret)>

Kimlik Doğrulama

Arayüz, HTTP Basic Auth kullanır:

• Kullanıcı Adı: Access Key
• Parola: Access Secret

Authorization başlığını oluşturma:

printf "%s:%s" "$ACCESS_KEY" "$ACCESS_SECRET" | base64

Genel Yanıt Yapısı

{
  "code": 0,
  "message": "ok",
  "data": {}
}

Alan	Tür	Anlam
code	integer	İş durum kodu. 0 başarıyı, 0 dışındaki değerler iş başarısızlığını gösterir.
message	string	İş durumu açıklaması; başarısızlık durumunda hata açıklamasıdır.
data	object	Arayüz iş verileri.

Çağıran taraf, HTTP durum kodunu ve iş durum kodunu birlikte ele almalıdır:

• HTTP 2xx değilse → HTTP hatası olarak işlem yapın.
• HTTP 2xx ve code != 0 → iş hatası olarak işlem yapın.
• HTTP 2xx ve code == 0 → ilgili data değerini okuyun.

---

İmza Arayüzü

Arayüz Açıklaması

POST /v1/codesign/sign

Orijinal imzalanacak hash baytlarını (Base64 kodlu) gönderin; uzak hizmet, belirtilen sertifikayı kullanarak RSA PKCS#1 imzasını tamamlar ve sonucu döndürür.

Dikkat

/v1/codesign/sign başarıyla imza içeriği döndürdüğünde imza başarılı sayılır ve imza sayısı 1 artar. Başarısız istekler imza sayısını tüketmez. report-sign çağrılıp çağrılmaması sayımı etkilemez.

İstek Parametreleri

{
  "code": "CERT_CODE",
  "digest": "BASE64_ENCODED_HASH",
  "algorithm": "SHA256",
  "padding": "PKCS1",
  "extra": {
    "platform": "windows/amd64",
    "version": "1.0.0",
    "revision": "abcdef0",
    "time": "2026-06-12T10:00:00+08:00",
    "hostname": "build-host-01",
    "signing_filename": "Example.exe",
    "signing_filesize": 1048576
  }
}

Alan	Tür	Zorunlu	Anlamı
code	string	Evet	Sertifika numarası, uzak imza sertifikasını seçmek için kullanılır.
digest	string	Evet	İmzalanacak hash'in ham baytlarının Base64 kodlaması. Çağıran tarafın hedef dosya ve imza aracı gereksinimlerine göre hash'i yerel olarak hesaplaması gerekir.
algorithm	string	Evet	Hash algoritması; SHA1, SHA256, SHA384, SHA512 desteklenir.
padding	string	是	RSA doldurma modu, şu anda sabit olarak PKCS1.
extra	object	否	İstemci bağlam bilgisi; imza kayıtları, denetim ve sorun giderme için kullanılır.

extra alan açıklaması:

Alan	Tür	Anlam
platform	string	İstemci platformu; örn. windows/amd64, linux/amd64.
version	string	İstemci sürümü.
revision	string	İstemci derleme revizyonu.
time	string	İstemci derleme zamanı veya istek zamanı.
hostname	string	İmzalamayı başlatan ana bilgisayar adı.
signing_filename	string	İmzalanan dosya adı veya yolu; güvenlik politikasına göre hassas verilerden arındırılması önerilir.
signing_filesize	integer	İmzalanan dosya boyutu (bayt).

İstek Örneği

curl -u "$ACCESS_KEY:$ACCESS_SECRET" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "code": "CERT_CODE",
    "digest": "BASE64_ENCODED_HASH",
    "algorithm": "SHA256",
    "padding": "PKCS1",
    "extra": {
      "platform": "windows/amd64",
      "version": "1.0.0",
      "hostname": "build-host-01",
      "signing_filename": "Example.exe",
      "signing_filesize": 1048576
    }
  }' \
  https://ssl.face.racent.com/v1/codesign/sign

Başarılı Yanıt

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "735985894427246592",
    "signature": "BASE64_ENCODED_SIGNATURE"
  }
}

Alan	Tür	Anlam
id	string	İmza kaydı ID'si, report-sign çağrılırken kullanılır.
signature	string	RSA imza sonucunun Base64 kodlaması.

---

İmza Sonucunu Bildirme

Arayüz Açıklaması

POST /v1/codesign/report-sign

İstemci, uzak imzalama sonucunu aldıktan sonra yerel işleme, yazma veya çağırana geri verme sırasında başarısız olabilir. Bu arayüz, istemcinin nihai işlem durumunu sunucuya geri iletmek için kullanılır; böylece imza kayıtlarının gösterimi ve denetim amaçlı sorun giderme kolaylaşır.

Açıklama

Bu arayüz yalnızca istemci işlem sonucunu kaydeder, /v1/codesign/sign sayım sonucunu değiştirmez. Bu arayüzün çağrılmaması başarılı imza sayısını etkilemez.

İstek Parametreleri

{
  "id": "735985894427246592",
  "status": 1
}

Alan	Tür	Gerekli	Anlam
id	string	Evet	/v1/codesign/sign tarafından döndürülen data.id.
status	integer	Evet	İstemcinin nihai işlem durumu: 1 başarılı, 2 başarısız.

İstek Örneği

curl -u "$ACCESS_KEY:$ACCESS_SECRET" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "id": "735985894427246592",
    "status": 1
  }' \
  https://ssl.face.racent.com/v1/codesign/report-sign

Başarılı Yanıt

{
  "code": 0,
  "message": "ok",
  "data": null
}

---

Hata Yanıtı Örneği

Kimlik doğrulama hatası:

{
  "code": 401,
  "message": "unauthorized",
  "data": null
}

Parametre hatası:

{
  "code": 400,
  "message": "invalid request",
  "data": null
}

Dikkat

Belirli hata kodları ve hata mesajları için sunucu tarafından fiilen dönen değerler esas alınır. Entegrasyon tarafı, iş mantığı dallandırması için sabit hata metinlerine bağımlı olmamalıdır.

---

Entegrasyon Önerileri

• Access Secret'ı gerektiği gibi koruyun; loglara, çökme raporlarına veya ön uç sayfalarına yazmayın.
• digest, hashlenmiş ham baytların Base64 kodlaması olmalıdır; onaltılık dize veya tam dosya içeriği değildir.
• algorithm, digest alanının gerçek hash algoritmasıyla tutarlı olmalıdır.
• Mevcut dolgu modu sabit olarak PKCS1 kullanır; başka değerler iletmeyin.
• digest ve signature alanları uzun olabilir; loglarda yalnızca uzunluk veya ön ek/son ek maskelenmiş sonuçların kaydedilmesi önerilir.
• İstemci tarafında nihai işlem tamamlandıktan sonra denetim ve sorun giderme için report-sign çağrılarak sonucun raporlanması önerilir.
• Ağ hataları, HTTP hataları ve iş hataları ayrı ayrı ele alınmalı; imzalı istekler için makul zaman aşımı ve yeniden deneme stratejileri belirlenmelidir.