API Entegrasyonu

sslTrus, kendi imzalama istemcisini, derleme sistemini veya diğer imza entegrasyon programlarını geliştirmesi gereken geliştiriciler için uygun olan uzak kod imzalama API'sini sunar.

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

İstemci şunlardan sorumludur:

• İmzalanacak verinin özetini hesaplamak.
• Hedef dosyanın gerektirdiği imza yapısını oluşturmak.
• Uzak imzalama arayüzünü çağırmak.
• Dönen imza sonucunu hedef dosyaya veya imza yapısına yazmak.
• Gerektiğinde istemcinin nihai işlem sonucunu raporlamak.

Kod imzalama özel anahtarı her zaman bulut HSM'de saklanır ve API aracılığıyla istemciye 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 imza arayüzü:

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

Sonuç raporlama arayüzü:

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

Gerçek dağıtım ortamında başka bir hizmet adresi kullanılıyorsa, teslimat veya işletme ekibinin sağladığı adres esas alınır.

Kimlik Doğrulama

API, HTTP Basic Auth kullanır.

Eşleşme ilişkisi:

Username = Access Key
Password = Access Secret

İstek başlığı:

Authorization: Basic <base64(accessKey:accessSecret)>

Örneğin:

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

Gerçek kullanımda curl, doğrudan -u parametresi aracılığıyla sağlanabilir:

curl -u "$ACCESS_KEY:$ACCESS_SECRET"

Access Secret hassas bir kimlik bilgisidir; kaynak koduna, genel yapılandırma dosyalarına, günlüklere veya ön uç sayfalarına yazılmamalıdır.

Genel istek biçimi

API kullanımı:

HTTPS
POST
JSON

İstek başlıkları:

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çıklaması:

Alan	Tür	Açıklama
code	integer	İş durum kodu, 0 başarıyı belirtir
message	string	Durum veya hata mesajı
data	object	Arayüz iş verisi

İstemcinin hem HTTP durum kodunu hem de iş durum kodunu kontrol etmesi gerekir.

Aşağıdaki şekilde işlem yapılması önerilir:

HTTP 非 2xx
    ↓
HTTP 请求失败

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

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

Yalnızca HTTP 200 durumuna bakarak imza isteğinin başarılı olduğu sonucuna varmayın.

İmza Arayüzü

Arayüz:

POST /v1/codesign/sign

Bu arayüz, imzalanacak özeti göndermek ve uzak özel anahtar imza sonucunu almak 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 PKCS1 olarak sabittir
extra	object	Hayır	İstemci bağlamı ve denetim bilgileri

Özet algoritması

Şu anda desteklenen:

SHA1
SHA256
SHA384
SHA512

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

{
  "algorithm": "SHA256"
}

algorithm, digest tarafından gerçekte kullanılan özet algoritmasıyla tutarlı olmalıdır.

digest biçimi

digest şu şekilde olmalıdır:

Ham baytları hash'le → Base64

Değil:

文件内容 Base64

也并非如此：

十六进制哈希字符串

Örneğin, bir SHA-256 özetinin kendisi 32 bayt ise, bu 32 ham bayt Base64 ile kodlandıktan sonra arayüze iletilmelidir.

padding

Şu anda sabit olarak kullanılır:

PKCS1

Yani:

{
  "padding": "PKCS1"
}

Başka doldurma yöntemleri aktarmayın.

extra

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

Desteklenenler:

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

Örneğin:

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

如果 signing_filename 内部 dizin、kullanıcı adı veya diğer hassas bilgiler içeriyorsa, müşteri tarafındaki güvenlik politikasına göre maskeleme yapılması önerilir.

İmza İsteği Örneği

curl kullanın：

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önen alanlar:

Alan	Tür	Açıklama
id	string	İmza kayıt kimliği
signature	string	RSA imza sonucunun Base64 kodlaması

Gerçek imzalama yeteneği için istemci ağırlıklı olarak şunları kullanır:

data.signature

Eğer yerel işlem tamamlandıktan sonra nihai durumun bildirilmesi gerekiyorsa, ayrıca şunların kaydedilmesi gerekir:

data.id

İstemci işlem akışı

Tipik akış:

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

Dikkat edilmesi gerekenler:

/v1/codesign/sign

Yalnızca alt düzey uzak özel anahtar imzalamasından sorumludur.

PE Authenticode, JAR, PDF veya diğer dosya biçimlerinde imza yapısının nasıl düzenleneceği, hedef biçime göre istemci tarafından ayrıca işlenir.

İmza sonucunu bildir

Arayüz:

POST /v1/codesign/report-sign

İstemci, uzak imzalama sonucunu aldıktan sonra sonraki süreçte yine de hata oluşabilir; örneğin:

• Nihai imza yapısının oluşturulması başarısız olur.
• Hedef dosyaya yazma başarısız olur.
• Yerel dosya izinleri hatalıdır.
• Sonraki istemci işleme adımlarında anormallik oluşur.

Nihai işlem durumunu sunucuya geri iletmek için bu arayüz kullanılabilir.

İ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ı ID'si
status	integer	Evet	İstemcinin nihai işlem durumu

Durum değerleri:

Durum	Açıklama
1	İstemci nihai işlemi başarıyla tamamladı
2	İstemci nihai işlemi başarısız oldu

İ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ı, uzak imzalama işleminin başarılı olup olmadığına göre belirlenir.

Şu durumda:

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

Aynı anda sağlandığında, başarılı bir imza olarak kabul edilir:

签名次数 +1

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

• Kimlik doğrulama başarısız olduğunda.
• Parametre hatası olduğunda.
• Ağ isteği başarısız olduğunda.
• İş isteği başarısız olduğunda.
• Sunucu imza içeriğini başarıyla döndürmediğinde.

Özellikle dikkat edilmesi gerekenler:

/v1/codesign/report-sign

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

İstemci uzak imzalama sonucunu başarıyla almış olsa bile, daha sonra yerel olarak dosyaya yazarken başarısız olursa, daha önce başarıyla tamamlanan uzak özel anahtar imzalama işlemi yine de bir imzalama sayısı oluşturmuş sayılır.

Daha fazla sayım kuralı için lütfen referans materyale bakın.

Hata İşleme

İstemci aşağıdaki durumları ayrı ayrı ele almalıdır:

1. Ağ hataları.
2. HTTP hataları.
3. API iş hataları.
4. İstemci yerel işlem 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 şekilde taşıyor mu?

Parametre hatası

Örneğin:

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

Özellikle şunları kontrol edin:

• code doğru mu?
• digest geçerli bir Base64 mü?
• algorithm özet ile eşleşiyor mu?
• padding, PKCS1 mı?

İstemci sabit olanlara bağımlı olmamalıdır:

message

Dize, program mantığını yürütür.

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

Zaman Aşımı ve Yeniden Deneme

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

Yeniden deneme gerektiğinde özellikle dikkat edilmelidir:

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

İstemci ağ hatası nedeniyle yanıt alamadıysa bu, sunucunun imzalamayı tamamlamadığı anlamına gelmez.

Bu nedenle otomatik yeniden deneme mekanizması tasarlanırken sınırsız veya koşulsuz olarak imzalama isteğinin tekrar tekrar gönderilmesinden kaçınılmalıdır.

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

• İstek başlangıç zamanı.
• Hedef sertifika numarası.
• Özet tanımlayıcı.
• HTTP durumu.
• İş durum kodu.
• Dönen imza kayıt ID’si.
• İstemcinin nihai işlem durumu.

Günlüklere tam Access Secret kaydetmeyin.

Günlük ve Denetim

Örneğin aşağıdakiler gibi gerekli imza bağlamının kaydedilmesi önerilir:

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

对于：

digest
signature

Bu tür uzun verilerin normal günlüklere tam olarak yazılması önerilmez.

Şunlar kaydedilebilir:

• Uzunluk.
• Karma (hash).
• Maskeleme sonrası ön ek ve son ek.

Dosya yolları da kullanıcı adı, proje adı veya dahili dizin bilgilerini içerebileceğinden, gerçek güvenlik gereksinimlerine göre maskelenip maskelenmeyeceğine 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 günlüklerde tam Authorization Header kaydedilmemelidir.
• Tam Access Secret kaydedilmemelidir.
• digest ve signature için gerekli günlük maskelemesi yapılmalıdır.
• Uzak imzalama hizmeti HTTPS üzerinden çağrılmalıdır.
• İstemci, HTTP durumunu ve iş durumunu doğrulamalıdır.
• Ağ istekleri için makul zaman aşımı ve yeniden deneme politikaları belirlenmelidir.

Uzak kod imzalama API'si özel anahtar yerine imza sonucunu döndürür.

Kod imzalama özel anahtarı her zaman uzak HSM'de tutulur.

API Ne Zaman Kullanılır?

Mevcut entegrasyon yöntemi gereksinimleri zaten karşılıyorsa, genellikle ilgili araç doğrudan kullanılabilir.

Senaryo	Önerilen Yöntem
EXE, DLL, MSI gibi dosyaları doğrudan imzalama	İstemci Aracı
Microsoft SignTool, Visual Studio gibi Windows yazılımları	Windows Provider
JAR dosyası imzalama	Java Entegrasyonu
GitHub Actions, Electron Builder gibi otomatik derleme	CI/CD ve Derleme Araçları
Kendi imzalama istemcinizi geliştirme	API
Dosya biçimi imzalama akışını kendiniz uygulama	API
Özet ve imza sonucunu doğrudan kontrol etme gereksinimi	API

API, alt düzey imzalama akışını kontrol etmesi gereken geliştiriciler için daha uygundur.

Yalnızca normal dosyalara kod imzası uygulanması gerekiyorsa, mevcut istemciyi veya standart Provider'ı öncelikli olarak kullanmak, imza dosya biçimini kendiniz işleme yükünü azaltabilir.