Ana içeriğe geç

Uzaktan Kod İmzalama API Referansı

Bu belge, uzaktan imzalama yeteneğini doğrudan entegre etmesi gereken geliştiricilere yöneliktir ve aşağıdaki iki arayüzü açıklar:

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

Erişim Adresi​

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

Diğer ortam adresleri için teslimat veya işletme ekibinin sağladığı adres esas alınır.

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": {}
}
AlanTürAnlam
codeintegerİş durum kodu. 0 başarıyı, 0 dışındaki değerler iş başarısızlığını belirtir.
messagestringİş durumu açıklaması; başarısızlık durumunda hata açıklamasıdır.
dataobjectArayüz iş verileri.

Çağıran taraf hem HTTP durum kodunu hem de iş durum kodunu işlemelidir:

  • HTTP 2xx değil → HTTP hatası olarak işle.
  • HTTP 2xx ve code != 0 → iş hatası olarak işle.
  • HTTP 2xx ve code == 0 → karşılık gelen data değerini oku.

İmza Arayüzü​

Arayüz Açıklaması​

POST /v1/codesign/sign

Ham hash’inin orijinal baytlarını (Base64 kodlu) gönderin; uzak hizmet, belirtilen sertifikayı kullanarak RSA PKCS#1 imzasını tamamlayıp sonucu döndürür.

Dikkat

/v1/codesign/sign imza içeriğinin başarıyla dönmesi imzanın başarılı olduğu anlamına gelir 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
  }
}
AlanTürZorunluAçıklama
codestringEvetSertifika numarası; uzak imza sertifikasını seçmek için kullanılır.
digeststringEvetİmzalanacak hash'in ham baytlarının Base64 kodlaması. Çağıran taraf, hedef dosyaya ve imza aracının gereksinimlerine göre hash'i yerel olarak hesaplamalıdır.
algorithmstringEvetHash algoritması; SHA1, SHA256, SHA384, SHA512 desteklenir.
paddingstringevetRSA dolgu modu, şu anda PKCS1 olarak sabittir.
extraobjecthayırİmza kayıtları, denetim ve sorun giderme için istemci bağlam bilgileri.

extra alan açıklaması:

AlanTürAnlam
platformstringİstemci platformu, örneğin windows/amd64, linux/amd64.
versionstringİstemci sürümü.
revisionstringİstemci derleme revizyonu.
timestringİstemci derleme zamanı veya istek zamanı.
hostnamestringİmzalamayı başlatan ana bilgisayar adı.
signing_filenamestringİmzalanan dosya adı veya yolu, güvenlik politikasına göre hassas bilgilerden arındırılması önerilir.
signing_filesizeintegerİmzalanan dosyanın 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"
  }
}
AlanTürAnlam
idstringİmza kaydı kimliği; report-sign çağrılırken kullanılır.
signaturestringRSA imza sonucunun Base64 ile kodlanmış hali.

İmza Sonucunun Bildirilmesi​

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şleme durumunu sunucuya geri iletmek için kullanılır; böylece imzalama kayıtlarının gösterimi ve denetim amaçlı sorun giderme kolaylaşır.

Açıklama

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

İstek Parametreleri​

{
  "id": "735985894427246592",
  "status": 1
}
AlanTürZorunluAnlam
idstringEvet/v1/codesign/sign tarafından döndürülen data.id.
statusintegerEvetİ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ı, sunucu tarafından gerçekte döndürülen değerlere tabidir. Entegrasyon tarafı, iş mantığı dallanması için sabit hata metinlerine bağımlı olmamalıdır.

Entegrasyon Önerileri​

  • Access Secret’ı uygun şekilde koruyun; günlüklere, çö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 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; günlüklerde yalnızca uzunluğun veya ön/arka ucu maskelenmiş sonucun kaydedilmesi önerilir.
  • İstemci tarafında nihai işlem tamamlandıktan sonra, daha sonraki denetim ve sorun giderme için report-sign çağrılarak sonucun bildirilmesi önerilir.
  • Ağ hatalarını, HTTP hatalarını ve iş hatalarını ayrı ayrı ele alın; imzalı istekler için makul zaman aşımı ve yeniden deneme politikaları belirleyin.
En son tarihinde güncellendi