API Entegrasyonu

sslTrus, kendi imza istemcisi, derleme sistemi veya diğer imza entegrasyon programlarını geliştirmesi gereken geliştiriciler için uzaktan kod imzalama API'si sağlar.

API, istemci tarafından hesaplanan dosya özetini alır; uzaktan kod imzalama hizmeti, belirtilen kod imzalama sertifikasını kullanarak özel anahtar imzasını tamamlar ve imza sonucunu geri döndürür.

İstemci aşağıdakilerden sorumludur:

İmzalanacak verinin özetini hesaplamak.
Hedef dosya için gereken imza yapısını oluşturmak.
Uzaktan imza arayüzünü çağırmak.
Döndürülen imza sonucunu hedef dosyaya veya imza yapısına yazmak.
Gerekirse istemcinin nihai işlem sonucunu raporlamak.

Kod imzalama özel anahtarı her zaman bulut HSM'sinde saklanır ve API üzerinden istemciye asla döndürülmez.

Erişim Adresi

Üretim ortamı varsayılan adresi:

https://ssl.face.racent.com

NICSRS ortamı:

https://ssl.face.nicsrs.com

Tam imzalama API uç noktası:

POST https://ssl.face.racent.com/v1/codesign/sign

Sonuç bildirim API uç noktası:

POST https://ssl.face.racent.com/v1/codesign/report-sign

Teslim edilen ortamda başka bir hizmet adresi kullanılıyorsa teslimat veya işletim ekibinin sağladığı adresi esas alın.

Kimlik doğrulama

API, HTTP Basic Auth kullanır.

Alanların karşılıkları:

Username = Access Key
Password = Access Secret

İstek başlığı:

Authorization: Basic <base64(accessKey:accessSecret)>

Örnek:

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

curl pratikte doğrudan -u parametresi ile sağlanabilir:

curl -u "$ACCESS_KEY:$ACCESS_SECRET"

Access Secret hassas bir kimlik bilgisidir; kaynak koda, herkese açık yapılandırma dosyalarına, günlüklere veya ön yüz sayfalarına yazılmamalıdır.

Genel istek biçimi

API şunları kullanır:

HTTPS
POST
JSON

İstek başlığı:

Content-Type: application/json
Accept: application/json
Authorization: Basic <credentials>

Genel Yanıt Formatı

API, birleşik bir JSON yapısı döndürür:

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

Alan açıklamaları:

Alan	Tür	Açıklama
`code`	integer	İşlem durum kodu; `0` başarı anlamına gelir
`message`	string	Durum veya hata bilgisi
`data`	object	API işlem verileri

İstemci hem HTTP durum kodunu hem de işlem durum kodunu değerlendirmelidir.

Aşağıdaki şekilde ele alınması önerilir:

HTTP 非 2xx
    ↓
HTTP 请求失败

HTTP 2xx + code != 0
    ↓
业务失败

HTTP 2xx + code == 0
    ↓
读取 data

İmza isteğinin başarılı olduğunu yalnızca HTTP 200 yanıtına göre değerlendirmeyin.

İmza Arayüzü

Arayüz:

POST /v1/codesign/sign

Bu API, imzalanacak özetin gönderilmesi ve uzak özel anahtarla imza sonucunun alınması için kullanılır.

İstek Parametreleri

İstek örneği:

{
  "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
  }
}

Ana parametreler:

Parametre	Tür	Zorunlu	Açıklama
`code`	string	Evet	Kod imzalama sertifika numarası
`digest`	string	Evet	İmzalanacak özetin ham baytlarının Base64 kodlaması
`algorithm`	string	Evet	Özet algoritması
`padding`	string	Evet	RSA dolgu yöntemi, şu anda sabit olarak `PKCS1`
`extra`	object	Hayır	İstemci bağlamı ve denetim bilgileri

Özet algoritması

Şu anda desteklenenler:

SHA1
SHA256

Örneğin SHA-256 kullanıldığında:

{
  "algorithm": "SHA256"
}

algorithm ile digest fiilen kullanılan özet algoritması aynı olmalıdır.

digest formatı

digest şu şekilde olmalıdır:

Ham hash baytları → Base64

Şu değildir:

文件内容 Base64

Şu da değildir:

十六进制哈希字符串

Örneğin, belirli bir SHA-256 özetinin kendisi 32 bayt ise, bu 32 ham bayt Base64 kodlanarak arayüze iletilmelidir.

padding

Şu anda sabit olarak şu kullanılmaktadır:

PKCS1

Yani:

{
  "padding": "PKCS1"
}

Diğer doldurma yöntemlerini iletmeyin.

ekstra

extra istemci bağlamını, denetim bilgilerini kaydetmek ve sorun gidermeye yardımcı olmak için kullanılır.

Desteklenen alanlar:

Alan	Tür	Açıklama
`platform`	string	İstemci platformu
`version`	string	İstemci sürümü
`revision`	string	İstemci build revizyonu
`time`	string	Build zamanı veya istek tarafı kayıt zamanı
`hostname`	string	İsteği başlatan ana bilgisayar adı
`signing_filename`	string	İmzalanan dosya adı veya yerel yol
`signing_filesize`	integer	Dosya boyutu, bayt cinsinden

Örneğin:

{
  "extra": {
    "platform": "linux/amd64",
    "version": "1.2.0",
    "hostname": "github-runner-01",
    "signing_filename": "app.exe",
    "signing_filesize": 5242880
  }
}

signing_filename iç dizinleri, kullanıcı adlarını veya başka hassas bilgileri içeriyorsa müşteri tarafındaki güvenlik politikasına göre maskelenmesi önerilir.

İmzalama isteği örneği

curl ile:

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": "linux/amd64",
      "version": "1.0.0",
      "hostname": "build-host-01",
      "signing_filename": "Example.exe",
      "signing_filesize": 1048576
    }
  }' \
  https://ssl.face.racent.com/v1/codesign/sign

İmza Yanıtı

Başarılı yanıt:

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

Dönüş alanları:

Alan	Tip	Açıklama
`id`	string	İmza kaydı kimliği
`signature`	string	RSA imza sonucunun Base64 kodlaması

Gerçek imza yeteneği için istemci temel olarak şunları kullanır:

data.signature

Yerel olarak işlem tamamlandıktan sonra nihai durumu raporlamanız gerekiyorsa, ayrıca şunları kaydetmeniz gerekir:

data.id

İstemci İşleme Akışı

Tipik akış:

读取待签名文件
      ↓
按照目标格式生成待签名数据
      ↓
计算摘要
      ↓
Base64 编码摘要
      ↓
POST /v1/codesign/sign
      ↓
获得 signature
      ↓
构造最终签名结构
      ↓
写回目标文件
      ↓
POST /v1/codesign/report-sign

Dikkat edilmesi gerekenler:

/v1/codesign/sign

Yalnızca temel seviyedeki uzak özel anahtar imzalamadan sorumludur.

PE Authenticode, JAR, PDF veya diğer dosya formatlarının imza yapısını nasıl düzenleyeceği, istemcinin hedef formata göre kendisinin işlemesine bağlıdır.

İmza Sonucunu Raporlama

Arayüz:

POST /v1/codesign/report-sign

İstemci, uzak imza sonucunu aldıktan sonra, sonraki süreçlerde yine de hatalar oluşabilir, örneğin:

Nihai imza yapısının oluşturulmasında hata.
Hedef dosyaya yazma hatası.
Yerel dosya izin hatası.
Sonraki istemci işlemlerinde anormallik.

Bu arayüzü kullanarak nihai işlem durumunu sunucuya geri iletebilirsiniz.

İstek Parametreleri

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

Parametreler:

Alan	Tür	Zorunlu	Açıklama
`id`	string	Evet	`/v1/codesign/sign` tarafından döndürülen imza kaydı kimliği
`status`	integer	Evet	İstemcideki son işlem durumu

Durum değerleri:

Durum	Açıklama
`1`	İstemcideki son işlem başarılı
`2`	İstemcideki son işlem 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
}

İmza Sayısı

API imza sayısı, uzaktan imzalama işleminin başarılı olup olmamasına göre belirlenir.

Şu durumlarda:

HTTP 2xx
code == 0
data.signature 非空

Aynı anda sağlandığında, tek bir başarılı imza olarak değerlendirilir:

签名次数 +1

Aşağıdaki durumlarda imza hakkı tüketilmez:

Kimlik doğrulama başarısız olursa.
Parametre hatası.
Ağ isteği başarısız olursa.
İş isteği başarısız olursa.
Sunucu tarafı imza içeriğini başarıyla döndürmezse.

Özellikle dikkat edilmesi gerekenler:

/v1/codesign/report-sign

Sadece istemcinin nihai işlem durumunu raporlar; bu yeni bir imza işlemi değildir ve imza sayısını artırmaz veya azaltmaz.

İstemci, uzak imza sonucunu başarıyla almış olsa bile, ardından yerel dosyaya yazma işlemi başarısız olursa, daha önce başarıyla tamamlanan uzak özel anahtar imzası yine de bir imza sayısı üretmiş olur.

Daha fazla sayım kuralı için Referans Kaynak bölümüne bakın.

Hata İşleme

İstemci, aşağıdakileri ayrı ayrı işlemelidir:

Ağ hataları.
HTTP hataları.
API iş hataları.
İstemci yerel işleme hataları.

Kimlik Doğrulama Başarısızlığı

Örneğin:

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

Kontrol edilmelidir:

Access Key doğru mu.
Access Secret doğru mu.
İstek Authorization Header’ı doğru taşıyor mu.

Parametre hatası

Örneğin:

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

Kontrol edilmesi gerekenler:

code doğru mu?
digest geçerli bir Base64 mı?
algorithm özet ile tutarlı mı?
padding değeri PKCS1 mı?

İstemci sabit bir değere güvenmemelidir:

message

Programın işleyişi bu dizenin sabit metnine dayandırılmamalıdır.

İşlem mantığı öncelikle durum kodlarına ve API sözleşmesine dayanmalıdır.

Zaman aşımı ve yeniden deneme

Uzak imzalama API'si çağrılırken makul bir ağ zaman aşımı ayarlanmalıdır.

Yeniden deneme gerektiğinde özellikle şunlara dikkat edin:

签名接口不是普通查询接口

İstemci, ağ anormalliği nedeniyle yanıt alamadıysa, bu her zaman sunucunun imzalamayı tamamlamadığı anlamına gelmez.

Bu nedenle, otomatik yeniden deneme mekanizması tasarlarken, imzalama isteklerinin sınırsız veya koşulsuz olarak tekrarlanmasından kaçınılmalıdır.

Aşağıdakilerin ayrı ayrı kaydedilmesi önerilir:

İstek başlangıç zamanı.
Hedef sertifika numarası.
Özet tanımlayıcısı.
HTTP durumu.
İş durum kodu.
Döndürülen imza kaydı kimliği.
İstemcinin nihai işleme durumu.

Günlüklere tam Access Secret kaydedilmemelidir.

Günlükler ve Denetim

Gerekli imzalama bağlamının kaydedilmesi önerilir, örneğin:

certificate code
platform
client version
hostname
filename
filesize
sign record id
result

İçin:

digest
signature

Bu boyuttaki büyük verilerin tamamen normal loglara yazılması önerilmez.

Kaydedilebilir:

Uzunluk.
Hash.
Maskeleme sonrası önek ve sonek.

Dosya yolları kullanıcı adı, proje adı veya dahili dizin bilgileri içerebilir; maskeleme yapılıp yapılmayacağına gerçek güvenlik gereksinimlerine göre karar verilmelidir.

Güvenlik Açıklamaları

API entegrasyonunda aşağıdaki ilkelere uyulması önerilir:

Access Secret, ön uç koduna kaydedilmemelidir.
Access Secret, Git deposuna gönderilmemelidir.
Normal loglarda tam Authorization Header kaydedilmemelidir.
Tam Access Secret kaydedilmemelidir.
digest ve signature için gerekli log maskeleme işlemleri yapılmalıdır.
Uzaktan imzalama hizmetine HTTPS üzerinden çağrı yapılmalıdır.
İstemci, HTTP durumunu ve iş durumunu doğrulamalıdır.
Ağ istekleri için makul zaman aşımı ve yeniden deneme stratejileri ayarlanmalıdır.

Uzaktan kod imzalama API'si imzalama sonucunu döndürür, özel anahtarı döndürmez.

Kod imzalama özel anahtarı her zaman uzaktaki HSM'de saklanır.

API Ne Zaman Kullanılır

Mevcut entegrasyon yöntemi ihtiyacı karşılıyorsa, genellikle ilgili aracı doğrudan kullanmak mümkündür.

Senaryo	Önerilen Yöntem
EXE, DLL, MSI gibi dosyaları doğrudan imzalama	İstemci Aracı
Microsoft SignTool, Visual Studio gibi Windows yazılımları	Windows Sağlayıcısı
JAR dosyası imzalama	Java Entegrasyonu
GitHub Actions, Electron Builder gibi otomatik derleme	CI/CD ve Derleme Araçları
Kendi imzalama istemcisini geliştirme	API
Dosya formatı imzalama sürecini kendi başına uygulama	API
Özet ve imzalama sonucunu doğrudan kontrol etme ihtiyacı	API

API, temel imzalama sürecini kontrol etmesi gereken geliştiriciler için daha uygundur.

Yalnızca normal dosyalar için kod imzalama yapılması gerekiyorsa, mevcut istemciyi veya standart Sağlayıcıyı öncelikli olarak kullanmak, imzalama dosya formatını kendi başına işleme iş yükünü azaltabilir.

Erişim Adresi​

Kimlik doğrulama​

Genel istek biçimi​

Genel Yanıt Formatı​

İmza Arayüzü​

İstek Parametreleri​

Özet algoritması​

digest formatı​

padding​

ekstra​

İmzalama isteği örneği​

İmza Yanıtı​

İstemci İşleme Akışı​

İmza Sonucunu Raporlama​

İstek Parametreleri​

İstek örneği​

Başarılı yanıt​

İmza Sayısı​

Hata İşleme​

Kimlik Doğrulama Başarısızlığı​

Parametre hatası​

Zaman aşımı ve yeniden deneme​

Günlükler ve Denetim​

Güvenlik Açıklamaları​

API Ne Zaman Kullanılır​

Erişim Adresi

Kimlik doğrulama

Genel istek biçimi

Genel Yanıt Formatı

İmza Arayüzü

İstek Parametreleri

Özet algoritması

digest formatı

padding

ekstra

İmzalama isteği örneği

İmza Yanıtı

İstemci İşleme Akışı

İmza Sonucunu Raporlama

İstek Parametreleri

İstek örneği

Başarılı yanıt

İmza Sayısı

Hata İşleme

Kimlik Doğrulama Başarısızlığı

Parametre hatası

Zaman aşımı ve yeniden deneme

Günlükler ve Denetim

Güvenlik Açıklamaları

API Ne Zaman Kullanılır