sgcSign Server: REST üzerinden Kendi Sunucunuzda Kod İmzalama ve Belge İmzalama

· Bileşenler

Kod imzalamanın bir anahtar yönetimi sorunu vardır. Olağan kurulum, bir sürümü imzalaması gereken her derleme ajanına bir .pfx dosyası kopyalar veya bir USB belirtecini takar. Özel anahtar, güvenilmeyen derleme betiklerini çalıştıran makinelerde son bulur, neyin kim tarafından imzalandığına dair bir kayıt yoktur ve sertifikayı döndürmek her ajana dokunmak anlamına gelir. sgcSign 2026.6, bunu yeni bir imzalama sunucusu ile yanıtlar: imzalamayı bir TLS REST API'si üzerinden sunan, kendi sunucunuzda barındırılan bir arka plan hizmeti. Böylece işlem hatlarınız ve geliştiricileriniz uzaktan imzalarken, imzalama anahtarı tek bir yerde kalır.

Anahtar sunucudan asla ayrılmaz. Daha da iyisi, sunucu bir donanım belirtecinin veya bir bulut KMS'inin önünde durabilir, böylece anahtar hiçbir zaman bir dosya olarak var olmaz. Her istek bir API anahtarıyla kimlik doğrulamasından geçer, hız sınırına tabidir ve kurcalamaya karşı korumalı bir denetim günlüğüne yazılır. Bu yazı, sunucunun neleri imzalayabileceğini, nasıl yapılandırılacağını, beş dakikalık bir hızlı başlangıcı ve onu çağırmanın iki yolunu kapsar: düz curl ve birlikte gelen sgcsign komut satırı istemcisi.

Neleri imzalar

Tek sunucu, tek API, sekiz imza biçimi. Aynı uç nokta şekli (POST /api/v1/sign/<format>) hem yürütülebilir dosyaları hem de belgeleri kapsar:

Her biçim isteğe bağlı bir RFC 3161 zaman damgası URL'sini kabul eder, böylece imzalama sertifikasının süresi dolduktan sonra bile imzalar geçerli kalır. Eşlik eden bir POST /api/v1/verify uç noktası mevcut bir imzayı denetler ve imzalayan konusunu, geçerliliğini ve zaman damgasını döndürür.

Takılabilir anahtar sağlayıcıları

Bir sağlayıcı, bir imzalama anahtarına adlandırılmış bir tutamaçtır. Çağıran taraf her istekte bir sağlayıcı adlandırır; anahtarı asla görmez. İhtiyacınız olduğu kadar çok kaydedebilirsiniz ve aynı sunucu, iç araçlar için yerel bir PFX'i, herkese açık sürümler için bulut destekli bir EV sertifikasıyla birlikte kullanabilir. Dokuz sağlayıcı türü desteklenir:

Gizli bilgiler yapılandırma dosyasının dışında kalır. Adı _env ile biten herhangi bir parametre bir ortam değişkeninden okunur, böylece PFX parolası, belirteç PIN'i veya bulut gizli bilgisi diske işlenmeden hizmet ortamı tarafından sağlanır.

Sunucuyu yapılandırma

Tüm sunucu tek bir JSON dosyası, sgcSignServer.conf.json tarafından yönetilir (belgelenmiş bir örnek sgcSignServer.conf.sample.json olarak gelir). Üst düzey şekil birkaç bloktan oluşur:

{
  "server": {
    "listen": "0.0.0.0",
    "port": 8443,
    "tls": {
      "enabled": true,
      "cert_file": "certs/server.crt",
      "key_file":  "certs/server.key"
    },
    "max_upload_mb": 512,
    "firewall": {
      "enabled": true,
      "whitelist": ["10.0.0.0/8"],
      "brute_force": { "enabled": true, "max_attempts": 5, "ban_duration_sec": 900 },
      "rate_limit":  { "enabled": true, "max_connections_per_ip": 30, "time_window_sec": 60 }
    }
  },
  "storage": { "sqlite_path": "data/sgcsignserver.db" },
  "admin": {
    "initial_user": "admin",
    "initial_password_env": "SGCSIGN_ADMIN_INIT_PW",
    "session_timeout_minutes": 60
  },
  "audit": { "retention_days": 365 },
  "providers": [
    {
      "name": "pfx-build",
      "type": "PFX",
      "params": { "file": "certs/build.pfx", "password_env": "SGCSIGN_PFX_PW" }
    },
    {
      "name": "ev-release",
      "type": "AzureTS",
      "params": {
        "tenant_id": "00000000-0000-0000-0000-000000000000",
        "client_id": "00000000-0000-0000-0000-000000000000",
        "client_secret_env": "SGCSIGN_AZURE_TS_SECRET",
        "account": "your-account",
        "certificate_profile": "your-profile",
        "endpoint": "https://eus.codesigning.azure.net/"
      }
    }
  ]
}

Bloklar doğrudan özelliklere eşlenir. server bağlanma adresini, bağlantı noktasını (varsayılan olarak 8443), TLS sertifikasını ve yerleşik güvenlik duvarını (IP izin ve reddetme listeleri, kaba kuvvet kilitleme, bağlantı hız sınırlama, yol geçişi ve yük korumaları) ayarlar. storage, kullanıcıları, API anahtarlarını, denetim günlüğünü ve web kancası kuyruğunu tutan SQLite veritabanını işaret eder. admin ilk kullanıcıyı ve oturumların ne kadar süreceğini tanımlar. audit saklama penceresini ayarlar. providers ise yukarıdaki listedir.

Önyükleme yönetici parolası dosyada asla saklanmaz. İlk başlangıçta, kullanıcı tablosu boş olduğunda, sunucu initial_password_env ile adlandırılan ortam değişkenini (varsayılan SGCSIGN_ADMIN_INIT_PW) okur ve yönetici hesabını oluşturur. Sonraki her başlangıçta bu değişken yoksayılır, böylece yalnızca ilk oturum açmayı tohumlar.

Beş dakikada hızlı başlangıç

Sunucuyu kurun (kurulum sihirbazı Windows hizmetini kaydeder veya sgcSignServer.exe --install çalıştırın), ardından:

1. Bir test kod imzalama sertifikası oluşturun ve bir PFX olarak dışa aktarın. Gerçek bir dağıtım için CA tarafından verilen sertifikanızı içe aktarırsınız veya bunu atlayıp bunun yerine bir sağlayıcıyı belirtecinize ya da bulut KMS'inize yönlendirirsiniz.

$cert = New-SelfSignedCertificate -Type CodeSigningCert `
  -Subject "CN=sgcSign Quickstart" -KeyAlgorithm RSA -KeyLength 3072 `
  -CertStoreLocation Cert:\CurrentUser\My -NotAfter (Get-Date).AddYears(1)
$pw = ConvertTo-SecureString "QuickStartPFX!" -Force -AsPlainText
Export-PfxCertificate -Cert $cert -Password $pw `
  -FilePath "C:\Program Files\sgcSign Server\certs\quickstart.pfx"

2. Gizli bilgileri makine ortam değişkenleri olarak ayarlayın ki hizmet hesabı bunları okuyabilsin:

setx /M SGCSIGN_ADMIN_INIT_PW "ChangeMeNow!"
setx /M SGCSIGN_PFX_PW        "QuickStartPFX!"

3. Tek bir PFX sağlayıcısı ile minimal bir yapılandırma yazın (yalnızca localhost testi için TLS kapalı):

{
  "server":   { "listen": "127.0.0.1", "port": 8443, "tls": { "enabled": false } },
  "storage":  { "sqlite_path": "data/sgcsignserver.db" },
  "admin":    { "initial_user": "admin", "initial_password_env": "SGCSIGN_ADMIN_INIT_PW" },
  "audit":    { "retention_days": 365 },
  "providers": [
    { "name": "pfx-quickstart", "type": "PFX",
      "params": { "file": "certs/quickstart.pfx", "password_env": "SGCSIGN_PFX_PW" } }
  ]
}

4. Hizmeti başlatın ve dinlediğini doğrulayın:

sc start sgcSignServer
sc query sgcSignServer

Başlangıçta durursa, hatayı canlı görmek için onu sgcSignServer.exe --console --config <path> ile ön planda çalıştırın (eksik bir SGCSIGN_ADMIN_INIT_PW veya okunamayan bir PFX olağan nedenlerdir). --selftest-providers bayrağı yapılandırmayı yükler, her sağlayıcıyı başlatır ve çıkar, böylece canlıya geçmeden önce anahtarları doğrulayabilirsiniz.

5. Oturum açın ve bir API anahtarı oluşturun. http://localhost:8443/admin adresini açın, önyükleme parolasıyla admin olarak oturum açın ve bir API anahtarı oluşturun. Düz metin anahtar oluşturma sırasında bir kez gösterilir; hemen kopyalayın. Anahtarlar sgcsk_ önekini taşır.

6. curl ile bir test yürütülebilir dosyası imzalayın:

curl -X POST http://localhost:8443/api/v1/sign/authenticode ^
  -H "X-API-Key: sgcsk_..." ^
  -F file=@app.exe ^
  -F provider=pfx-quickstart ^
  -F hash=sha256 ^
  --output app-signed.exe

İşte tüm döngü bu: bir sağlayıcı yapılandırın, bir anahtar verin, imzalayın. Buradan kendinden imzalı PFX'i gerçek bir sertifikayla değiştirir, TLS'i açar ve güvenlik duvarını CI alt ağınıza kilitlersiniz.

REST üzerinden imzalama

Her imzalama isteği, dosya ve birkaç form alanı ile bir POST isteğidir. Kimlik doğrulama tek bir başlıktır: ya X-API-Key: sgcsk_... ya da Authorization: Bearer sgcsk_.... Yanıt, application/octet-stream olarak imzalanmış yapıttır; imzalayan konusu ve imzalama süresi X-Sgcsign-Signer-Subject ve X-Sgcsign-Duration-Ms başlıklarında döndürülür.

Görünür bir imza gerekçesi ve konumu ile bir PDF imzalama:

curl -X POST https://sign.acme.local:8443/api/v1/sign/pades \
  -H "X-API-Key: sgcsk_..." \
  -F file=@invoice.pdf \
  -F provider=qualified-eu \
  -F tsa_url=http://timestamp.digicert.com \
  -F reason=Approved \
  -F location="Madrid, Spain" \
  -F signer_name="Acme Billing" \
  -o invoice-signed.pdf

Bir eIDAS XAdES profili ile bir XML faturası imzalama:

curl -X POST https://sign.acme.local:8443/api/v1/sign/xades \
  -H "X-API-Key: sgcsk_..." \
  -F file=@invoice.xml \
  -F provider=qualified-eu \
  -F profile=eidas \
  -F xades_type=enveloped \
  -o invoice-signed.xml

Bir imzayı doğrulamak, bir dosya yerine JSON döndürür:

curl -X POST https://sign.acme.local:8443/api/v1/verify \
  -H "X-API-Key: sgcsk_..." \
  -F file=@app-signed.exe \
  -F format=authenticode

{ "valid": true, "status": "valid",
  "subject": "CN=Acme Inc., O=Acme, C=US",
  "has_timestamp": true, "timestamp_time": "2026-06-15T13:01:17.000Z" }

sgcsign komut satırı istemcisi

Sunucu, dört fiile sahip küçük bir çapraz biçimli CLI olan sgcsign ile gelir: sign, verify, keys ve health. Sunucu URL'si, API anahtarı ve sağlayıcı, bayraklardan veya SGCSIGN_SERVER, SGCSIGN_APIKEY ve SGCSIGN_PROVIDER ortam değişkenlerinden gelebilir; bu da CI'da gizli bilgileri komut satırının dışında tutar:

set SGCSIGN_SERVER=https://sign.acme.local:8443
set SGCSIGN_APIKEY=sgcsk_...

sgcsign sign -f authenticode -p pfx-build -o app-signed.exe app.exe ^
  --tsa http://timestamp.digicert.com --desc "Acme Installer"

sgcsign verify -f authenticode app-signed.exe

Authenticode için bant genişliği tasarrufu sağlayan bir hile vardır. Ön karma kipinde (--prehash, varsayılan olarak açık) CLI, PE karmasını yerel olarak hesaplar ve çok megabaytlık bir ikili dosya yerine yalnızca karmayı, birkaç yüz baytı yükler. Sunucu karmayı imzalar ve istemcinin dosyaya gömdüğü ayrık bir PKCS#7 blob'u döndürür. Büyük bir yükleyiciyi imzalayan, bant genişliği kısıtlı bir CI ajanında bu, çok megabaytlık bir yüklemeyi minik bir yüklemeye dönüştürür.

Güvenlik ve operasyonlar

Sunucu, gerçek bir imzalama anahtarının önünde gözetimsiz çalışacak şekilde tasarlanmıştır, bu nedenle operasyonel yüzey en az kriptografi kadar önemlidir:

Neden kendi sunucunuzda barındırmalısınız

Sunucunun amacı, riskli, anahtar taşıyan bir derleme ajanları filosunu tek bir sağlamlaştırılmış uç noktaya indirgemektir. İmzalama anahtarı yalnızca sunucuda veya sunucunun önünde durduğu HSM ya da bulut KMS'inde yaşar, derleme betiklerinizi çalıştıran makinelerde asla. Erişim, projelere kapsamlanmış, kotalı, anahtar başına API belirteçleriyle denetlenir ve her imza, denetlediğiniz bir denetim günlüğüne kaydedilir. Bir sertifikayı döndürmek, ele geçirilmiş bir ajanın anahtarını iptal etmek veya neyin kim tarafından imzalandığını kanıtlamak; bunların hepsi birçok yer yerine tek bir bakılacak yere dönüşür.

Erişilebilirlik

sgcSign Server, sgcSign 2026.6.0'ın bir parçasıdır. Bir Windows hizmeti veya bir konsol uygulaması olarak çalışır, yukarıda gösterilen tek JSON dosyası tarafından yapılandırılır ve curl, birlikte gelen sgcsign CLI'si veya OpenAPI açıklaması üzerinden herhangi bir HTTP istemcisi tarafından yönetilir.

Sorularınız, geri bildiriminiz veya kurmaya yönelik yardıma mı ihtiyacınız var? İletişime geçin. Kodu yazan kişilerden bir yanıt alacaksınız.