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

完整签名接口：

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

结果上报接口：

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

如果实际交付环境使用其他服务地址，请以交付或运维提供的地址为准。

身份认证

API 使用 HTTP Basic Auth。

对应关系：

Username = Access Key
Password = Access Secret

İstek başlığı:

Authorization: Basic <base64(accessKey:accessSecret)>

例如：

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 属于敏感凭证，不应写入源代码、公开配置文件、日志或前端页面。

通用请求格式

API 使用：

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

字段说明：

字段	类型	说明
`code`	integer	业务状态码，`0` 表示成功
`message`	string	状态或错误信息
`data`	object	接口业务数据

客户端需要同时判断 HTTP 状态码和业务状态码。

建议按照以下方式处理：

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:

哈希原始字节 → Base64

不是：

文件内容 Base64

也不是：

十六进制哈希字符串

Ö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 包含内部目录、用户名或其他敏感信息，建议根据客户侧安全策略进行脱敏。

签名请求示例

使用 curl：

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
}

参数：

字段	类型	必填	说明
`id`	string	是	`/v1/codesign/sign` 返回的签名记录 ID
`status`	integer	是	客户端最终处理状态

状态值：

状态	说明
`1`	客户端最终处理成功
`2`	客户端最终处理失败

请求示例

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

成功响应

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

字符串执行程序逻辑。

业务处理应优先依据状态码和接口契约。

超时与重试

调用远程签名接口时，应设置合理的网络超时。

需要重试时，应特别注意：

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

İ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​

身份认证​

通用请求格式​

Genel Yanıt Formatı​

İmza Arayüzü​

İstek Parametreleri​

Özet algoritması​

digest formatı​

padding​

ekstra​

签名请求示例​

İmza Yanıtı​

İstemci İşleme Akışı​

İmza Sonucunu Raporlama​

İstek Parametreleri​

请求示例​

成功响应​

İmza Sayısı​

Hata İşleme​

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

Parametre hatası​

超时与重试​

Günlükler ve Denetim​

Güvenlik Açıklamaları​

API Ne Zaman Kullanılır​

Erişim Adresi

身份认证

通用请求格式

Genel Yanıt Formatı

İmza Arayüzü

İstek Parametreleri

Özet algoritması

digest formatı

padding

ekstra

签名请求示例

İmza Yanıtı

İstemci İşleme Akışı

İmza Sonucunu Raporlama

İstek Parametreleri

请求示例

成功响应

İmza Sayısı

Hata İşleme

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

Parametre hatası

超时与重试

Günlükler ve Denetim

Güvenlik Açıklamaları

API Ne Zaman Kullanılır