Ana içeriğe geç

Uzak Kod İmzalama API Referansı

Bu makale, uzaktan imza yeteneklerini doğrudan entegre etmesi gereken geliştiricilere yöneliktir ve aşağıdaki iki API'yi açıklamaktadır:

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

Hizmet adresi​

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

Diğer ortam adresleri gerekiyorsa, teslimat veya operasyon ekibinin sağladığı adres geçerli kabul edilir.

Genel Kurallar​

İstek biçimi​

  • Protokol: HTTPS
  • Metod: POST
  • Gövde: JSON
  • Başlıklar:
Content-Type: application/json
Accept: application/json
Authorization: Basic <base64(accessKey:accessSecret)>

Kimlik Doğrulama​

Arayüz, HTTP Temel Kimlik Doğrulaması kullanır:

  • Kullanıcı Adı: Access Key
  • Şifre: Access Secret

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

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

Genel yanıt yapısı​

{
  "code": 0,
  "message": "ok",
  "data": {}
}
AlanTürAnlam
codeintegerİşlem durum kodu. 0 başarıyı, 0 dışındaki değerler işlem hatasını belirtir.
messagestringİşlem durumu açıklaması; hata durumunda hata açıklaması.
dataobjectAPI işlem verileri.

Çağrı yapan taraf, hem HTTP durum kodunu hem de iş durum kodunu aynı anda ele almalıdır:

  • HTTP durumu 2xx değilse → HTTP hatası olarak işlenir.
  • HTTP 2xx ve code != 0 → işletme hatası olarak işlenir.
  • HTTP 2xx ve code == 0 → ilgili data alanı okunur.

İmzalama Arayüzü​

Arayüz Açıklaması​

POST /v1/codesign/sign

İmzalanacak hash ham 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 imza içeriğini başarıyla döndürdüğünde imzalama başarılı sayılır ve imza sayısı 1 artar. Başarısız istekler imza hakkını tüketmez. report-sign çağrısının yapılıp yapı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ürZorunluAnlam
codestringEvetSertifika numarası, uzaktan imza sertifikasını seçmek için kullanılır.
digeststringEvetİmzalanacak karma (hash) orijinal baytlarının Base64 kodlaması. Çağıran taraf, hedef dosya ve imza aracı gereksinimlerine göre karmayı yerel olarak hesaplamalıdır.
algorithmstringEvetKarma algoritması, SHA1, SHA256, SHA384, SHA512 destekler.
paddingstringEvetRSA dolgu modu, şu anda sabit olarak PKCS1 ayarlıdır.
extraobjectHayırİstemci bağlam bilgisi, imza kaydı, denetim ve sorun giderme için kullanılır.

extra alan açıklaması:

AlanTürAnlam
platformstringİstemci platformu; örneğin windows/amd64 veya linux/amd64.
versionstringİstemci sürümü.
revisionstringİstemci derlemesinin revizyonu.
timestringİstemci derleme zamanı veya istek zamanı.
hostnamestringİmzalama isteğini gönderen ana makinenin adı.
signing_filenamestringİmzalanan dosyanın adı veya yolu; güvenlik politikasına göre maskelenmesi ö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
idstringreport-sign çağrılırken kullanılan imza kaydı kimliği.
signaturestringRSA imza sonucunun Base64 kodlaması.

İmza Sonucunu Raporlama​

Arayüz Açıklaması​

POST /v1/codesign/report-sign

İstemci, uzak imza sonucunu aldıktan sonra, sonucu yerel olarak işlerken, yazarken veya çağıran tarafa geri iletirken 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örüntülenmesi ve denetim/inceleme kolaylaşır.

Bilgi

Bu API yalnızca istemcideki işlem sonucunu kaydeder ve /v1/codesign/sign çağrısının sayım sonucunu değiştirmez. Bu API'nin çağrılmaması başarılı imza sayısını etkilemez.

İstek Parametreleri​

{
  "id": "735985894427246592",
  "status": 1
}
AlanTipZorunluAnlam
idstringEvet/v1/codesign/sign tarafından döndürülen data.id.
statusintegerEvetİstemci son 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

Kesin hata kodları ve iletileri sunucunun gerçek yanıtına bağlıdır. Entegrasyonu yapan taraf, işlem dallarını belirlemek için sabit hata metinlerine güvenmemelidir.

Entegrasyon Önerisi​

  • Access Secret'i özenle koruyun; günlüklere, hata raporlarına veya ön yüz sayfalarına yazmayın.
  • digest, hash ham baytlarının Base64 kodlaması olmalıdır; onaltılık (hex) bir dize veya tam dosya içeriği değildir.
  • algorithm, digest ile aynı gerçek hash algoritmasıyla tutarlı olmalıdır.
  • Mevcut doldurma (padding) modu sabit olarak PKCS1 kullanılır; başka bir değer iletmeyin.
  • digest ve signature alanları uzun olabilir; günlüklerde yalnızca uzunluğun veya ön/son eklerin maskelenmiş sonuçlarının kaydedilmesi önerilir.
  • İstemci tarafında son işlem tamamlandıktan sonra sonuçların report-sign ile raporlanması önerilir; bu, sonraki denetim ve sorun giderme için kolaylık sağlar.
  • Ağ hatalarını, HTTP hatalarını ve iş hatalarını ayrı ayrı ele alın; imza istekleri için makul zaman aşımı ve yeniden deneme stratejileri belirleyin.
En son tarihinde güncellendi